用途:为 REST API 设计提供与框架无关的规范与模式,适用于设计端点、错误响应、分页、版本控制或整体 API 结构时参考。
主要能力: 资源命名:集合用复数名词(/users),多词资源用小写连字符(/ledger-accounts),嵌套最多两层,过滤/排序/分页用查询参数,动词仅用于不适合 CRUD 的动作(activate、publish、send)。 版本控制:在 URL 路径中版本化(/api/v1/users、/api/v2/users),不使用请求头或查询参数。 错误响应:采用 RFC 7807 Problem Details,字段含 type、status、title、detail、instance、traceId;提供 AppError 基类及 NotFoundError、ConflictError、ServiceUnavailableError 等具体错误类型。 分页:推荐游标分页,请求参数 limit、cursor,响应含 items、nextCursor、hasMore;实现时多取一条判断 hasMore。相比 offset 更稳定、性能更好、无重复遗漏。 过滤与排序:查询参数实现,排序用 - 前缀表示降序。 HTTP 状态码:200、201、204、400、401、403、404、409、422、429、500、503 等按语义使用。 响应封装:简单 CRUD 直接返回资源,分页时才使用封装。 时间戳:统一 ISO 8601 UTC 格式,使用 toISOString()。 幂等性:非幂等操作(POST、PATCH)使用 Idempotency-Key 请求头,先查已存在记录再创建。
使用方式:作为设计参考与代码模式指南,示例使用 Fastify 与 Drizzle 风格查询,但原则与框架无关。
限制:资料未提供安装命令、收费信息、平台支持范围或具体效果数据。