Building Quarkus apps with Quarkus Command Line Interface (CLI)

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

JBang

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}
Example 1. Use a recent JBang version

如果你收到了一个有关 app 不可读的错误,则你可能安装了低于 v0.56.0 的 JBang 版本。请将其移除或升级到最新版本。 如果你正在第一次安装 JBang,则开始一个新的会话来更新你的 PATH

SDKMAN!

SDKMAN! 可用于管理开发环境。它可以在大多数基于 Unix 的系统上管理多个软件开发工具包的并行版本,这使得它成为了非常好的选择,可以方便地使用多个 JDK 版本。 使用 SDKMAN!,你还可以安装流行的 Java 工具,包括 Quarkus CLI。

在安装 Quarkus CLI 之前,请确保你拥有 a JDK installed。 若要列出可用 Java 版本,请使用 sdk list java。然后,可以使用 sdk install java x.y.z-open(或您偏好的另一供应商的 JDK)安装所需的 OpenJDK 版本。

若要使用 SDKMAN! 安装 Quarkus CLI,请运行以下命令:

sdk install quarkus

它将安装 Quarkus CLI 的最新版本。 安装后,quarkus 将会出现在你的 $PATH 中,如果你运行 quarkus --version,它将打印已安装的版本:

quarkus --version
{quarkus-version}

SDKMAN! 会在有新版本时通知,以便轻松更新:

sdk upgrade quarkus
Homebrew

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

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

Scoop 是一个适用于 Windows 的软件包管理器。你可以使用 Scoop 来安装(以及更新)Quarkus CLI。

在安装 Quarkus CLI 之前请确保你已安装了 JDK。你可以通过 scoop install openjdk17 安装适用于 Java 17 的 JDK,也可以通过 scoop install openjdk21 安装适用于 Java 21 的 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)

尽管此文档是一个有用的参考,但客户端帮助是权威来源。 如果你没有看到预期输出,请使用 --help 验证你是否已使用正确的参数调用命令。

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 的文件夹,并使用默认的 groupIdartifactIdversion 值(groupId='org.acme'artifactId='code-with-quarkus'version='1.0.0-SNAPSHOT')。

上面显示的表情可能不完全匹配。表情的外观会随着所使用的字体或终端/环境而有所不同。例如,IntelliJ IDEA 有几个长期未解决的问题,涉及到终端中表情的行为/呈现。

你可以使用 group:artifactId:version 坐标语法直接从命令行中指定 groupIdartifactIdversion。你可以有选择地省略片段以使用默认值:

# 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 createquarkus extension list 都允许你以两种方式之一明确指定 Quarkus 版本:

  1. 指定特定的平台发布 BOMQuarkus Platform release BOMgroupId: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 选项查看已计算的值。

  2. 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

Adding extensions

Quarkus CLI 可通过 add 子命令向项目中添加一个或多个扩展:

quarkus ext add kubernetes health
[SUCCESS] ✅ Extension io.quarkus:quarkus-kubernetes has been installed
[SUCCESS] ✅ Extension io.quarkus:quarkus-smallrye-health has been installed

你可以安装与 glob 模式匹配的所有扩展:

quarkus ext add smallrye-*

Removing extensions

使用 Gemin,可通过 remove/rm 子命令从项目中删除一个或多个扩展:

quarkus ext rm kubernetes
[SUCCESS] ✅ Extension io.quarkus:quarkus-kubernetes has been uninstalled

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)而有所不同。

运行 quarkus build --clean,以作为构建的一部分执行清理。

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)而有所不同。

运行 quarkus dev --clean,以作为构建的一部分执行清理。

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>

Pushing

image push 命令类似于 image build,提供了一些将映像推送至目标容器注册表所需的基本选项。

quarkus image push --registry=<image registry> --registry-username=<registry username> --registry-password-stdin

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 能够获取可用扩展列表,但对于扩展的确切版本不是非常准确(它使用扩展目录中找到的版本)。

Local path scanning

扫描以 `quarkus-`为前缀的可执行文件路径元素。

Using JBang aliases

扫描本地或项目 jbang 目录以查找以 `quarkus-`为前缀的别名。

Using the JBang quarkusio catalog

扫描 `quarkusio`目录以查找以 `quarkus-`为前缀的别名。

使用 JBang 二进制文件。如果缺少,它将在 `.jbang`下自动安装。

Explicitly using the plugin commands

请参见下面的 quarkus plugin add

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

有效目录是 userproject 目录的组合,后者可以覆盖前者的条目(例如,为插件使用不同的版本或位置)。

如果项目目录可用,它将始终得到优先考虑,除非使用 --user 标志明确指定。

插件表的 scope 列指示插件位于/将被添加到哪里。

Removing plugins

使用 quarkus plugin remove <plugin name> 删除插件。

quarkus plugin remove kill
Removed plugin:
    Name 	 Type  	 Scope 	 Location               	 Description
    kill 	 jbang 	 user  	 quarkus-kill@quarkusio

Syncing plugins

若要删除过时的插件或发现扩展提供的新的插件,可以使用 quarkus plugin sync 命令。此命令将清除添加到目录中但不再可用的二进制文件和 JBang 别名。

用户使用 URL/Maven 坐标明确添加的远程插件从删除中排除。

还可通过任何 CLI 命令隐式执行此命令:

  • Weekly

  • 自上次目录更新以来,如果项目文件已更新(仅限于模块)。