用途:在多个 API 端点之间统一响应契约,提升一致性与开发者体验。适合后端团队在 API 数量增多、响应格式混乱时进行规范化改造。
主要能力:审计现有 API 并记录不一致点;定义统一响应信封(success、data、error、meta);标准化分页(page/limit/total/total_pages/has_next/has_prev 及游标分页);定义错误分类(ErrorCode)与错误码到 HTTP 状态码的映射;提供 Express 响应与错误规范化中间件;提供共享 TypeScript 接口与 ApiResponseBuilder 工具类;给出 URL/Header 版本策略;提供 OpenAPI 契约文档示例;规划五阶段渐进式迁移计划。
使用方式:按核心工作流先审计、再定义标准、创建共享类型、构建中间件、编写 OpenAPI 文档、执行迁移。中间件通过包裹 res.json 自动规范化成功响应,错误中间件按映射设置状态码。版本中间件可为路由设置 apiVersion。迁移分阶段进行,先并行部署、再弃用通知、双格式支持、切换默认、最终移除旧格式。
限制:资料未提供具体安装命令、依赖版本、支持的框架范围、许可与收费信息;示例基于 Express 与 TypeScript,其他技术栈需自行适配。