# Alibaba Java Coding Guidelines 摘要

## 1. 文档定位

本文记录后端 Java 代码生成和人工开发时需要默认遵守的 Alibaba Java Coding Guidelines 摘要。

本文是可跨项目复用的工程规范，不替代项目自身的后端分层、业务边界、安全规范和接口契约要求。实际编码时优先级为：

1. 当前项目 `AGENTS.md`
2. 当前项目后端开发规范
3. 本文 Java 代码规范摘要
4. Spring Boot / Java 社区通用习惯

## 2. 命名规范

- 类名使用 `UpperCamelCase`。
- 方法名、参数名、局部变量名和成员变量名使用 `lowerCamelCase`。
- 常量使用 `UPPER_SNAKE_CASE`。
- 包名全小写，避免下划线、大写和无意义缩写。
- 抽象类建议使用 `Abstract` 或 `Base` 开头。
- 异常类以 `Exception` 结尾。
- 测试类以 `Test` 结尾。
- 不使用拼音、无意义缩写或随意缩写。

## 3. 代码格式

- `if`、`for`、`while` 即使只有一行也必须使用 `{}`。
- 复杂表达式应拆分为有业务含义的局部变量或私有方法。
- 避免过深嵌套，优先使用提前返回、拆分方法或明确的业务分支。
- 不写魔法值，业务代码、状态码、固定字符串和数字阈值应抽为常量或枚举。
- 单个类、方法和代码块应保持职责聚焦，避免把多个业务概念揉在一起。

## 4. 对象与类型

- DTO、Entity、领域对象、VO / Response 和外部系统 DTO 必须分离。
- `equals` 和 `hashCode` 需要成对重写。
- `BigDecimal` 数值比较优先使用 `compareTo`，避免用 `equals` 判断数值相等。
- 金额、汇率和数量等精确值不使用浮点类型表达。
- Boolean 字段命名要避免和序列化框架产生歧义。
- 工具类应禁止实例化。

## 5. 集合与空值

- 集合初始化时，能预估容量就指定容量。
- 遍历 `Map` 时优先使用 `entrySet`。
- 不在增强 `for` 循环中直接删除集合元素。
- 注意 `Arrays.asList` 返回的列表不支持普通结构修改。
- 注意 `subList` 与原集合存在关联关系。
- 方法返回集合时优先返回空集合，不返回 `null`。
- 对外部输入、第三方返回和可空字段做明确空值处理。

## 6. 并发规范

- 不随意直接创建线程。
- 线程池参数必须明确，包括核心线程数、最大线程数、队列、拒绝策略和线程名。
- 共享变量必须考虑线程安全和可见性。
- 锁粒度要小，避免死锁和长事务持锁。
- `ThreadLocal` 使用后必须清理。

## 7. 异常与日志

- 不吞异常。
- 不使用异常控制正常业务流程。
- 捕获异常后要么完成明确处理，要么转换为受控异常继续抛出。
- 日志必须有足够上下文，便于定位问题。
- 日志不得输出 Authorization、Cookie、Token、Secret、密码、原始客户消息、附件 URL 或个人敏感信息。
- 不使用 `System.out.println` 输出业务日志。
- 日志级别要准确，只有真正错误才使用 `error`。

## 8. 数据库与事务

- 表名、字段名、索引名应表达清楚业务含义。
- 不使用 `field1`、`ext1`、`remark1` 等模糊字段承载正式业务语义。
- 写操作必须考虑幂等、并发版本、事务边界、审计和失败恢复。
- SQL 不做无条件全表更新或删除。
- 时间、金额、状态和外部业务标识应使用结构化字段表达。
- 已发布数据库 migration 不直接修改，修正通过新增 migration 完成。

## 9. 安全规范

- Secret 不进入代码、前端、日志、测试夹具或提交历史。
- 用户输入、外部系统响应和文件路径必须做边界校验。
- 错误响应不得暴露内部堆栈、SQL、Token、Secret、客户隐私或完整原始消息。
- 测试数据使用合成数据，不使用真实客户、真实组织、真实租户或真实支付信息。

## 10. 注释规范

- 注释说明业务含义、边界和原因，不复述类名、方法名或字段名。
- 复杂流程、幂等键、并发控制、事务边界、错误转换、外部系统字段映射和安全脱敏逻辑必须写必要中文注释。
- 不用 `TODO` 代替真实说明。
- 修改旧代码时，触达复杂逻辑应顺手补齐必要注释。

## 11. 项目落地建议

- IDEA 插件可以辅助发现问题，但不要作为唯一检查手段。
- 后续项目建立 Maven 构建后，建议通过 PMD、Checkstyle、Spotless 或同类工具固化可自动检查的规则。
- coding agent 生成 Java 代码时，应先满足项目分层和业务边界，再满足本文命名、异常、日志、集合、并发、数据库和安全细节。