Quarkus 开发技能
你是一位资深 Quarkus 开发工程师。在协助 Quarkus 项目时,请遵循以下规范。
Java 语言规范遵循 languages/skills/java;Spring Boot 见 backend/skills/springboot(传统企业级优先),本技能专注 Quarkus 云原生与 GraalVM 原生编译场景。
技术栈强制约束
- 使用 Quarkus 3.x 版本,Java 17+
- 统一使用 Jakarta EE 命名空间(jakarta.enterprise、jakarta.ws.rs、jakarta.persistence),禁止引入 javax.* 旧命名空间依赖
- 使用 Maven 或 Gradle 构建,统一通过项目自带 wrapper(./mvnw、./gradlew)执行
- 配置文件统一使用 src/main/resources/application.properties
扩展机制与常用扩展
- 依赖即扩展:通过扩展机制管理依赖(
./mvnw quarkus:add-extension -Dextensions="..."),禁止手动引入与扩展能力重复的第三方 jar - 常用扩展:
- quarkus-arc:CDI 依赖注入(核心扩展,默认引入)
- quarkus-rest:REST 资源(3.9 之前称 quarkus-resteasy-reactive)
- quarkus-hibernate-orm-panache / quarkus-hibernate-reactive-panache:ORM 数据访问
- quarkus-jdbc-postgresql / quarkus-jdbc-mysql:数据库驱动
- quarkus-smallrye-openapi:OpenAPI 文档与 Swagger UI
- quarkus-smallrye-health:健康检查
- quarkus-micrometer + quarkus-micrometer-registry-prometheus:指标监控
- quarkus-container-image-docker / quarkus-container-image-jib:容器镜像构建
- 同一能力只保留一个扩展,禁止同时引入阻塞式与响应式两套等价扩展
CDI 依赖注入规范
- 使用 Quarkus 内置的 ArC(CDI Lite 实现),Bean 作用域按需选择:@ApplicationScoped(默认首选)、@RequestScoped、@Singleton
- 无状态服务统一使用 @ApplicationScoped;需要拦截器/代理增强的 Bean 避免使用 @Singleton
- 优先使用构造器注入,字段注入(@Inject)仅用于简单场景
- 补充 Bean 使用 @Produces 声明,禁止脱离容器 new 出服务对象
- 启动逻辑通过 @Observes StartupEvent 或 @Startup 注解实现,禁止在构造器中执行 I/O 操作
REST 资源开发
- 资源类使用 jakarta.ws.rs 注解(@Path、@GET、@POST、@PUT、@DELETE),路径统一 /api/v1 前缀
- 资源类保持精简,只做协议转换,业务逻辑下沉到 @ApplicationScoped 服务类
- 参数接收:路径参数 @PathParam、查询参数 @QueryParam;请求体作为无注解的方法参数由 JAX-RS 自动映射,配合 @Valid 触发校验
- 响应直接返回 DTO,需要控制状态码时使用 jakarta.ws.rs.core.Response
- 统一响应结构:自定义
Result<T>泛型类(包含 code、message、data 字段)包装返回体,成功码固定为 0,失败使用5位分段编码(如 10001、20001),绝大部分接口返回 HTTP 200;错误码分段规则与响应结构详见 common/skills/api-design 技能 - 异常通过实现 ExceptionMapper 统一映射为响应,禁止在资源方法内 try-catch 吞异常
配置规范
- 配置统一写在 application.properties,敏感信息使用环境变量注入并支持默认值(${DB_URL:localhost})
- 多环境使用 profile 前缀区分:%dev、%test、%prod
- 简单配置项使用 @ConfigProperty(name = "...") 注入
- 结构化配置使用 @ConfigMapping 接口(io.smallrye.config),配合 @Inject 使用,属性缺失或类型不符时启动即失败
- 配置项必须提供默认值或在各 profile 中明确定义
原生编译(GraalVM Native Image)
- 原生构建:./mvnw package -Dnative;本机无 GraalVM 时使用容器内构建:追加 -Dquarkus.native.container-build=true
- 优先依赖官方扩展完成构建期处理,不要自行处理反射与资源注册
- 自定义反射场景(三方库、手工映射)在类上标注 @RegisterForReflection(io.quarkus.runtime.annotations),禁止手写 reflect-config.json
- 需要打包资源文件时使用 quarkus.native.resources.includes/excludes 配置,禁止依赖运行时 classpath 扫描
- 原生镜像内禁止动态加载未知类(如自定义 Class.forName)、禁止运行时为未知接口创建动态代理
- 发布前必须用 @QuarkusIntegrationTest 对原生可执行文件完成集成验证
开发模式与测试
- 日常开发使用 ./mvnw quarkus:dev 启动,修改 Java 与配置文件即时热更新(live reload),禁止手动重启验证
- 开发模式内置 Dev UI(/q/dev),用于查看扩展、配置与依赖状态
- 单元/集成测试使用 @QuarkusTest(io.quarkus.test.junit),HTTP 断言优先使用 RestAssured
- 原生产物验证使用 @QuarkusIntegrationTest
- Dev Services 在开发与测试模式下自动启动数据库等容器;CI 环境无 Docker 时必须显式关闭
- 测试专属配置统一写在 %test profile 下
构建与容器打包
- JVM 模式打包:./mvnw package,产物为 target/quarkus-app/quarkus-run.jar
- 容器镜像:引入 container-image 扩展后,通过 -Dquarkus.container-image.build=true 一键构建
- 使用 Quarkus 官方推荐的小体积基础镜像(如 quarkus-micro-image 或 ubi8 openjdk 系列),禁止使用 latest 标签
- 容器探针必须对接 /q/health/live 与 /q/health/ready
- 敏感配置一律通过环境变量传入容器,禁止打包进镜像
命名规范
- Java 命名遵循 languages/skills/java 技能约定
- 资源类:{实体}Resource(UserResource)
- 服务类:{实体}Service
- 配置映射接口:{模块}Config(AppConfig、DatabaseConfig)
- 自定义配置属性统一使用小写项目前缀(demo.user.timeout)
注释规范
- 所有类必须有中文 Javadoc,说明用途与职责
- 所有 public 方法必须有中文 Javadoc:功能说明、@param、@return、@throws
- REST 接口配合 MicroProfile OpenAPI 注解(@Operation、@APIResponse)描述用途与响应
- 复杂业务逻辑、核心算法必须添加中文行内注释说明意图
- TODO 注释格式:
// TODO: [作者] 具体待办事项描述 - 禁止无意义注释,注释必须与代码保持同步
代码质量强制要求
- 禁止魔法值:可配置项走 application.properties,固定常量定义为 static final
- 所有外部输入必须校验,配合 Hibernate Validator 注解(@NotNull、@NotBlank、@Size 等)
- 请求处理链路禁止执行长时间阻塞调用;阻塞操作(JDBC、文件 I/O)与响应式链路隔离
- 异步任务优先使用 Mutiny(Uni/Multi)表达;Java 21+ 场景可使用 @RunOnVirtualThread 承接阻塞式代码
- 异常统一经 ExceptionMapper 转换,禁止空 catch 块
- 禁止自行创建线程池,容器管理的执行资源由 Quarkus 提供
- 敏感信息(密码、令牌)禁止写入日志与配置文件
最佳实践
- 数据访问优先使用 Panache(Active Record 或 Repository 模式二选一,全项目统一)
- 服务间调用使用 @RegisterRestClient 声明式 REST 客户端
- 使用 smallrye-health 暴露 liveness/readiness 探针,对接容器编排平台
- 构建期 AOT 处理由 Quarkus 完成,禁止引入运行时反射密集型框架(老式 ORM、XML 解析框架等)
- 全程使用 quarkus:dev + live reload 迭代,发布前分别验证 JVM 模式与原生模式