JQuick-Curl XML 配置模式：接口与代码解耦的企业级方案，第三方接口治理终于清爽了
项目地址：https://github.com/dromara/jquick-curl
Maven坐标
<dependency>
<groupId>io.github.paohaijiao</groupId>
<artifactId>jquick-curl</artifactId>
<version>2.1.0</version>
</dependency>
前言
前一篇我们讲了 @JCurlCommand 注解模式，它非常适合快速开发。但当项目中的第三方接口调用越来越多时，一个问题就会逐渐冒出来：curl 命令散落在 Java 接口中，改配置不够集中，排查也不够顺手。尤其是企业项目里，一个模块可能接十几个外部系统，接口数量上百，这时候你就会开始需要“配置和代码解耦”。
这正是 JQuick-Curl XML 模式的价值。它允许你把 curl 命令集中写在 XML 中，把 Java 接口只保留为方法声明。对企业场景来说，这种方式更利于治理：接口统一存放、统一审查、统一变更，也更适合多人协作。
如果说注解模式适合快速上手，那么 XML 模式更像是 JQuick-Curl 的企业级组织方式。
正文
为什么 XML 模式在企业里更有优势
很多 Java 团队一提 XML 就本能抗拒，觉得“是不是老了”。但工程实践里，配置化本身并不过时，过时的是无边界地滥用配置。对于第三方接口调用，XML 模式有几个很现实的好处。
第一，接口定义集中。所有 curl 都在同一个或同一批 XML 文件里，便于统一查看。第二，变更更可控。接口地址、Header、Body、变量策略调整时，不必每次都动 Java 类。第三，职责更清晰。Java 接口只表达“有哪些能力”，XML 表达“这些能力怎么发请求”。
XML 模式的核心结构
JQuick-Curl 的 XML 核心元素是 <curls> 和 <curl>。
<curls namespace="...">：绑定 Java 接口全类名<curl name="..." returnClass="...">：对应一个接口方法
简单理解就是：XML 中的 namespace 对应接口，name 对应方法名。
实战代码块
第一步：准备 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/1
</curl>
<curl name="createUser" returnClass="java.lang.String">
curl -X POST https://api.example.com/users \
-H "Content-Type: application/json" \
-d '{"name":"Ada","email":"ada@example.com"}'
</curl>
</curls>
第二步：定义 Java 接口
import com.github.paohaijiao.domain.req.JQuickCurlReq;
public interface UserApi {
String getUser(JQuickCurlReq request);
String createUser(JQuickCurlReq request);
}
可以看到，这里 Java 接口完全没有出现 curl 命令。代码层变得非常干净。
第三步：创建 XML 代理并调用
import com.github.paohaijiao.xml.JQuickCurlXmlParseFactory;
import com.github.paohaijiao.xml.factory.JQuickXmlFactory;
import com.github.paohaijiao.xml.handler.JQuickParseHandler;
public class XmlDemo {
public static void main(String[] args) {
JQuickParseHandler parser = new JQuickCurlXmlParseFactory();
JQuickXmlFactory factory = new JQuickXmlFactory(parser, "apis.xml");
UserApi api = factory.createApi(UserApi.class);
String result = api.getUser(new JQuickCurlReq());
System.out.println(result);
}
}
这就是 XML 模式最核心的用法。对于企业项目来说，这种结构已经足够支撑中等规模的第三方接口调用管理。
XML 模式最适合哪类接口
非常适合下面几类场景：
- 同一个业务域下有很多外部接口
- 接口地址、Header、Body 容易变
- 希望接口描述与业务代码分离
- 需要运维、测试、开发都能较直观地查看请求定义
与注解模式怎么选
简单来说：
- 少量接口、快速开发：优先注解模式
- 多接口、要集中治理：优先 XML 模式
它们并不是互斥的。很多项目完全可以两者并存：临时或简单接口用注解，稳定且量大的第三方接口用 XML。
XML 模式的一个重要价值：配置审查能力
当你把接口定义集中在 XML 中后，很多事情会更容易做：
- 统一检查是否带鉴权头
- 统一检查测试环境和生产环境地址差异
- 统一审查第三方接口调用风险
- 统一沉淀对接规范
这类能力在中大型团队中特别有价值。因为真正复杂的不是“会不会发请求”，而是“请求定义如何治理”。
注意点 / 踩坑提示
1. namespace 必须和 Java 接口全限定名一致
这是 XML 代理绑定成功的前提。
2. <curl name> 必须和接口方法名一致
名称不一致，创建代理后方法就无法正确映射。
3. returnClass 要写真实返回类型
如果你想返回 String、byte[] 或业务类，需要在 XML 里写清楚对应类型。
4. XML 适合治理，不适合无脑堆积
建议按业务域拆分多个 XML 文件，而不是所有第三方接口都堆在一个超大配置文件里。
总结
JQuick-Curl 的 XML 配置模式，把第三方接口调用从“散落在 Java 代码中的命令”提升到了“可集中治理的配置资产”。这对企业项目尤其重要。它既保留了 curl 转 java 的高效率，又补足了注解模式在大规模场景下的治理短板。
如果你手上的项目已经进入多系统、多接口、多团队协作阶段，那么 XML 模式很可能比注解模式更适合作为主方案。它不是为了显得高级，而是为了让接口定义更清晰、变更更集中、维护成本更低。
下一篇预告
下一篇我们进入非常高频的业务能力：文件上传下载。单文件上传、多文件上传、带表单字段一起传、文件下载保存，这些在 JQuick-Curl 中到底怎么写。
