上传源代码版本

.trae/documents/接口限流模块开发计划.md

@@ -0,0 +1,58 @@
+# 接口限流模块开发计划
+
+## 需求背景
+客户频繁推送历史数据，导致系统负载过高，需要开发接口限流模块限制客户端请求频率。
+
+## 技术选型
+使用成熟的`AspNetCoreRateLimit`库实现限流功能，该库支持：
+- IP地址限流
+- 客户端ID限流
+- 全局限流
+- 自定义限流规则
+- 可配置的限流阈值
+- 支持内存存储和分布式存储
+
+## 实现步骤
+
+### 0. 前置说明：Nginx反向代理场景支持
+应用层完全可以实现限流，针对Nginx反向代理场景：
+- 需要配置Nginx转发客户端真实IP（添加`X-Forwarded-For`和`X-Real-IP`请求头）
+- 应用层配置`ForwardedHeaders`中间件，读取真实客户端IP进行限流
+- 限流规则依然可以基于真实IP生效，不受反向代理影响
+
+### 1. 安装NuGet包
+安装`AspNetCoreRateLimit`和`Microsoft.AspNetCore.HttpOverrides` NuGet包到CONTROLLER项目
+
+### 2. 配置限流规则
+在`appsettings.json`中添加限流配置：
+- 支持按IP限流，默认限制每分钟60次请求
+- 支持针对特定IP白名单/黑名单
+- 支持针对特定接口设置不同的限流规则
+- 限流响应返回429 Too Many Requests状态码，包含重试时间提示
+
+### 3. 注册服务与代理配置
+在`Program.cs`中添加相关配置：
+- 配置`ForwardedHeaders`中间件，支持读取Nginx转发的真实客户端IP
+- 注册内存缓存（已存在，可复用）
+- 注册IP限流配置，指定从`X-Forwarded-For`头读取客户端IP
+- 注册限流策略
+
+### 4. 配置中间件
+在`Program.cs`的中间件管道中添加限流中间件，放在路由中间件之前，控制器中间件之前
+
+### 5. 自定义限流响应（可选）
+自定义限流触发时的返回格式，与系统现有错误响应格式保持一致
+
+### 6. 测试验证
+- 模拟高频请求，验证限流是否生效
+- 验证白名单IP是否不受限流限制
+- 验证不同接口的限流规则是否正确应用
+
+### 7. 文档更新
+在配置文档中说明限流相关配置项的含义和修改方法
+
+## 预期效果
+- 恶意高频请求被拦截，返回429状态码
+- 正常用户请求不受影响
+- 限流阈值可通过配置文件灵活调整，无需重新发布
+- 系统负载显著降低