用途与范围 本技能面向已有 Quarkus 项目内部的应用代码编写,不负责项目创建、Dev Services 与测试专项、原生与容器镜像等主题;核心 JPA 映射与查询设计可参考可选技能或 Hibernate ORM 指南。
主要能力 覆盖 REST 接口(Quarkus REST 配合 Jackson)、参数校验(Hibernate Validator)、异常映射器、OpenAPI、类型化配置(@ConfigMapping 与 @ConfigProperty)、CDI/ArC Bean 定义、Hibernate ORM 与 Panache 的仓储模式、Mutiny 异步与阻塞处理、Kafka 消息、OIDC 鉴权与角色控制,以及健康检查、Micrometer/Prometheus 指标、OpenTelemetry、容错、REST 客户端、调度与缓存等运维相关扩展。
使用方式 先读取 pom.xml 或 build.gradle,确认 quarkus.platform.version、Java 版本与已有扩展,保留项目现有版本与扩展;通过 quarkus extension add 或 Maven 的 add-extension 命令添加依赖,避免手写 artifact id 与版本,可用 installable 搜索候选扩展。新增 Kafka、OIDC/Keycloak 等基础设施依赖前先询问用户;不使用 Spring 兼容扩展,除非项目已在用。用 jakarta.* 导入、DTO 使用 record、资源类保持轻量并委托给服务层;不硬编码密钥或把凭据写入 application.properties。通过开发模式与 /q/dev-ui 检查,并运行 verify,每个功能配 @QuarkusTest,未实际运行不得声称可用。
关键决策与配置 JSON REST API 选用 quarkus-rest-jackson、quarkus-hibernate-validator、quarkus-smallrye-openapi;单值用 @ConfigProperty,成组配置用 @ConfigMapping;Bean 默认 @ApplicationScoped,无状态持有类用 @Singleton;数据库用 quarkus-hibernate-orm-panache 加 JDBC 驱动并按仓储模式组织;默认采用命令式,必要时用 @RunOnVirtualThread 或 Uni;消息用 quarkus-messaging-kafka;鉴权用 quarkus-oidc 与 @RolesAllowed;运维侧用 smallrye-health、micrometer-registry-prometheus、opentelemetry、smallrye-fault-tolerance;出站 HTTP、调度、缓存分别用 quarkus-rest-client-jackson、quarkus-scheduler、quarkus-cache。
常见陷阱 Quarkus 在构建期解析 CDI,未被引用的 Bean 可能被移除,程序化查找的 Bean 需标 @Unremovable;不要从其他 Bean 或测试直接读写 @ApplicationScoped Bean 的公共字段,因为会命中客户端代理而非实例,应改用方法;不要在事件循环(@NonBlocking 方法或返回 Uni/Multi 的 I/O 线程)上阻塞,需先移除已有 @NonBlocking 再加 @Blocking 或 @RunOnVirtualThread;构建期属性变更需重新构建,运行期属性可用环境变量覆盖;不要在 %dev/%test 中配置数据库、消息代理或 Keycloak 的 URL,否则会禁用 Dev Services;drop-and-create 仅用于开发测试,生产应使用 Flyway 或 Liquibase。
适用场景与限制 适合在既有 Quarkus 项目中按上述技术栈实现和验证应用功能;资料基于 Quarkus 3.40.1 与 3.27.6(Java 21、Maven)的验证环境,具体扩展名称与行为需按项目实际版本复核。项目创建、Dev Services 专项测试、原生与容器镜像不在本技能范围内。