# Java Coding Convention

> 阿里巴巴Java开发手册 — 编程规约审查与指导。当用户涉及以下任何场景时触发： - 审查Java代码的命名风格、代码格式、常量定义是否规范 - 检查Java OOP代码（equals、BigDecimal、包装类型、序列化等）是否符合规约 - 审查Java集合使用（ArrayList、HashMap、subList、toArray等）是否正确 - 检查Java并发代码（线程池、锁、ThreadLocal、volatile等）是否安全 - 审查Java日期时间处理、控制语句、注释是否符合规范 - 进行Java代码走查、Code Review - 编写Java代码时需要遵循命名、格式等规范建议 - 用户提到"Java开发手册"、"阿里巴巴规约"、"Java规约"等关键词 此技能也适用于Java代码重构、代码质量改进、新功能编码时的规范约束。

- Skill: `greenplumwine/java-coding-convention` (Agent Skill, multi-file: 12 files)
- Install (CLI): `npx skillmds@latest add greenplumwine/java-coding-convention`
- Raw SKILL.md: https://api.skillmd.com/api/skills/greenplumwine/java-coding-convention/raw
- Safety review: pending
- Works with: Claude Code, Claude.ai, OpenAI Codex
- Category: Coding & Dev Tools
- Author: Greenplumwine (https://skillmd.com/u/greenplumwine)
- Updated: 2026-09-17
- Page: https://skillmd.com/skills/greenplumwine/java-coding-convention

---


# Java 编程规约技能

## 作用

本技能基于《阿里巴巴Java开发手册》的编程规约章节，为Java开发者提供全面的代码规范审查和指导。

涵盖以下规约领域：

| 规约领域 | 说明 |
|---------|------|
| 命名风格 | 类名、方法名、变量名、常量、包名等命名规范 |
| 常量定义 | 魔法值禁止、常量分层、枚举使用 |
| 代码格式 | 缩进、空格、换行、行宽、方法长度等 |
| OOP规约 | equals、BigDecimal、包装类型、序列化、POJO等 |
| 日期时间 | SimpleDateFormat线程安全、日期处理 |
| 集合处理 | ArrayList、HashMap、subList、toArray、foreach等 |
| 并发处理 | 线程池、锁、ThreadLocal、volatile、并发工具类 |
| 控制语句 | switch、if-else、三目运算、循环 |
| 注释规约 | 类注释、方法注释、特殊注释标记 |
| 前后端规约 | 接口规范、API设计 |

## 使用方法

1. **按需加载规约** — 输入：用户问题或待审查代码的特征描述；执行：选择对应的规约文件读取，不要一次性加载所有文件；输出：已加载的规约领域清单
2. **代码审查** — 输入：Java 代码片段或文件路径；执行：读取相关规约文件后逐条对照检查；输出：按【强制】【推荐】【参考】分级的问题清单 + 正例参考
3. **编码指导** — 输入：用户正在编写的 Java 代码场景；执行：引用相关规约条款分析；输出：符合规约的编码建议 + 示例代码

## 编程审查检查点

执行 Java 编程规约审查时，以下场景需先向用户确认，再执行后续操作：

| 场景 | 检查内容 |
|------|---------|
| 建议批量修改代码格式 | 大量格式调整建议输出前，确认用户是否接受自动格式化（如 IDE 快捷键） |
| 涉及并发安全改造 | 建议引入锁、线程池等并发机制前，确认当前代码运行环境是否为多线程场景 |
| 用户未提供代码 | 提示用户粘贴 Java 代码，说明本技能涵盖的 10 个审查维度 |
| 建议重构类结构 | 涉及类拆分、合并或接口变更时，确认影响范围和兼容性要求 |

## 规约文件索引

所有规约原文存放于 `references/` 目录下，按小节拆分，按需读取：

```
references/
├── naming-style.md          # 命名风格（类名、方法名、变量名、常量、包名等）
├── constant-definition.md   # 常量定义（魔法值、常量分层、枚举）
├── code-format.md           # 代码格式（缩进、空格、换行、行宽）
├── oop-convention.md        # OOP规约（equals、BigDecimal、包装类型、序列化）
├── datetime-convention.md   # 日期时间（SimpleDateFormat、日期处理）
├── collection-convention.md # 集合处理（ArrayList、HashMap、subList、toArray）
├── concurrency-convention.md # 并发处理（线程池、锁、ThreadLocal、volatile）
├── control-statement.md     # 控制语句（switch、if-else、三目运算）
├── comment-convention.md    # 注释规约（类注释、方法注释、特殊标记）
├── frontend-backend.md      # 前后端规约（接口规范、API设计）
└── other-convention.md      # 其他
```

### 按需读取指引

根据任务类型，读取对应的规约文件：

| 任务类型 | 需要读取的规约文件 |
|---------|------------------|
| 审查命名规范 | naming-style.md |
| 审查常量使用 | constant-definition.md |
| 审查代码格式 | code-format.md |
| 审查OOP相关代码 | oop-convention.md |
| 审查日期时间处理 | datetime-convention.md |
| 审查集合使用 | collection-convention.md |
| 审查并发代码 | concurrency-convention.md |
| 审查控制语句 | control-statement.md |
| 审查注释 | comment-convention.md |
| 审查前后端接口 | frontend-backend.md |
| 全面代码审查 | 按代码涉及领域，逐个读取相关文件 |

## 边界条件处理

| 场景 | 处理方式 |
|------|---------|
| 用户未提供代码 | 提示用户粘贴 Java 代码，说明本技能涵盖的 10 个审查维度，或提供代码文件路径 |
| 代码片段不完整（缺少依赖类） | 基于可见代码给出审查建议，同时提示完整代码可能暴露更多问题 |
| 非 Java 代码 | 说明本技能专为 Java 设计，但命名风格和常量定义原则可通用参考 |
| 框架特定代码（Spring Boot / Android） | 通用 Java 规约适用，框架特有注解和配置不在本技能审查范围内 |
| references 文件缺失 | 基于通用 Java 编码规范给出建议，提示检查 references 目录完整性 |

## 规约适用性判断

不是所有代码都需要检查所有规约。审查时应结合上下文判断规约是否适用，避免对单线程代码套用并发规约、对临时脚本套用工程规约等误判。

| 规约领域 | 适用场景 | 不适用场景 |
|---------|---------|-----------|
| 命名风格 | 所有代码 | 无 |
| 常量定义 | 所有代码 | 无 |
| 代码格式 | 所有代码 | 无 |
| OOP规约 | 所有面向对象代码 | 纯过程式代码 |
| 日期时间 | 涉及日期处理的代码 | 无日期操作的代码 |
| 集合处理 | 使用集合的代码 | 未使用集合的代码 |
| 并发处理 | 存在多线程调用特征的代码：类名含Concurrent/Thread/Pool/Executor、使用了synchronized/volatile/Atomic等关键字、处于Web/Spring等天然多线程环境、用户明确提及多线程场景 | 纯单线程工具类、main方法临时测试代码 |
| 控制语句 | 所有代码 | 无 |
| 注释规约 | 所有代码 | 无 |
| 前后端规约 | Web接口相关代码 | 纯后端计算代码 |

## 规约等级说明

原文中的规约分为三个等级：
- **【强制】**：必须遵守，违反会导致严重问题
- **【推荐】**：建议遵守，不遵守可能影响代码质量
- **【参考】**：供参考，根据具体情况决定是否采用

## 审查输出格式

审查Java代码时，按以下结构输出：

1. **【强制】违规项** — 必须修复的问题，说明违反的规约编号和内容
2. **【推荐】改进项** — 建议改进的代码，说明原因
3. **【参考】优化建议** — 可酌情采纳的建议
4. **正例参考** — 提供符合规约的代码示例