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

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

**Maven坐标**
```xml
<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` 中取值替换。

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

## 实战代码块

```java
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、请求体中的局部字段。只要是字符串层面替换，就可以考虑这种方式。

```java
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
<?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>
```

对应的接口：

```java
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、打日志、做请求预处理，让外部接口调用真正进入工程化阶段。

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

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

JQuick-Curl 动态参数完整详解，彻底解决占位符失效问题

人工智能

JQuick-Curl动态参数实战：详解${}与#{}占位符区别，解决替换失效问题。覆盖注解模式与XML配置场景，教你正确选择变量风格，实现认证信息、URL路径及业务参数的灵活注入，附源码示例与踩坑指南，助力curl模板工程化落地。

代码解释

GitHub

JSON

Java

热销域名限时优惠，新客首年免费！


domain

2026上云采购 | AI焕新·智启新局

文章

问答

视频

教程

学习中心

腾讯云实验室

直播

竞赛

腾讯云代码分析专区

腾讯iOA零信任安全管理系统专区

腾讯云架构师技术同盟交流圈

腾讯云数据库专区

腾讯云智能顾问专区

腾讯云原生专区

腾讯混元专区

腾讯云TCE专区

腾讯云Lighthouse专区

腾讯云HAI专区

腾讯云Edgeone专区

腾讯云存储专区

腾讯云智能专区

腾讯轻联专区 

腾讯云开发专区

TAPD专区

腾讯轻量云游戏服专区

EdgeOne AI 安全实战专区

腾讯云最具价值专家

腾讯云架构师技术同盟

腾讯云创作之星

腾讯云开发者先锋

腾讯云代码助手

云原生构建

TAPD 敏捷项目管理

Cloud Studio

SDK中心

API中心

命令行工具

涵盖代码开发、场景应用、自动测试全流程，助你从零构建专属AI助手

一站式MCP教程库，解锁AI应用新玩法

聚焦“写作效率、视觉美观与运行性能”三方面进行全面升级，为您提供更高效、稳定的创作环境

社区富文本&Markdown编辑器全新改版上线，欢迎大家体验!

诚挚邀请您参与本次调研，分享您的真实使用感受与建议。您的反馈至关重要，感谢您的支持与参与！

社区新版编辑器体验调研

JQuick-Curl 动态参数完整详解，彻底解决占位符失效问题-腾讯云开发者社区-腾讯云

JQuick-Curl 动态参数完整详解，彻底解决占位符失效问题

JQuick-Curl 动态参数完整详解，彻底解决占位符失效问题

社区

活动

圈层

关于

腾讯云开发者

热门产品

热门推荐

更多推荐