API模块规范

概述

API模块规范是用于定义API接口开发标准的规范性文档，涵盖了请求校验、认证、响应格式、分页和限流等关键方面。

关键内容

1. 请求校验：
2. 使用Zod做schema校验
3. 始终校验输入数据
4. 校验失败时返回400状态码

5. 提供字段级别的错误详情

6. 认证：

7. 所有端点都需要JWT token进行认证
8. token放在Authorization header中传输
9. token有效期为24小时后过期

10. 实现refresh token机制以延长会话

11. 响应格式：

12. 成功响应包含success、data、timestamp和version字段
13. 错误响应包含success(false)、error对象和timestamp

14. 统一的JSON格式确保客户端处理的一致性

15. 分页与限流：

16. 使用基于cursor的分页而非offset分页
17. 单页最大数量限制为100，默认页大小为20

18. 限流机制：已认证用户每小时1000次，公开端点每小时100次

19. 缓存策略：

20. 使用Redis做会话缓存
21. 默认缓存时长为5分钟
22. 写操作时失效缓存以保证数据一致性

来源

• directory-api-CLAUDE — API模块规范

相关

• Zod — uses
• JWT — uses
• Redis — uses
• 请求校验 — extends
• 认证机制 — extends
• 分页 — extends