[18.0.0.1 以及更新版本]

配置 MicroProfile Rest 用戶端

使用 mpRestClient-1.0 特性來呼叫 MicroProfile Rest 用戶端。

開始之前

「MicroProfile Rest 用戶端 1.0」需要 Java SDK 8。

關於這項作業

「MicroProfile Rest 用戶端」是以 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 用戶端介面。@RegisterRestClient 註釋會告知 MicroProfile Rest 用戶端實作動態實作介面。@RegisterProvider 註釋會告知 MicroProfile Rest 用戶端實作程式碼登錄指定的提供者類別。您可以針對您需要的提供者(數目不限),在相同介面上重複 @RegisterProvider 註釋。
    5. 將用戶端注入至另一個受管理物件。將 @Inject 註釋與 @RestClient 裝飾字元合併,以注入 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 用戶端」實作中之遠端端點的 baseUrl URL。使用「MicroProfile 配置」來指定 <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