SuperAPI AI 工具集
合作ENAI 行业资讯收藏
Skill 广场java-coding-standards

java-coding-standards

编程与开发

查看项目

更新于 10-15 08:39

技能介绍

用途

本技能为 Spring Boot 与 Quarkus 服务中的 Java（17+）代码提供可读、可维护的编码规范。适用于以下场景：

  • 在 Spring Boot 或 Quarkus 项目中编写或评审 Java 代码
  • 统一命名、不可变性或异常处理约定
  • 使用 record、密封类或模式匹配（Java 17+）
  • 审查 Optional、Streams 或泛型的使用
  • 规划包结构与项目布局
  • [QUARKUS] 处理 CDI 作用域、Panache 实体或响应式管道

框架识别

应用规范前，先根据构建文件判断框架：

  • 构建文件包含 quarkus → 应用 [QUARKUS] 约定
  • 构建文件包含 spring-boot → 应用 [SPRING] 约定
  • 两者都未检测到 → 只应用共享约定

核心原则

  • 清晰优先于炫技
  • 默认不可变；尽量减少共享可变状态
  • 快速失败，抛出有意义的异常
  • 命名与包结构保持一致
  • [QUARKUS] 优先构建期处理而非运行期处理；尽量避免运行期反射

主要能力

命名

  • 类/record 使用 PascalCase；方法/字段使用 camelCase；常量使用 UPPER_SNAKE_CASE
  • [QUARKUS] JAX-RS 资源命名为 *Resource，而非 *Controller
  • [SPRING] REST 控制器命名为 *Controller

不可变性

  • 优先使用 record 和 final 字段；只提供 getter，不提供 setter
  • [QUARKUS] Panache active-record 实体使用 public 字段（Quarkus 约定，构建期生成访问器）
  • [QUARKUS] Panache MongoDB 实体使用 @MongoEntity 注解

Optional 用法

  • find* 方法返回 Optional
  • 使用 map/flatMap 而非 get()，配合 orElseThrow 抛出领域异常

Streams 最佳实践

  • 用 Streams 做转换，保持管道简短
  • 避免复杂嵌套 Streams；为清晰起见优先使用循环

依赖注入

  • [SPRING] 优先构造器注入，避免字段上的 @Autowired
  • [QUARKUS] 支持构造器注入；包级私有字段注入可接受（避免代理问题）
  • [QUARKUS] 需要拦截或懒初始化时避免 @Singleton，改用 @ApplicationScoped

响应式模式 [QUARKUS]

  • 响应式端点返回 Uni/Multi
  • 使用非阻塞管道组合（chain）
  • 避免在 Uni/Multi 管道内进行阻塞调用
  • 避免对共享 Uni 多次订阅；使用 Uni.memoize()

异常

  • 领域错误使用非受检异常；技术异常包装上下文
  • 创建领域专属异常（如 MarketNotFoundException）
  • 避免宽泛的 catch (Exception ex)，除非集中重新抛出或记录
  • 集中式异常处理：[SPRING] 使用 @RestControllerAdvice；[QUARKUS] 使用 ExceptionMapper 或 @ServerExceptionMapper

泛型与类型安全

  • 避免原始类型；声明泛型参数
  • 可复用工具优先使用有界泛型

项目结构

  • [SPRING] 包结构：config、controller、service、repository、domain、dto、util；资源文件 application.yml；测试镜像 main
  • [QUARKUS] 包结构：config、resource、service、repository、domain、dto、util、mapper；资源文件 application.properties（支持 YAML 需 quarkus-config-yaml）、import.sql；测试镜像 main

格式与风格

  • 统一使用 2 或 4 空格缩进（遵循项目标准）
  • 每个文件一个公共顶层类型
  • 方法保持短小专注；提取辅助方法
  • 成员顺序：常量、字段、构造器、公共方法、protected、private

应避免的代码坏味道

  • 长参数列表 → 使用 DTO/构建器
  • 深层嵌套 → 提前返回
  • 魔法数字 → 命名常量
  • 静态可变状态 → 优先依赖注入
  • 静默 catch 块 → 记录并处理或重新抛出
  • [QUARKUS] 在需要 @ApplicationScoped 时误用 @Singleton——破坏代理与拦截
  • [QUARKUS] 混用 quarkus-resteasy-reactive 与 quarkus-resteasy（经典）——选定一种栈
  • [QUARKUS] 同一限界上下文中混用 Panache active-record 与 repository 模式——选定一种

日志

  • [SPRING] 使用 SLF4J：LoggerFactory.getLogger，log.info("fetch_market slug={}", slug)
  • [QUARKUS] 使用 JBoss Logging：Logger.getLogger，log.infof("fetch_market slug=%s", slug)
  • [QUARKUS] 替代方案：@Inject Logger log（CDI 注入，作用域为声明类）

空值处理

  • 仅在不可避免时接受 @Nullable；否则使用 @NonNull
  • 对输入使用 Bean Validation（@NotNull、@NotBlank）
  • [QUARKUS] 在 @BeanParam、@RestForm 和请求体参数上应用 @Valid

配置

  • [SPRING] 使用 @ConfigurationProperties
  • [QUARKUS] 使用 @ConfigMapping（类型安全、构建期校验）或 @ConfigProperty

测试期望

共享：JUnit 5 + AssertJ；Mockito 模拟；避免部分模拟；测试确定性，无隐藏 sleep。

  • [SPRING] @WebMvcTest 用于控制器切片，@DataJpaTest 用于仓库切片，@SpringBootTest 保留给完整集成测试，@MockBean 替换 bean
  • [QUARKUS] 纯 JUnit 5 + Mockito 用于单元测试（不用 @QuarkusTest），@QuarkusTest 保留给 CDI 集成测试，@InjectMock 替换 CDI bean，Dev Services 用于数据库/Kafka/Redis，@QuarkusTestResource 管理自定义外部服务生命周期

使用方式

该技能以规范文档形式提供，包含具体代码示例（PASS/FAIL 标注），供编写或评审 Java 代码时参照执行。技能会先读取构建文件识别框架，再应用对应约定。

适用场景

  • Spring Boot 或 Quarkus 服务的日常开发与代码评审
  • 团队统一 Java 编码风格与项目结构
  • 引入 Java 17+ 新特性（record、密封类、模式匹配）时的规范参考
  • Quarkus 响应式编程与 CDI 作用域的正确使用

限制

  • 仅覆盖 Java 17+ 的 Spring Boot 与 Quarkus 服务，其他框架或语言暂未提供
  • 具体版本兼容性、安装方式、收费与价格信息暂未提供
  • 示例中的类名与包名仅为演示，实际项目需按自身命名调整