${} 全局变量 & #{方法参数}：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 中取值替换。
最典型的场景就是基础认证。
实战代码块
import com.github.paohaijiao.anno.JCurlCommand;
import com.github.paohaijiao.domain.req.JQuickCurlReq;
import com.github.paohaijiao.executor.JCurlInvoker;
public interface AuthApi {
@JCurlCommand("curl -u ${user}:${password} https://api.github.com/user -X GET")
String currentUser(JQuickCurlReq request);
static void main(String[] args) throws Exception {
AuthApi api = JCurlInvoker.createProxy(AuthApi.class);
JQuickCurlReq req = new JQuickCurlReq();
req.put("user", "demo-user");
req.put("password", "demo-password");
String result = api.currentUser(req);
System.out.println(result);
}
}
这里的 user、password 都来自 JQuickCurlReq。这也是当前项目测试用例里真实使用过的方式。
${} 还能放在哪里
不仅可以放认证信息，也可以放 URL、Header、请求体中的局部字段。只要是字符串层面替换，就可以考虑这种方式。
public interface VariableApi {
@JCurlCommand("curl -X GET https://api.example.com/users/${id}")
String getUser(JQuickCurlReq request);
}
JQuickCurlReq req = new JQuickCurlReq();
req.put("id", 1001);
#{} 更常见于 XML 配置模式
在 XML 模式里，#{} 通常用于方法参数或上下文变量表达，配合 XML 动态能力使用更自然。它更偏“配置化模板占位”，而不是单纯注解模式里的 Map 替换。
例如：
<?xml version="1.0" encoding="UTF-8"?>
<!DOCTYPE curls PUBLIC "-//PAOHAIJIAO//DTD API CURL 1.0//EN"
"classpath:paohaijiao/dtd/Jquick-curl.dtd">
<curls namespace="com.example.UserApi">
<curl name="getUser" returnClass="java.lang.String">
curl -X GET https://api.example.com/users/#{id}
</curl>
</curls>
对应的接口：
import com.github.paohaijiao.domain.req.JQuickCurlReq;
public interface UserApi {
String getUser(JQuickCurlReq request);
}
如果你使用 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、打日志、做请求预处理，让外部接口调用真正进入工程化阶段。
