云原生微服务后端开发规范

云原生微服务后端开发规范一、架构设计原则（一）高内聚。各微服务应聚焦核心业务能力，服务内部紧密耦合，对外接口简洁清晰。接口设计需遵循单一职责原则，每个接口功能限定在单一业务场景内。服务拆分应基于业务边界，避免技术驱动导致的过度拆分。服务粒度需适中，过粗导致调用链过长，过细则增加运维复杂度。设计阶段需绘制服务依赖图，明确服务间调用关系，标注调用频率、数据交互量等关键指标。（二）低耦合。服务间交互采用轻量级协议，优先使用RESTfulAPI或gRPC，避免直接依赖数据库或缓存。服务间依赖关系需通过API网关统一管理，实现服务发现、负载均衡、熔断降级等能力。设计阶段需建立服务契约，采用OpenAPI规范定义接口，通过契约测试工具确保接口一致性。服务版本管理需遵循语义化版本控制，兼容性变更需提前发布通知依赖方。二、接口开发规范（一）参数校验。所有入参必须进行严格校验，包括类型、长度、格式、范围等。校验逻辑应在服务层统一处理，避免分散在业务代码中。异常处理需标准化，校验失败时返回统一错误码和错误信息，错误信息应包含字段名、错误类型等详细信息。参数默认值需在接口文档中明确说明，避免客户端猜测默认行为。（二）响应规范。响应数据结构应统一，包含状态码、消息体、时间戳等通用字段。业务数据需封装在标准对象中，字段命名遵循驼峰命名法，首字母大写。响应头设置需规范，必须设置Content-Type为application/json，建议设置Cache-Control、X-Request-Id等关键头。错误响应需包含错误码、错误消息、建议操作等字段，便于客户端调试。三、数据管理规范（一）数据库设计。表名命名需遵循小写下划线规范，如user_info。字段命名采用驼峰命名法，首字母大写。主键设计优先使用UUID，避免自增ID跨机房冲突。索引设计需基于查询频率，复合索引字段顺序需根据查询占比确定。数据库连接需使用连接池，配置合理的最大连接数、最小空闲数等参数。（二）事务管理。跨服务调用必须使用分布式事务，优先采用2PC或TCC模式。事务边界划分需清晰，每个服务只处理自身业务范围的事务。事务补偿需设计幂等操作，避免重复执行导致数据不一致。事务日志需异步写入，保证系统高可用时业务数据不丢失。设计阶段需编写事务依赖图，标注所有事务依赖关系。四、安全防护规范（一）认证授权。所有接口必须进行身份认证，优先采用JWT或OAuth2.0协议。认证流程需在网关层统一处理，避免服务间传递Token。权限控制采用RBAC模型，角色权限需通过中间表关联，避免硬编码权限。敏感操作需进行二次验证，如短信验证码、动态口令等。（二）防攻击设计。接口需限制调用频率，超过阈值时返回429错误。参数校验需防范SQL注入、XSS攻击等常见风险。传输过程必须使用HTTPS，所有密钥需通过KMS管理。日志系统需记录所有请求参数、响应结果、异常信息，便于安全审计。设计阶段需进行渗透测试，发现漏洞及时修复。五、运维监控规范（一）日志规范。日志格式需统一，包含时间戳、服务名、请求ID、请求方法、响应码等字段。日志级别分为DEBUG、INFO、WARN、ERROR，生产环境默认INFO。日志存储采用分布式日志系统，配置合理的保留周期。关键业务操作需添加业务日志，便于问题排查。（二）监控指标。核心指标包括QPS、响应时间、错误率、资源利用率等。监控告警需分级分类，设置合理的阈值，避免告警风暴。监控数据需接入Prometheus等时序数据库，保留至少7天数据。设计阶段需绘制监控拓扑图，明确各组件监控指标和采集方式。六、部署发布规范（一）版本管理。代码版本采用Git，分支策略遵循Gitflow模型。主分支必须冻结，所有发布需通过Feature分支合并。版本号遵循语义化规范，如v1.2.3。构建流程需自动化，配置Nexus等私有仓库管理依赖。（二）发布流程。发布前必须进行全量测试，包括单元测试、集成测试、压力测试。发布过程需使用蓝绿部署或金丝雀发布，优先采用滚动更新。发布操作必须通过Jenkins等CI工具执行，避免人工操作。发布后需验证业务功能，确认数据一致性。七、附则说明本规范适用于所有云原生微服务后端开发项目，自发布之日起实施。各开发团队需指定接口人负