Migrating to Quarkus REST (formerly RESTEasy Reactive)
Migrating from RESTEasy Classic to Quarkus REST (formerly RESTEasy Reactive) is straightforward in most cases, however there are a few cases that require some attention. This document provides a list of issues users attempting the migration should be aware of.
| The reference documentation of Quarkus REST can be found here. |
サーバー
The server part of Quarkus REST (quarkus-rest and its dependencies) provide an implementation of the Jakarta REST specification, but leverage Quarkus' build time processing
and the unified I/O model provided by Vert.x.
依存関係
The following table matches the legacy RESTEasy dependencies with the new Quarkus REST ones.
| Legacy | Quarkus REST |
|---|---|
|
|
|
|
|
|
|
|
|
|
The quarkus-resteasy-mutiny does not have a corresponding dependency, as Quarkus REST provides Mutiny integration out of the box.
|
アノテーション
Quarkus REST does not support the various custom annotation under the org.jboss.resteasy.annotations package.
The following table matches the legacy RESTEasy annotations with the new Quarkus REST ones.
| Legacy | Quarkus REST | Comments |
|---|---|---|
|
|
パス部分がメソッドパラメータ名と一致する場合は、このアノテーションは必要ありません |
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
The previous table does not include the org.jboss.resteasy.annotations.Form annotation because there is no Quarkus REST specific replacement for it.
Users are instead encouraged to use the Jakarta REST standard jakarta.ws.rs.BeanParam annotation which is supported on both the server and the client.
|
Jakarta RESTプロバイダー
Although Quarkus REST provides the same spec compliant behavior as RESTEasy Classic does, it does not include the same exact provider implementations at runtime.
The most common case where the difference in providers might result in different behavior, is the included jakarta.ws.rs.ext.ExceptionMapper implementations. To see what classes are included in the application, launch the application in dev mode and navigate to http://localhost:8080/q/dev-ui/io.quarkus.quarkus-rest/exception-mappers.
サービスローディング
RESTEasy Classic supports determining providers at build time using Java’s Service Loader. In order to ensure that all providers are determined at build time, Quarkus REST does not support this feature. Instead, users that have providers in application dependencies are encouraged to index those dependencies using one of the methods described in the Bean Discovery section of the CDI guide.
マルチパート対応
HTTP Multipart support in Quarkus REST does not reuse the same types or annotations as RESTEasy Classic and thus users are encouraged to read this part of the reference documentation.
Users migrating multipart resources to Quarkus REST should be aware of the configuration parameter quarkus.http.limits.max-form-attribute-size, as this poses an upper limit to the size of each part.
Any request with a part size exceeding this configuration value will result in HTTP status code 413.
|
デフォルトのメディアタイプ
Quarkus uses smart defaults when determining the media type of Jakarta REST methods in order to simplify common use cases.
The difference between quarkus-rest and quarkus-resteasy is the use of text/plain as the default media type instead of text/html
when the method returns a String.
Injection of @SessionScoped beans
@SessionScoped beans are currently not supported. Should you really need this functionality, you’ll need to use RESTEasy Classic instead of RESTEasy Reactive.
サーブレット
Quarkus REST does not support servlets.
If your project depends on servlets you have to migrate them.
A servlet-based JAX-RS implementation must support injections of these types with the @Context annotation: ServletConfig, ServletContext, HttpServletRequest and HttpServletResponse.
Since Quarkus REST is not servlet-based these injections will not work.
特に、 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;
}
}サードパーティのライブラリも同様です。もしそれらがサーブレットに依存しているのであれば、移行パスを見つける必要があります。
認証と認可の失敗をログに記録
The Quarkus REST 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 REST Client (quarkus-rest-client and its dependencies) replaces the legacy RESTEasy Classic-based quarkus-resteasy-client and leverages Quarkus' build time processing
and the unified I/O model provided by Vert.x.
依存関係
The following table matches the legacy RESTEasy Classic-based REST Client dependencies with the new REST Client ones.
| Legacy | Quarkus REST |
|---|---|
|
|
|
|
|
|
|
|
|
代替はありません。Mutinyをネイティブにサポートしています |
Keycloak adminクライアント
When using quarkus-rest-client, users can use the quarkus-keycloak-admin-rest-client to administer the target Keycloak instance
by leveraging the rest client.
When using quarkus-resteasy-client however, users must use quarkus-keycloak-admin-resteasy-client to access the same functionality
and use the legacy RESTEasy Classic-based REST Client.
OIDC
When using quarkus-rest-client, users can use the quarkus-rest-client-oidc-filter extension to acquire and refresh access tokens from OpenID Connect and OAuth 2.0 compliant Authorization Servers.
When using quarkus-resteasy-client however, users must use quarkus-resteasy-client-oidc-filter to access the same functionality.
Similarly, quarkus-rest-client-oidc-token-propagation allows user of the legacy REST to propagate the current Bearer or Authorization Code Flow access tokens.
When using quarkus-resteasy-client however, users must use quarkus-resteasy-client-oidc-token-propagation to access the same functionality.
カスタムエクステンション
このセクションは、Jakarta RESTおよび/またはREST Client機能に依存するカスタムエクステンションを開発したユーザーだけが読む必要のある高度なセクションです。
依存関係
A first concern is whether custom extensions should depend on Quarkus REST 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-rest-spi-deployment,
while the runtime modules will have optional dependencies on the runtime modules of both RESTEasy flavors.
Quarkusがこの戦略を用いて、コアリポジトリでRESTEasyの両方のフレーバーをサポートしている好例は、 [こちら](https://github.com/quarkusio/quarkus/pull/21089) と [こちら] (https://github.com/quarkusio/quarkus/pull/20874) にあります。
一般に、両方のフレーバーをサポートするために、カスタムエクステンションの2つの異なるバージョンを用意する必要はないはずです。このような選択が厳密に必要なのは、エクステンションの消費者（Quarkusアプリケーションなど）がRESTEasyのバージョンを自分で選択する必要がない場合のみです。
リソースとプロバイダーのディスカバリー
Custom extensions that contain Jakarta REST 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 Quarkus REST.
ビルドアイテムによるプロバイダー登録
Extensions that register providers via build items use the io.quarkus.resteasy.common.spi.ResteasyJaxrsProviderBuildItem build item in RESTEasy Classic.
With Quarkus REST however, extensions need to use specific build items, such as io.quarkus.resteasy.reactive.spi.MessageBodyWriterBuildItem and io.quarkus.resteasy.reactive.spi.MessageBodyWriterBuildItem.
