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

接口限流模块开发计划

需求背景

客户频繁推送历史数据，导致系统负载过高，需要开发接口限流模块限制客户端请求频率。

技术选型

使用成熟的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状态码
• 正常用户请求不受影响
• 限流阈值可通过配置文件灵活调整，无需重新发布
• 系统负载显著降低