用 Feat 发出 HTTP 请求

这篇教程聚焦在最常用的场景上：先把 HTTP 请求发出去，再逐步补上请求头、查询参数、POST JSON 和响应回调。

你会完成什么

• 创建一个 HttpClient
• 发送一个 GET 请求
• 读取响应头和响应体
• 发送 JSON POST 请求
• 理解 submit()、onSuccess()、onFailure() 的基本协作方式

前置条件

• JDK 1.8 或更高版本
• Maven 3.0 或更高版本
• 已引入 feat-core

如果你还没有引入依赖：

pom.xml

<dependency>
    <groupId>tech.smartboot.feat</groupId>
    <artifactId>feat-core</artifactId>
    <version>${feat.version}</version>
</dependency>

步骤 1：发送第一个 GET 请求

最短路径是先请求一个现成地址，确认客户端工作正常：

HttpGetDemo.java

import tech.smartboot.feat.core.client.HttpClient;

public class HttpGetDemo {
    public static void main(String[] args) {
        HttpClient httpClient = new HttpClient("https://smartboot.tech");
        httpClient.get("/feat/")
                .onSuccess(response -> System.out.println(response.body()))
                .onFailure(Throwable::printStackTrace)
                .submit();
    }
}

这个例子里：

• new HttpClient("https://smartboot.tech") 使用 host + schema 形式创建客户端
• get("/feat/") 发起 GET 请求
• onSuccess(...) 处理成功响应
• onFailure(...) 处理异常
• submit() 真正提交请求

Tip

submit() 返回的是 CompletableFuture<HttpResponse>。如果你只想走回调模式，可以像上面一样直接注册回调；如果你要和别的异步流程拼接，可以进一步操作这个 Future。

步骤 2：读取状态码和响应头

如果你不仅关心响应体，还想知道状态码和头部信息，可以用 onResponseHeader(...)：

ResponseHeaderDemo.java

import tech.smartboot.feat.core.client.HttpClient;

public class ResponseHeaderDemo {
    public static void main(String[] args) {
        HttpClient httpClient = new HttpClient("https://smartboot.tech");
        httpClient.get("/feat/")
                .onResponseHeader(response -> {
                    System.out.println("status: " + response.statusCode());
                    for (String name : response.getHeaderNames()) {
                        System.out.println(name + ": " + response.getHeader(name));
                    }
                })
                .submit();
    }
}

这适合做：

• 响应状态判断
• 内容类型检查
• 调试接口返回头

步骤 3：添加请求头和查询参数

Feat HttpClient 的 header 设置是通过 Consumer<Header> 完成的，不是传统的 header("k", "v") 形式：

HttpGetWithHeaderDemo.java

import tech.smartboot.feat.core.client.HttpClient;
import tech.smartboot.feat.core.common.HeaderName;

public class HttpGetWithHeaderDemo {
    public static void main(String[] args) {
        HttpClient httpClient = new HttpClient("https://smartboot.tech");
        httpClient.get("/feat/")
                .header(header -> header
                        .set(HeaderName.USER_AGENT, "feat-doc-demo")
                        .keepalive(true))
                .addQueryParam("from", "docs")
                .onSuccess(response -> System.out.println(response.body()))
                .onFailure(Throwable::printStackTrace)
                .submit();
    }
}

这里最常用的几个能力是：

• header(...).set(...)：覆盖同名请求头
• header(...).add(...)：追加同名请求头
• keepalive(true)：控制连接复用
• addQueryParam(...)：追加查询参数

步骤 4：发送 POST JSON 请求

对于 POST JSON，最省事的方式是直接用 postJson(...)：

HttpPostJsonDemo.java

import tech.smartboot.feat.core.client.HttpClient;

import java.util.HashMap;
import java.util.Map;

public class HttpPostJsonDemo {
    public static void main(String[] args) {
        HttpClient httpClient = new HttpClient("https://api.example.com");

        Map<String, Object> payload = new HashMap<>();
        payload.put("name", "feat");
        payload.put("type", "demo");

        httpClient.post("/users")
                .postJson(payload)
                .onSuccess(response -> {
                    System.out.println("status: " + response.statusCode());
                    System.out.println(response.body());
                })
                .onFailure(Throwable::printStackTrace)
                .submit();
    }
}

postJson(...) 会自动完成两件事：

• 把对象序列化成 JSON
• 设置合适的 Content-Type 和 Content-Length

步骤 5：使用通用 REST 入口

如果你不想分别调用 get()、post()，也可以使用更通用的 rest(...)：

HttpRestDemo.java

import tech.smartboot.feat.core.client.HttpClient;
import tech.smartboot.feat.core.common.HttpMethod;

public class HttpRestDemo {
    public static void main(String[] args) {
        HttpClient client = new HttpClient("https://smartboot.tech");
        client.options().debug(true);

        client.rest(HttpMethod.GET, "/feat/")
                .onSuccess(response -> {
                    System.out.println("Status Code: " + response.statusCode());
                    System.out.println("Body: " + response.body());
                })
                .submit();
    }
}

当你在封装通用 API 客户端、动态决定方法类型时，rest(...) 会更合适。

常见问题

new HttpClient("localhost:8080") 直接报错

HttpClient(String url) 必须传完整 URL，包括 schema。正确写法类似：

new HttpClient("http://localhost:8080");

get() 调用抛出 UnsupportedOperationException

无参 get() 只支持在“完整 URL 构造函数”下使用，例如：

new HttpClient("http://localhost:8080/hello").get();

如果你是 new HttpClient("localhost", 8080) 这种构造方式，就要使用 get("/hello")。

为什么 GET 不能写请求体

HttpGet.body() 明确不支持请求体，这是客户端 API 的设计约束。需要请求体时，改用 post(...) 或 rest(...)。

我想看更细的网络调试信息

可以打开调试：

httpClient.options().debug(true);

下一步

• SSE 客户端：如果你要处理流式事件响应
• WebSocket 客户端：如果你要建立双向实时连接
• Feat Core 快速入门：如果你还需要先搭一个本地服务做联调