117 lines
6.3 KiB
Markdown
117 lines
6.3 KiB
Markdown
---
|
|
name: java-coding-style
|
|
description: 面向 Vibe Coding Agent 的 Java 编写、修改、重构、审查与验证规范，以《阿里巴巴 Java 开发手册》为质量基线并适配现代 JDK 与项目既有约定。凡任务涉及 Java、Spring、Jakarta、Quarkus、MyBatis、JPA、Maven、Gradle、单元测试、并发、异常日志、数据库访问或 Java 代码 Review 时使用。
|
|
---
|
|
|
|
# Java 代码风格
|
|
|
|
将本 Skill 作为 Java 任务的语言级质量规范；将项目的任务治理 Skill 作为流程级规范。两者同时触发时，先执行任务分级与门禁，再在实现、Review 和验证阶段执行本 Skill。
|
|
|
|
## 规则优先级
|
|
|
|
按以下顺序解决冲突：
|
|
|
|
```text
|
|
平台安全规则与用户本次明确要求
|
|
→ 已确认的需求、接口和验收标准
|
|
→ 作用域最近的 AGENTS.md、项目规范、构建配置与 formatter
|
|
→ 相邻代码中稳定且合理的架构惯例
|
|
→ 本 Skill 的必须项
|
|
→ 本 Skill 的推荐项
|
|
```
|
|
|
|
不得以“遵循阿里规范”为由破坏兼容性、绕过项目门禁或批量改写无关代码。发现项目惯例存在明显缺陷、安全问题或与必须项冲突时，说明证据、影响和建议，不得静默复制缺陷。
|
|
|
|
## 规则等级
|
|
|
|
- **必须**：默认不可违反。仅在更高优先级规则明确要求时例外，并记录原因。
|
|
- **推荐**：无冲突时采用；不采用时应有可说明的工程理由。
|
|
- **参考**：根据 JDK、框架、性能数据和业务上下文选择。
|
|
|
|
规则等级用于约束 Agent，不代表已配置静态检查。只有实际运行的检查才能报告为通过。
|
|
|
|
## 开始实现前
|
|
|
|
1. 查找并读取作用域内的 `AGENTS.md`、README、构建文件、formatter、Checkstyle、PMD、SpotBugs、Error Prone 和测试配置。
|
|
2. 确认 Java/JDK 版本、框架版本、模块边界、包结构、依赖管理方式及相邻实现惯例。
|
|
3. 从用户需求或已确认文档提取可观察行为、边界条件、异常语义、兼容性约束和验收证据。
|
|
4. 检查工作区已有改动，避免覆盖、格式化或修复任务范围外的代码。
|
|
5. 按任务内容加载本 Skill 的参考文件：
|
|
- 命名、格式、常量、注释：读取 [references/01-命名格式与注释.md](references/01-命名格式与注释.md)。
|
|
- 类型、OOP、API、空值：读取 [references/02-类型OOP与API设计.md](references/02-类型OOP与API设计.md)。
|
|
- 集合、并发、日期时间：读取 [references/03-集合并发与时间.md](references/03-集合并发与时间.md)。
|
|
- 异常、日志、安全：读取 [references/04-异常日志与安全.md](references/04-异常日志与安全.md)。
|
|
- 分层、持久化、依赖：读取 [references/05-工程分层与数据访问.md](references/05-工程分层与数据访问.md)。
|
|
- 测试、Review、验证：实现和审查阶段读取 [references/06-测试审查与验证.md](references/06-测试审查与验证.md)。
|
|
|
|
只加载与任务相关的规则；进行完整 Java Review 时加载全部参考文件。
|
|
|
|
## 编写代码
|
|
|
|
遵循以下顺序：
|
|
|
|
```text
|
|
确认行为与边界
|
|
→ 找到最小改动点
|
|
→ 先写或调整能失败的测试
|
|
→ 实现最小充分代码
|
|
→ 清理命名、结构和重复
|
|
→ 执行静态审查
|
|
→ 运行相关验证
|
|
```
|
|
|
|
必须：
|
|
|
|
- 保持单一职责和清晰依赖方向，不为了“更优雅”引入无需求支撑的抽象、框架或设计模式。
|
|
- 优先复用项目内已验证的组件；新增公共工具前确认没有等价实现。
|
|
- 把校验放在信任边界，把业务不变量放在领域或服务边界；不要依赖控制器校验保护所有调用路径。
|
|
- 维持 API、序列化、数据库和异常契约兼容；任何破坏性变化都必须显式列出并获得相应确认。
|
|
- 仅修改任务需要的代码。不要顺手全局格式化、升级依赖或清理无关告警。
|
|
- 对非显然的业务决策写“为什么”的注释；不要用注释复述代码。
|
|
- 不生成凭据、真实个人信息、生产数据或可被误用的安全绕过代码。
|
|
|
|
## Java 专项审查
|
|
|
|
实现后逐项检查：
|
|
|
|
1. 正确性：空值、边界、溢出、精度、时区、编码、异常路径和资源释放。
|
|
2. 契约：参数、返回值、异常、幂等性、事务、序列化和向后兼容。
|
|
3. 并发：共享可变状态、原子性、可见性、锁范围、线程池和 `ThreadLocal` 清理。
|
|
4. 数据：参数绑定、查询规模、索引假设、批量操作、事务边界和 N+1 查询。
|
|
5. 安全：认证与授权、对象级权限、注入、反序列化、路径/URL、敏感信息和重放。
|
|
6. 可维护性：命名、职责、重复、嵌套、隐藏副作用和测试可读性。
|
|
|
|
发现问题时按严重性报告：`阻断`、`严重`、`一般`、`建议`。给出文件、位置、触发条件、影响和最小修复建议；不得只报风格偏好。
|
|
|
|
## 验证
|
|
|
|
优先使用项目已有命令和 CI 等价检查。按改动范围选择：
|
|
|
|
- 运行目标单元测试，再运行受影响模块测试。
|
|
- 运行编译、格式、静态分析和集成测试中与风险相称的部分。
|
|
- 项目已配置 Alibaba P3C/PMD 时运行其既有任务；未配置时不要擅自安装插件或新增构建依赖。
|
|
- 对并发、事务、时区、序列化或安全变更补充针对性验证，不能只依赖 happy path。
|
|
|
|
报告每个实际命令、结果和未执行项。不得把“代码看起来正确”写成测试通过，不得用全量构建失败掩盖目标测试结果。
|
|
|
|
## 交付格式
|
|
|
|
最终说明至少包含：
|
|
|
|
- 完成的行为与主要代码位置；
|
|
- 与需求直接相关的设计决定；
|
|
- 实际执行的测试和静态检查；
|
|
- 未验证内容、遗留风险和明确例外。
|
|
|
|
若仅做 Review，不修改代码；若用户要求实现，则完成实现、Review 和验证后再交付。
|
|
|
|
## 规范来源与适配
|
|
|
|
本 Skill 以阿里巴巴公开的 Java 开发规约及 P3C 工具规则为基线，并将其改写为 Agent 可执行指令：
|
|
|
|
- [Alibaba Java Coding Guidelines](https://alibaba.github.io/Alibaba-Java-Coding-Guidelines/)
|
|
- [阿里巴巴 Java 开发手册中文目录](https://alibaba.github.io/p3c/)
|
|
- [Alibaba P3C](https://github.com/alibaba/p3c)
|
|
|
|
阿里规约按“强制、推荐、参考”分级；本 Skill 对应为“必须、推荐、参考”。历史性规则不得脱离项目 JDK、框架、序列化协议和工具链机械套用。
|