互联网行业研发部开发人员代码编写手册

互联网行业研发部开发人员代码编写手册互联网行业研发部开发人员代码编写手册文档说明目的：统一研发团队编码规范、提升代码可读性、可维护性、降低线上缺陷、便于代码评审、交接与问题排查；适用范围：研发部所有后端、前端、移动端、测试开发、运维开发人员；适用语言：Java/Go/Python/JavaScript/TypeScript/SQL（可根据团队业务自行增删）；基本原则：可读性优先、简洁克制、防御性编程、可测试、敬畏线上；优先级：安全>正确性>可读性>性能>代码简洁；补充规则：语言特有规范优先对应语言官方规范，本手册为通用强制基线。一、通用编码总则（所有开发强制遵守）1.1命名规范见名知意，禁止拼音缩写、无意义变量名

❌a、b、temp、data、info、xx、sjh、userxx

✅userOrderList、paymentStatus、cancelOrderTime禁止中英文混合命名，禁止中文命名；常量：全大写下划线分隔MAX_RETRY_COUNT；布尔变量建议使用is/has/can前缀：isDeleted、hasPermission、canSubmit；循环临时变量：短循环可用i,j，多层嵌套禁止；超过3行循环必须使用业务名称。数据库表/字段：小写+下划线，禁止驼峰。1.2注释规范注释是解释「为什么」，不要重复描述代码做了什么

❌//查询用户列表

✅//兼容老版本未迁移历史数据，仅查询未逻辑删除用户类、公共对外接口必须编写文档注释：入参含义、返回值、异常场景、业务约束；复杂算法、特殊业务规则、临时兼容方案、线上hack代码必须增加注释，并标注待清理时间；禁止保留大量注释掉的废弃代码（提交前删除，历史版本可通过Git追溯）；关键业务分支、异常捕获点增加注释；单纯if/else不需要冗余注释。1.3格式与排版统一缩进：4空格或2空格（团队统一，不可混用），禁止Tab；单行长度建议：不超过120字符，超长及时换行；运算符前后保留空格；大括号统一风格：左大括号不换行；代码块之间使用空行分隔逻辑块，不要密集堆砌；禁止无意义多余空行、连续3行及以上空行。1.4控制语句规范禁止多层嵌套（if嵌套建议不超过3层，超过优先重构、抽取方法）；优先卫语句（提前return/continue），减少深层if嵌套；if/for/while即使只有一行代码，必须加大括号；禁止复杂超长条件表达式，可抽取为布尔变量；switch/if分支尽量覆盖全部场景，处理default/else兜底逻辑。1.5常量与魔法值严禁代码中直接写魔法数字、魔法字符串（0、1、2、"success"、"fail"）；业务状态、错误码、渠道值、超时时间统一抽取常量；环境配置、超时、限流阈值等优先放入配置中心/配置文件，不硬编码。1.6异常处理通用规则禁止空捕获catch{}，吃掉异常不打印日志；捕获异常必须打印完整堆栈日志，重要异常附加业务上下文（订单号、用户ID）；区分业务异常与系统异常，不要统一捕获Exception掩盖未知错误；不随意吞异常，无法处理的异常向上抛出或清晰告警；不要用异常做正常业务流程控制（不要try-catch代替if判断）。1.7日志规范（重中之重）日志分级：TRACE<DEBUG<INFO<WARN<ERROR；线上环境默认关闭DEBUG，核心链路合理使用INFO；ERROR日志：业务失败、系统异常、调用外部报错；每条日志尽量携带链路标识：traceId、userId、orderId等关键上下文；禁止日志打印明文密码、验证码、身份证、银行卡等敏感信息；避免高频循环打印大量日志，防止磁盘打满；日志内容清晰，便于告警、检索、定位故障。1.8安全编码强制要求所有外部输入（http参数、mq消息、前端传参）不可信任，必须校验；防SQL注入、XSS、命令注入；参数禁止直接拼接SQL；敏感数据传输、存储遵循加密规范；接口返回做好字段脱敏；权限校验不能只依赖前端，后端接口必须二次鉴权；接口增加参数长度、范围校验，避免超大参数引发OOM；禁止代码硬编码密钥、账号密码、accessKey；所有密钥使用配置中心保管。1.9并发与资源规范IO流、数据库连接、Redis连接、文件句柄必须关闭，使用try-with-resources/finally；异步线程、定时任务合理设置线程池，禁止无限创建线程；锁粒度尽量小，避免死锁；不在锁内执行耗时网络调用；循环内不频繁创建销毁连接、不频繁查询数据库；外部接口调用必须设置超时时间，杜绝无限阻塞。二、后端开发专项规范（Java/Go/Python）2.1分层规范（通用DDD/三层架构）Controller→Service→Dao/MapperController：只做参数接收、参数校验、组装返回、统一异常处理；禁止业务逻辑；Service：核心业务逻辑、事务控制、跨DAO调用；Dao/Mapper：仅数据库操作，不包含业务判断；禁止跨层调用：Controller不能直接调用Mapper；DTO（入参出参）、BO（业务对象）、DO（数据库实体）严格分层，不要直接返回数据库DO给前端。2.2数据库编码规范SQL禁止select*，明确需要查询字段；大表禁止无索引查询、禁止orderby无索引、禁止like%xxx前缀模糊查询；批量操作慎用in，in集合数量建议控制在1000以内；事务范围尽可能小，避免长事务；禁止在循环中执行单条SQL（优先批量insert/update）；更新语句必须携带条件，防止全表更新；分页查询必须强制参数校验，限制最大页大小，防止深度分页。2.3接口与外部调用调用第三方HTTP、RPC、MQ、缓存做好超时、重试、熔断降级；重试增加间隔，避免风暴；幂等接口才可重试；远程调用结果做空判断，防止空指针；定义统一返回结构体，统一错误码体系。三、前端开发专项规范（JS/TS/Vue/React）优先使用TypeScript，强制类型定义；组件职责单一，超大组件拆分为子组件；禁止在模板中写复杂计算，使用computed/工具函数；接口请求统一封装，统一拦截错误、统一loading、统一报错提示；避免频繁DOM操作，合理使用防抖、节流；敏感信息不存储在localStorage；常量统一管理，接口地址统一配置；异步请求统一trycatch，处理网络异常；禁止使用var，统一使用const/let。四、Git代码提交规范分支规范：main/master：线上稳定分支，禁止直接提交；develop：开发主干；feature/xxx：需求分支；hotfix/xxx：线上紧急修复；CommitMessage规范：

[类型]简要描述|工单号

类型：feat新功能/fix缺陷/refactor重构/docs文档/test测试/optimize优化

示例：[fix]修复订单支付状态同步异常|TICKET-1234一次提交只完成一件事，不要混合多个需求、多个bug；提交前执行：代码格式化、静态检查、自测；禁止提交密钥、本地配置、日志文件、IDE配置、编译产物。五、自测与交付要求代码合并MR/PR前必须完成：静态代码检查（Lint、Sonar、语法检查）无新增高危问题；正常流程、异常流程、边界条件自测；并发、空参数、极端参数场景验证；SQL语句执行计划检查；日志、异常分支验证；无硬编码密钥、无敏感信息输出；删除调试代码（console、print、临时测试代码）。六、禁止行为（红线清单，代码评审直接打回）直接复制网上代码未经校验直接上线；提交临时调试代码、sleep、强制开关、测试后门；不做参数校验直接落库、直接执行SQL；捕获异常不打印日志，发生故障无法排查；循环内频繁访问数据库、Redis；长事务、无超时的外部调用；魔法值泛滥、命名混乱、完全无注释