JmsHttp 1.x.x 使用指南

📖 快速开始

什么是 JmsHttp？

JmsHttp 是一个轻量级的 HTTP 客户端框架，基于装饰器模式提供灵活的扩展能力。它支持限流、重试、域名级限流等功能，采用链式构建和装饰器组装机制。

💡 核心理念

装饰器模式，灵活扩展
链式 API，代码简洁
支持全局限流和域名级限流
自动重试机制，应对网络抖动
装饰器顺序可控（order 机制）

第一个 JmsHttp 程序

// ① 创建最简单的 HTTP 客户端（无装饰器）
HttpClient client = HttpClient.builder()
    .build();

// ② 创建请求
HttpRequest request = HttpRequest.builder()
    .url("https://api.example.com/data")
    .method(RequestMethod.GET)
    .build();

// ③ 执行请求
HttpResponse response = client.execute(request);

// ④ 处理响应
System.out.println("状态码：" + response.getCode());
System.out.println("响应体：" + response.getBody());

✅ 简化版（推荐）

// 直接执行请求（不使用装饰器）
HttpResponse response = HttpResponse.executeRequest(
    HttpRequest.builder()
        .url("https://api.example.com/data")
        .method(RequestMethod.GET)
        .build()
);

带限流和重试的 HTTP 客户端

// 创建带限流和重试的客户端
HttpClient client = HttpClient.builder()
    .openRateLimit(100)           // 全局最大 100 并发
    .retryTimes(3)                   // 失败重试 3 次
    .build();

// 执行请求
HttpResponse response = client.execute(request);

📦 核心概念

1. HttpClient - HTTP 客户端

HttpClient 是 HTTP 请求的核心执行者，负责管理和执行 HTTP 请求。通过 Builder 模式构建，支持动态添加装饰器。

重要特性

Builder 模式构建，链式调用
支持动态添加装饰器
装饰器按 order 排序执行
线程安全，可复用
内置连接池优化（keepAlive）

// 创建空客户端
HttpClient client = HttpClient.builder()
    .build();

// 创建带限流的客户端
HttpClient client = HttpClient.builder()
    .openRateLimit(100)
    .build();

// 创建带重试的客户端
HttpClient client = HttpClient.builder()
    .retryTimes(3)
    .build();

// 组合多个装饰器
HttpClient client = HttpClient.builder()
    .openRateLimit(100)           // 全局限流
    .openDomainRateLimit(50)      // 域名限流
    .retryTimes(3)                // 重试
    .build();

2. HttpRequest - HTTP 请求

HttpRequest 封装 HTTP 请求的所有信息，包括 URL、方法、头、参数等。

// 使用 Builder 创建请求
HttpRequest request = HttpRequest.builder()
    .url("https://api.example.com/users")
    .method(RequestMethod.GET)
    .param("page", "1")
    .param("size", "10")
    .addHeader("Authorization", "Bearer token123")
    .connectTimeout(5000)
    .readTimeout(10000)
    .redirect(true)
    .build();

// POST 请求带请求体
HttpRequest postRequest = HttpRequest.builder()
    .url("https://api.example.com/users")
    .method(RequestMethod.POST)
    .body("{\"name\":\"John\",\"age\":30}")
    .addHeader("Content-Type", "application/json")
    .build();

3. HttpResponse - HTTP 响应

HttpResponse 封装 HTTP 响应的所有信息，包括状态码、头、体等。

HttpResponse response = client.execute(request);

// 获取状态码
int statusCode = response.getCode();

// 获取响应体
String body = response.getBody();

// 获取响应头
List<String> contentType = response.getHeader("Content-Type");
Map<String, List<String>> headers = response.getHeaders();

// 获取响应时间
long responseTime = response.getResponseTime();

// 获取请求方式
RequestMethod method = response.getRequestMethod();

// 获取 URL
String url = response.getUrl();

// 获取响应消息
String message = response.getMessage();

4. HttpDecorator - HTTP 装饰器

装饰器是 JmsHttp 的灵魂！ 所有扩展功能都通过装饰器实现。

装饰器接口规范

decorate(supplier, request) - 装饰方法
getName() - 获取装饰器名称
setOrder(order) - 设置执行顺序
getOrder() - 获取执行顺序
compareTo() - 比较顺序（order 小的先执行）

// AbstractHttpDecorator 抽象基类
public abstract class AbstractHttpDecorator implements HttpDecorator {
    protected int order;
    
    @Override
    public void setOrder(int order) {
        this.order = order;
    }
    
    @Override
    public int getOrder() {
        return this.order;
    }
    
    @Override
    public int compareTo(HttpDecorator o) {
        return this.getOrder() - o.getOrder();
    }
}

5. HttpRateLimiter - 全局限流器

控制整个系统的总并发连接数，使用 CAS 乐观锁实现。

// 创建限流器（最大 100 并发）
HttpRateLimiter rateLimiter = new HttpRateLimiter(100);

// 获取当前活跃连接数
int activeCount = rateLimiter.getActiveCount();

// 获取剩余可用连接数
int remaining = rateLimiter.getRemainingCapacity();

// 获取最大连接数
int maxConnectNumber = rateLimiter.getMaxConnectNumber();

// 在 Builder 中使用
HttpClient client = HttpClient.builder()
    .openRateLimit(100)
    .build();

6. DomainRateLimiter - 域名级限流器

为不同主机地址（host:port）设置独立的并发限制。

域名限流器特性

自动从 URL 提取 host:port
支持自定义主机的限流值
CAS 乐观锁实现，线程安全
支持清理空闲主机计数器

// 创建域名限流器（默认每主机 50 并发）
DomainRateLimiter domainLimiter = new DomainRateLimiter(50);

// 为特定主机设置独立限流值
domainLimiter.setHostLimit("api.weixin.qq.com:443", 100);

// 获取某主机的活跃连接数
int active = domainLimiter.getActiveCount("api.weixin.qq.com:443");

// 获取所有主机的活跃连接数
Map<String, Integer> counts = domainLimiter.getAllActiveCounts();

// 清理空闲主机
domainLimiter.cleanupIdleHosts();

// 移除主机的自定义配置
domainLimiter.removeHostLimit("api.weixin.qq.com:443");

// 在 Builder 中使用
HttpClient client = HttpClient.builder()
    .openDomainRateLimit(50)
    .build();

7. HttpRetryer - HTTP 重试器

在网络抖动等异常情况下自动重试，提高请求成功率。

// 创建重试器（重试 3 次）
HttpRetryer retryer = new HttpRetryer(3);

// 获取重试次数
int retryTimes = retryer.getRetryTimes();

// 在 Builder 中使用
HttpClient client = HttpClient.builder()
    .retryTimes(3)
    .build();

⚠️ 重试机制说明

仅对 RuntimeException 进行重试
每次重试间隔递增（1 秒、2 秒、3 秒...）
达到最大重试次数后抛出异常
InterruptedException 会中断重试

💡 实战场景

场景 1：调用 RESTful API

// GET 请求
HttpClient client = HttpClient.builder().build();

HttpRequest request = HttpRequest.builder()
    .url("https://api.github.com/users/octocat")
    .method(RequestMethod.GET)
    .addHeader("Accept", "application/vnd.github.v3+json")
    .build();

HttpResponse response = client.execute(request);

if (response.getCode() == 200) {
    String userInfo = response.getBody();
    System.out.println(userInfo);
}

场景 2：POST JSON 数据

HttpClient client = HttpClient.builder().build();

String jsonBody = "{\"username\":\"john\",\"password\":\"secret\"}";

HttpRequest request = HttpRequest.builder()
    .url("https://api.example.com/login")
    .method(RequestMethod.POST)
    .body(jsonBody)
    .addHeader("Content-Type", "application/json")
    .build();

HttpResponse response = client.execute(request);

if (response.getCode() == 200) {
    String token = response.getBody();
    System.out.println("登录成功，Token: " + token);
}

场景 3：带参数的 GET 请求

HttpClient client = HttpClient.builder().build();

HttpRequest request = HttpRequest.builder()
    .url("https://api.example.com/search")
    .method(RequestMethod.GET)
    .param("q", "java http client")
    .param("page", "1")
    .param("size", "20")
    .build();

HttpResponse response = client.execute(request);
System.out.println("搜索结果：" + response.getBody());

场景 4：高并发限流场景

// 创建带限流的客户端（全局 100 并发，每域名 50 并发）
HttpClient client = HttpClient.builder()
    .openRateLimit(100)
    .openDomainRateLimit(50)
    .build();

// 批量请求
for (int i = 0; i < 200; i++) {
    final int index = i;
    new Thread(() -> {
        HttpRequest request = HttpRequest.builder()
            .url("https://api.example.com/data/" + index)
            .method(RequestMethod.GET)
            .build();
        
        try {
            HttpResponse response = client.execute(request);
            System.out.println("请求 " + index + " 完成，状态码：" + response.getCode());
        } catch (Exception e) {
            System.err.println("请求 " + index + " 失败：" + e.getMessage());
        }
    }).start();
}

场景 5：不稳定网络的重试场景

// 创建带重试的客户端（重试 3 次）
HttpClient client = HttpClient.builder()
    .retryTimes(3)
    .build();

HttpRequest request = HttpRequest.builder()
    .url("https://unstable-api.example.com/data")
    .method(RequestMethod.GET)
    .connectTimeout(10000)  // 增加超时时间
    .readTimeout(30000)
    .build();

try {
    HttpResponse response = client.execute(request);
    System.out.println("请求成功：" + response.getBody());
} catch (HttpException e) {
    System.err.println("请求失败（已重试 3 次）：" + e.getMessage());
}

场景 6：多域名不同限流策略

// 创建域名限流器
DomainRateLimiter domainLimiter = new DomainRateLimiter(20); // 默认每域名 20 并发

// 为重要 API 设置更高的限流值
domainLimiter.setHostLimit("api.payment.com:443", 100);
domainLimiter.setHostLimit("api.user.com:443", 50);

HttpClient client = HttpClient.builder()
    .addDecorator(domainLimiter)
    .build();

// 访问不同域名会自动应用对应的限流策略

⚙️ 高级用法

装饰器执行顺序

装饰器按照 order 从小到大排序执行，order 越小越靠近内层（基础逻辑）。

装饰器执行流程

Builder 按添加顺序分配 order（0, 1, 2...）
TreeSet 自动按 order 排序
执行时从外到内（order 大到小）
返回时从内到外（order 小到大）

// 示例：retryTimes(order=0) + openRateLimit(order=1)
HttpClient client = HttpClient.builder()
    .retryTimes(3)              // order = 0（内层）
    .openRateLimit(100)         // order = 1（外层）
    .build();

// 执行流程：
// 请求 → HttpRateLimiter（限流检查）→ HttpRetryer（重试逻辑）→ 实际 HTTP 请求
// 响应 ← HttpRateLimiter ← HttpRetryer ← 实际 HTTP 响应

// ✅ 这个顺序非常合理：
// - 限流在外层：快速失败，不浪费资源
// - 重试在内层：专心应对网络抖动
// - 限流异常不会触发重试

自定义装饰器

继承 AbstractHttpDecorator 实现自定义装饰器。

// 日志记录装饰器
public class HttpLoggingDecorator extends AbstractHttpDecorator {
    
    private static final Logger logger = Logger.getLogger(HttpLoggingDecorator.class);
    
    @Override
    public HttpResponse decorate(Supplier<HttpResponse> supplier, HttpRequest request) {
        long startTime = System.currentTimeMillis();
        
        logger.info("开始请求：" + request.getUrl());
        logger.info("请求方法：" + request.getMethod());
        
        try {
            HttpResponse response = supplier.get();
            
            long costTime = System.currentTimeMillis() - startTime;
            logger.info("请求完成：" + response.getCode() + ", 耗时：" + costTime + "ms");
            
            return response;
            
        } catch (Exception e) {
            logger.error("请求失败：" + e.getMessage(), e);
            throw e;
        }
    }
    
    @Override
    public String getName() {
        return "HttpLoggingDecorator";
    }
}

// 使用自定义装饰器
HttpLoggingDecorator loggingDecorator = new HttpLoggingDecorator();
loggingDecorator.setOrder(2);

HttpClient client = HttpClient.builder()
    .retryTimes(3)
    .openRateLimit(100)
    .addDecorator(loggingDecorator)
    .build();

监控装饰器状态

// 全局限流器监控
HttpRateLimiter rateLimiter = (HttpRateLimiter) client.getDecorator(HttpRateLimiter.class);

if (rateLimiter != null) {
    System.out.println("当前活跃连接：" + rateLimiter.getActiveCount());
    System.out.println("剩余可用连接：" + rateLimiter.getRemainingCapacity());
    System.out.println("最大连接数：" + rateLimiter.getMaxConnectNumber());
}

// 域名限流器监控
DomainRateLimiter domainLimiter = (DomainRateLimiter) client.getDecorator(DomainRateLimiter.class);

if (domainLimiter != null) {
    Map<String, Integer> activeCounts = domainLimiter.getAllActiveCounts();
    activeCounts.forEach((host, count) -> 
        System.out.println(host + ": " + count + " 活跃连接")
    );
}

获取装饰器

// 按名称获取装饰器
HttpDecorator decorator = client.getDecorator("HttpRateLimiter");

// 按类型获取装饰器
HttpDecorator decorator = client.getDecorator(HttpRateLimiter.class);
HttpRateLimiter rateLimiter = (HttpRateLimiter) decorator;

响应信息处理

HttpResponse response = client.execute(request);

// 检查状态码
if (response.getCode() == 200) {
    // 成功
    String result = response.getBody();
    System.out.println("成功：" + result);
    
} else if (response.getCode() == 404) {
    // 资源不存在
    System.err.println("资源不存在");
    
} else if (response.getCode() >= 500) {
    // 服务器错误
    System.err.println("服务器错误：" + response.getMessage());
}

// 解析 JSON 响应
if ("application/json".equals(response.getHeader("Content-Type").get(0))) {
    JsonObject json = JsonParser.parseString(response.getBody()).getAsJsonObject();
    // 处理 JSON...
}

⚠️ 注意事项

❌ 常见错误

忘记设置请求 URL → 抛出 HttpRequestException
重复使用已关闭的连接 → 连接池自动管理，无需担心
装饰器顺序错误 → 导致限流失效或重试行为异常
在装饰器中修改 request 引用 → 破坏装饰器链

✅ 最佳实践

使用 Builder 模式创建请求和客户端
合理设置超时时间（connectTimeout, readTimeout）
根据实际需求选择限流值
装饰器顺序：重试（order=0）→ 限流（order=1）→ 其他（order=2+）
使用域名限流时，为关键服务设置独立限流值

超时设置

// ✅ 推荐：根据业务场景设置超时
HttpRequest request = HttpRequest.builder()
    .url("https://api.example.com/data")
    .connectTimeout(5000)   // 连接超时 5 秒
    .readTimeout(10000)      // 读取超时 10 秒
    .build();

// ❌ 不推荐：超时时间过短或过长
HttpRequest badRequest = HttpRequest.builder()
    .url("https://api.example.com/data")
    .connectTimeout(100)     // 太短，容易失败
    .readTimeout(60000)      // 太长，响应慢
    .build();

异常处理

try {
    HttpClient client = HttpClient.builder()
        .retryTimes(3)
        .build();
    
    HttpRequest request = HttpRequest.builder()
        .url("https://api.example.com/data")
        .method(RequestMethod.GET)
        .build();
    
    HttpResponse response = client.execute(request);
    
    if (response.getCode() != 200) {
        System.err.println("HTTP 错误：" + response.getCode());
    }
    
} catch (HttpRequestException e) {
    // 请求异常（如 URL 无效、连接失败）
    logger.error("请求异常", e);
    
} catch (HttpResponseException e) {
    // 响应异常（如读取响应失败）
    logger.error("响应异常", e);
    
} catch (HttpException e) {
    // 通用 HTTP 异常
    logger.error("HTTP 异常", e);
    
} catch (Exception e) {
    // 其他异常
    logger.error("未知异常", e);
}

装饰器顺序陷阱

⚠️ 错误的装饰器顺序

// ❌ 错误：限流在内层，重试在外层
HttpClient.builder()
    .openRateLimit(100)      // order = 0（内层）
    .retryTimes(3)           // order = 1（外层）
    .build();

// 问题：限流异常会触发重试，浪费资源

// ✅ 正确：重试在内层，限流在外层
HttpClient.builder()
    .retryTimes(3)           // order = 0（内层）
    .openRateLimit(100)      // order = 1（外层）
    .build();

// 优势：限流快速失败，重试专心应对网络抖动

资源释放

// ✅ JmsHttp 自动管理连接池，无需手动释放
// System.setProperty 已配置连接池参数：
// - http.keepAlive = true
// - http.maxConnections = 200
// - http.keepAlive.timeout = 600000

// ✅ 推荐：复用 HttpClient 实例
HttpClient client = HttpClient.builder()
    .openRateLimit(100)
    .build();

// 多次使用同一个 client
for (int i = 0; i < 100; i++) {
    HttpResponse response = client.execute(request);
}

📊 性能参考

基于实测数据：

操作	场景	耗时	说明
简单 GET 请求	本地 API	~5ms	✅ 极快
简单 GET 请求	远程 API	~50ms	✅ 很快
POST JSON	远程 API	~80ms	✅ 正常
限流检查	CAS 操作	<1ms	✅ 几乎无开销
重试机制	网络抖动	1-3 秒	✅ 指数退避

结论

JmsHttp 基于 JDK HttpURLConnection，性能优秀。装饰器带来的开销极小（<1ms），限流和重试机制有效提升了系统的稳定性和容错能力。

装饰器性能对比

装饰器	额外开销	线程安全	适用场景
HttpRateLimiter	<0.5ms	✅ CAS	控制总并发
DomainRateLimiter	<1ms	✅ CAS	按域名限流
HttpRetryer	0ms（不重试）	✅ 无状态	网络抖动
自定义装饰器	取决于实现	取决于实现	按需定制

🎯 总结

JmsHttp 的优势

✅ 易用性：Builder 模式，链式调用
✅ 灵活性：装饰器模式，自由组合
✅ 扩展性：支持自定义装饰器
✅ 稳定性：限流保护，重试容错
✅ 性能优：CAS 乐观锁，连接池优化
✅ 可控性：order 机制精确控制装饰器顺序

核心组件

组件	职责	关键特性
`HttpClient`	HTTP 客户端，执行请求	Builder 模式、装饰器管理、线程安全
`HttpRequest`	HTTP 请求封装	Builder 模式、URL/头/参数、超时配置
`HttpResponse`	HTTP 响应封装	状态码/头/体、响应时间、执行请求
`HttpDecorator`	装饰器接口	decorate 方法、order 机制、Comparable
`AbstractHttpDecorator`	装饰器抽象基类	order 字段、compareTo 实现、简化开发
`HttpRateLimiter`	全局限流器	CAS 乐观锁、活跃计数、容量查询
`DomainRateLimiter`	域名级限流器	host:port 键控、自定义限流、清理空闲
`HttpRetryer`	HTTP 重试器	指数退避、RuntimeException 重试、中断支持
`HttpException`	HTTP 异常基类	RuntimeException、三种构造方法
`HttpRequestException`	请求异常	继承 HttpException、请求阶段错误
`HttpResponseException`	响应异常	继承 HttpException、响应阶段错误

适用场景

RESTful API 调用
微服务间 HTTP 通信
第三方服务集成（支付、短信、邮件）
高并发 HTTP 请求（带限流）
不稳定网络环境（带重试）
多域名 API 调用（域名级限流）
任何需要 HTTP 请求的 Java 应用

🚀 快速上手口诀

Builder 构建请求易，装饰器来添功能
重试在内限流外，order 顺序要分明
全局限流控总量，域名限流更精细
网络抖动用重试，稳定高效没问题