JQuick-Curl 快速上手：Maven 依赖与第一个 HelloWorld 请求

项目地址 ：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 后端开发者第一次接触 JQuick-Curl 时，都会有两个疑问：第一，这东西到底怎么接进项目；第二，能不能像 HelloWorld 一样快速跑起来。如果一个 java http 客户端框架需要先理解一大堆概念、再搭很多配置、再补很多样板代码，那它就失去了"快速接入"的意义。

JQuick-Curl 的优势就在这里。它对熟悉 curl 命令的开发者非常友好，尤其适合 1-5 年经验的 Java 工程师：你不需要先抽象 DTO、也不需要先封装模板，只要把 curl 命令通过 @JCurlCommand 放进接口方法，就可以直接执行。

这一篇我们不谈复杂能力，只解决一个目标：让你的第一个 java curl 执行示例真正跑起来，并理解最基本的调用流程。

正文

第一步：引入 Maven 依赖

先在项目中加入依赖。这个步骤和普通 Java 开源库没有区别。

xml 复制代码

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

如果你是 SpringBoot 项目，直接放到现有 Maven 工程里即可；如果你是普通 Java 工程，也同样可以使用。JQuick-Curl 本质上是一个通用 Java HTTP 客户端框架，不依赖 Spring 容器才能运行。

第二步：理解最小调用模型

JQuick-Curl 的最小调用模型非常简单：

定义一个接口
在接口方法上写 @JCurlCommand
方法参数一般使用 JQuickCurlReq
用 JCurlInvoker.createProxy 创建代理对象
直接调用方法

如果你之前用过 OpenFeign，会觉得它也有点声明式味道；但 JQuick-Curl 的最大区别是，方法上写的不是 URL 和注解组合，而是一整条 curl 命令。

第三步：写第一个 HelloWorld 请求

为了尽量降低上手门槛，建议先用一个公开可访问的简单 GET 请求验证环境。比如 https://httpbin.org/get 这种接口。

实战代码块

java 复制代码

import com.github.paohaijiao.anno.JCurlCommand;
import com.github.paohaijiao.domain.req.JQuickCurlReq;
import com.github.paohaijiao.executor.JCurlInvoker;

public interface HelloWorldApi {

    @JCurlCommand("curl -X GET https://httpbin.org/get")
    String hello(JQuickCurlReq request);

    static void main(String[] args) throws Exception {
        HelloWorldApi api = JCurlInvoker.createProxy(HelloWorldApi.class);
        JQuickCurlReq req = new JQuickCurlReq();
        String result = api.hello(req);
        System.out.println(result);
    }
}

这个示例里有几个关键点。

第一，@JCurlCommand 里写的是原生 curl 命令格式，而不是 Java 风格配置。第二，返回值直接声明成 String，表示我们先拿原始响应字符串。第三，JQuickCurlReq 现在虽然没传值，但后面做动态变量替换时会非常重要。

第四步：带参数的 HelloWorld

如果你只是看 GET 请求，可能还感受不到它和普通 java http 客户端的差异。下面给一个带 Header 和 Body 的例子，更接近实际开发。

java 复制代码

import com.github.paohaijiao.anno.JCurlCommand;
import com.github.paohaijiao.domain.req.JQuickCurlReq;
import com.github.paohaijiao.executor.JCurlInvoker;

public interface DemoPostApi {

    @JCurlCommand("curl -X POST https://httpbin.org/post -H 'Content-Type: application/json' -d '{\"name\":\"jquick-curl\"}'")
    String post(JQuickCurlReq request);

    static void main(String[] args) throws Exception {
        DemoPostApi api = JCurlInvoker.createProxy(DemoPostApi.class);
        String result = api.post(new JQuickCurlReq());
        System.out.println(result);
    }
}

这里最重要的体验是：curl 怎么写，Java 基本就怎么写。对做 curl 转 java 的开发者来说，这是非常顺手的。

第五步：它背后做了什么

JQuick-Curl 在执行时，主要完成了几件事：

解析 @JCurlCommand 中的 curl 字符串
把请求方法、Header、Body、认证、上传下载选项拆开
构建底层 HTTP 请求
执行请求
把响应转换为你声明的方法返回类型

也就是说，它把你原本要自己手写的一大堆请求拼接代码，统一封装了起来。

第六步：什么时候适合用这种 HelloWorld 接入方式

适合以下几种情况：

项目中需要快速接第三方接口调用
文档给的就是 curl 命令
调试优先，希望命令与代码保持一致
暂时不想写复杂模板类和 DTO

如果你的业务请求数量很多、规则复杂，后面还可以切换到 XML 配置模式，形成更企业级的治理方式。

注意点 / 踩坑提示

1. 方法参数先统一用 `JQuickCurlReq`

即使一开始没参数，也建议保留 JQuickCurlReq。后面做占位符变量时会直接用上。

2. 第一篇示例先返回 `String`

刚开始不要急着把响应转实体，先确认请求链路是通的，再做对象映射，排查问题更简单。

3. curl 字符串要保证自己先能跑通

JQuick-Curl 最大的价值之一是复用 curl，但前提是 curl 本身是正确的。建议先在终端验证。

4. 不要一开始就上复杂上传下载

入门阶段先走通 GET/POST，再逐步增加文件上传、下载、认证、代理等能力。

总结

JQuick-Curl 的快速上手非常适合熟悉 curl 命令的 Java 工程师。引入依赖后，你只需要写一个接口、一个 @JCurlCommand、一个代理调用，就能完成第一个 HelloWorld 请求。相比传统 RestTemplate 对比方案，它最大的不同在于：请求不是从 Java Builder 开始，而是从现成 curl 开始。

这让它在第三方接口调用、调试联调、curl 转 java 场景中非常高效。对日常开发来说，这种"少写模板、多复用命令"的方式，往往比额外封装更实用。

下一篇预告

下一篇我们不只讲会不会用，而是讲选型：JQuick-Curl 和 RestTemplate、OkHttp、OpenFeign 到底有什么差异，哪些场景适合它，哪些场景不适合它。

#Java #JQuickCurl #HTTP客户端 #curl转java #后端开发

JQuick-Curl 快速上手：Maven 依赖与第一个 HelloWorld 请求