rate-limit

使用 Upstash 进行速率限制

速率限制是滥用防护和成本控制的一层。接入中间件之前，先设计好策略。

工作流

1. 检查 Next.js／运行时／版本、部署的代理／CDN、身份验证／API 密钥模型、已安装的 Upstash 版本、受保护的路由、操作成本、现有配额，以及中间件／代理是否已处理请求。
2. 为每类路由定义策略表：标识符、算法／时间窗口／突发限制、成本权重、用户层级、响应行为和存储故障时的行为。只有在无法推断威胁／成本权衡时才提问。
3. 优先使用经过身份验证的用户、API 密钥或租户+用户标识符。仅对匿名流量使用 IP，且只能使用部署环境提供的可信来源。绝不信任来自公共互联网的任意 x-forwarded-for；配置可信代理层级／平台标头。不要将未知客户端都归为 127.0.0.1。
4. 按环境和路由／策略设置命名空间。除非有意使用不同的密钥实施分层限制，否则不要对同一个请求同时应用全局中间件和单路由限流器。
5. 配置明确的 Upstash 超时和日志／指标。按端点选择故障时的行为：
   • 低风险的可用性路径可选择故障时放行，并降低遥测级别；
   • 身份验证、高成本生成或易受滥用影响的路径可使用本地紧急限流、排队、额度预留，或故障时拒绝并返回明确的临时响应。
6. 返回 429，并带有非负的 Retry-After 和一致的速率限制标头。在适用时，也为成功响应添加标头。故障放行降级期间，不要发送具有误导性的零限制值。
7. 对于加权任务，根据服务器计算的批次／操作成本消耗令牌。必要时，将速率限制与请求体大小限制、并发控制、幂等性、预算／额度以及提供商配额结合使用。
8. 如果 SDK 提供待处理的 Promise，请使用运行时的 waitUntil 机制，确保分析数据同步等异步工作继续执行。

验证

尽可能使用带有隔离密钥前缀以及可控时钟／时间窗口的确定性测试。测试允许／阻止／重置行为、路由隔离、已验证身份和匿名密钥、伪造的转发标头、付费／免费策略、并发、加权请求、存储超时／故障行为，以及重复中间件的规避情况。运行仓库的 lint／类型／测试／构建流程；仅在启用 Upstash 分析功能时检查相关数据。

输出

报告策略表、标识符信任模型、已更改的文件／环境变量名称、故障时的行为、响应标头、分层控制、自动化测试证据，以及尚待完成的 Upstash／部署配置。