# cloud-platform-http-limiter **Repository Path**: chenqian1995/cloud-platform-http-limiter ## Basic Information - **Project Name**: cloud-platform-http-limiter - **Description**: No description available - **Primary Language**: Unknown - **License**: Not specified - **Default Branch**: master - **Homepage**: None - **GVP Project**: No ## Statistics - **Stars**: 1 - **Forks**: 0 - **Created**: 2026-04-09 - **Last Updated**: 2026-04-11 ## Categories & Tags **Categories**: Uncategorized **Tags**: None ## README # Cloud Platform HTTP Limiter [![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT) [![Java](https://img.shields.io/badge/Java-8+-blue.svg)](https://openjdk.java.net/) [![Maven Central](https://img.shields.io/badge/Maven-1.0.0-orange.svg)](https://search.maven.org/) **Java 通用 HTTP 限流请求工具类** > 用于业务侧提交 HTTP 请求任务，严格按自定义频率限流调度，异步排队执行，防止高频压垮第三方接口 ## ✨ 特性 - 🚀 **无侵入** - 纯 Java 实现，无业务耦合，可直接集成复用 - 🎯 **高通用** - 支持任意 HTTP 方法、请求头、请求体格式 - 📊 **灵活限流** - 支持 QPS 限流和分钟级限流，可运行时动态调整 - 🔄 **异步调度** - 线程安全队列 + 线程池，异步非阻塞执行 - 📬 **回调通知** - 提供异步回调接口，返回每个任务执行结果 - 🔁 **失败重试** - 支持配置重试次数和间隔，自动重试失败任务 - 🛡️ **线程安全** - 全链路线程安全设计，支持高并发提交 ## 📦 快速开始 ### 1. Maven 依赖 ```xml com.cloud.platform cloud-platform-http-limiter 1.0.0 ``` ### 2. 初始化配置 ```java import com.cloud.platform.limiter.*; // 创建限流配置（每秒 5 次请求） RateConfig config = RateConfig.builder() .mode(RateConfig.RateMode.QPS) // 限流模式：QPS .rate(5) // 每秒 5 次 .timeoutMs(30000) // 超时 30 秒 .retryTimes(3) // 失败重试 3 次 .retryIntervalMs(1000) // 重试间隔 1 秒 .corePoolSize(5) // 核心线程数 5 .maxPoolSize(20) // 最大线程数 20 .queueCapacity(10000) // 队列容量 10000 .build(); // 初始化调度器（单例） HttpRateLimiter limiter = HttpRateLimiter.init(config); // 注册回调（可选） limiter.setCallback(new TaskCallback() { @Override public void onCompleted(TaskResult result) { if (result.isSuccess()) { System.out.println("✅ 任务成功：" + result.getTaskId() + ", 状态码：" + result.getStatusCode() + ", 耗时：" + result.getCostMs() + "ms"); } else { System.out.println("❌ 任务失败：" + result.getTaskId() + ", 错误：" + result.getErrorMessage()); } } }); // 启动调度器 limiter.start(); ``` ### 3. 提交任务 #### 单任务提交 ```java // GET 请求 RequestTask getTask = RequestTask.builder() .url("https://api.example.com/data") .method("GET") .headers(Collections.singletonMap("Authorization", "Bearer token123")) .build(); String taskId = limiter.submitTask(getTask); System.out.println("任务已提交：" + taskId); ``` ```java // POST 请求（JSON 格式） RequestTask postTask = RequestTask.builder() .url("https://api.example.com/users") .method("POST") .headers(Collections.singletonMap("Content-Type", "application/json")) .bodyType(RequestTask.BodyType.JSON) .bodyString("{\"name\":\"张三\",\"age\":25}") .build(); limiter.submitTask(postTask); ``` #### 批量任务提交 ```java List tasks = new ArrayList<>(); for (int i = 0; i < 100; i++) { RequestTask task = RequestTask.builder() .taskId("batch-" + i) // 自定义任务 ID .url("https://api.example.com/data/" + i) .method("GET") .build(); tasks.add(task); } List taskIds = limiter.submitBatchTask(tasks); System.out.println("批量提交成功：" + taskIds); ``` ### 4. 查看统计 ```java HttpRateLimiter.Stats stats = limiter.getStats(); System.out.println("统计信息：" + stats); // 输出：Stats{提交=100, 完成=98, 失败=2, 队列=0, 活跃线程=3, 线程池队列=0} ``` ### 5. 动态调整限流 ```java // 从每秒 5 次调整为每秒 10 次 RateConfig newConfig = RateConfig.builder() .mode(RateConfig.RateMode.QPS) .rate(10) .timeoutMs(30000) .build(); limiter.updateRate(newConfig); ``` ### 6. 优雅关闭 ```java // 应用退出前关闭 limiter.shutdown(); ``` ## 📖 详细文档 - **[原理详解](docs/PRINCIPLE.md)** - 完整的架构设计、令牌桶算法原理、线程模型 - **[使用示例](src/test/java/com/cloud/platform/limiter/HttpRateLimiterDemo.java)** - 完整的使用演示 - **[限流测试](src/test/java/com/cloud/platform/limiter/RateLimitTest.java)** - 限流效果验证 ### 限流模式 #### QPS 限流（每秒请求数） ```java RateConfig config = RateConfig.builder() .mode(RateConfig.RateMode.QPS) .rate(5) // 每秒 5 次 .build(); ``` 适用于：需要严格控制每秒请求数的场景，如第三方 API 调用限制。 #### 分钟级限流 ```java RateConfig config = RateConfig.builder() .mode(RateConfig.RateMode.PER_MINUTE) .rate(100) // 每分钟 100 次 .build(); ``` 适用于：分钟级别总量控制的场景，如邮件发送、短信通知等。 ### 请求体类型支持多种请求体格式： ```java // JSON 格式 RequestTask.builder() .bodyType(RequestTask.BodyType.JSON) .bodyString("{\"key\":\"value\"}") .build(); // 表单格式 RequestTask.builder() .bodyType(RequestTask.BodyType.FORM) .bodyString("name=张三&age=25") .build(); // 原始字符串 RequestTask.builder() .bodyType(RequestTask.BodyType.RAW) .bodyString("纯文本内容") .build(); // 字节流 RequestTask.builder() .bodyType(RequestTask.BodyType.BYTES) .bodyBytes(new byte[]{...}) .build(); // 无请求体 RequestTask.builder() .bodyType(RequestTask.BodyType.NONE) .build(); ``` ### 自定义超时和重试支持为每个任务单独配置超时和重试： ```java RequestTask task = RequestTask.builder() .url("https://api.example.com/slow-api") .timeoutMs(60000) // 单独配置 60 秒超时 .retryTimes(5) // 单独配置重试 5 次 .retryIntervalMs(2000) // 单独配置重试间隔 2 秒 .build(); ``` ### 回调接口完整回调示例： ```java limiter.setCallback(new TaskCallback() { @Override public void onCompleted(TaskResult result) { // 任务完成（成功或失败都会调用） log.info("任务完成：{}", result); } @Override public void onFailed(TaskResult result) { // 任务失败（可选实现） log.error("任务失败：{}", result.getErrorMessage()); } @Override public void onRetry(String taskId, int retryCount, String errorMsg) { // 任务重试（可选实现） log.warn("任务重试：{}, 第{}次，错误：{}", taskId, retryCount, errorMsg); } }); ``` ### 队列控制 ```java // 清空队列（丢弃所有待执行任务） limiter.clearQueue(); // 暂停调度（停止产生令牌） limiter.pause(); // 恢复调度（重新开始产生令牌） limiter.resume(); ``` ## 🎯 使用场景 ### 1. 控制突发流量（推荐） **场景**：初始允许快速通过一批请求，后续严格限流 ```java // 初始允许 10 个请求快速通过，后续每秒 5 个 RateConfig config = RateConfig.builder() .mode(RateConfig.RateMode.QPS) .rate(5) // 每秒 5 个令牌 .build(); // 启动时会自动填充初始令牌（最多 10 个） // - 前 1 秒：快速消耗完 10 个初始令牌，10 个请求全部通过 // - 后续时间：每秒仅能通过 5 个请求 // - 限流效果：将请求频率从 10 次/秒降低到 5 次/秒，降幅 50% ``` ### 2. 突发 + 低频限流 **场景**：第一秒快速通过 10 个请求，后续每 2 秒 1 个请求 ```java // 第一秒 10 个突发，后续每 2 秒 1 个（0.5 QPS） RateConfig config = RateConfig.builder() .mode(RateConfig.RateMode.QPS) .rate(0.5) // 每秒 0.5 个令牌 = 每 2 秒 1 个 .build(); // 限流效果： // - 前 1 秒：快速消耗完 10 个初始令牌，10 个请求全部通过 // - 后续时间：每 2 秒仅能通过 1 个请求 // - 限流效果：将请求频率从 10 次/秒降低到 0.5 次/秒，降幅 95% ``` **支持的小数 rate 示例：** ```java rate(0.5) // 每 2 秒 1 个请求 rate(0.2) // 每 5 秒 1 个请求 rate(0.1) // 每 10 秒 1 个请求 rate(0.01) // 每 100 秒 1 个请求 ``` **原理**： - 启动时填充 `min(rate, 100)` 个初始令牌 - 支持初始突发，快速处理积压请求 - 后续按配置的速率平滑限流 ### 2. 严格限流（无突发） **场景**：需要严格控制每秒请求数，不允许突发 ```java // 每秒严格限制 2 次请求，无突发 RateConfig config = RateConfig.builder() .mode(RateConfig.RateMode.QPS) .rate(2) .build(); HttpRateLimiter limiter = HttpRateLimiter.init(config); limiter.start(); // 不立即提交任务，等待 1 秒让令牌桶稳定 Thread.sleep(1000); // 现在提交任务，严格按每秒 2 次的速度执行 ``` ### 3. 第三方 API 调用限流 ```java // 某第三方 API 限制每秒最多 10 次调用 RateConfig config = RateConfig.builder() .mode(RateConfig.RateMode.QPS) .rate(10) .build(); HttpRateLimiter limiter = HttpRateLimiter.init(config); limiter.start(); // 提交 1000 个请求，会自动按每秒 10 次的速度执行 for (int i = 0; i < 1000; i++) { RequestTask task = RequestTask.builder() .url("https://third-party-api.com/data/" + i) .method("GET") .build(); limiter.submitTask(task); } ``` ### 2. 邮件/短信批量发送 ```java // 每分钟最多发送 100 条短信 RateConfig config = RateConfig.builder() .mode(RateConfig.RateMode.PER_MINUTE) .rate(100) .build(); // 提交发送任务 List tasks = new ArrayList<>(); for (String phone : phoneList) { RequestTask task = RequestTask.builder() .url("https://sms-api.com/send") .method("POST") .bodyType(RequestTask.BodyType.JSON) .bodyString("{\"phone\":\"" + phone + "\",\"content\":\"验证码：123456\"}") .build(); tasks.add(task); } limiter.submitBatchTask(tasks); ``` ### 3. 数据同步任务 ```java // 从外部系统同步数据，控制请求频率 limiter.setCallback(new TaskCallback() { @Override public void onCompleted(TaskResult result) { if (result.isSuccess()) { // 解析响应，存入数据库 String data = result.getResponseBody(); saveToDatabase(data); } else { // 记录失败，后续人工处理 logError(result); } } }); ``` ## 🔧 配置说明 ### RateConfig 参数详解 | 参数 | 类型 | 默认值 | 说明 | |------|------|--------|------| | `mode` | RateMode | QPS | 限流模式（QPS/PER_MINUTE） | | `rate` | long | 1 | 限流值（每秒/每分钟请求数） | | `timeoutMs` | long | 30000 | 请求超时时间（毫秒） | | `retryTimes` | int | 3 | 失败重试次数 | | `retryIntervalMs` | long | 1000 | 重试间隔（毫秒） | | `corePoolSize` | int | 5 | 线程池核心线程数 | | `maxPoolSize` | int | 20 | 线程池最大线程数 | | `queueCapacity` | int | 10000 | 任务队列容量（0 表示无界） | ### TaskResult 字段说明 | 字段 | 类型 | 说明 | |------|------|------| | `taskId` | String | 任务 ID | | `success` | boolean | 是否成功 | | `statusCode` | int | HTTP 状态码 | | `responseBody` | String | 响应内容 | | `responseHeaders` | Map | 响应头 | | `errorMessage` | String | 错误信息 | | `exceptionType` | String | 异常类型 | | `retryCount` | int | 重试次数 | | `costMs` | long | 执行耗时（毫秒） | | `attachment` | Object | 附加数据 | ## ⚠️ 注意事项 1. **单例模式** - `HttpRateLimiter` 是单例，全局只需要一个实例 2. **启动顺序** - 必须先 `init()` 初始化，再 `start()` 启动，最后 `submitTask()` 提交任务 3. **优雅关闭** - 应用退出前调用 `shutdown()`，确保任务执行完成 4. **队列容量** - 队列满时提交任务会抛出 `RejectedExecutionException` 5. **线程安全** - 所有方法都是线程安全的，可多线程并发调用 ## 📝 许可证 MIT License © 2024 chenqian1995 ## 🤝 贡献欢迎提交 Issue 和 Pull Request！ ## 📧 联系方式 - Email: chenqian1995@163.com - Gitee: https://gitee.com/chenqian1995