uhaiin.com

阿里巴巴 Java 代码规范（即《阿里巴巴 Java 开发手册》）是一套由阿里巴巴集团总结并发布的 Java 编程最佳实践，旨在提升代码质量、可读性、可维护性和团队协作效率。该规范已被广泛应用于国内众多企业和开发团队，并被集成到 IDE 工具中（如 Alibaba Java Coding Guidelines 插件）。

以下是该规范的核心内容分类目录，适合作为技术分享的结构：

阿里巴巴 Java 代码规范

1. 编程规约

• 命名风格
  • 类名使用 UpperCamelCase（大驼峰）
  • 方法名、参数名、变量名使用 lowerCamelCase（小驼峰）
  • 常量名全部大写，用下划线分隔
  • 杜绝使用 l、O 等易混淆字母命名变量
  • 包名统一使用小写字母，单数形式
• 常量定义
  • 不允许出现魔法值（如直接写 3600、”UTF-8”）
  • 常量必须定义在 constant 类或枚举中
  • 使用 BigDecimal 处理金额时，必须通过字符串构造
• 代码格式
  • 大括号使用 大括号换行（K&R 风格）
  • 方法参数过长时，换行对齐
  • 每行不超过 120 个字符
  • 空行与缩进规范，提升可读性
• OOP 规约（面向对象）
  • 避免用 Object 的 equals 直接比较 null
  • 覆盖 equals 时必须覆盖 hashCode
  • 使用 Optional 时避免过度嵌套或用于方法参数/返回值泛滥
  • 接口方法默认不加 public（接口方法天然 public）
• 集合处理
  • 初始化集合时指定初始容量，避免频繁扩容
  • 使用 isEmpty() 而非 size() == 0 判断集合为空
  • 不要在 foreach 循环中进行元素增删操作
  • 使用 Comparator 链式调用排序（Java 8+）
• 并发处理
  • 禁止使用 Executors 创建线程池，推荐使用 ThreadPoolExecutor 显式创建
  • 必须使用 ThreadLocal 时，注意 remove() 防止内存泄漏
  • 高并发场景下注意 SimpleDateFormat 的线程安全问题，推荐使用 DateTimeFormatter
• 控制语句
  • if/else、for、while 等必须使用大括号
  • switch 必须有 default 分支
  • 避免多层嵌套，控制圈复杂度
• 注释规约
  • 类、方法必须有 Javadoc 注释
  • 方法注释需说明用途、参数、返回值、异常
  • 注释与代码同步更新，禁止无意义注释
• 异常处理
  • 不要捕获异常后“吞掉”不处理
  • 不要用异常控制流程（如用 catch 做条件判断）
  • 自定义异常应继承 RuntimeException，并命名以 Exception 结尾
  • finally 块中不允许使用 return
• 日志规约
  • 使用 SLF4J 门面 + Logback 实现，禁止直接使用 System.out 或 printStackTrace
  • 日志输出禁止拼接字符串，使用占位符 {}
    示例：logger.info("User {} logged in at {}", userId, time);
  • 生产环境禁止输出 debug 级别日志
  • 异常日志必须记录完整堆栈

2. 异常日志

• 错误码统一定义规范
• 日志文件滚动策略与敏感信息脱敏
• 异常分层处理：DAO、Service、Controller 各层异常职责
• 使用 MDC 实现链路追踪上下文记录

3. 单元测试

• 测试类命名：XXXTest，与被测类同名加后缀
• 测试方法命名建议：方法名_场景_预期结果，如 saveUser_nullName_throwException
• 单元测试必须遵循 AIR 原则：Automatic（自动化）、Independent（独立运行）、Repeatable（可重复）
• 禁止使用 System.out 验证测试结果，必须使用 assert
• 测试数据准备应可重复执行，避免依赖外部状态

4. 安全规约

• 防止 SQL 注入：禁止字符串拼接 SQL，优先使用预编译（PreparedStatement）或 MyBatis 参数化
• 防止 XSS、CSRF 攻击（结合 Spring Security）
• 敏感数据加密存储（如密码、身份证号）
• 不要在日志中打印密钥、密码等敏感信息

5. 数据库规约

• 建表必须有创建时间和 修改时间等 时间字段
• 禁止使用 select *，必须明确指定字段
• IN 操作的集合元素数不超过 1000
• 字段必须有注释，命名使用小写字母+下划线（如 user_id）
• 合理使用索引，避免在索引字段上做函数运算
• 分页查询注意性能，避免深分页

6. 工程结构

• 分层命名规范：controller、service、dao、dto、vo、entity 等
• 接口与实现分离，使用 ServiceImpl 命名实现类
• 二方库变更必须通知所有依赖方
• 应用分层领域模型规范（DO、DTO、BO、VO 等的使用场景）

7. 设计规约（设计模式与架构）

• 优先使用组合而非继承
• 类成员访问控制“最小化”
• 避免一个类承担过多职责（SRP 原则）
• 推荐使用工厂模式、策略模式解耦业务逻辑
• 高并发场景下避免使用 BigDecimal(double) 构造方法

8. IDE 辅助与插件实践

• 安装 Alibaba Java Coding Guidelines 插件（IntelliJ IDEA / Eclipse）
• 开发中实时扫描违规代码
• 代码提交前进行规范检查（可集成到 CI 流程）

9. 实战案例对比

• 展示“不规范代码” vs “规范后代码”
• 典型问题分析：如空指针、线程安全、日志泄露、异常处理不当
• 结合 SonarLint / Checkstyle 实现自动化检测

10. 总结与建议

• 规范不是约束，而是质量保障
• 团队统一规范，提升协作效率
• 持续集成中加入代码规范检查（如 Git Hook + 插件扫描）
• 推荐阅读：《阿里巴巴 Java 开发手册》最新版（如黄山版、龙井版等