Quarkus REST (旧 RESTEasy Reactive) への移行
RESTEasy Classicから Quarkus REST (旧: RESTEasy Reactive) への移行は、ほとんどの場合簡単ですが、いくつかの注意が必要なケースがあります。 この文書では、移行を試みるユーザが注意すべき問題のリストを提供します。
| Quarkus REST のリファレンスドキュメントは こちら にあります。 |
サーバー
Quarkus REST (旧: RESTEasy Reactive) のサーバー部分 ( quarkus-resteasy-reactive とその依存関係) は、Jakarta REST仕様の実装を提供しますが、
Quarkusのビルド時処理とVert.xが提供する統一I/Oモデルを活用しています。
依存関係
次の表は、従来の RESTEasy 依存関係と新しい Quarkus REST 依存関係を対応付けています。
| Legacy | Quarkus REST |
|---|---|
|
|
|
|
|
|
|
|
|
|
quarkus-resteasy-mutiny は、Quarkus REST が Mutiny のインテグレーションを最初から提供するため、対応する依存関係がありません。
|
アノテーション
Quarkus REST は、 org.jboss.resteasy.annotations パッケージの各種カスタムアノテーションには対応していません。
次の表は、従来の RESTEasy アノテーションと新しい Quarkus REST アノテーションを対応させたものです。
| Legacy | Quarkus REST | Comments |
|---|---|---|
|
|
パス部分がメソッドパラメータ名と一致する場合は、このアノテーションは必要ありません |
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
前の表には org.jboss.resteasy.annotations.Form アノテーションは含まれていません。これは、Quarkus REST 固有の代替が存在しないためです。
代わりに、サーバーとクライアントの両方でサポートされている Jakarta REST 標準の jakarta.ws.rs.BeanParam アノテーションを使用することを推奨します。
|
Jakarta RESTプロバイダー
Quarkus REST は RESTEasy Classic と同じ仕様に準拠した動作を提供しますが、実行時にまったく同じプロバイダー実装は含まれません。
プロバイダの違いによって動作が異なる最も一般的なケースは、 jakarta.ws.rs.ext.ExceptionMapper の実装です。アプリケーションに含まれるクラスを確認するには、開発モードでアプリケーションを起動し、 http://localhost:8080/q/dev-ui/quarkus-rest/exception-mappers を開いてください。
サービスローディング
RESTEasy Classic は、すべてのプロバイダーがビルド時に決定されるように、Java のサービスローダーを使用してビルド時にプロバイダーを決定するサポートを提供します。 Quarkus REST はこの機能をサポートしていません。代わりに、アプリケーションの依存関係にプロバイダーを持つユーザーは、それらの依存関係をインデックス化することが推奨されます。 CDI ガイドの Bean Discovery セクションで説明されている方法のいずれかを使用します。
マルチパート対応
Quarkus REST の HTTP マルチパートサポートは、RESTEasy Classic と同じ型やアノテーションを再利用しないため、ユーザーには、this リファレンスドキュメントの一部を参照することを推奨します。
マルチパートリソースを Quarkus REST に移行するユーザーは、各パーツのサイズに上限を設定する設定パラメーター quarkus.http.limits.max-form-attribute-size に注意する必要があります。
この設定値を超える部分サイズのリクエストには、HTTP ステータスコード 413 が返されます。
|
デフォルトのメディアタイプ
Quarkusでは、一般的なユースケースで簡単に使えるようにするために、Jakarta RESTメソッドのメディアタイプを決定する際にスマートデフォルトを使用しています。
quarkus-rest と quarkus-resteasy の違いは、メソッドが String を返すときに、
text/html の代わりに text/plain をデフォルトのメディアタイプとして使用することです。
@SessionScoped Bean の注入
@SessionScoped Bean は現在サポートされていません。この機能が本当に必要な場合は、RESTEasy Reactive ではなく RESTEasy Classic を使用する必要があります。
サーブレット
Quarkus REST はサーブレットをサポートして いません 。
プロジェクトが servlet に依存している場合は、それらを移行する必要があります。
サーブレット・ベースの JAX-RS 実装では、 @Context アノテーションを使用して、これらの型の注入をサポートする必要があります： ServletConfig 、 ServletContext 、 HttpServletRequest 、および 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;
}
}サードパーティのライブラリも同様です。もしそれらがサーブレットに依存しているのであれば、移行パスを見つける必要があります。
認証と認可の失敗をログに記録する
Quarkus REST エンドポイントのセキュリティーチェックは、CDI インターセプター が呼び出される前に実行されます。 Quarkus Security 認証例外をログに記録する最も安全な方法として、プロアクティブ認証が有効になっていることを確認し、Vert.x HTTP ルート失敗ハンドラーを使用することが挙げられます。 詳細は、プロアクティブ認証ガイドの 認証例外応答のカスタマイズ セクションを参照してください。
クライアント
REST クライアント (quarkus-rest-client`とその依存関係) は、従来の RESTEasy Classic ベースの `quarkus-resteasy-client を置き換え、Quarkus のビルド時処理と
Vert.x が提供する統合 I/O モデルを活用します。
依存関係
次の表は、従来の RESTEasy Classic ベースの REST クライアントの依存関係と新しい REST クライアントの依存関係を対応付けています。
| Legacy | Quarkus REST |
|---|---|
|
|
|
|
|
|
|
|
|
代替ではなく、Mutiny をネイティブにサポートしています |
Keycloak adminクライアント
quarkus-rest-client を使用する場合、ユーザーは quarkus-keycloak-admin-rest-client を使用して、
RESTクライアントを活用してターゲットの Keycloakインスタンスを管理できます。
ただし、 quarkus-resteasy-client を使用する場合、ユーザーは同じ機能にアクセスするために quarkus-keycloak-admin-resteasy-client を使用する必要があります。
従来の RESTEasy Classic ベースの REST クライアントを使用します。
OIDC
quarkus-rest-client を使用する場合、ユーザーは quarkus-rest-client-oidc-filter エクステンションを使用して、OpenID Connect および OAuth 2.0 準拠の認可サーバーからアクセストークンを取得および更新できます。
ただし、 quarkus-resteasy-client を使用する場合、ユーザーは同じ機能にアクセスするために quarkus-resteasy-client-oidc-filter を使用する必要があります。
同様に、 quarkus-rest-client-oidc-token-propagation は、従来の REST のユーザーが現在の Bearer または Authorization Code Flow のアクセストークンを伝搬することを可能にします。
ただし、 quarkus-resteasy-client を使用する場合、ユーザーは同じ機能にアクセスするために quarkus-resteasy-client-oidc-token-propagation を使用する必要があります。
カスタムエクステンション
このセクションは、Jakarta RESTおよび/またはREST Client機能に依存するカスタムエクステンションを開発したユーザーだけが読む必要のある高度なセクションです。
依存関係
最初の懸念は、カスタムエクステンションが Quarkus REST に明示的に依存する必要があるか、または代わりに両方の RESTEasy フレーバーをサポートしてユーザーに決定させるかということです。 エクステンションが汎用的である場合は、後者のオプションを選択するのが理にかなっている可能性がありますが、前者は、カスタムのエクステンションが 特定のユーザー/アプリケーションセットによって使用されている場合には最も簡単なオプションです。
両方のエクステンションをサポートすることを選択した場合、カスタムエクステンションのデプロイメントモジュールは通常、SPIモジュール - quarkus-jaxrs-spi-deployment , quarkus-resteasy-common-spi , quarkus-rest-spi-deployment に依存し、
ランタイムモジュールは両方のRESTEasy フレーバーのランタイムモジュールに optional 依存することになります。
一般に、両方のフレーバーをサポートするために、カスタムエクステンションの2つの異なるバージョンを用意する必要はないはずです。このような選択が厳密に必要なのは、エクステンションの消費者（Quarkusアプリケーションなど）がRESTEasyのバージョンを自分で選択する必要がない場合のみです。
リソースとプロバイダーのディスカバリー
Jakarta REST Resources、Providers、REST Clientインターフェースを実行時モジュールに含み、
Jandexインデックスに依存するカスタムエクステンションは（たとえば、空の META-INF/beans.xml ファイルを持つため）、
Quarkus REST でこれらを検出できるように、追加で設定を行う必要はありません。
ビルドアイテムによるプロバイダー登録
ビルド アイテムを介してプロバイダーを登録するエクステンションは、RESTEasy Classic の io.quarkus.resteasy.common.spi.ResteasyJaxrsProviderBuildItem ビルド アイテムを使用します。
ただし、Quarkus REST では、エクステンションは io.quarkus.resteasy.reactive.spi.MessageBodyWriterBuildItem や io.quarkus.resteasy.reactive.spi.MessageBodyWriterBuildItem などの特定のビルド アイテムを使用する必要があります。