![[18.0.0.1 and later]](../ng_v18001plus.gif)
配置 MicroProfile Rest Client
使用 mpRestClient-1.0 功能部件调用 MicroProfile Rest Client。
开始之前
关于此任务
MicroProfile Rest Client 基于 JAX-RS 2.0 客户机 API 构建,以提供一种类型安全的方法来通过 HTTP 调用 RESTful 服务。您可以使用更加以模型为中心的代码来编写客户机应用程序。请完成下列步骤以创建自己的 REST 客户机。
过程
- 创建一个表示远程服务的接口。使该接口的方法与端点的 RESTful API 相匹配。 以下示例显示了一个访问服务以获取在线音乐的样本接口。
@Path("/playlist") @Consumes("application/json") public interface MusicPlaylistService { @GET List<String> getPlaylistNames(); @GET @Path("/{playlistName}") List<Song> getPlaylist(@PathParam("playlistName") name) throws UnknownPlaylistException; @POST @Path("/{playlistName}") long newPlayList(@PathParam("playlistName") name, List<Song> playlist) throws PlaylistAlreadyExistsException; @PUT @Path("/{playlistName}") long updatePlayList(@PathParam("playlistName") name, List<Song> playlist) throws UnknownPlaylistException; }
与服务器端上的 JAX-RS 相似,样本接口使用 @Path、@Consumes、@GET 和 @PathParam 之类的注释。
- 调用该接口中定义的方法。 样本接口定义了您可调用的方法。
- 调用 getPlaylistNames 方法可获取可用的播放列表名称。REST 客户机实现将 GET 请求发送至 <baseUrl>/playlist 位置处的端点。此位置接受 application/json 媒体类型的字符串列表,这些字符串指示可用的播放列表名称。
- 调用 getPlaylist 方法可查看播放列表中包含哪些歌曲。此方法会抛出 UnknownPlaylistException 错误,远程服务上也可能会指出该错误,并且该错误可能返回 HTTP 404 响应。
- 使用 ResponseExceptionMapper 命令来处理异常。 以下示例将 HTTP 404 响应转换为特定异常。
在此示例中,UnknownPlaylistException 和 PlaylistAlreadyExistsException 案例都是 BasePlaylistException 案例的子类。toThrowable 响应将返回异常实例,而不是抛出异常。@Provider public class PlaylistResponseExceptionMapper implements ResponseExceptionMapper<BasePlaylistException> { @Override public boolean handles(int statusCode, MultivaluedMap<String, Object> headers) { return statusCode == 404 // Not Found || statusCode == 409; // Conflict } @Override public BasePlaylistException toThrowable(Response response) { switch(response.getStatus()) { case 404: return new UnknownPlaylistException(); case 409: return new PlaylistAlreadyExistsException(); } return null; } }
- 在您编写接口和响应异常映射器之后,请构建实现并将其启动。可以使用 RestClientBuilder API 或上下文和依赖性注入 (CDI) 和“MP 配置”来构建实现。
- 可选: 使用 RestClientBuilder API,此 API 更冗长,但在 CDI 不可用的环境(例如,测试环境)中非常有用。
- 创建 RestClientBuilder API 的实例。
- 指定远程端点的 baseURL URL,在构建客户机之前,这是必需的。
- 注册响应异常映射器。如果需要注册其他提供程序类(例如 MessageBodyReaders、MessageBodyWriters、filters 或 interceptors),请使用 register 方法进行注册。
- 构建客户机并传入接口类。
- 在客户机上调用方法,就像您使用其他 Java™ 对象时一样。
... URL apiUrl = new URL("http://localhost:9080/onlineMusicService"); MusicPlaylistService playlistSvc = RestClientBuilder.newBuilder() .baseUrl(apiUrl) .register(PlaylistResponseExceptionMapper.class) .build(MusicPlaylistService.class); List<String> playlistNames = playlistSvc.getPlaylistNames(); for (String name : playlistNames) { List<Song> songs = playlistSvc.getPlaylist(name); if (hasSongBy(songs, "band name")) { coolPlaylists.add(name); } } ...
- 可选: 使用 CDI 和“MP 配置”实例化客户机。
- 安装 Liberty server.xml 文件中的 mpRestClient-1.0 功能部件。
- 添加 cdi-1.2 或 cdi-2.0 功能部件。
- 添加 mpConfig-1.1 或 mpConfig-1.2 功能部件。
- 使用以下注释更新 MusicPlaylistService 接口:
@Dependent 注释或其他作用域注释(例如 @ApplicationScoped 或 @RequestScoped)是 CDI 检测和管理 Rest Client 接口所必需的。@RegisterRestClient 注释告知 MicroProfile Rest Client 实现动态地实现接口。@RegisterProvider 注释告知 MicroProfile Rest Client 实现代码注册所指定的提供者类。您可以针对所需的任意数目的提供者在同一接口上重复 @RegisterProvider 注释。@Path("/playlist") @Consumes("application/json") @Dependent @RegisterRestClient @RegisterProvider(PlaylistResponseExceptionMapper.class) public interface MusicPlaylistService { ...
- 将客户机注入另一个受管对象中。将 @Inject 注释与
@RestClient 修饰符相结合,以告知 CDI 注入 MusicPlaylistService 接口的实例:
@WebServlet(urlPatterns = "/PlaylistServlet") public class PlaylistServlet extends HttpServlet { @Inject @RestClient private MusicPlaylistService playlistService; @Override public void doGet(HttpServletRequest request, HttpServletResponse response) throws ServletException, IOException { List<String> names = playlistService.getPlaylistNames(); ...
- 使用“MP 配置”在 MP Rest Client 实现中指示远程端点的 baseUrl URL。请使用 MicroProfile Config 指定 <fullyQualifiedInterfaceName>/mp-rest/url 配置属性。一个选项是在 jvm.options 文件中设置系统属性:
-Dcom.mypkg.MusicPlaylistService/mp-rest/url=http://localhost:9080/onlineMusicService
当您想要引导客户机时,CDI 注入更简单。使用“MP 配置”时,您可以对不同的环境使用不同的 URL(例如,对测试环境使用一个 URL,并对生产环境使用另一个 URL),而无需更改代码。

文件名:twlp_mp_restclient.html