401-frameworks-quarkus-core

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Translation

Chinese

Quarkus Core Guidelines

Quarkus核心指南

Apply Quarkus core guidelines for CDI beans, configuration, profiles, and lifecycle.

What is covered in this Skill?

@QuarkusMain and application entry (when custom main is needed)
CDI scopes: @ApplicationScoped, @Singleton, @Dependent; bean disambiguation (@Default, @Alternative, @Named)
Constructor injection with @Inject
CDI interceptors (@Interceptor, @InterceptorBinding) for cross-cutting concerns
CDI events: @Observes StartupEvent / ShutdownEvent, @ObservesAsync for async dispatch
Programmatic injection with Instance<T> for dynamic bean selection
@ConfigMapping and structured configuration with Bean Validation (@Valid)
Profile-specific properties (%dev, %test, %prod) and @IfBuildProfile
Startup and shutdown observers (@Startup, @PreDestroy)
SmallRye Health probes (@Liveness, @Readiness)
Virtual threads with @RunOnVirtualThread (Java 21+)
Native-image safety: @RegisterForReflection, @DisabledOnNativeImage

Scope: Apply recommendations based on the reference rules and good/bad code examples.

遵循Quarkus针对CDI Bean、配置、配置文件及生命周期的核心指南。

本Skill涵盖哪些内容？

@QuarkusMain与应用入口（当需要自定义主类时）
CDI作用域：@ApplicationScoped、@Singleton、@Dependent；Bean消歧义（@Default、@Alternative、@Named）
使用@Inject的构造函数注入
用于横切关注点的CDI拦截器（@Interceptor、@InterceptorBinding）
CDI事件：@Observes StartupEvent / ShutdownEvent、用于异步分发的@ObservesAsync
使用Instance<T>进行程序化注入以实现动态Bean选择
@ConfigMapping与结合Bean Validation（@Valid）的结构化配置
特定配置文件属性（%dev、%test、%prod）及@IfBuildProfile
启动与关闭观察者（@Startup、@PreDestroy）
SmallRye健康探针（@Liveness、@Readiness）
结合@RunOnVirtualThread的虚拟线程（Java 21+）
原生镜像安全：@RegisterForReflection、@DisabledOnNativeImage

适用范围： 基于参考规则及代码示例的优劣来应用相关建议。

Constraints

约束条件

Before applying any Quarkus changes, ensure the project compiles. If compilation fails, stop immediately. After applying improvements, run full verification.

MANDATORY: Run
```
./mvnw compile
```
or
```
mvn compile
```
before applying any change
PREREQUISITE: Project must compile successfully before applying Quarkus core improvements
SAFETY: If compilation fails, stop immediately — compilation failure is a blocking condition
BLOCKING CONDITION: Compilation errors must be resolved by the user before proceeding
VERIFY: Run
```
./mvnw clean verify
```
or
```
mvn clean verify
```
after applying improvements
BEFORE APPLYING: Read the reference for detailed rules, good/bad patterns, and constraints

在应用任何Quarkus相关修改前，确保项目可编译。若编译失败，立即停止。应用优化后，执行完整验证。

强制要求：在应用任何修改前执行
```
./mvnw compile
```
或
```
mvn compile
```
前提条件：在应用Quarkus核心优化前，项目必须编译成功
安全要求：若编译失败，立即停止——编译失败属于阻塞性条件
阻塞性条件：用户必须先解决编译错误，才能继续操作
验证步骤：应用优化后执行
```
./mvnw clean verify
```
或
```
mvn clean verify
```
应用前准备：阅读参考文档以了解详细规则、优劣模式及约束条件

When to use this skill

何时使用本Skill

Review Java code for Quarkus application structure and CDI
Apply best practices for Quarkus configuration and beans
Improve CDI interceptors, events, or programmatic injection in Quarkus
Add SmallRye Health probes or virtual-thread configuration

审查Quarkus应用结构与CDI相关的Java代码
应用Quarkus配置与Bean的最佳实践
优化Quarkus中的CDI拦截器、事件或程序化注入
添加SmallRye健康探针或虚拟线程配置

Reference

参考资料

For detailed guidance, examples, and constraints, see references/401-frameworks-quarkus-core.md.

如需详细指南、示例及约束条件，请参阅references/401-frameworks-quarkus-core.md。