用途
该技能用于创建一个新的 Quarkus 项目(Maven 或 Gradle),可通过 Quarkus CLI、code.quarkus.io API 或 Maven 插件完成脚手架,选择所需扩展,并在开发模式下运行。
主要能力
- 环境检测:检查 Java 版本(Java 17、21 或 25)、可选的 Quarkus CLI 版本以及 Maven/Gradle 版本。若目录中已存在 Quarkus 项目(如含 io.quarkus.platform BOM、quarkus-maven-plugin 或 io.quarkus Gradle 插件),则不再脚手架,而是读取其 Quarkus 版本并保持。
- 流版本选择:新项目使用 https://code.quarkus.io/api/streams 中标注推荐的流(LTS 流),不自行编造补丁版本,由工具选择。Quarkus 4.0 仍为 beta,除非有要求否则不使用。若扩展在推荐流中缺失,CLI 会静默选择较旧流,因此需检查生成构建文件中的 quarkus.platform.version。
- 脚手架方式:
- Quarkus CLI(可通过 https://quarkus.io/get-started/ 安装,例如 SDKMAN 的 sdk install quarkus): quarkus create app com.example:demo --extension='rest-jackson,hibernate-orm-panache,jdbc-postgresql,hibernate-validator,smallrye-health' --java=21 --maven(或 --gradle)
- 无 CLI 时使用 Maven 插件(版本固定为 https://quarkus.io/guides/maven-tooling 中的当前发布版): mvn io.quarkus.platform:quarkus-maven-plugin:QUARKUS_VERSION:create -DprojectGroupId=com.example -DprojectArtifactId=demo -Dextensions='rest-jackson,hibernate-orm-panache,jdbc-postgresql' -DbuildTool=maven(或 gradle)
- 或通过 https://code.quarkus.io 网页 UI / REST API 生成并解压,例如 https://code.quarkus.io/d?g=com.example&a=demo&e=rest-jackson&b=MAVEN。
- 扩展选择:技能给出需求与扩展的对应表,包括 REST + JSON 用 rest-jackson(Quarkus REST,非旧版 resteasy)、数据库 ORM 用 hibernate-orm-panache 与 jdbc-postgresql、校验用 hibernate-validator、健康/指标用 smallrye-health 与 micrometer-registry-prometheus、认证用 oidc 或 smallrye-jwt、OpenAPI 用 smallrye-openapi、REST 客户端用 rest-client-jackson、容器用 container-image-jib(或 container-image-docker)。后续可通过 quarkus extension add <name> 或 ./mvnw quarkus:add-extension -Dextensions=<name> 添加,quarkus extension list --installable 列出可安装项。
- 目录布局与运行:Java 源码位于 src/main/java,配置位于 src/main/resources/application.properties,Docker 文件位于 src/main/docker,测试位于 src/test/java(@QuarkusTest / @QuarkusIntegrationTest)。开发模式命令为 ./mvnw quarkus:dev(或 quarkus dev、./gradlew quarkusDev),提供热重载、http://localhost:8080/q/dev-ui 的 Dev UI、Dev Services 自动容器以及按 r 的持续测试。打包用 ./mvnw package,生成可运行的 target/quarkus-app/quarkus-run.jar。生成的测试包含 *IT 类,Maven 默认跳过(模板中 <skipITs>true</skipITs>),可用 ./mvnw verify -DskipITs=false 或 -Dnative 运行。
使用方式
按技能说明:先检测环境;对已有项目不重复脚手架;新项目选择推荐 LTS 流并让工具决定补丁版本;从三种脚手架方式中选一种;按需选择扩展;随后以开发模式运行并利用 Dev UI、Dev Services 和持续测试。
适用场景
需要初始化 Quarkus 应用、搭建 REST/数据库/校验/健康检查/认证/OpenAPI/REST 客户端/容器镜像等技术栈组合,并在本地进行开发调试与测试时使用。相关技能包括 quarkus-dev-services-and-testing、quarkus-native-and-container。
限制与注意事项
技能说明中提示:不要使用 Quarkus 4.0(beta),除非明确要求;不要自行编造补丁版本;扩展在推荐流中缺失时 CLI 可能静默选用较旧流,需检查生成文件中的 quarkus.platform.version;升级前应先阅读上游资料(quarkus update 指南、迁移指南、发布公告、LTS 政策),冲突时以上游页面为准。技能内容标注已在 Quarkus 3.40.1(当前推荐 LTS 流)及 3.27.6(较旧 LTS)上验证脚手架、./mvnw verify、./gradlew build、开发模式、Dev Services PostgreSQL 等。