后端微服务统一接口定义规范

后端微服务统一接口定义规范一、总则（一）目的明确。为规范后端微服务接口定义，提升系统交互效率，本规范旨在统一接口设计标准，确保各服务间数据交互的一致性与可靠性。（二）适用范围。本规范适用于公司所有新建及改扩建微服务项目的接口设计，涵盖RESTful风格API、RPC调用及消息队列等交互方式。二、接口命名规范（一）层级结构。接口命名需遵循"模块+业务+动作"三级结构，如"order/createOrder"。各层级间用中划线分隔，首字母大写。（二）命名规则。模块名称采用领域驱动设计（DDD）术语，业务名称需体现核心功能，动作名称使用动词或动词短语。示例："user/getUserInfo"表示获取用户信息接口。三、请求参数标准（一）参数类型。所有接口参数必须使用JSON格式传递，禁止使用application/x-www-form-urlencoded。基本类型参数需明确指定数据格式，如int32、string等。（二）参数校验。必须实现参数非空校验，对特殊字符、长度、范围等需在服务端进行二次校验。校验失败时需返回400错误码及具体错误信息。四、响应格式标准（一）状态码规范。成功响应必须使用200状态码，错误响应需使用4xx或5xx系列状态码。各状态码需有明确语义定义，如403表示权限不足。（二）数据结构。响应体必须包含code、message、data三级结构。data字段为实际业务数据，需使用数组或对象形式返回。示例：```json{"code":200,"message":"操作成功","data":{"id":123,"name":"张三"}}```五、版本控制策略（一）版本号格式。接口版本号必须位于URL路径中，格式为"/v{版本号}/模块/业务"。当前版本为"/v1/"，新增版本需按语义化版本管理。（二）变更流程。版本升级必须遵循"向下兼容"原则，重大变更需通过技术委员会审批。变更后需在接口文档中标注版本变更说明。六、安全设计要求（一）认证机制。所有接口必须实现JWT认证，请求头需包含Authorization字段。服务端需校验token有效性，无效时返回401错误。（二）权限控制。需实现基于角色的访问控制（RBAC），接口需标注requiredRoles属性，服务端需校验用户角色匹配。示例：```yamlpaths:/order/createOrder:post:tags:security:parameters:in:bodyrequired:trueschema:type:objectresponses:200:description:创建订单成功```七、性能要求标准（一）响应时间。核心接口响应时间必须控制在200ms以内，边缘接口不超过500ms。需在服务端实现请求耗时监控。（二）并发能力。接口需支持至少100qps并发请求，高并发场景需进行压力测试并优化。服务端需配置合理的超时时间。八、异常处理规范（一）错误码体系。必须使用公司统一错误码标准，错误码需保持全局唯一。示例：10001表示参数校验失败，10002表示权限不足。（二）异常响应。异常响应必须包含错误码、错误信息、请求ID等字段。服务端异常需捕获并封装为标准错误格式返回。九、接口文档要求（一）文档模板。必须使用Swagger/OpenAPI规范编写接口文档，文档需包含接口描述、参数说明、响应示例等要素。（二）更新机制。接口文档需与代码实现同步更新，开发完成3日内必须完成文档录入。技术委员会定期抽查文档准确性。十、实施与监督（一）责任分工。各业务线技术负责人为本规范执行第一责任人，需组织团队进行规范培训。架构组负责技术指导与监督。（二）考核机制。将接口规范执行情况纳入技术考核指标，每季度进行一次全面检查。不符合规范的开发任务不予评审通过。十一、附则（一