The English version of quarkus.io is the official project site. Translated sites are community supported on a best-effort basis.

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

quarkus-resteasy-reactive

quarkus-resteasy-jackson

quarkus-resteasy-reactive-jackson

quarkus-resteasy-jsonb

quarkus-resteasy-reactive-jsonb

quarkus-resteasy-jaxb

quarkus-resteasy-reactive-jaxb

quarkus-resteasy-qute

quarkus-resteasy-reactive-qute

quarkus-resteasy-mutiny は、RESTEasy Reactive が Mutiny の統合を最初から提供するため、対応する依存関係がありません。

アノテーション

RESTEasy Reactiveは、 org.jboss.resteasy.annotations パッケージの各種カスタムアノテーションには対応していません。

次の表は、従来のRESTEasyアノテーションと新しいRESTEasy Reactiveアノテーションを対応させたものです。

Legacy RESTEasy Reactive Comments

org.jboss.resteasy.annotations.jaxrs.PathParam

org.jboss.resteasy.reactive.RestPath

パス部分がメソッドパラメータ名と一致する場合は、このアノテーションは必要ありません

org.jboss.resteasy.annotations.jaxrs.QueryParam

org.jboss.resteasy.reactive.RestQuery

org.jboss.resteasy.annotations.jaxrs.FormParam

org.jboss.resteasy.reactive.RestForm

org.jboss.resteasy.annotations.jaxrs.HeaderParam

org.jboss.resteasy.reactive.RestHeader

org.jboss.resteasy.annotations.jaxrs.CookieParam

org.jboss.resteasy.reactive.RestCookie

org.jboss.resteasy.annotations.jaxrs.MatrixParam

org.jboss.resteasy.reactive.RestMatrix

org.jboss.resteasy.annotations.cache.Cache

org.jboss.resteasy.reactive.Cache

org.jboss.resteasy.annotations.cache.NoCache

org.jboss.resteasy.reactive.NoCache

org.jboss.resteasy.annotations.SseElementType

org.jboss.resteasy.reactive.RestStreamElementType

org.jboss.resteasy.annotations.Separator

org.jboss.resteasy.reactive.Separator

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 になります。

デフォルトのメディアタイプ

Quarkusでは、一般的なユースケースで簡単に使えるようにするために、Jakarta RESTメソッドのメディアタイプを決定する際にスマートデフォルトを使用しています。 quarkus-resteasy-reactivequarkus-resteasy の違いは、メソッドが String を返すときに、 text/html の代わりに text/plain をデフォルトのメディアタイプとして使用することです。

サーブレット

RESTEasy Reactiveはサーブレットをサポートして いません 。 プロジェクトが servlet に依存している場合は、それらを移行する必要があります。 サーブレット・ベースの JAX-RS 実装では、 @Context アノテーションを使用して、これらの型の注入をサポートする必要があります: ServletConfigServletContextHttpServletRequest 、および HttpServletResponse 。 RESTEasy Reactive はサーブレットベースではないため、これらの注入は機能しません。

特に、 quarkus-undertow のような、インターフェイスを提供するエクステンションに依存している場合、これが失敗するとは限りません。 たとえば、これをコンパイル出来ても、呼び出すときに例外が発生します:

@Path("/reactive")
public class ReactiveResource {

    @Context
    HttpServletRequest httpServletRequest;

    @GET
    @Produces(MediaType.TEXT_PLAIN)
    public String servletContextPath() {

        String contextPath = httpServletRequest.getContextPath();

        return "My context path is: " + contextPath;
    }
}

サードパーティのライブラリも同様です。もしそれらがサーブレットに依存しているのであれば、移行パスを見つける必要があります。

Log authentication and authorization failures

The RESTEasy Reactive endpoint security checks are performed before CDI interceptors are invoked. The safest approach to log Quarkus Security authentication exceptions is to ensure that proactive authentication is enabled and to use Vert.x HTTP route failure handlers. For more information, see the Customize authentication exception responses section of the Proactive authentication guide.

クライアント

The Reactive REST Client (quarkus-rest-client-reactive and its dependencies) replaces the legacy quarkus-resteasy-client and leverages Quarkus' build time processing and the unified I/O model provided by Vert.x.

依存関係

次の表は、従来の REST Client の依存関係と、新しい Reactive REST Client の依存関係を対応付けたものです。

Legacy RESTEasy Reactive

quarkus-resteasy-client

quarkus-rest-client-reactive

quarkus-resteasy-client-jackson

quarkus-rest-client-reactive-jackson

quarkus-resteasy-client-jsonb

quarkus-rest-client-reactive-jsonb

quarkus-resteasy-client-jaxb

quarkus-rest-client-reactive-jaxb

quarkus-resteasy-client-mutiny

No replacement, natively supports Mutiny

Keycloak adminクライアント

When using quarkus-resteasy-client, users can use the quarkus-keycloak-admin-client to administer the target Keycloak instance by leveraging the rest client.

一方、 quarkus-rest-client-reactive を使用する場合、ユーザーは同じ機能にアクセスするために quarkus-keycloak-admin-client-reactive を使用し、reactive REST Client を使用する必要があります。

OIDC

When using quarkus-resteasy-client, users can use the quarkus-oidc-client-filter extensions to acquire and refresh access tokens from OpenID Connect and OAuth 2.0 compliant Authorization Servers.

一方、 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.MessageBodyWriterBuildItemio.quarkus.resteasy.reactive.spi.MessageBodyWriterBuildItem などの特定のビルド アイテムを使用する必要があります。

RESTクライアント

REST クライアントを使用する Quarkus アプリケーションの一部として実行されるコードは、アプリケーションの static-init フェーズで必要な設定がすべて完了しているため、Reactive REST クライアントを安全に使用できます。

関連コンテンツ