Java微服务网关接口定义规范

Java微服务网关接口定义规范一、接口命名规范（一）统一性原则。接口命名必须遵循全小写字母，单词之间使用下划线分隔的规范，例如user_login、product_search。各微服务接口命名需保持一致性，避免因命名混乱导致调用冲突。1.命名规则必须符合驼峰命名法反写形式，首字母始终为小写2.接口名称需直接反映功能用途，避免使用抽象词汇3.系统预留命名空间包括api_、service_、action_等前缀，禁止擅自扩展4.新增接口需在接口设计评审阶段完成命名标准化审核（二）版本控制要求。接口命名需包含版本号标识，采用"接口名_版本号"的格式，例如user_login_v1。版本号采用语义化版本控制规则，主版本号（Major）重大变更时必须更新接口定义，次版本号（Minor）允许添加新功能而不破坏兼容性，修订号（Patch）用于修复bug。1.主版本号变更必须同步更新网关路由配置2.版本号变更需在API文档中明确标注变更日志3.禁止通过修改接口参数实现版本兼容4.接口废弃时需采用"接口名_deprecated_vX"的命名方式二、请求参数规范（一）参数类型约束。所有接口参数必须使用Java标准数据类型，禁止使用自定义类型或枚举类型作为参数值，参数值转换由网关统一处理。1.整型参数必须使用Integer类型，禁止Long类型2.字符串参数必须使用String类型，禁止使用字符数组3.日期参数统一使用ISO8601格式，禁止使用LocalDate等不可见格式4.数组参数必须使用List类型，禁止使用数组类型（二）参数校验规则。所有入参必须实施强制性校验，校验规则包括：1.必填参数校验，空值时返回400错误2.长度校验，字符串参数设置最大长度限制3.格式校验，邮箱、手机号等特殊格式参数必须验证格式4.范围校验，数值参数设置最小值和最大值5.正则校验，特殊格式参数使用正则表达式验证（三）参数顺序要求。参数声明顺序必须与API文档中展示的顺序完全一致，参数分组时保持业务逻辑的连贯性，例如先声明用户标识参数，再声明权限参数。三、响应格式规范（一）统一响应结构。所有接口必须返回JSON格式响应，结构如下：{"code":200,"message":"操作成功","data":{//业务数据}}1.状态码code必须使用整型，200表示成功，4xx表示客户端错误，5xx表示服务端错误2.消息内容message必须使用简体中文，长度不超过100字符3.数据对象data为业务数据，空数据时返回null而非空集合（二）错误码规范。系统定义的错误码必须符合以下规则：1.错误码为三位数字，前缀与业务领域相关，例如1001表示用户认证失败2.错误码必须保持全局唯一性，通过错误码字典管理3.错误码与消息内容必须保持一一对应关系4.错误码需提供中文和英文双语说明（三）数据封装规则。业务数据封装必须遵循：1.对象属性命名使用驼峰命名法2.数组类型数据必须使用List封装3.嵌套对象使用驼峰命名法反写作为属性名4.日期类型统一使用ISO8601格式四、安全规范（一）认证机制要求。所有接口必须实施认证，认证方式包括：1.JWT令牌认证，令牌有效期不超过24小时2.OAuth2.0授权码模式，刷新令牌有效期72小时3.API密钥认证，密钥有效期不超过90天4.双因素认证，短信验证码或动态口令（二）权限控制规则。权限控制必须遵循最小权限原则：1.角色权限控制，通过角色ID关联权限点2.资源权限控制，接口URL必须包含资源标识3.操作权限控制，请求方法必须与操作类型匹配4.权限校验必须放在认证之后、业务逻辑之前（三）加密传输要求。所有接口必须使用HTTPS协议，要求包括：1.TLS1.2以上版本加密2.HSTS头部配置，有效期至少6个月3.客户端证书校验，要求客户端提供证书4.传输数据必须使用JWT或OAuth2.0加密五、性能规范（一）响应时间要求。接口响应时间必须满足：1.95%请求响应时间不超过200毫秒2.P95请求响应时间不超过500毫秒3.长查询接口必须设置超时时间，默认30秒4.异步接口必须提供异步查询入口（二）并发控制规则。并发控制措施包括：1.请求频率限制，每个用户每分钟不超过1000次2.负载均衡配置，使用轮询或加权轮询算法3.缓存配置，热点数据必须配置缓存4.限流策略，使用令牌桶算法控制并发（三）资源使用约束。系统资源使用必须符合：1.内存使用率不超过70%2.CPU使用率不超过50%3.连接数不超过1000个4.磁盘空间剩余量不低于20%六、异常处理规范（一）异常分类标准。系统异常分为：1.校验异常，参数校验失败抛出2.业务异常，业务逻辑错误抛出3.系统异常，系统内部错误抛出4.安全异常，安全验证失败抛出（二）异常处理流程。异常处理必须遵循：1.全局异常处理器捕获所有异常2.异常信息必须包含错误码和详细描述3.系统异常必须记录日志并通知运维4.业务异常必须提供解决方案建议（三）异常响应规范。异常响应必须符合：1.400错误响应校验异常2.401错误响应认证异常3.403错误响应权限异常4.500错误响应系统异常5.503错误响应服务不可用七、文档规范（一）文档更新要求。接口文档必须同步更新：1.接口变更时同步更新API文档2.文档更新必须经过技术负责人审核3.文档版本与API版本保持一致4.文档必须包含测试用例（二）文档内容标准。文档必须包含：1.接口描述，说明接口用途和业务场景2.请求参数，详细说明参数名称、类型、必填、示例3.响应数据，详细说明返回字段和示例4.错误码，提供错误码和错误说明（三）文档维护责任。文档维护责任分配：1.前端团队负责接口调用文档2.后端团队负责接口定义文档3.产品团队负责业务需求文档4.文档更新必须通过代码审查流程八、实施要求（一）开发规范。接口开发必须遵循：1.接口开发必须使用SpringCloudGateway框架2.接口类必须使用Interface注解标记3.接口方法必须使用RestController注解4.参数校验必须使用Validation注解（二）测试规范。接口测试必须包括：1.单元测试覆盖率不低于80%2.集成测试使用Postman进行3.性能测试使用JMeter进行4.安全测试使用OWASPZAP进行（三）部署规范。接口部署必须符合：1.部署前必须进行代码扫描2.部署流程必须使用CI/CD工具3.部署后必须进行接口验证4.环境隔离要求，开发、测试、生产环境必须分离九、附则本规范自发布之日起实施，所有现有接口必须按照本规范进行迁移。接口