后端研发代码编写规范手册

后端研发代码编写规范手册一、总则（一）适用范围。本手册适用于公司所有后端研发人员，涵盖代码编写、版本控制、测试验证等全生命周期环节。（二）基本原则。代码编写应遵循规范统一、高效可维护、安全可靠的原则，确保系统整体质量。（三）责任主体。研发人员需对本职责范围内的代码质量负全责，项目经理对项目整体代码规范执行监督。二、命名规范（一）模块命名。采用小写字母加下划线方式，如user_management_module。（二）类命名。使用驼峰式命名法，首字母大写，如UserManager。（三）方法命名。小写字母加下划线，如get_user_info。（四）变量命名。局部变量用小写字母加下划线，如total_count；全局变量首字母大写，如MAX_TIMEOUT。（五）常量命名。全大写字母加下划线，如API_TIMEOUT_3000。三、代码结构（一）文件组织。每个功能模块独立文件，文件名与模块名一致，禁止超过200行代码的单一文件。（二）包结构。采用分层架构，如com/company/project/module/submodule。（三）代码布局。类定义与接口定义各占一行，方法之间空一行，参数与返回值之间空一格。（四）注释规范。类头部必须包含作者、创建日期、功能描述；方法头部注明参数说明、返回值说明；关键逻辑处添加行内注释。四、编程规范（一）数据类型。优先使用基本类型而非包装类，如使用int而非Integer；集合类优先使用泛型，如List<String>。（二）异常处理。捕获具体异常而非Exception，如捕获SQLException而非Exception；业务异常需自定义并继承RuntimeException。（三）条件判断。禁止连续if，使用elseif或switch；多条件判断用逻辑与而非嵌套，如if（a>0&&a<100）。（四）循环结构。for循环明确迭代变量初始化、条件、步进；while循环确保终止条件，避免死循环。（五）并发处理。使用ThreadLocal替代synchronized；锁降级优先可重入锁而非全局锁；线程池使用固定大小避免资源耗尽。（六）API设计。RESTful风格统一资源路径；参数验证必须完整，如密码需前端加密传输；响应码遵循HTTP标准。五、版本控制（一）提交规范。每次提交必须包含清晰描述，如"Fix:用户登录接口超时问题"；分支命名遵循origin/feature/module格式。（二）代码审查。核心模块必须通过CodeReview，审查人需在JIRA系统记录意见；代码合并前必须通过SonarQube扫描。（三）冲突处理。分支合并前必须确保无冲突；冲突解决需提交补丁并说明原因。（四）历史追溯。禁止直接修改历史提交，必须创建新提交覆盖；重要变更需标注版本号。六、测试规范（一）单元测试。测试覆盖率不低于80%，使用JUnit框架；每个public方法必须对应测试用例。（二）集成测试。接口调用需模拟真实环境，使用Mockito框架；测试数据必须与生产环境类型一致。（三）性能测试。核心接口响应时间控制在500ms内；并发测试需模拟至少1000用户量。（四）回归测试。新功能上线前必须执行完整回归测试，使用自动化脚本执行。七、部署规范（一）环境管理。开发环境使用Docker容器；测试环境与生产环境配置差异必须文档化。（二）发布流程。发布前必须执行全链路压测；灰度发布比例不超过30%，监控异常需自动回滚。（三）日志规范。所有业务操作必须记录日志，日志级别分为INFO/WARN/ERROR；敏感信息禁止明文记录。（四）备份策略。数据库备份每日执行，文件系统备份每周执行；备份文件存储需异地存储。八、安全规范（一）输入验证。所有用户输入必须过滤特殊字符；SQL查询必须使用预编译语句。（二）权限控制。使用RBAC模型；敏感操作必须二次验证；API密钥有效期不超过90天。（三）加密传输。HTTPS协议必须使用TLS1.2以上版本；JWT令牌有效期不超过24小时。（四）漏洞扫描。每月执行安全扫描，高危漏洞必须7日内修复；禁止使用已知高危组件。九、文档规范（一）设计文档。接口文档使用Swagger格式；数据库表结构必须包含注释。（二）运维文档。异常监控方案必须明确阈值；应急处理流程需包含联系人。（三）更新日志。每次版本变更必须记录，包括新增功能、修复问题、已知缺陷。（四）知识沉淀。技术方案必须存档，重要决策需会议纪要佐证。十、附则（一）考核机制。代码规范执行情况纳入绩效考核，占比不低于10%；季度抽查不合格需