[18.0.0.1 and later]

配置 MicroProfile Rest Client

使用 mpRestClient-1.0 功能部件调用 MicroProfile Rest Client。

开始之前

MicroProfile Rest Client 1.0 需要 Java SDK 8。

关于此任务

MicroProfile Rest Client 基于 JAX-RS 2.0 客户机 API 构建,以提供一种类型安全的方法来通过 HTTP 调用 RESTful 服务。您可以使用更加以模型为中心的代码来编写客户机应用程序。请完成下列步骤以创建自己的 REST 客户机。

过程

  1. 创建一个表示远程服务的接口。使该接口的方法与端点的 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 之类的注释。

  2. 调用该接口中定义的方法。
    样本接口定义了您可调用的方法。
    • 调用 getPlaylistNames 方法可获取可用的播放列表名称。REST 客户机实现将 GET 请求发送至 <baseUrl>/playlist 位置处的端点。此位置接受 application/json 媒体类型的字符串列表,这些字符串指示可用的播放列表名称。
    • 调用 getPlaylist 方法可查看播放列表中包含哪些歌曲。此方法会抛出 UnknownPlaylistException 错误,远程服务上也可能会指出该错误,并且该错误可能返回 HTTP 404 响应。
  3. 使用 ResponseExceptionMapper 命令来处理异常。 以下示例将 HTTP 404 响应转换为特定异常。
    @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;
        }
    
    }
    在此示例中,UnknownPlaylistExceptionPlaylistAlreadyExistsException 案例都是 BasePlaylistException 案例的子类。toThrowable 响应将返回异常实例,而不是抛出异常。
  4. 在您编写接口和响应异常映射器之后,请构建实现并将其启动。可以使用 RestClientBuilder API 或上下文和依赖性注入 (CDI) 和“MP 配置”来构建实现。
  5. 可选: 使用 RestClientBuilder API,此 API 更冗长,但在 CDI 不可用的环境(例如,测试环境)中非常有用。
    1. 创建 RestClientBuilder API 的实例。
    2. 指定远程端点的 baseURL URL,在构建客户机之前,这是必需的。
    3. 注册响应异常映射器。如果需要注册其他提供程序类(例如 MessageBodyReadersMessageBodyWritersfiltersinterceptors),请使用 register 方法进行注册。
    4. 构建客户机并传入接口类。
    5. 在客户机上调用方法,就像您使用其他 Java™ 对象时一样。
    以下示例显示了使用 RestClientBuilder API 来构建并调用实现的样本代码。
    ...
    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);
        }
    }
    ...
  6. 可选: 使用 CDI 和“MP 配置”实例化客户机。
    1. 安装 Liberty server.xml 文件中的 mpRestClient-1.0 功能部件。
    2. 添加 cdi-1.2cdi-2.0 功能部件。
    3. 添加 mpConfig-1.1mpConfig-1.2 功能部件。
    4. 使用以下注释更新 MusicPlaylistService 接口:
      @Path("/playlist")
      @Consumes("application/json")
      @Dependent
      @RegisterRestClient
      @RegisterProvider(PlaylistResponseExceptionMapper.class)
      public interface MusicPlaylistService {
          ...
      @Dependent 注释或其他作用域注释(例如 @ApplicationScoped@RequestScoped)是 CDI 检测和管理 Rest Client 接口所必需的。@RegisterRestClient 注释告知 MicroProfile Rest Client 实现动态地实现接口。@RegisterProvider 注释告知 MicroProfile Rest Client 实现代码注册所指定的提供者类。您可以针对所需的任意数目的提供者在同一接口上重复 @RegisterProvider 注释。
    5. 将客户机注入另一个受管对象中。将 @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();
              ...
    6. 使用“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