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

后端开发代码编写规范手册一、总则规范（一）适用范围。本手册适用于公司所有后端开发人员，涵盖代码编写、版本控制、测试部署等全生命周期环节。（二）基本原则。代码质量应遵循高效性、可读性、可维护性、安全性四大原则，确保系统稳定运行。二、命名规范（一）类命名规则。采用驼峰命名法，首字母大写，如UserInfo、OrderService。（二）方法命名规则。采用小写字母加下划线分隔，如getUserInfo、calculateTotalPrice。（三）变量命名规则。局部变量使用小写字母加下划线，如user_id、total_amount。（四）常量命名规则。全大写字母加下划线，如MAX_TIMEOUT、DEFAULT_PAGE_SIZE。三、代码结构规范（一）文件组织。每个模块独立成文件，文件名与模块名保持一致，如User模块使用user_module.py。（二）包结构。遵循分层设计，标准结构为：base（基础层）domain（领域层）service（服务层）controller（控制层）。（三）代码布局。方法内逻辑超过20行需添加分隔符，使用四个空格缩进，每行长度不超过120字符。四、编程规范（一）注释规范。类方法上方必须添加功能说明，关键业务逻辑处添加行内注释。（二）异常处理。使用try-catch结构捕获异常，自定义异常需继承BaseException，如BusinessException。（三）数据库操作。禁止在业务方法中直接写SQL，使用ORM框架或DAO模式封装数据访问。（四）API设计。RESTful风格统一使用GET/POST/PUT/DELETE动词，参数命名保持一致。五、安全规范（一）输入验证。所有外部输入必须进行非空、长度、格式校验，使用参数化查询防止SQL注入。（二）权限控制。核心接口需添加RBAC校验，使用@Auth注解标记敏感操作。（三）加密处理。密码存储使用bcrypt加密，HTTPS传输必须配置HSTS头。（四）日志规范。关键操作必须记录操作人、时间、IP等信息，使用结构化日志格式。六、版本控制规范（一）提交信息。遵循ConventionalCommits规范，如"feat:添加用户登录功能"。（二）分支管理。主分支维护生产代码，开发分支进行功能开发，使用PullRequest流程。（三）代码审查。每个提交必须通过SonarQube扫描，至少两位成员CodeReview。七、测试规范（一）单元测试。使用JUnit/PyTest等框架，测试覆盖率不低于80%，核心模块达到100%。（二）集成测试。编写Mock测试环境，模拟第三方接口调用。（三）性能测试。接口响应时间控制在200ms内，高并发场景QPS不低于预期值。八、部署规范（一）环境管理。区分开发、测试、生产环境，使用配置中心统一管理参数。（二）发布流程。执行Docker容器化部署，使用Jenkins自动化构建。（三）回滚机制。每次发布必须配置金丝雀发布，保留30天历史版本。九、文档规范（一）接口文档。使用Swagger自动生成，包含请求参数、响应示例、错误码说明。（二）设计文档。核心模块需提供时序图、状态机图，使用PlantUML绘制。（三）维护文档。记录重构历史、技术债清单，定期评审优化方案。十、附则说明（一）本规范自发布之日起生效，由技术部负责解释和修订。（二）各团队需制定符合本规范的实施细则，定期开展代码评审。（三）违反本规范导致系统故障的，将按《技术责任制度》追究相关责任。（四）本规范将根据技术发展动态调整，每年至少更新一次。（五）所有开发人员必须参加规范培训考核，合格后方可参与核心项目开发。（六）代码评审结果将纳入绩效考核体系，作为晋升的重要参考依据。（七）鼓励使用静态代码分析工具，SonarQube报告必须通过才能合并分支。（八）禁止在代码