用途：为 REST API 设计提供框架无关的模式参考，覆盖端点设计、错误响应、分页、版本控制与整体 API 结构。
主要能力：资源命名（集合用复数名词、多词资源用小写连字符、嵌套最多两层、过滤排序分页用查询参数、动词仅用于非 CRUD 动作）；路径版本控制（/api/v1/users、/api/v2/users，不放在请求头或查询参数中）；RFC 7807 Problem Details 错误格式（type、status、title、detail、instance、traceId）；基于游标的分页（limit、cursor、nextCursor、hasMore，多取一条判断 hasMore）；过滤与排序（sort 用 - 前缀表示降序）；HTTP 状态码约定；响应信封仅在分页等需要元数据时使用；时间戳统一用 ISO 8601 UTC；幂等性通过 Idempotency-Key 请求头实现。
使用方式：先检查所属包与现有实现，复用项目已有的类型、辅助函数、错误、生命周期行为与测试工具。上述模式是可选方案而非实现清单，仅在当前任务需要时引入。内部迁移时保留现有 API 契约；仅当任务明确变更公共 API 时，才应用版本控制、分页、错误格式、状态码与幂等性指导。
适用场景：设计或显式变更公共 REST API 时，如新增端点、调整响应结构、引入分页或版本。
限制：不将 REST 偏好扩展为无关的迁移范围；内部工作应保留当前路由、载荷、错误、状态码、分页与幂等行为。详细错误处理示例见 references/error-responses.md。