企业官网建设流程全解析

${} 全局变量 & #{方法参数}：JQuick-Curl 动态参数完整详解，彻底解决占位符失效问题

项目地址：https://github.com/dromara/jquick-curl

Maven坐标

<dependency><groupId>io.github.paohaijiao</groupId><artifactId>jquick-curl</artifactId><version>2.1.0</version></dependency>

前言

只要一个 java http 客户端 真正进入业务开发，动态参数就绕不开。域名要换、用户凭证要换、Token 要换、路径参数要换、请求体中的字段要换。如果这些值全部写死在 curl 里，JQuick-Curl 再方便，也只能停留在 Demo 层。

JQuick-Curl 的实用价值之一，就是支持动态参数能力。尤其在第三方接口调用中，账号、密码、环境域名、业务参数几乎不可能固定。你需要一种方式，把“curl 命令模板”和“运行时参数”分开管理。

在 JQuick-Curl 里，最常见的两个占位方式是${}和#{}。很多人第一次使用时最容易踩坑的地方，也就在这里：到底什么时候用${}，什么时候用#{}，为什么有时替换生效，有时却失效？

这一篇就把这件事讲透。

正文

${}适合什么场景

${}更适合在注解模式里，结合JQuickCurlReq传递变量。它的使用方式很直观：curl 命令里写占位符，请求执行前从JQuickCurlReq中取值替换。

最典型的场景就是基础认证。

实战代码块

importcom.github.paohaijiao.anno.JCurlCommand;importcom.github.paohaijiao.domain.req.JQuickCurlReq;importcom.github.paohaijiao.executor.JCurlInvoker;publicinterfaceAuthApi{@JCurlCommand("curl -u ${user}:${password} https://api.github.com/user -X GET")StringcurrentUser(JQuickCurlReqrequest);staticvoidmain(String[]args)throwsException{AuthApiapi=JCurlInvoker.createProxy(AuthApi.class);JQuickCurlReqreq=newJQuickCurlReq();req.put("user","demo-user");req.put("password","demo-password");Stringresult=api.currentUser(req);System.out.println(result);}}

这里的user、password都来自JQuickCurlReq。这也是当前项目测试用例里真实使用过的方式。

${}还能放在哪里

不仅可以放认证信息，也可以放 URL、Header、请求体中的局部字段。只要是字符串层面替换，就可以考虑这种方式。

publicinterfaceVariableApi{@JCurlCommand("curl -X GET https://api.example.com/users/${id}")StringgetUser(JQuickCurlReqrequest);}JQuickCurlReqreq=newJQuickCurlReq();req.put("id",1001);

#{}更常见于 XML 配置模式

在 XML 模式里，#{}通常用于方法参数或上下文变量表达，配合 XML 动态能力使用更自然。它更偏“配置化模板占位”，而不是单纯注解模式里的 Map 替换。

例如：

<?xml version="1.0" encoding="UTF-8"?><!DOCTYPEcurlsPUBLIC"-//PAOHAIJIAO//DTD API CURL 1.0//EN""classpath:paohaijiao/dtd/Jquick-curl.dtd"><curlsnamespace="com.example.UserApi"><curlname="getUser"returnClass="java.lang.String">curl -X GET https://api.example.com/users/#{id}</curl></curls>

对应的接口：

importcom.github.paohaijiao.domain.req.JQuickCurlReq;publicinterfaceUserApi{StringgetUser(JQuickCurlReqrequest);}

如果你使用 XML 动态条件、XML 集中治理，通常会更多接触#{}这种表达。

两者怎么选

可以先记一个最实用的经验：

• 注解模式 +JQuickCurlReq：优先${}
• XML 模式 + 配置化请求：优先#{}

这不是绝对语法哲学，而是最不容易踩坑的实践方式。

动态参数在业务里最有价值的地方

1. 环境切换

测试环境、预发环境、生产环境域名不同，最适合提成变量。

2. 凭证注入

账号、密码、Token 绝不能硬编码在源码里。用变量替换后，可以运行时注入。

3. 业务参数拼接

订单号、用户编号、查询日期、分页参数等，都是典型动态值。

4. 统一模板复用

同一条 curl 模板，只换几个参数，就可以复用到多个请求场景。

为什么有时候占位符会失效

这是很多人最容易踩的坑。常见原因有四类。

第一，JQuickCurlReq中没放对应 key。第二，占位符名字和put的 key 不一致。第三，写错了占位符风格，在注解场景误用#{}。第四，引号、转义或路径拼接导致最终命令并不是你以为的样子。

推荐的排查思路

• 先把 curl 固定写死，确认命令本身可用
• 再逐步把一个字段替换成变量
• 每次只增加一个变量，便于定位问题
• 优先从 URL 或认证信息开始变量化，再处理复杂 JSON

注意点 / 踩坑提示

1. 占位符名称要完全一致

${user}就必须对应req.put("user", value)，大小写和拼写都不能错。

2. 注解模式优先用${}

如果你当前主要用@JCurlCommand，那就先别混用#{}。

3. 敏感信息不要硬编码

账号、密码、Token 最好通过配置中心、环境变量或运行时参数注入。

4. 复杂 JSON 变量替换要特别注意引号

字符串值本身如果需要双引号，必须提前处理好，避免替换后 JSON 结构损坏。

总结

动态参数能力是 JQuick-Curl 真正走向业务可用的关键。没有变量替换，它只是把 curl 放进 Java；有了${}和#{}，它才真正具备模板化第三方接口调用能力。对于日常的 curl 转 java 场景来说，这一步意义非常大。

最稳妥的实践是：注解模式优先${}，XML 模式优先#{}，先从认证和 URL 开始变量化，再逐步处理更复杂的请求体。这样既容易上手，也更不容易出错。

下一篇预告

下一篇我们讲 JQuick-Curl 的拦截器实战：怎么统一加 Token、打日志、做请求预处理，让外部接口调用真正进入工程化阶段。

#Java #JQuickCurl #动态参数 #第三方接口调用 #curl转java