java-coding-convention

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

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. 正例参考 — 提供符合规约的代码示例