SuperAPI AI 工具集

backend/api-development

编程与开发

查看项目

更新于 11-14 16:54

技能介绍

用途

本技能提供一套后端 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 及部分常见库为例,未提供其他语言或框架的实现;未说明收费、价格、平台支持范围或效果数据,暂未提供。