Building Quarkus apps with Quarkus Command Line Interface (CLI)
你可以使用 `quarkus`命令创建项目、管理扩展,并使用基础项目构建工具执行必要的构建和开发任务。
Installing the CLI
Quarkus CLI 可在多个面向开发者的包管理器中使用,例如:
如果你已经使用(或希望使用)上述工具之一,这是安装 Quarkus CLI 并使其保持更新的最简单的方式。
除了这些包管理器之外,还可以通过 JBang 安装 Quarkus CLI。选择对你来说最实用的工具:
-
JBang - 适用于 Linux、macOS 和 Windows
-
SDKMAN! - 适用于 Linux 和 macOS
-
Homebrew - 适用于 Linux 和 macOS
-
Chocolatey - for Windows
-
Scoop - for Windows
Quarkus CLI 以 jar 的形式提供,可以使用 JBang 进行安装。 JBang 将使用你现有的 Java,如果需要,还可以为你安装一个 Java。 在 Linux、macOS 和 Windows 上(使用 WSL 或与 bash 兼容的外壳,如 Cygwin 或 MinGW)
curl -Ls https://sh.jbang.dev | bash -s - trust add https://repo1.maven.org/maven2/io/quarkus/quarkus-cli/
curl -Ls https://sh.jbang.dev | bash -s - app install --fresh --force quarkus@quarkusio
在 Windows 上使用 Powershell:
iex "& { $(iwr https://ps.jbang.dev) } trust add https://repo1.maven.org/maven2/io/quarkus/quarkus-cli/"
iex "& { $(iwr https://ps.jbang.dev) } app install --fresh --force quarkus@quarkusio"
如果已经安装了 JBang,你可以直接使用它:
# This can also be used to update to the latest version
jbang app install --fresh --force quarkus@quarkusio
如果要使用特定的版本,你可以直接选择一个版本:
# Create an alias in order to use a specific version
jbang app install --name qs3.5.0 https://repo1.maven.org/maven2/io/quarkus/quarkus-cli/3.5.0/quarkus-cli-3.5.0-runner.jar
如果你已经在本地构建了 Quarkus,你可以使用该版本:
# Use the latest (or locally built) snapshot (with qss as an alias)
jbang app install --force --name qss ~/.m2/repository/io/quarkus/quarkus-cli/999-SNAPSHOT/quarkus-cli-999-SNAPSHOT-runner.jar
安装后,quarkus
将会出现在你的 $PATH
中,如果你运行 quarkus --version
,它将打印已安装的版本:
quarkus --version
{quarkus-version}
如果你收到了一个有关 app
不可读的错误,则你可能安装了低于 v0.56.0 的 JBang 版本。请将其移除或升级到最新版本。
如果你正在第一次安装 JBang,则开始一个新的会话来更新你的 PATH
。
SDKMAN! 可用于管理开发环境。它可以在大多数基于 Unix 的系统上管理多个软件开发工具包的并行版本,这使得它成为了非常好的选择,可以方便地使用多个 JDK 版本。 使用 SDKMAN!,你还可以安装流行的 Java 工具,包括 Quarkus CLI。
在安装 Quarkus CLI 之前,请确保你拥有 a JDK installed。
若要列出可用 Java 版本,请使用 |
若要使用 SDKMAN! 安装 Quarkus CLI,请运行以下命令:
sdk install quarkus
它将安装 Quarkus CLI 的最新版本。
安装后,quarkus
将会出现在你的 $PATH
中,如果你运行 quarkus --version
,它将打印已安装的版本:
quarkus --version
{quarkus-version}
SDKMAN! 会在有新版本时通知,以便轻松更新:
sdk upgrade quarkus
Homebrew是面向 macOS(和 Linux)的包管理器。 您可以使用 Homebrew 安装(和更新)Quarkus CLI。
在安装 Quarkus CLI 之前,请确保安装 JDK。我们尚未添加显式依赖项,因为我们希望确保您可以使用您偏好的 JDK 版本。 您可以使用 `brew install openjdk`为最新 Java 版本、`brew install openjdk@17`为 Java 17 或 `brew install openjdk@21`为 Java 21 安装 JDK。 |
若要使用 Homebrew 安装 Quarkus CLI,请运行以下命令:
brew install quarkusio/tap/quarkus
它将安装 Quarkus CLI 的最新版本。 此命令还可以用来更新 Quarkus CLI。
安装后,quarkus
将会出现在你的 $PATH
中,如果你运行 quarkus --version
,它将打印已安装的版本:
quarkus --version
{quarkus-version}
您可以使用以下方式升级 Quarkus CLI:
brew update 1
brew upgrade quarkus 2
1 | 更新所有软件包定义和 Homebrew 本身 |
2 | 将 Quarkus CLI 升级到最新版本 |
Chocolatey是针对 Windows 的程序包管理器。 您可以使用 Chocolatey 安装(和更新)Quarkus CLI。
在安装 Quarkus CLI 之前,请确保安装 JDK。 您可以使用 `choco install temurin17`为 Java 17 或 `choco install temurin21`为 Java 21 安装 JDK。 |
若要使用 Chocolatey 安装 Quarkus CLI,请运行以下命令:
choco install quarkus
它将安装 Quarkus CLI 的最新版本。
安装后,quarkus
将会出现在你的 $PATH
中,如果你运行 quarkus --version
,它将打印已安装的版本:
quarkus --version
{quarkus-version}
您可以使用以下方式升级 Quarkus CLI:
choco upgrade quarkus
Scoop 是一个适用于 Windows 的软件包管理器。你可以使用 Scoop 来安装(以及更新)Quarkus CLI。
在安装 Quarkus CLI 之前请确保你已安装了 JDK。你可以通过 |
若要使用 Scoop 安装 Quarkus CLI,请运行以下命令:
scoop install quarkus-cli
它将安装 Quarkus CLI 的最新版本。安装完成,quarkus
将位于你的 $PATH
,且如果你运行 quarkus --version
,它将打印已安装的版本:
quarkus --version
{quarkus-version}
您可以使用以下方式升级 Quarkus CLI:
scoop update quarkus-cli
Using the CLI
使用 --help
以显示所有可用命令的帮助信息:
quarkus --help
Usage: quarkus [-ehv] [--refresh] [--verbose] [--config=CONFIG]
[-D=<String=String>]... [COMMAND]
Options:
--refresh Refresh the local Quarkus extension registry cache
--config=CONFIG Configuration file
-h, --help Display this help message.
-v, --version Print CLI version information and exit.
-e, --errors Display error messages.
--verbose Verbose mode.
-D=<String=String> Java properties
Commands:
create Create a new project.
app Create a Quarkus application project.
cli Create a Quarkus command-line project.
extension Create a Quarkus extension project
build Build the current project.
dev Run the current project in dev (live coding) mode.
test Run the current project in continuous testing mode.
extension, ext Configure extensions of an existing project.
list, ls List platforms and extensions.
categories, cat List extension categories.
add Add extension(s) to this project.
remove, rm Remove extension(s) from this project.
image Build or push project container image.
build Build a container image.
docker Build a container image using Docker.
buildpack Build a container image using Buildpack.
jib Build a container image using Jib.
openshift Build a container image using OpenShift.
push Push a container image.
deploy Deploy application.
kubernetes Perform the deploy action on Kubernetes.
openshift Perform the deploy action on OpenShift.
knative Perform the deploy action on Knative.
kind Perform the deploy action on Kind.
minikube Perform the deploy action on minikube.
registry Configure Quarkus registry client
list List enabled Quarkus registries
add Add a Quarkus extension registry
remove Remove a Quarkus extension registry
info Display project information and verify versions
health (platform and extensions).
update, up, upgrade Suggest recommended project updates with the
possibility to apply them.
version Display CLI version information.
plugin, plug Configure plugins of the Quarkus CLI.
list, ls List CLI plugins.
add Add plugin(s) to the Quarkus CLI.
remove Remove plugin(s) to the Quarkus CLI.
sync Sync (discover / purge) CLI Plugins.
completion bash/zsh completion: source <(quarkus completion)
尽管此文档是一个有用的参考,但客户端帮助是权威来源。
如果你没有看到预期输出,请使用 |
Creating a new project
要创建新项目,请使用 create
命令(如果没有指定,则隐含 app
子命令):
quarkus create
-----------
applying codestarts...
📚 java
🔨 maven
📦 quarkus
📝 config-properties
🔧 dockerfiles
🔧 maven-wrapper
🚀 resteasy-codestart
-----------
[SUCCESS] ✅ quarkus project has been successfully generated in:
--> /<output-dir>/code-with-quarkus
这将在你的当前工作目录中创建一个名为 code-with-quarkus
的文件夹,并使用默认的 groupId
、artifactId
和 version
值(groupId='org.acme'
、artifactId='code-with-quarkus'
和 version='1.0.0-SNAPSHOT'
)。
上面显示的表情可能不完全匹配。表情的外观会随着所使用的字体或终端/环境而有所不同。例如,IntelliJ IDEA 有几个长期未解决的问题,涉及到终端中表情的行为/呈现。 |
你可以使用 group:artifactId:version
坐标语法直接从命令行中指定 groupId
、artifactId
和 version
。你可以有选择地省略片段以使用默认值:
# Create a project with groupId=org.acme, artifactId=bar, and version=1.0.0-SNAPSHOT
quarkus create app bar
# Create a project with groupId=com.foo, artifactId=bar, and version=1.0.0-SNAPSHOT
quarkus create app com.foo:bar
# Create a project with groupId=com.foo, artifactId=bar, and version=1.0
quarkus create app com.foo:bar:1.0
输出将显示你的项目正在创建:
-----------
applying codestarts...
📚 java
🔨 maven
📦 quarkus
📝 config-properties
🔧 dockerfiles
🔧 maven-wrapper
🚀 resteasy-codestart
-----------
[SUCCESS] ✅ quarkus project has been successfully generated in:
--> /<output-dir>/bar
-----------
使用 --help
选项显示创建项目的选项:
quarkus create app --help
quarkus create cli --help
Specifying the Quarkus version
quarkus create
和 quarkus extension list
都允许你以两种方式之一明确指定 Quarkus 版本:
-
指定特定的平台发布 BOMQuarkus Platform release BOM 由
groupId:artifactId:version
(GAV)坐标标识。在指定平台发布 BOM 时,你可以使用空片段回退到默认值(用quarkus create app --help
显示)。如果你仅指定一个片段(没有:
),则假定为一个版本。io.quarkus.platform
是默认groupId
。指定-P :quarkus-bom:
等同于-P io.quarkus.platform:quarkus-bom:${project.version}
。请注意,你必须指定groupId
才能配合使用快照,例如,-P io.quarkus::999-SNAPSHOT
等同于-P io.quarkus:quarkus-bom:999-SNAPSHOT
。 默认值可能会更改。使用--dry-run
选项查看已计算的值。 -
Specify a Platform Stream平台流针对远程注册表进行操作。每个注册表定义了一个或多个平台流,每个流定义了一个或多个平台发布 BOM 文件,其中定义了使用该流的项目应如何配置。 使用
platformKey:streamId
语法标识流。可以使用-S platformKey:streamId
指定特定流。在指定流时,基于流资源解析规则,将用 discovered 默认值替换空段。
Working with extensions
quarkus ext --help
Listing extensions
Quarkus CLI 可用于列出 Quarkus 扩展。
quarkus ext ls
可以使用四个选项之一来控制结果格式:
-
--name
仅显示名称(artifactId) -
--concise
显示名称(artifactId)和说明 -
--full
显示简洁格式和版本/状态相关列。 -
--origins
显示简洁信息以及扩展的 Quarkus 平台发布源。
quarkus ext ls
的行为会因上下文而异。
Listing extensions for a Quarkus release
如果从项目外部调用 Quarkus CLI,Quarkus 将列出 CLI 本身所用的 Quarkus 版本中可用的所有扩展。
你还可以使用 -P
或 -S
列出 Quarkus 的特定版本扩展,如 Specifying the Quarkus version 中所述。
此模式默认使用 --origins
格式。
Listing extensions for a Quarkus project
在使用 Quarkus 项目时,CLI 将列出当前项目安装的扩展,默认使用 --name
格式。
使用 --installable
或 -i
选项列出可从项目使用的 Quarkus 平台安装的扩展。
你可以使用搜索(--search
或 -s
)缩小或筛选列表。
quarkus ext list --concise -i -s jdbc
JDBC Driver - DB2 quarkus-jdbc-db2
JDBC Driver - PostgreSQL quarkus-jdbc-postgresql
JDBC Driver - H2 quarkus-jdbc-h2
JDBC Driver - MariaDB quarkus-jdbc-mariadb
JDBC Driver - Microsoft SQL Server quarkus-jdbc-mssql
JDBC Driver - MySQL quarkus-jdbc-mysql
JDBC Driver - Oracle quarkus-jdbc-oracle
JDBC Driver - Derby quarkus-jdbc-derby
Elytron Security JDBC quarkus-elytron-security-jdbc
Agroal - Database connection pool quarkus-agroal
Build your project
要使用 Quarkus CLI 构建项目(在本示例中使用默认配置),请使用 build
命令:
quarkus build
[INFO] Scanning for projects...
[INFO]
[INFO] ---------------------< org.acme:code-with-quarkus >---------------------
[INFO] Building code-with-quarkus 1.0.0-SNAPSHOT
[INFO] --------------------------------[ jar ]---------------------------------
[INFO]
...
[INFO] ------------------------------------------------------------------------
[INFO] BUILD SUCCESS
[INFO] ------------------------------------------------------------------------
[INFO] Total time: 8.331 s
[INFO] Finished at: 2021-05-27T10:13:28-04:00
[INFO] ------------------------------------------------------------------------
输出会根据项目使用的构建工具(Maven、Gradle 或 JBang)而有所不同。 |
运行 |
Development mode
要从 Quarkus CLI 启动开发模式,请使用 dev
命令:
quarkus dev
[INFO] Scanning for projects...
[INFO]
[INFO] ---------------------< org.acme:code-with-quarkus >---------------------
[INFO] Building code-with-quarkus 1.0.0-SNAPSHOT
[INFO] --------------------------------[ jar ]---------------------------------
[INFO]
...
Listening for transport dt_socket at address: 5005
__ ____ __ _____ ___ __ ____ ______
--/ __ \/ / / / _ | / _ \/ //_/ / / / __/
-/ /_/ / /_/ / __ |/ , _/ ,< / /_/ /\ \
--\___\_\____/_/ |_/_/|_/_/|_|\____/___/
2021-05-27 10:15:56,032 INFO [io.quarkus] (Quarkus Main Thread) code-with-quarkus 1.0.0-SNAPSHOT on JVM (powered by Quarkus 999-SNAPSHOT) started in 1.387s. Listening on: http://localhost:8080
2021-05-27 10:15:56,035 INFO [io.quarkus] (Quarkus Main Thread) Profile dev activated. Live Coding activated.
2021-05-27 10:15:56,035 INFO [io.quarkus] (Quarkus Main Thread) Installed features: [cdi, rest, smallrye-context-propagation]
--
Tests paused, press [r] to resume
输出会根据项目使用的构建工具(Maven、Gradle 或 JBang)而有所不同。 |
运行 |
Shell autocomplete and aliases
Bash 和 Zsh 提供自动命令补全:
# Setup autocompletion in the current shell
source <(quarkus completion)
如果您选择对 quarkus
命令使用别名,请使用以下命令调整命令补全:
# Add an alias for the quarkus command
alias q=quarkus
# Add q to list of commands included in quarkus autocompletion
complete -F _complete_quarkus q
Container images
Quarkus CLI 允许构建容器映像,而不改动项目配置(添加/移除容器映像扩展)。要构建项目映像:
quarkus image build
image build
命令可以直接使用,也可以选择子命令。可用的子命令包括:
-
docker
-
buildpacks
-
jib
-
openshift
每个子命令都对应于由 Quarkus 支持的映像构建工具,并可以访问特定配置选项。
例如,要将 Cloud Native Buildpack 与自定义构建器映像一起使用,请使用以下命令:
quarkus image build buildpack --builder-image <your builder image>
Extending the CLI
Quarkus CLI 嵌入了一个插件系统,可用于向 CLI 动态添加命令和子命令。
What is a plugin
插件可以是任何可执行文件、jar 或 Java 命令,可以在本地找到或远程获取。
插件分类如下:
-
Plugins executed via shell
-
executable(以
quarkus-
为前缀的任何在本地找到的可执行文件) -
Plugins executed via jbang
-
jar(在本地找到的任何可运行的 jar)
-
jbang alias(以
quarkus-
为前缀的任何 jbang 别名,可通过本地安装或 quarkusio 目录安装) -
maven(GACTV 表单中指向可运行 jar 的任何 maven 坐标)
How to obtain plugins
插件可以通过下面描述的多个来源找到。
Extensions
Quarkus 扩展可以将 `cli-plugins`列表定义为其元数据的一部分。该列表可能包含指向可执行 jar 的 GACTV 字符串。
目前,CLI 能够获取可用扩展列表,但对于扩展的确切版本不是非常准确(它使用扩展目录中找到的版本)。
Managing plugins
使用以下命令管理插件。
Listing plugins
以下命令列出已安装的插件:
quarkus plugin list
No plugins installed!
To include the installable plugins in the list, append --installable to the command.
列出可用/可安装插件:
quarkus plugin list --installable
Name Type Scope Location Description
kill jbang user quarkus-kill@quarkusio
* fmt jbang user quarkus-fmt@quarkusio
greeter executable user /home/iocanel/bin/quarkus-greeter
Use the 'plugin add' subcommand and pass the location of any plugin listed above, or any remote location in the form of URL / GACTV pointing to a remote plugin.
`list`命令的输出可以使用 `type`使用 `-t`进行过滤,或使用 `-s`标志和搜索模式按名称过滤。
例如,要列出所有以字母 `k`开头的可安装插件,请使用以下命令:
quarkus plugin list --installable -s "k*"
Name Type Scope Location Description
kill jbang user quarkus-kill@quarkusio
Use the 'plugin add' subcommand and pass the location of any plugin listed above, or any remote location in the form of URL / GACTV pointing to a remote plugin.
Adding plugins
要添加任何可安装插件,请使用 quarkus plugin add <name or location>
:
quarkus plugin add kill
Added plugin:
Name Type Scope Location Description
* kill jbang user quarkus-kill@quarkusio
上面的命令通过 `name`安装了一个插件,使用 `quarkus plugin list --installable`列出的名称。
现在可以使用 `quarkus kill`执行已安装的命令。
用户并不局限于 `quarkus plug list --installable`发现的插件。只要用户提供指向可执行 jar 或 Java 文件的 URL 或 Maven 坐标,用户就可以安装插件。 |
您可以通过 Maven 坐标将可执行 jar 安装为插件。
例如,我们使用 io.quarkiverse.authzed:quarkus-authzed-cli:runner:jar:0.2.0
,这是一个真正的可执行 jar,可为 quarkus-authzed
扩展提供 CLI 实用程序。
quarkus plugin add io.quarkiverse.authzed:quarkus-authzed-cli:runner:jar:0.2.0 -d "Authzed CLI"
Added plugin:
Name Type Location Description
* authzed maven io.quarkiverse.authzed:quarkus-authzed-cli:runner:jar:0.2.0 Authzed CLI
还可以设置将在帮助输出中显示的描述。 |
quarkus --help
Usage: quarkus [-ehv] [--refresh] [--verbose] [--config=CONFIG]
[-D=<String=String>]... [COMMAND]
...
Commands:
...
plugin, plug Configure plugins of the Quarkus CLI.
list, ls List CLI plugins.
add Add plugin(s) to the Quarkus CLI.
remove Remove plugin(s) to the Quarkus CLI.
sync Sync (discover / purge) CLI Plugins.
completion bash/zsh completion: source <(quarkus completion)
authzed Authzed CLI
...
Where are the plugins added?
将插件添加到插件目录中,该目录位于: <user home>/.quarkus/cli/plugins/quarkus-cli-catalog.json
。
有一个第二个插件目录相对于当前项目(如果可用): <project root>/.quarkus/cli/plugins/quarkus-cli-catalog.json
。
有效目录是 user
和 project
目录的组合,后者可以覆盖前者的条目(例如,为插件使用不同的版本或位置)。
如果项目目录可用,它将始终得到优先考虑,除非使用 --user
标志明确指定。
插件表的 scope
列指示插件位于/将被添加到哪里。