RESTEasy Reactiveへの移行
RESTEasy ClassicからRESTEasy Reactiveへの移行は、ほとんどの場合簡単ですが、いくつかの注意が必要なケースがあります。この文書では、移行を試みるユーザが注意すべき問題のリストを提供します。
RESTEasy Reactiveのリファレンスドキュメントは こちら でご覧いただけます。 |
サーバー
RESTEasy Reactiveのサーバー部分( quarkus-resteasy-reactive
とその依存関係)は、Jakarta REST仕様の実装を提供しますが、Quarkusのビルド時処理とVert.xが提供する統一I/Oモデルを活用しています。
依存関係
次の表は、従来のRESTEasyの依存関係と新しいRESTEasy Reactiveの依存関係を対応付けたものです。
Legacy | RESTEasy Reactive |
---|---|
|
|
|
|
|
|
|
|
|
|
quarkus-resteasy-mutiny は、RESTEasy Reactive が Mutiny の統合を最初から提供するため、対応する依存関係がありません。
|
アノテーション
RESTEasy Reactiveは、 org.jboss.resteasy.annotations
パッケージの各種カスタムアノテーションには対応していません。
次の表は、従来のRESTEasyアノテーションと新しいRESTEasy Reactiveアノテーションを対応させたものです。
Legacy | RESTEasy Reactive | Comments |
---|---|---|
|
|
パス部分がメソッドパラメータ名と一致する場合は、このアノテーションは必要ありません |
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
org.jboss.resteasy.annotations.Form アノテーションは、RESTEasy Reactive固有の代替品がないため、前の表には含まれていません。その代わりに、サーバーとクライアントの両方でサポートされているJakarta REST標準の jakarta.ws.rs.BeanParam アノテーションを使用することが推奨されます。
|
Jakarta RESTプロバイダー
RESTEasy Reactiveは、RESTEasy Classicと同じ仕様に準拠した動作を提供しますが、実行時に正確に同じプロバイダの実装が含まれているわけではありません。
プロバイダーの違いによって動作が異なる可能性がある最も一般的なケースは、含まれる jakarta.ws.rs.ext.ExceptionMapper
の実装です。アプリケーションに含まれるクラスを確認するには、開発モードでアプリケーションを起動し、 http://localhost:8080/q/dev-ui/io.quarkus.quarkus-resteasy-reactive/exception-mappers に移動します。
サービスローディング
RESTEasy Classicは、JavaのService Loaderを使用して、ビルド時にプロバイダを決定することをサポートしています。すべてのプロバイダがビルド時に決定されるようにするため、RESTEasy Reactive はこの機能をサポートしていません。代わりに、アプリケーションの依存関係にプロバイダがあるユーザは、CDI ガイドの Beanディスカバリー セクションで説明されている方法のいずれかを使用して、これらの依存関係のインデックスを作成することが推奨されます。
マルチパート対応
RESTEasy ReactiveのHTTP Multipartサポートは、RESTEasy Classicと同じ型やアノテーションを再利用 しない ため、ユーザーはリファレンスドキュメントの この 部分を読むことが推奨されます。
multipart リソースを RESTEasy Reactive に移行するユーザーは、設定パラメータ quarkus.http.limits.max-form-attribute-size に注意する必要があります。これにより、各パートのサイズに上限が設定されるためです。 この設定値を超えるパーツ サイズのリクエストは、HTTP ステータス コード 413 になります。
|
クライアント
Reactive REST Client ( quarkus-rest-client-reactive
とその依存関係) は、レガシー quarkus-rest-client
を置き換えるものですが、Quarkus のビルド時処理と Vert.x が提供する統一 I/O モデルを活用します。
依存関係
次の表は、従来の REST Client の依存関係と、新しい Reactive REST Client の依存関係を対応付けたものです。
Legacy | RESTEasy Reactive |
---|---|
|
|
|
|
|
|
|
|
Keycloak adminクライアント
quarkus-rest-client
を使用する場合、ユーザーは quarkus-keycloak-admin-client
を使用して、RESTクライアントを活用してターゲットのKeycloakインスタンスを管理することができます。
一方、 quarkus-rest-client-reactive
を使用する場合、ユーザーは同じ機能にアクセスするために quarkus-keycloak-admin-client-reactive
を使用し、reactive REST Client を使用する必要があります。
OIDC
quarkus-rest-client
を使用する場合、ユーザーは quarkus-oidc-client-filter
エクステンションを使用して、OpenID Connect および OAuth 2.0 準拠の Authorization Server からアクセストークンを取得し、更新することができます。
一方、 quarkus-rest-client-reactive
を使用する場合、同じ機能を利用するためには、 quarkus-oidc-client-filter-reactive
を使用する必要があります。
同様に、 quarkus-oidc-token-propagation
は、従来の REST のユーザーが現在の Bearer
または Authorization Code Flow
のアクセストークンを伝搬することを可能にします。
一方、 quarkus-rest-client-reactive
を使用する場合、同じ機能を利用するためには、 quarkus-oidc-token-propagation-reactive
を使用する必要があります。
カスタムエクステンション
このセクションは、Jakarta RESTおよび/またはREST Client機能に依存するカスタムエクステンションを開発したユーザーだけが読む必要のある高度なセクションです。
依存関係
カスタムエクステンションはRESTEasy Reactiveに明示的に依存するか、RESTEasyの両方のフレーバーをサポートし、ユーザーの判断に委ねるかが最初の関心事です。エクステンションが汎用的なものであれば、後者のオプションを選択することが理にかなっていると思われます。
両方のエクステンションをサポートすることを選択した場合、カスタムエクステンションのデプロイメントモジュールは通常、SPIモジュール - quarkus-jaxrs-spi-deployment
, quarkus-resteasy-common-spi
, quarkus-resteasy-reactive-spi-deployment
に依存し、ランタイムモジュールは両方のRESTEasyフレーバーのランタイムモジュールに optional
依存することになります。
Quarkusがこの戦略を用いて、コアリポジトリでRESTEasyの両方のフレーバーをサポートしている好例は、 [こちら](https://github.com/quarkusio/quarkus/pull/21089) と [こちら] (https://github.com/quarkusio/quarkus/pull/20874) にあります。
一般に、両方のフレーバーをサポートするために、カスタムエクステンションの2つの異なるバージョンを用意する必要はないはずです。このような選択が厳密に必要なのは、エクステンションの消費者(Quarkusアプリケーションなど)がRESTEasyのバージョンを自分で選択する必要がない場合のみです。
リソースとプロバイダーのディスカバリー
Jakarta REST Resources、Providers、REST Clientインターフェースを実行時モジュールに含み、Jandexインデックスに依存するカスタムエクステンションは(例えば、空の META-INF/beans.xml
ファイルを持つため)、RESTEasy Reactiveでこれらを検出できるようにするための追加設定を行う必要はありません。
ビルドアイテムによるプロバイダー登録
ビルド アイテムを介してプロバイダーを登録するエクステンションは、RESTEasy Classicの io.quarkus.resteasy.common.spi.ResteasyJaxrsProviderBuildItem
ビルド アイテムを使用します。 ただし、RESTEasy Reactive では、エクステンションは io.quarkus.resteasy.reactive.spi.MessageBodyWriterBuildItem
や io.quarkus.resteasy.reactive.spi.MessageBodyWriterBuildItem
などの特定のビルド アイテムを使用する必要があります。