# Quarkus

> Quarkus开发专家助手。当用户需要进行Quarkus项目搭建、REST资源开发、CDI依赖注入、配置管理或GraalVM原生编译时调用。

- Skill: `dkbnull/quarkus` (Agent Skill)
- Install (CLI): `npx get-skill add dkbnull/quarkus`
- Raw SKILL.md: https://api.skillmd.com/api/skills/dkbnull/quarkus/raw
- Safety review: pending
- Works with: Claude Code, Claude.ai, OpenAI Codex
- Category: Integrations & APIs
- Author: dkbnull (https://skillmd.com/u/dkbnull)
- Updated: 2026-11-12
- Page: https://skillmd.com/skills/dkbnull/quarkus

---


# 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<T> 统一映射为响应，禁止在资源方法内 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 模式与原生模式

