后端服务稳定编码规范指南

后端服务稳定编码规范指南一、总则（一）适用范围。本指南适用于公司所有后端服务开发、测试、运维及代码审查等环节，涵盖但不限于API接口、业务逻辑、数据处理、系统架构等核心领域。（二）核心目标。通过标准化编码实践，提升系统可用性、可维护性，降低故障率，确保服务连续性。（三）基本原则。遵循最小权限原则、单一职责原则、高内聚低耦合原则，优先采用成熟稳定的技术方案。二、代码结构规范（一）目录层级。项目根目录下必须包含config、controller、domain、entity、exception、helper、infra、interface、service、utils等标准模块，各模块功能职责明确。（二）文件命名。类文件名使用驼峰式命名法，如UserServiceImpl；接口文件名以I前缀标识，如IUserService；配置文件使用小写字母加下划线，如perties。（三）代码组织。每个方法内部遵循“声明-处理-返回”结构，异常处理集中配置，避免try-catch滥用。服务层方法命名需体现操作语义，如getUserById而非fetchUser。三、接口设计规范（一）参数校验。所有入参必须进行非空、类型、范围校验，校验逻辑统一封装在Validation工具类中，失败时抛出自定义ValidateException。（二）响应格式。标准响应体包含code、message、data三个字段，code为5位数字错误码，如10001表示参数错误。接口版本号通过HTTP头X-API-Version传递。（三）幂等设计。对于可能产生副作用的接口，必须实现幂等机制，可通过分布式锁或请求去重表实现。四、异常处理规范（一）异常分类。系统异常分为业务异常（BusinessException）、系统异常（SystemException）、验证异常（ValidateException）三类，分别对应不同HTTP状态码。（二）异常捕获。全局异常处理器需捕获所有Checked异常，记录日志并返回统一错误格式；非Checked异常需在方法内做终极捕获，防止线程泄漏。（三）日志记录。异常信息必须包含堆栈跟踪、请求参数、用户ID等关键信息，使用结构化日志格式便于检索。五、性能优化规范（一）缓存策略。一级缓存使用Redis集群，二级缓存使用本地GuavaCache，缓存失效策略优先采用LRU，热点数据设置TTL为300秒。（二）数据库交互。禁止在循环内执行SQL，批量操作使用PreparedStatement，慢查询阈值设为1秒，SQL执行前必须开启profiling。（三）异步处理。耗时操作必须通过消息队列（Kafka）解耦，服务端采用异步接收模式，消费端保证至少一次投递。六、安全防护规范（一）权限控制。采用RBAC模型，接口权限通过@RequiresRole注解声明，操作权限通过@RequiresPermission注解声明，权限校验集中配置在Interceptor中。（二）数据脱敏。敏感字段（手机号、身份证等）在日志、响应中必须脱敏，脱敏规则统一维护在DataMask工具类中，脱敏长度固定为4位。（三）防攻击设计。限制接口调用频率（默认每分钟100次），防止SQL注入需使用预编译语句，XSS攻击通过参数编码处理。七、测试规范（一）单元测试。核心业务方法覆盖率必须达到80%，使用JUnit5编写，测试类命名格式为被测类名+Test，测试数据使用Mockito生成。（二）集成测试。数据库操作使用内存数据库H2，服务间依赖通过契约测试（SpringCloudContract）定义，测试用例需覆盖所有异常场景。（三）性能测试。接口QPS测试在压测平台JMeter执行，目标TPS达到设计值的1.5倍，响应时间P95控制在200ms以内。八、部署规范（一）容器化标准。Docker镜像构建必须使用多阶段构建，基础镜像选择alpine，运行时依赖使用LayerCaching优化，镜像大小不超过200MB。（二）发布流程。采用蓝绿部署策略，发布前必须执行SonarQube扫描，构建流水线使用JenkinsPipeline，回滚机制通过KubernetesRollback实现。（三）监控配置。Prometheus监控指标必须包含jvm、gc、db、latency等维度，Grafana面板每5分钟自动刷新，告警规则设置在Alertmanager中。九、文档规范（一）接口文档。使用Swagger3.0自动生成，每个接口必须包含请求参数、响应示例、异常说明，文档更新需触发GitLabCI重新生成。（二）设计文档。核心模块需提供时序图、状态机图，设计评审通过后存入Confluence，变更时执行CodeReview流程。（三）运维文档。编写故障排查手册，包含常见问题复现步骤、定位方法、解决方案，文档需随版本迭代同步更新。十、附则（一）审查机制。代码提交前必须通过SonarQube静态扫描，扫描失败禁止合并，审查通过需两名资深工程师签字确认。（二）版本管理。分支命名遵循git-f