后端开发技术规范

后端开发技术规范一、通用编码规范（一）代码风格。采用PascalCase命名类名，camelCase命名方法与变量，使用const定义常量。代码缩进统一为4个空格，行宽限制为100字符。禁止使用魔法数字，必须定义枚举或常量替代。注释采用Javadoc格式，类方法上方必须包含功能描述与参数说明。（二）版本控制。所有代码提交必须遵循"YYYYMMDD-简短描述"格式。分支命名采用"feature/模块名-功能描述"规范。强制要求pre-commit钩子检查代码风格与静态语法。二、数据库交互规范（一）SQL编写。禁止使用动态SQL，所有查询必须使用预编译语句。索引命名采用"表名_字段名"格式，复合索引字段顺序需经过性能分析确定。存储过程必须包含错误处理与事务管理。（二）ORM使用。禁止直接使用底层SQL构建，必须通过ORM框架封装。实体类必须实现软删除接口，关联查询必须开启懒加载优化。所有数据库操作必须记录审计日志。三、接口设计标准（一）协议选择。RESTful风格必须使用JSON格式，禁止使用XML。长连接场景必须采用WebSocket协议，心跳间隔设置为30秒。缓存接口必须实现ETag校验机制。（二）参数校验。所有入参必须进行类型、长度、格式校验，异常响应必须包含400错误码与详细错误信息。分页参数必须设置默认值与最大限制，防止越界查询。四、安全防护要求（一）认证授权。JWT令牌有效期不得超过24小时，刷新令牌必须使用HTTPS传输。权限控制必须遵循最小权限原则，角色设计采用RBAC模型。（二）防攻击措施。所有接口必须开启防SQL注入过滤，文件上传必须限制类型与大小。敏感操作必须进行二次验证，登录失败5次自动锁定账号。五、性能优化准则（一）缓存策略。一级缓存使用Redis集群，过期时间设置为300秒。二级缓存采用本地内存缓存，容量限制为500MB。缓存穿透必须使用布隆过滤器。（二）异步处理。耗时操作必须使用消息队列，最大堆积量限制为10000条。任务超时时间设置为5分钟，失败重试间隔为1分钟。六、部署运维规范（一）环境管理。开发、测试、生产环境必须使用独立配置，变量命名采用"ENV_大写模块名"格式。容器化部署必须使用DockerCompose编排，镜像层数限制为5层。（二）监控告警。所有接口必须接入Prometheus监控系统，关键指标设置告警阈值。日志收集使用ELK堆栈，慢查询阈值设置为500毫秒。七、异常处理机制（一）全局异常。必须实现统一的异常捕获类，所有未处理的异常必须记录完整堆栈信息。自定义异常必须继承标准异常类，并定义清晰的错误码体系。（二）容灾方案。核心服务必须实现多机房部署，数据同步延迟控制在2秒以内。服务熔断使用Hystrix模式，降级阈值设置为并发请求的30%。八、文档管理要求（一）代码注释。类方法上方必须包含Javadoc注释，说明功能、参数与返回值。核心算法必须添加流程图说明，复杂逻辑使用伪代码描述。（二）变更记录。每次版本发布必须提交CHANGELOG文档，包含新增功能、修复问题与已知缺陷。技术决策必须记录在Wiki页面，并标注决策人及日期。九、团队协作规范（一）代码评审。所有提交必须经过至少2人评审，评审意见必须记录在GitLabMergeRequest。代码合并必须由项目负责人批准，禁止越权操作。（二）技术分享。每月组织技术分享会，分享内容必须包含实际案例与解决方案。新人培养周期设置为3个月，必须完成至少2个核心模块的迭代。十、附则说明本规范自发布之日起生效，所有项目必