RESTEasy Reactiveへの移行
RESTEasy ClassicからRESTEasy Reactiveへの移行は、ほとんどの場合簡単ですが、いくつかの注意が必要なケースがあります。この文書では、移行を試みるユーザが注意すべき問題のリストを提供します。
| RESTEasy Reactiveのリファレンスドキュメントは こちら でご覧いただけます。 |
サーバー
RESTEasy Reactiveのサーバー部分（ quarkus-resteasy-reactive とその依存関係）は、JAX-RS仕様の実装を提供しますが、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 |
|---|---|---|
|
|
パス部分がメソッドパラメータ名と一致する場合は、このアノテーションは必要ありません |
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
The previous table does not include the org.jboss.resteasy.annotations.Form annotation because there is no RESTEasy Reactive specific replacement for it. Users are instead encouraged to use the JAX-RS standard javax.ws.rs.BeanParam annotation which is supported on both the server and the client.
|
JAX-RSプロバイダー
RESTEasy Reactiveは、RESTEasy Classicと同じ仕様に準拠した動作を提供しますが、実行時に同じ正確なプロバイダの実装が含まれているわけではありません。
プロバイダの違いで動作が異なる可能性がある最も一般的なケースは、同梱の javax.ws.rs.ext.ExceptionMapper 実装です。アプリケーションにどのようなクラスが含まれているかを確認するには、開発モードでアプリケーションを起動し、 http://localhost:8080/q/dev/io.quarkus.quarkus-resteasy-reactive/exception-mappers を開いてください。
サービスローディング
RESTEasy Classicは、JavaのService Loaderを使用して、ビルド時にプロバイダを決定することをサポートしています。すべてのプロバイダがビルド時に決定されるようにするため、RESTEasy Reactive はこの機能をサポートしていません。代わりに、アプリケーションの依存関係にプロバイダがあるユーザは、CDI ガイドの Beanディスカバリー セクションで説明されている方法のいずれかを使用して、これらの依存関係のインデックスを作成することが推奨されます。
マルチパート対応
RESTEasy ReactiveのHTTP Multipartサポートは、RESTEasy Classicと同じ型やアノテーションを再利用して いない ため、ユーザーはリファレンスドキュメントの この部分を読むことが推奨されます。
クライアント
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 を使用する必要があります。
Custom extensions
This is an advanced section that only needs to be read by users who have developed custom extensions that depend on JAX-RS and / or REST Client functionality.
依存関係
A first concern is whether custom extensions should depend on RESTEasy Reactive explicitly, or alternatively support both RESTEasy flavors and leave it to the user to decide. If the extension is some general purpose extension, it probably makes sense to choose the latter option, while the former option is easiest to adopt when the custom extension is used by a specific set of users / applications.
When opting for supporting both extensions, the deployment module of the custom extension will usually depend on the SPI modules - quarkus-jaxrs-spi-deployment, quarkus-resteasy-common-spi, quarkus-resteasy-reactive-spi-deployment, while the runtime modules will have optional dependencies on the runtime modules of both RESTEasy flavors.
A couple good examples of how Quarkus uses this strategy to support both RESTEasy flavors in the core repository can be seen [here](https://github.com/quarkusio/quarkus/pull/21089) and [here](https://github.com/quarkusio/quarkus/pull/20874).
In general, it should not be needed to have two different versions of the custom extension to support both flavors. Such a choice is only strictly necessary if it is desired for the extension consumers (i.e. Quarkus applications) to not have to select a RESTEasy version themselves.
Resource and Provider discovery
Custom extensions that contain JAX-RS Resources, Providers or REST Client interfaces in their runtime modules and depend on Jandex indexing for their discovery (for example because they have an empty META-INF/beans.xml file) don’t have to perform any additional setup to make these discoverable by RESTEasy Reactive.
Provider registration via Build Items
Extensions that register providers via build items use the io.quarkus.resteasy.common.spi.ResteasyJaxrsProviderBuildItem build item in RESTEasy Classic. With RESTEasy Reactive however, extensions need to use specific build items, such as io.quarkus.resteasy.reactive.spi.MessageBodyWriterBuildItem and io.quarkus.resteasy.reactive.spi.MessageBodyWriterBuildItem.
