后端能力复用模块接口约束规范文档

后端能力复用模块接口约束规范文档一、接口设计原则（一）标准化统一。接口命名需遵循小写字母开头，单词间使用下划线分隔的规范，如getUserInfo。各模块接口版本号统一采用主版本号.次版本号.修订号格式，主版本号重大变更时需同步更新接口文档，次版本号新增功能不改变原有接口，修订号修复bug不改变接口行为。1.接口命名规范接口名称需使用动宾结构，动词表示操作类型，宾语表示操作对象，如listUsers表示获取用户列表。禁止使用缩写，特殊业务场景可使用业务术语，但需保持全篇统一，如orderConfirm表示订单确认。2.版本管理规范接口版本号变更需遵循语义化版本控制，主版本号变更需通知所有依赖方，次版本号变更允许向后兼容，修订号变更禁止破坏性修改。版本号通过HTTP头X-API-Version传递，默认值为1.0.0。3.请求参数规范查询参数使用GET方法传递，表单参数使用POST方法传递，JSON数据使用PUT/PATCH方法传递。参数命名需使用驼峰命名法，首字母大写，如userId。参数类型需严格限制，字符串参数必须使用双引号，日期参数统一使用ISO8601格式。二、数据传输约束（二）格式标准化。数据传输必须使用UTF-8编码，JSON格式必须符合RFC7159标准，日期格式必须使用ISO8601标准。所有接口响应必须包含Content-Type头部，值统一为application/json。1.JSON数据规范对象属性必须使用双引号，数组元素必须使用逗号分隔，嵌套对象需保持层级一致，如{"userId":"1001","userInfo":{"name":"张三","createTime":"2023-01-01T08:00:00Z"}}2.日期时间规范所有日期时间参数必须使用ISO8601格式，时区统一使用UTC，如"2023-12-31T23:59:59Z"。本地时间需注明时区，如"2023-12-31T16:00:00+08:00"。3.字符串规范所有字符串参数必须使用UTF-8编码，禁止使用ISO-8859-1等过时编码。特殊字符需进行转义，如"\"转义为\\"。中文参数必须使用双字节UTF-8编码。三、接口安全约束（三）权限控制规范。所有接口必须实现身份验证，使用JWT或OAuth2.0协议，有效期不超过24小时。敏感接口需增加二次验证，如短信验证码或动态口令。1.身份验证机制JWT令牌必须包含alg字段（HS256或RS256算法），exp字段（过期时间），sub字段（用户标识）。令牌通过Authorization头部传递，格式为"Bearer{token}"。2.权限控制策略使用RBAC模型控制访问权限，每个接口必须定义最小权限原则，如获取用户信息的接口只能访问当前用户数据。权限判断通过中间件实现，拒绝访问时返回403状态码。3.敏感操作保护敏感操作必须增加二次验证，如修改密码需验证旧密码，删除数据需二次确认。二次验证通过POST方法传递验证码，验证码有效期30分钟。四、异常处理规范（四）错误响应规范。所有接口必须返回标准JSON格式错误响应，包含code、message、timestamp、traceId字段。系统级错误使用5xx状态码，业务级错误使用4xx状态码。1.错误码体系错误码必须使用6位数字，前两位表示错误类型（01系统错误，02业务错误），后四位表示具体错误。如010001表示身份验证失败，020100表示参数校验错误。2.错误响应格式{"code":"010001","message":"身份验证失败","timestamp":"2023-07-01T12:00:00Z","traceId":"a1b2c3d4-e5f6-7890-g1h2-i3j4k5l6m7n8"}3.异常处理流程500内部错误必须记录完整堆栈信息，并返回通用错误提示。4xx业务错误需提供具体解决建议，如"缺少参数：userId"。五、性能约束标准（五）性能指标规范。所有接口必须满足P99响应时间小于500ms，并发能力不低于1000qps。慢查询接口需添加监控告警，超过阈值自动降级。1.响应时间标准使用Prometheus+Grafana监控系统响应时间，P95指标不得高于200ms，P99指标不得高于500ms。慢查询接口需添加缓存层，如Redis。2.并发能力标准接口并发能力测试必须使用JMeter或k6工具，测试环境需模拟生产负载。高并发接口需使用限流降级策略，如令牌桶算法。3.资源使用标准所有接口必须限制内存使用量不超过500MB，CPU使用率不超过70%。资源使用超标时需触发熔断机制，返回503服务不可用。六、文档维护规范（六）文档更新机制。接口文档必须与代码同步更新，使用Swagger或OpenAPI自动生成。每次变更需通过CodeReview流程，并通知相关方。1.文档生成规范使用Swagger3.0规范定义接口，包含paths、parameters、responses、requestBody等元素。文档必须包含示例请求和响应，如{"paths":{"/users/{userId}":{"get":{"summary":"获取用户信息","parameters":[{"name":"userId","in":"path","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"成功响应","content":{"application/json":{"schema":{"$ref":"/components/schemas/UserInfo"}}}}}}}}}2.文档更新流程接口变更必须先更新文档，再提交代码。使用GitLab或Jir