后端服务开发技术规范实施细则

后端服务开发技术规范实施细则一、通用开发规范（一）编码标准。采用UTF-8编码，文件名使用小写字母加中划线连接，如api-user-service.java。变量命名遵循驼峰式，类名首字母大写，方法名首字母小写。代码缩进统一使用4个空格，行宽控制在100字符以内。禁止使用魔法数字，必须定义常量替代，如TIMEOUT_30MIN=30000。（二）版本控制。必须使用Git进行代码管理，分支命名规范为：feature/模块名-功能描述，如feature/user-api-add-login。提交信息必须包含英文单数动词，如add,fix,remove，并附带简要原因。强制要求每周进行一次代码合并，合并冲突必须由项目负责人解决。（三）日志规范。所有核心业务操作必须记录日志，日志级别分为ERROR,WARN,INFO,DEBUG,TRACE。ERROR级别需包含完整堆栈信息，WARN级别需记录业务上下文，INFO级别记录操作结果。禁止在生产环境输出DEBUG及以上级别日志。日志格式采用JSON结构，包含时间戳、用户ID、操作类型、结果码等字段。二、接口设计规范（一）接口命名。RESTful风格接口命名必须使用名词或名词短语，如getUserProfile,createOrder。禁止使用动词或动宾结构。接口版本号统一放在路径中，如/v1/users。（二）参数校验。所有入参必须进行非空校验，数字类型必须校验范围，日期格式必须验证有效性。校验失败时必须返回400状态码，并附带错误码和提示信息。禁止在参数校验中抛出异常，统一使用Result对象封装响应。（三）数据传输。JSON传输时必须指定字符集，如application/json;charset=UTF-8。复杂对象必须使用DTO（DataTransferObject）传输，禁止直接传输POJO（PlainOldJavaObject）。响应头必须包含Content-Type和Cache-Control，如Cache-Control:no-cache。三、数据库交互规范（一）SQL编写。禁止使用SELECT*语句，必须明确指定字段。禁止使用动态SQL拼接，所有SQL必须使用预编译语句。复杂查询必须使用WITH语句优化，禁止在WHERE条件中使用函数。（二）事务管理。所有涉及多表更新的操作必须使用事务控制，事务隔离级别统一设置为READCOMMITTED。禁止在同一个事务中执行跨模块操作，必须通过消息队列解耦。事务超时时间统一设置为3秒。（三）索引设计。所有查询字段必须建立索引，索引命名格式为模块_字段_类型，如user_id_idx。禁止使用函数索引，复合索引字段顺序必须根据查询频率排序。索引维护必须定期执行，每月分析一次表空间。四、安全防护规范（一）认证授权。必须使用JWT（JSONWebToken）进行身份认证，Token有效期统一设置为24小时。权限控制必须使用RBAC（Role-BasedAccessControl）模型，禁止越权访问。API接口必须配置速率限制，如每个用户每分钟不超过1000次请求。（二）防攻击措施。所有接口必须开启XSS（跨站脚本）过滤，参数必须进行转义处理。禁止使用eval等危险函数，所有JSON解析必须使用官方库。必须配置OWASPTop10防护，如SQL注入、CSRF（跨站请求伪造）拦截。（三）敏感数据加密。用户密码必须使用bcrypt算法加盐存储，加密强度不低于12位。支付信息、身份证等敏感数据必须使用AES-256加密，密钥必须分离存储。所有敏感数据传输必须使用HTTPS协议。五、性能优化规范（一）缓存策略。核心数据必须使用Redis缓存，缓存失效时间统一设置为1小时。缓存穿透必须使用布隆过滤器，缓存击穿必须使用互斥锁。缓存更新必须使用发布订阅模式，禁止覆盖旧数据。（二）异步处理。所有耗时操作必须使用消息队列，如RabbitMQ或Kafka。队列消息必须设置TTL（TimeToLive），过期时间为5分钟。异步任务必须使用补偿机制，失败时必须重试3次。（三）性能监控。必须使用Prometheus监控系统性能，指标包括QPS（每秒查询率）、Latency（延迟）、ErrorRate（错误率）。关键接口必须设置告警阈值，如ErrorRate超过2%必须立即通知负责人。性能压测必须每月进行一次，模拟峰值流量测试。六、运维部署规范（一）环境管理。开发、测试、生产环境必须分离，禁止交叉使用。环境变量必须使用配置中心管理，如Apollo或Nacos。所有变更必须经过CodeReview，禁止直接提交到生产环境。（二）部署流程。必须使用CI/CD（持续集成/持续部署）工具，如Jenkins或GitLabCI。部署必须执行三步验证：测试环境验证、灰度发布、全量发布。每次部署必须记录日志，包含时间、操作人、版本号、操作结果。（三）应急响应。所有服务必须配置熔断器，如Hystrix或Sentinel。服务降级必须设置自动触发条件，如并发量超过1000必须降级。故障恢复必须制定预案，包括手动切换、自动恢复、数据回滚等方案。七、附则说明本规范自发