用途
本技能提供一套后端 API 开发方法论,用于在项目中按统一规范设计、实现和检查 API 接口,覆盖契约管理、接口设计、请求验证、错误处理、安全、分层架构、日志与性能等环节。
主要能力
- API 契约管理:实现前须阅读 architecture.md §5(API 设计),获取 API 规范(RESTful/GraphQL)、接口列表(方法、路径、描述、认证要求)、请求/响应格式约定与错误码规范;端点方法、路径、参数需与契约一致,偏离须在输出报告中标注原因;请求/响应类型导出到共享文件供前端引用。
- RESTful 设计:给出列表、详情、创建、更新、删除的标准方法与路径(如 GET /api/users、GET /api/users/:id、POST /api/users 等),统一成功响应(success/data/message)与错误响应(success/error.code/message/details)结构,以及分页请求参数与分页响应格式。
- 请求验证:分路由层(路径与查询参数)、中间件层(请求体格式与必填字段)、Service 层(业务规则)三层;文档以 Zod 为例演示 CreateUserSchema 及在路由处理器中的验证与错误返回。常见规则包括必填、类型检查、格式验证、范围限制和业务规则。
- 错误处理:列出验证错误 400、认证错误 401、权限错误 403、资源不存在 404、冲突 409、服务器错误 500 及对应错误码,并给出统一错误处理中间件示例。
- 安全实现:JWT 生成与验证中间件、基于角色的访问控制(RBAC)的 requireRole 中间件、输入消毒(SQL 注入、XSS、CSRF、文件上传校验)以及 express-rate-limit 速率限制示例。
- 分层架构:Controller 层处理 HTTP 请求响应、Service 层封装业务逻辑(如邮箱唯一性检查、抛出 NotFoundError/ConflictError)、Repository 层负责数据库操作。
- 日志记录:ERROR/WARN/INFO/DEBUG 级别及 winston 配置与使用示例。
- 性能优化:数据库索引、避免 N+1、JOIN 替代多次查询、分页;Redis 缓存读取与 setex 过期写入;连接池大小配置与释放。
- 检查清单:实现前阅读契约、确认格式与认证方案、探索现有代码模式;实现后核对端点一致性、请求验证、统一错误处理、认证授权、TDD(先有失败测试并验证 RED)、单元/集成/E2E 测试、日志与 Lint。
使用方式
按文档流程在实现 API 前先阅读 architecture.md §5 并对齐契约,编码时套用统一响应/错误结构与分层职责,按检查清单逐项核对。文档中的代码示例(Zod、JWT、express-rate-limit、winston、ioredis 等)可直接参考,但需结合项目实际技术栈。
适用场景
适用于需要按规范构建后端接口、统一错误与响应格式、补充认证授权与请求验证、进行 API 代码审查或为前后端协作导出类型的开发场景。
限制
文档以 TypeScript/Express 及部分常见库为例,未提供其他语言或框架的实现;未说明收费、价格、平台支持范围或效果数据,暂未提供。