REST 资源命名与错误结构统一实践（2025）

REST 资源命名与错误结构统一实践（2025）统一的资源命名与错误结构是 API 可用性的基础。一、资源命名名词复数：`/users`、`/orders`；避免动词化路径。层级关系：`/users/{id}/orders` 表示归属关系。过滤与排序：使用查询参数，如 `?status=active&sort=created_at`。二、状态码与方法方法语义：GET/POST/PUT/PATCH/DELETE 按语义使用。状态码：2xx 成功、4xx 客户端错误、5xx 服务端错误。三、错误结构统一结构：`code`、`message`、`details`、`traceId`。本地化与可追溯：保留 `traceId` 以支持追踪与审计。四、分页与一致性分页：cursor 优先，返回 `next_cursor` 与 `limit`。一致性：字段命名与大小写统一；时间使用 ISO8601。注意事项关键词、分类与描述与正文一致；规范与术语为通用与可验证实践。与契约文档与网关策略协同统一。