后端代码开发规范手册

后端代码开发规范手册一、通用原则（一）适用范围。本规范适用于公司所有后端开发项目，包括但不限于Web应用、微服务、API接口等。（二）核心要求。确保代码质量、可维护性、安全性、性能达标，符合行业最佳实践。（三）版本控制。所有代码必须通过Git进行版本管理，遵循统一的分支策略。二、命名规范（一）项目命名。采用小写字母加中划线方式，如user-management-system。（二）模块命名。使用名词或名词短语，如order-service、payment-api。（三）类命名。遵循驼峰命名法，首字母大写，如UserRepository。（四）方法命名。使用动词或动宾短语，如calculateTotalPrice、fetchUserDetails。（五）变量命名。使用小写字母加下划线，如user_id、status_code。（六）常量命名。全大写字母加下划线，如MAX_TIMEOUT_30。三、代码结构（一）文件组织。每个模块独立文件夹，包含主类文件、接口文件、实体类、工具类等。（二）目录层级。根目录下设置config、entity、dao、service、controller、utils等标准目录。（三）包结构。采用分层包结构，如com/company/project/module/submodule。（四）代码长度。单个方法不超过50行，类文件不超过200行，超过需拆分。（五）注释规范。类文件顶部必须包含作者、创建日期、描述性注释；方法需标注功能说明、参数含义、返回值说明。四、编码规范（一）分号使用。Java必须使用分号作为语句结束符，禁止隐式语句。（二）缩进规则。使用4个空格缩进，禁止使用tab键。（三）代码行宽。单行代码不超过120字符，超出需换行。（四）空行使用。方法内部逻辑块之间、类成员之间建议空一行。（五）导入管理。使用lombok减少重复导入，避免import语句堆积。（六）异常处理。使用try-catch结构，捕获具体异常类型而非Exception。（七）条件语句。避免else-if嵌套过深，超过3层需重构。（八）循环规范。for循环使用增强型，避免手动计数；while循环需明确终止条件。五、数据库交互（一）SQL规范。使用预编译语句，避免动态拼接SQL。（二）索引设计。主键自增，根据查询频率创建索引。（三）事务管理。明确事务边界，遵循ACID原则。（四）ORM使用。MyBatis/JPA需遵循命名规则，避免冗余映射。（五）分页处理。使用标准分页参数，如limit/offset或PageRequest。（六）数据校验。在DAO层校验数据完整性，如非空、长度限制。六、API设计（一）RESTful原则。资源命名使用名词，路径层级清晰。（二）HTTP方法。GET用于查询，POST用于创建，PUT用于更新，DELETE用于删除。（三）状态码。使用标准HTTP状态码，如200/201/400/404/500。（四）参数传递。查询参数使用问号分隔，表单参数使用x-www-form-urlencoded。（五）响应格式。统一使用JSON，错误响应包含code/message字段。（六）版本控制。通过URL路径或header传递版本号。七、安全规范（一）认证授权。使用JWT或OAuth2，遵循最小权限原则。（二）密码存储。使用bcrypt加盐存储，避免明文传输。（三）防注入。所有用户输入必须过滤，使用预编译语句。（四）XSS防护。对输出内容进行编码，使用CSP策略。（五）CSRF防护。使用CSRFtoken，禁用SameSite属性。（六）敏感信息。日志不记录敏感信息，配置文件使用加密存储。八、性能优化（一）缓存策略。使用Redis/Memcached，设置合理的过期时间。（二）数据库优化。批量操作、索引优化、查询分析。（三）异步处理。使用消息队列处理耗时任务，如RabbitMQ/Kafka。（四）负载均衡。配置Nginx/HAProxy，使用轮询或加权轮询。（五）资源限制。设置JVM堆内存、线程池大小，避免内存溢出。（六）监控指标。配置Prometheus/Grafana，监控响应时间、QPS。九、测试规范（一）单元测试。使用JUnit/Mockito，覆盖率不低于80%。（二）集成测试。模拟真实环境交互，测试接口连通性。（三）接口测试。使用Postman/JMeter，验证功能正确性。（四）异常测试。覆盖所有分支逻辑，包括空值、异常流。（五）测试数据。使用Mock数据，避免依赖外部资源。（六）测试报告。提交Jenkins报告，包含测试用例和结果。十、部署规范（一）环境划分。开发/测试/预发布/生产，使用Docker容器化。（二）构建流程。使用Maven/Gradle自动化构建，配置CI/CD。（三）日志管理。使用ELK堆栈，配置日志级别和格式。（四）回滚机制。配置金丝雀发布，支持快速回滚。（五）监控告警。配置Nagios/Zabbix，设置阈值告警。（六）备份策略。每日增量备份，每周全量备份。十一、文档规范（一）设计文档。包含架构图、接口文档、数据库设计。（二）API文档。使用Swagger自动生成，包含请求参数和响应示例。（三）部署文档。包含环境配置、启动步骤、故障排查。（四）测试文档。记录测试用例、覆盖率、问题列表。（五）变更记录。每次修改需记录时间、作者、内容。（六）知识库。沉淀常见问题解决方案，定期更新。十二、团队协作（一）代码审查。每周进行CodeReview，使用GitLab/GitHub。（二）需求管理。使用Jira/禅道，明确需求优先级。（三）任务分配。按能力分配任务，避免单点依赖。（四）沟通机制。每日站会，使用Slack/Teams沟通。（五）文档同步。使用Confluence/Wiki，实时更新文档。（六）培训计划。每月组织技术分享，提升团队水平。十三、附则（一）本规范自发布之日起实施，由技术部负责解释