Quarkusエクステンションの使い方徹底ガイド
はじめに
Quarkusエクステンションは、アプリケーションに機能を追加・削除できる仕組みです。今回はQuarkusエクステンションの使い方にフォーカスして手順やバージョンの考え方を紹介します。
この記事は、Quarkus in Actionのサンプルアプリケーションを使ってQuarkusの機能を紹介するシリーズの4回目です。
第1回 SDKMANを使ってQuarkusを学習するための環境を整備する
第2回 GraalVMを使ってQuarkusアプリケーションからネイティブイメージを生成する
第3回 Quarkusアプリケーションをコンテナー化する方法
本記事に登場するQuarkus CLIのインストール方法や実行環境については第1回の記事をご覧ください。
Quarkus CLIのタブ補完
Quarkus CLIのコマンドを使うときにタブ補完の設定を.bashrcにしておくとコマンド入力が簡単になります。この記事では、quarkus extensionという長めのコマンドを使うので最初に紹介しておきますね。
$ echo 'source <(quarkus completion)' >> ~/.bashrc
$ source ~/.bashrcQuarkusエクステンションとは
Quarkusエクステンションは、Quarkusアプリケーションの機能を拡張するためのモジュールです。
エクステンションの典型的な例としてはO/RマッピングにつかうHibernateや、RESTサーバーやクライアントを実装するときに使うRESTEasyのようなものがあります。
Quarkusエクステンションの探し方
Quarkusはたくさんのエクステンションを提供しています。この記事を書いている時点で746個のエクステンションが https://quarkus.io/extensions/ 上で公開されています。
たとえば、RESTを実装するための quarkus-rest エクステンションを選択するには、上のWebサイトから検索フィールドで "REST" を入力して検索すると見つかります。
検索結果から [REST] をクリックすると、quarkus-rest エクステンションの詳細情報（バージョンやガイド、Javadoc、リポジトリなど）が表示されます。
Quarkusエクステンションの使い方は、上のWebページのガイドのリンクをクリックすると表示されます。言語メニューで「日本語」に切り替えると以下のように日本語で表示されます。
参考
Quarkus公式サイトの日本語版のソースはGitHub上で公開されています。
Quarkusエクステンションを含むアプリケーションの作り方
Quarkus CLIを使う場合
過去の記事でも何度も触れていますが、quarkus crate appコマンドを使ってアプリケーションプロジェクト作成時に --extension オプションを使うことでエクステンションを指定することができます。
$ quarkus create app org.acme:quarkus-in-action --extension quarkus-restこれにより、アプリケーションのpom.xmlに quarkus-rest の依存関係が以下のように追加されます。
<dependency>
<groupId>io.quarkus</groupId>
<artifactId>quarkus-rest</artifactId>
</dependency>CLIエクステンションを検索するには、quarkus extention categoriesコマンドでカテゴリを表示します。
$ quarkus extension categories
Available Quarkus extension categories:
alt-languages
ai
business-automation
cloud
compatibility
core
data
integration
messaging
miscellaneous
observability
reactive
security
serialization
web
grpc
To get more information, append `--full` to your command line.
To list extensions in given category, use:
`quarkus extension list --installable --category "categoryId"`
TIPS
タブ補完の設定をしていれば、quarkus extention categoriesとタイプする代わりに、qua<TAB> exte<TAB> cate<TAB>で入力できます。extensionコマンドにはextという短縮形が、categoriesにはcatという短縮系があるので、qua<TAB> ext catでもOKです。
カテゴリに含まれるエクステンションのリストの詳細は、quarkus extension list --installable --category "categoryId"とします。messagingカテゴリに含まれるエクステンションのリストは以下のようになります。
$ quarkus extension list --installable --category messaging
Current Quarkus extensions installable:
✬ ArtifactId Extension Name
citrus-quarkus Citrus
quarkus-artemis-core Artemis Core
quarkus-artemis-jms Artemis JMS
✬ quarkus-google-cloud-pubsub Google Cloud Pubsub
quarkus-hivemq-client Quarkus - HiveMQ Client
✬ quarkus-kafka-client Apache Kafka Client
✬ quarkus-kafka-streams Apache Kafka Streams
quarkus-kafka-streams-processor Kafka Streams Processor
✬ quarkus-messaging Messaging
✬ quarkus-messaging-amazon-sqs Messaging - Amazon SQS Connector
✬ quarkus-messaging-amqp Messaging - AMQP Connector
✬ quarkus-messaging-kafka Messaging - Kafka Connector
✬ quarkus-messaging-mqtt Messaging - MQTT Connector
quarkus-messaging-nats-jetstream Reactive Messaging Nats Jetstream
✬ quarkus-messaging-pulsar Messaging - Pulsar Connector
✬ quarkus-messaging-rabbitmq Messaging - RabbitMQ Connector
✬ quarkus-qpid-jms AMQP 1.0 JMS client - Apache Qpid JMS
quarkus-rabbitmq-client RabbitMQ Client
quarkus-reactive-messaging-http Reactive HTTP and WebSocket Connector
quarkus-reactive-messsaging-nats-jetstream Reactive Messsaging Nats Jetstream
To get more information, append `--full` to your command line.
Add an extension to your project by adding the dependency to your pom.xml or use `quarkus extension add "artifactId"`
エクステンションの詳細を知りたい場合は、上のコマンドに --full オプションをつけます。エクステンションのバージョンや（エクステンションの使い方を説明した）ガイドのリンクが表示されます。
$ quarkus extension list --installable --category messaging --full
Current Quarkus extensions installable:
✬ ArtifactId Extension Version Guide
citrus-quarkus Citrus 4.5.2 https://github.com/christophd/citrus-demo-quarkus
quarkus-artemis-core Artemis Core 3.6.1 https://docs.quarkiverse.io/quarkus-artemis/dev/index.html
quarkus-artemis-jms Artemis JMS 3.6.1 https://docs.quarkiverse.io/quarkus-artemis/dev/index.html
✬ quarkus-google-cloud-pubsub Google Cloud Pubsub 2.14.0 https://quarkiverse.github.io/quarkiverse-docs/quarkus-google-cloud-services/main/pubsub.html
quarkus-hivemq-client Quarkus - HiveMQ Client 2.3.0 https://quarkiverse.github.io/quarkiverse-docs/quarkus-hivemq-client/dev/index.html
✬ quarkus-kafka-client Apache Kafka Client 3.18.1 https://quarkus.io/guides/kafka
✬ quarkus-kafka-streams Apache Kafka Streams 3.18.1 https://quarkus.io/guides/kafka-streams
quarkus-kafka-streams-processor Kafka Streams Processor 4.0.3 https://docs.quarkiverse.io/quarkus-kafka-streams-processor/dev/index.html
✬ quarkus-messaging Messaging 3.18.1 https://quarkus.io/guides/messaging
✬ quarkus-messaging-amazon-sqs Messaging - Amazon SQS Connector 2.20.0 https://docs.quarkiverse.io/quarkus-amazon-services/dev/amazon-sqs.html
✬ quarkus-messaging-amqp Messaging - AMQP Connector 3.18.1 https://quarkus.io/guides/amqp
✬ quarkus-messaging-kafka Messaging - Kafka Connector 3.18.1 https://quarkus.io/guides/kafka-getting-started
✬ quarkus-messaging-mqtt Messaging - MQTT Connector 3.18.1
quarkus-messaging-nats-jetstream Reactive Messaging Nats Jetstream 3.17.15 https://docs.quarkiverse.io/quarkus-reactive-messaging-nats-jetstream/dev/
✬ quarkus-messaging-pulsar Messaging - Pulsar Connector 3.18.1 https://quarkus.io/guides/pulsar
✬ quarkus-messaging-rabbitmq Messaging - RabbitMQ Connector 3.18.1 https://quarkus.io/guides/rabbitmq
✬ quarkus-qpid-jms AMQP 1.0 JMS client - Apache Qpid JMS 2.7.1 https://quarkus.io/guides/jms
quarkus-rabbitmq-client RabbitMQ Client 3.2.1
quarkus-reactive-messaging-http Reactive HTTP and WebSocket Connector 2.4.1
quarkus-reactive-messsaging-nats-jetstream Reactive Messsaging Nats Jetstream 1.11.0 https://docs.quarkiverse.io/quarkus-reactive-messsaging-nats-jetstream/dev/
Add an extension to your project by adding the dependency to your pom.xml or use `quarkus extension add "artifactId"`
Webサイトを使う場合
Webサイト(https://code.quarkus.io/)から対話的にプロジェクトを作成することもできます。
画面左上のQUARKUSの文字の右隣にバージョン選択メニューがあります。デフォルトでは最新版が選択されています。
code.quarkus.ioの画面のSearch from an extensions presentの表示の下に、よく使うエクステンションがアイコンとして表示されています。Seachフィールドで検索文字列を入力して望みのエクステンションを探すこともできます。
[REST Service] のアイコンをクリックするとRESTのエクステンションがアプリケーションに含まれるようになります。
ここで、[Generate your application] ボタンを押すと、アプリケーションのプロジェクトをZipでダウンロードできます。
メニューから [Download as a zip] を選択すると以下の画面が表示されますので、[DOWNLOAD THE ZIP] を押してZIPファイルをダウンロードします。
Quarkusエクステンションの追加と削除
既存のプロジェクトにあとからエクステンションを追加するには quarkus extension add コマンドを使います。例えば、プロジェクトに quarkus-messaging-kafka エクステンションを追加したい場合、以下のようにします。
$ quarkus extension add "quarkus-messaging-kafka"こうすることで、以下の依存関係がpom.xmlに追加されます。
<dependency>
<groupId>io.quarkus</groupId>
<artifactId>quarkus-messaging-kafka</artifactId>
</dependency>プロジェクトからエクステンションを削除するにはquarkus extension removeコマンドを使います。
$ quarkus extension remove "quarkus-messaging-kafka"Quarkusのバージョン管理
Quarkusのバージョンはどこで設定されているか
Quarkusは内部でMavenを使ってJavaライブラリの依存関係を管理をしています。Mavenにおける依存関係やプラグインを管理する設定ファイルがpom.xmlです。pom.xmlはアプリケーションプロジェクトの直下に置かれています。
$ tree -L 2 quarkus-in-action/
quarkus-in-action/
├── META-INF
│ └── MANIFEST.MF
├── README.md
├── mvnw
├── mvnw.cmd
├── pom.xml
└── src
├── main
└── testアプリケーションが使っているQuarkusのバージョン文字列は、このpom.xmlに書かれています。pom.xmlを見ると先頭の方の<properties>内の<quarkus.platform.version>にQuarkusのバージョンが書かれています。この例ではアプリケーションが使っているQuarkusのバージョンが3.18.1であることがわかります。
<quarkus.platform.artifact-id>quarkus-bom</quarkus.platform.artifact-id>
<quarkus.platform.group-id>io.quarkus.platform</quarkus.platform.group-id>
<quarkus.platform.version>3.18.1</quarkus.platform.version>
pom.xmlはプロジェクト作成時に生成されるので、アプリケーションが使用するQuarkusのバージョンが決まるのはプロジェクト作成時です。
ここで登場するquarkus.platformについては以下に説明があります。
Quarkusエクステンションのバージョンはどこで指定されているか
Quarkusエクステンションを追加することによって、pom.xmlに以下が追加されたことを思い出してください。ここにエクステンションのバージョンは書かれていません。
<dependency>
<groupId>io.quarkus</groupId>
<artifactId>quarkus-rest</artifactId>
</dependency>Quarkusのバージョンと、Quarkusエクステンションのバージョンの関係はどうなっているでしょうか？
QuarkusのバージョンはBOMで管理されます。 BOM（Bill of Materials）とは、複数の依存関係のバージョンを一元管理するための POM ファイル です。pom.xmlで調べた<quarkus.platform.version>はこのBOMのバージョンになります。具体的にどのようになっているか、Maven Central Repostoryに登録されているquarkus-bomのバージョン3.18.1の内容を調べてみましょう。
BOMにはQuarkus 3.18.1で使う依存ライブラリのバージョンが明記されています。このBOMにQuarkusエクステンションのバージョンも定義されています。以下を見るとquarkus-restエクステンションのバージョンが3.18.1であることがわかります。
こうして、アプリケーションのpom.xmlに記されたQuarkusのバージョンによって、そこで使われるエクステンションのバージョンは自動的に決まることがわかりました。
参考
Mavenのpom.xmlに定義されたライブラリはさらに他のライブラリに依存していることが多いです。ライブラリAがライブラリBに依存するとは、ライブラリAのJARに含まれるpom.xmlを見ると、そこにライブラリBが依存関係として宣言されているということです。ここで、さらにライブラリBがライブラリCに依存すると、A→B→Cのような依存関係になります。このようなライブラリ間の関係を推移的依存関係と言います。
pom.xmlの推移的依存関係を展開したものをEffective POMと言います。これがアプリケーション依存ライブラリをすべて含んだ最終形のPOMになります。Effective POMの依存関係にはBOMで定義したバージョンが埋め込まれます。当該アプリケーションのQuarkusが使うすべてのライブラリのバージョンを調べたい場合は、Effective POMを確認してください。
Effective POMは、以下のコマンドで表示することができます。BOMのバージョンを変更して、それがEffective POMにどのように反映されるか調べてみてください。
$ mvn help:effective-pom
Quarkusのバージョン管理はBOMにまかせる
ここまでの説明を整理すると、QuarkusエクステンションのMavenの依存管理は以下のようになっています。
Quarkusエクステンションは、それを実現するための依存関係をアプリケーションのpom.xmlに追加する。この時点でpom.xmlに追加されたエクステンションにはバージョンは指定されてない。
プロジェクトに追加されたQuarkusエクステンションの実際のバージョンは、アプリケーションのpom.xmlで指定されたBOMのバージョンによって決まる。
注意
Quarkus 3.18.1のアプリケーションのpom.xmlを手で編集して、エクステンションにバージョン3.17.8を指定したら、実際には指定された3.17.8の方のバージョンが使われてしまいます。しかし、このような指定をすると、Quarkus Coreとエクステンションの非互換の問題が発生する可能性があります。依存関係のバージョン管理はBOMの設定にまかせるのがベストプラクティスです。
<dependency>
<groupId>io.quarkus</groupId>
<artifactId>quarkus-rest</artifactId>
<version>3.17.8</version> <!--- このような指定はしないで! -->
</dependency>
Quarkusのバージョンを確認する
アプリケーションが使っているQuarkusバージョンを調べたいときは、pom.xmlを見ればわかりますが、quarkus infoコマンドによって、そのアプリケーションで指定されたQuarkusのバージョンを調べることもできます。
注意
quarkus versionコマンドは、Quarkus CLIのバージョンを表示します。これはアプリケーションが使っているQuarkusのバージョンとは別のものです。
$ quarkus version
3.17.7
Quarkusのバージョンを更新する
アプリケーションで使うQuarkusのバージョンを更新するには、quarkus updateコマンドを使います。以下の例では、ログを見ると、Quarkusのバージョンが3.17.8が3.18.1に変更されています。オプションでターゲットバージョンを指定することも可能です（quarkus update -hで調べられます）。
注意
当然ながら、Quarkusバージョンの更新によってはアプリケーションがビルドエラーになったり、動作しなくなることがありますので、Quarkusのリリースノート等のドキュメントを見て、アップデートの影響を検討してから実施してください。
pom.xmlにおいて、アップデート後のBOMのバージョンを確認すると、たしかに3.18.1に変更されています。
まとめ
この記事ではQuarkusエクステンションの使い方を詳細に説明しました。また、Quarkusのバージョン管理の考え方も一緒に解説しました。QuarkusではBOMを使ってライブラリ間の整合性を保っています。
Quarkusアプリケーションの作成方法
Quarkusアプリケーションの検索方法
Quarkusプロジェクトへのエクステンションの追加・削除の方法
Quarkusアプリケーションのバージョンの確認方法
Quarkusアプリケーションの更新方法
QuarkusガイドやQuarkus in Actionなどの本では、Mavenライブラリの管理の仕組みを知っていることが大前提になっていると思います。これらのドキュメントを書いているのはQuarkus開発者なので、pomx.mlを見ればわかることを丁寧に説明はしてくれません。
しかし、Javaは知っていてもMavenはそれほど詳しくないという開発者も多いと思います。Maven BOMに馴染みのない方にとって本記事が少しでも参考になると嬉しいです。