本技能提供一套框架无关的 REST API 设计原则，适合在定义接口端点、错误响应、分页、版本控制与整体结构时参考。
用途：为 REST 接口建立统一、可预测的约定，减少不一致与后期改动成本。
主要能力： 一、资源命名。集合用复数名词，例如 /api/v1/users；多词资源用小写加连字符，如 /ledger-accounts；嵌套不超过两层；过滤、排序、分页走查询参数；仅在无法用 CRUD 表达时用动词，如 /users/:id/activate。 二、版本控制。版本放在 URL 路径（/api/v1/、/api/v2/），便于测试与调试。示例中按 v1Routes、v2Routes 分别注册到不同前缀。 三、错误响应。采用 RFC 7807 Problem Details，字段包括 type、status、title、detail、instance、traceId。可用 AppError 抽象基类派生 NotFoundError、ConflictError、ServiceUnavailableError 等领域错误，并提供 toResponse 生成标准结构。 四、分页。大数据集用游标分页，请求带 limit 与 cursor，响应返回 items、nextCursor、hasMore；实现时多取一条判断是否还有更多。相比 offset，游标分页更稳定、走索引、不重不漏。 五、过滤与排序。用查询参数，如 status、author；排序支持 -createdAt 表示降序、name 表示升序，可组合使用。 六、状态码。成功用 200、201、204；客户端错误用 400、401、403、404、409、422、429；服务端用 500、503。 七、响应包裹。简单 CRUD 直接返回资源，不套 success/data；分页等需要元数据时可用包裹结构。 八、时间戳统一用 ISO 8601 UTC，通过 toISOString() 序列化。 九、幂等性。对 POST、PATCH 等非幂等操作使用 Idempotency-Key 请求头，先查是否已存在相同键，存在则返回原结果，避免重试造成重复。
使用方式：在设计接口时对照上述约定；需要详细错误示例可参考 references/error-responses.md。
适用场景：新 API 设计、接口重构、团队规范制定。
限制：本文档面向框架无关原则，未绑定具体语言或框架，示例涉及 Fastify、Drizzle 风格查询仅供说明；未提供安装命令、收费信息、性能数据或具体平台支持情况。