HomeJimu HarnessCommunityModelsResourcesDocumentationSkillAgentMCPTeamAbout us
Sign up / Sign in

Quick links

Jimu AI

Jimu AI — tools for building intelligent applications

Loading...
← Back to skills

java-code-style

v1.0.3
HK-hub

Java/Spring Boot 代码风格规范与审查助手,支持制定规范、审查代码风格、沉淀团队约定和输出可执行检查表。

CodingJavaSpring Boot代码规范代码审查
↓ 1 downloads

name: java-code-style description: | Java/Spring Boot 代码风格规范与审查助手,支持制定规范、审查代码风格、沉淀团队约定和输出可执行检查表。 author: "HK-hub" license: "MIT" category: "coding" tags: "Java, Spring Boot, 代码规范, 代码审查" source: "https://github.com/HK-hub/AgentSkills" version: "0.1.0"

Java Code Style Skill

将个人经验、团队约定与业界规范沉淀为可执行的 Java 代码风格工作流。

Skill Goal

在 Java 后端场景中完成以下任务:

  1. 产出可落地的代码风格规范(不是口号式原则)。
  2. 对现有代码进行结构化风格审查(分级、可追踪、可修复)。
  3. 在不改变业务语义的前提下提供最小改动的重构建议。
  4. 统一团队在命名、异常、日志、边界分层、并发与数据库访问上的实践。

Baseline Reference

优先参考以下资料作为基础规范源:

  • references/阿里巴巴Java开发规范(嵩山版).md

在引用规则时,尽量给出“章节 + 页码段”定位,避免泛化描述。

已知目录主干(来自手册):

  • 编程规约(命名、常量、格式、OOP、日期时间、集合、并发、控制语句、注释、前后端、其他)
  • 异常日志(错误码、异常处理、日志规约)
  • 单元测试
  • 安全规约
  • MySQL 数据库(建表、索引、SQL、ORM)
  • 工程结构(应用分层、二方库依赖、服务器)
  • 设计规约

Operating Mode

默认按以下模式工作:

  1. 先识别任务类型:规范制定 / 代码审查 / 代码改写。
  2. 再识别技术上下文:JDK 版本、Spring Boot 版本、ORM、日志框架、构建工具。
  3. 再应用规则:强制项优先于推荐项。
  4. 最后输出可执行结果:问题清单、改写建议、统一模板。

Required Inputs

在信息不足时,先补齐最小上下文:

  • Java 与 Spring Boot 版本(例如 JDK 17 + Spring Boot 3.x)。
  • 架构风格(分层/DDD/Clean Architecture)。
  • 团队禁用项(如字段注入、通配符导入、System.out.println)。
  • 当前目标(写新代码 / 审查旧代码 / 统一历史代码)。

若用户未提供,先按“通用企业级后端默认值”执行,并在输出中明确假设。

Rule Hierarchy

将规则分成三层:

  • L1 强制(Blocking):违反后必须修改。
  • L2 推荐(Important):建议修改,影响可维护性与协作效率。
  • L3 参考(Nice-to-have):优化项,可在时间允许时处理。

将手册中的【强制 / 推荐 / 参考】映射到上述等级,并保持一致。

Style Dimensions

审查或制定规范时,至少覆盖以下维度:

1) 命名与语义

  • 统一类名、方法名、变量名风格。
  • 禁止歧义缩写与混乱命名。
  • 保证命名可表达业务含义与边界语义。

2) 常量与魔法值

  • 抽离魔法值。
  • 常量命名语义完整。
  • 明确常量作用域(类内/模块内/跨模块)。

3) 代码结构与可读性

  • 方法复杂度不设硬性上限,但必须保证可读性与可维护性。
  • 强制使用卫语句(early return)减少分支金字塔。
  • 工具类保持单一职责,优先复用成熟生态工具(如 Apache Commons Lang3、Commons Collections4、Guava),避免重复造轮子。
  • 简单循环场景优先使用 for / while,禁止使用 stream().forEach(...)。
  • 禁止在 Stream 管道中编写复杂业务逻辑或超长 lambda/匿名内部类;复杂逻辑先抽离为具名方法。
  • Service 按 DDD 语义拆分,避免“万能服务类”。

4) OOP 与分层边界

  • 严格区分 DTO / VO / DO / Entity / Command / Query。
  • 实体类优先使用 Lombok 减少样板 getter/setter 代码。
  • Service/DAO 默认采用接口 + Impl 模式。
  • 保留 Manager 层,用于第三方适配、通用能力下沉与多 DAO 组合复用。
  • 禁止跨层泄漏(Controller 直接拼 SQL、Repository 承担业务编排等)。
  • 保持接口契约清晰,避免“万能服务类”。

5) 集合与并发

  • 明确集合类型选择依据。
  • 并发问题优先通过业务流程拆解降低冲突,再考虑锁策略。
  • 优先减少分布式锁使用,避免将锁作为默认方案。
  • JDK >= 21 时,优先评估虚拟线程方案。
  • 明确并发访问场景与线程安全策略,避免无边界并发、隐式共享可变状态。

6) 控制流与防御性编程

  • 强制卫语句,减少深层嵌套。
  • 判空统一优先使用 Objects.isNull / Objects.nonNull。
  • 相等判断统一优先使用 Objects.equals。
  • 字符串判空/非空统一优先使用 StringUtils.isEmpty / StringUtils.isNotEmpty。
  • 集合判空/非空统一优先使用 CollectionUtils.isEmpty / CollectionUtils.isNotEmpty。
  • if 判断中禁止直接使用逻辑非 !,布尔判断优先使用 BooleanUtils.isFalse / BooleanUtils.isTrue。
  • Optional 与 null 不做过度限制,按上下文选择。
  • 对集合型返回(如 DB/RPC 查询 List),无数据或参数不合法时默认返回空列表。
  • 在系统边界进行输入校验。

7) 异常、错误码、日志

  • 业务异常体系主要用于 Controller 内部调用链(Manager/Service/Repository)。
  • 端点 Controller 与 RPC 返回以 Result 结构为主,统一承载 success/errorCode/errorMessage。
  • RuntimeException 可直接使用,不强制必须自定义业务异常。
  • 项目存在错误码规范时遵循现有规范;不存在时按通用规范与项目经验建立。
  • 日志避免“无意义、无上下文”输出;敏感信息与日志级别策略按具体项目场景定义。

8) 数据库与 ORM

  • 以 MyBatis Plus 为主,兼容 MyBatis Flex、Jimmer 等 ORM 选型。
  • SQL 可读、可维护、可索引命中。
  • ORM 映射避免 N+1 与隐式全表扫描风险。
  • 更新语句必须维护 update_time。
  • SQL 风格不做硬编码约束,优先询问项目/团队偏好后统一(如关键字大小写、别名习惯、分页写法)。
  • 索引设计与查询模式一致。

9) 缓存与一致性

  • Redis 操作强制优先使用 Redisson;仅在无法满足需求时才可评估其他框架。
  • 涉及本地缓存或分布式缓存时,必须建立 XXXCacheManager 作为统一入口。
  • 所有缓存 get/set/refresh 等操作必须通过 XXXCacheManager,禁止业务代码直接操作缓存客户端。
  • 缓存 Key 规范、TTL 策略与一致性策略必须集中定义并可审查;缓存刷新策略不设统一硬规则,按具体项目约定执行。

10) 测试与可验证性

  • 关键业务规则必须可单元测试。
  • 复杂分支必须有边界场景用例。
  • 风格改写不改变行为,需有回归验证建议。

11) 工程结构与设计一致性

  • 目录结构与架构分层一致。
  • 模块职责边界清晰。
  • 避免循环依赖与跨模块隐式耦合。

Output Contracts

A. 规范制定输出模板

按如下结构输出:

  1. 适用范围(技术栈、模块范围、执行阶段)
  2. 规则分级表(L1/L2/L3)
  3. 禁止项清单(可直接放进团队 code review)
  4. 示例对照(Bad / Good)
  5. 落地机制(审查节奏、自动化检查建议)

默认附带以下固定禁止项 Top 10:

  1. 禁止在 if 条件中直接使用逻辑非 !,统一使用 BooleanUtils.isFalse/isTrue。
  2. 禁止手写 obj == null / obj != null 判空链式判断,统一使用 Objects.isNull/nonNull。
  3. 禁止使用存在空指针风险的相等判断(如 a.equals(b)),统一使用 Objects.equals(a, b)。
  4. 禁止手写字符串判空表达式(如 str == null || str.length() == 0),统一使用 StringUtils.isEmpty/isNotEmpty。
  5. 禁止手写集合判空表达式(如 list == null || list.isEmpty()),统一使用 CollectionUtils.isEmpty/isNotEmpty。
  6. 禁止在简单遍历场景使用 stream().forEach(...),统一使用 for/while。
  7. 禁止在 Stream 管道中编写复杂业务逻辑、超长 lambda 或庞大匿名内部类。
  8. 禁止跨层职责泄漏(如 Controller 直接拼 SQL、Repository 承担业务编排)。
  9. 禁止在更新链路遗漏 update_time 维护。
  10. 禁止输出无意义、无上下文日志。

B. 代码审查输出模板

按如下格式输出:

  • Summary:总体结论(通过 / 需整改)
  • Findings:
    • CRITICAL:阻断问题(必须改)
    • MAJOR:重要问题(建议尽快改)
    • MINOR:优化问题
  • 每条问题必须包含:
    1. 位置(文件/类/方法)
    2. 问题说明
    3. 违反规则
    4. 修改建议(尽量给出示例)

C. 改写建议输出模板

  • 先给“最小变更方案”(优先)。
  • 再给“增强方案”(可选)。
  • 标注潜在影响面(接口、事务、SQL、并发语义)。

Refactor Guardrails

执行代码风格重构时,遵循以下护栏:

  1. 保持业务语义不变。
  2. 保持对外契约不变(除非用户明确要求)。
  3. 单次改动聚焦一种问题,避免混合重构。
  4. 不引入与任务无关的新抽象。
  5. 避免“顺手大改”。

Conflict Resolution Policy

当“个人习惯、团队约定、手册规则”冲突时,按以下优先级处理:

  1. 项目既有强约束(lint、框架约束、历史兼容要求)
  2. 团队明确约定
  3. 手册强制项
  4. 个人风格偏好

输出时明确说明冲突点与取舍理由。

Default Java/Spring Backend Defaults

当用户未给团队规则时,使用以下默认基线:

  • Controller 层只做协议转换与参数校验,对外以 Result 结构返回。
  • Service 层承载业务编排,按 DDD 进行职责拆分。
  • 保留 Manager 层用于第三方适配、通用能力下沉和多 DAO 组合复用。
  • Repository/Mapper 层只处理持久化。
  • 事务边界不做硬性限制,可根据场景位于 Service/Manager/定时任务。
  • ORM 默认 MyBatis Plus,兼容 MyBatis Flex/Jimmer。
  • 更新语句默认维护 update_time。
  • JDK >= 21 时优先评估虚拟线程。
  • 优先构造器注入,避免隐藏依赖。

Trigger Examples

以下用户表达应触发本技能:

  • “帮我做一份 Java 后端代码规范。”
  • “这段 Spring Boot 代码风格不统一,帮我审查。”
  • “把我的编码习惯沉淀成团队 SKILL。”
  • “给我一套 Java 异常和日志规范模板。”
  • “按阿里规范 + 团队经验,给出可执行检查表。”

Non-Goals

以下内容不作为默认目标,除非用户显式要求:

  • 大规模架构迁移
  • 业务逻辑重写
  • 与风格无关的性能专项优化
  • 与风格无关的基础设施改造

Additional Resources

Reference Files

  • references/阿里巴巴Java开发规范(嵩山版).md:原始规范全文(转换版)
  • references/rules-mapping.md:本 Skill 的 L1/L2/L3 映射与规则索引

Example Files

  • examples/review-output-template.md:标准化审查报告模板
  • examples/refactor-before-after.md:常见风格改写对照(Bad/Good)

Quick Checklist

交付前至少检查:

  • 是否明确适用范围。
  • 是否给出分级规则。
  • 是否给出可执行禁止项。
  • 是否包含 Bad/Good 示例。
  • 是否给出落地与审查机制。
  • 是否区分“必须改”与“可优化”。

Collaboration Questions for Tailoring

每轮优化优先询问并固化以下偏好:

  1. 命名与分层:DO/DTO/VO/Entity/Command/Query 边界、Service 接口化、Manager 职责。
  2. 代码结构:是否强制卫语句、工具类复用策略、DDD 拆分粒度。
  3. 空值策略:Optional 使用边界、null 语义、空列表返回约定。
  4. 异常体系:业务异常与 RuntimeException 的边界、Result 使用场景。
  5. 错误码:沿用项目规范或新建规范的原则。
  6. 日志规范:上下文字段、级别约束、敏感信息处理策略。
  7. ORM/SQL:技术选型、update_time 约束、SQL 风格约束强度。
  8. 并发与事务:事务边界、锁策略优先级、虚拟线程采用条件。

在后续版本中,根据真实审查案例持续补充例外规则与反例库。