alibaba-java-coding-guidelines-skill

阿里巴巴 Java 开发规约

概览

使用本 skill 时，把《阿里巴巴 Java 开发手册》当作 Java 代码生成、重构和审查的默认质量基线。优先处理强制规则，再处理推荐规则；如果项目本地约定和规约冲突，说明冲突点并以用户或项目约定为准。

详细规则摘要见 references/alibaba-java-rules.md。需要精确出处或完整条文时，打开官方页面：https://alibaba.github.io/Alibaba-Java-Coding-Guidelines/。

兼容性

这是通用 Agent Skill，不绑定单个应用或运行器。Claude Code、Codex 以及其他支持 Agent Skills 目录规范的工具都应只依赖 SKILL.md 和按需读取的 references/ 内容。

agents/openai.yaml 只是 OpenAI/Codex UI 元数据，属于可选增强；不应作为 Claude Code 或其他 agent 使用本 skill 的前提。

校验入口提供 Python、Node.js、Go 三种等价实现：scripts/validate_skill.py、scripts/validate_skill.mjs、scripts/validate_skill.go。使用者可以按本地运行时任选其一；需要验证三者一致时运行 tests/test_validators.sh。

使用场景

• •审查 Java、Spring、MyBatis、Maven、SQL、DDL、日志、异常处理或安全相关改动。
• •生成新类、接口、DTO、VO、DO、枚举、异常类、测试类、Mapper、Service、DAO 或 SQL。
• •重构命名、常量、集合、并发、控制流、日志、异常和数据库访问代码。
• •给出代码评审意见、整改清单、规范符合性报告或自动修复建议。

工作流程

1. 先识别任务类型：代码生成、代码审查、重构、SQL/DDL 审查、依赖治理、安全检查。
2. 读取当前项目的已有风格、包结构、测试框架和持久层写法，避免只按通用规约硬套。
3. 按严重级别处理：

- 强制：发现违反时必须指出或修复。 - 推荐：默认遵循；如果不采用，说明权衡。 - 参考：作为设计建议，不阻塞交付。

1. 针对相关模块读取 references/alibaba-java-rules.md 中对应小节。
2. 输出结果时按影响排序：正确性和安全性、稳定性和性能、可维护性、风格一致性。

代码生成规则

• •命名必须清晰准确：类名用 UpperCamelCase，方法、参数、成员变量和局部变量用 lowerCamelCase，常量用大写加下划线。
• •代码注释使用中文；公开 API、复杂业务规则、异常含义和空值语义要写清楚。
• •不使用魔法值；固定范围值优先使用枚举。
• •日志使用 SLF4J 门面，不直接绑定具体日志实现；低级别日志使用占位符或级别判断。
• •资源关闭优先使用 try-with-resources；不要在 finally 中 return 或抛出新异常。
• •MyBatis 参数默认使用 #{}，禁止把用户输入拼进 SQL。
• •Web、Open API、SQL、HTML 输出和用户输入必须做权限、参数校验、转义或脱敏。

代码审查输出

审查时优先给出可执行意见。每条意见包含：

• •级别：强制、推荐或参考。
• •位置：文件和行号，能定位就定位。
• •问题：违反了哪类规约。
• •风险：可能造成的错误、安全、性能或维护成本。
• •建议：给出可落地的改法。

如果没有发现问题，说明已检查的范围，并点出仍未覆盖的风险，例如没有运行测试、没有看到数据库索引信息、没有线上日志配置等。

常见误区

• •不要只检查格式；命名、空值、异常边界、日志上下文、事务、SQL 注入和权限校验同样重要。
• •不要把推荐规则包装成强制缺陷；推荐项要讲清收益和代价。
• •不要为了规约牺牲项目一致性；本地架构分层、包名和框架约束要先看再改。
• •不要依赖某个 agent 产品的专属工具、路径或配置；只把它们作为可选增强。
• •不要大段复述官方文档；只加载和任务相关的规则摘要。