![[18.0.0.1 以及更新版本]](../ng_v18001plus.gif)
配置 MicroProfile Rest 用戶端
使用 mpRestClient-1.0 特性來呼叫 MicroProfile Rest 用戶端。
開始之前
關於這項作業
「MicroProfile Rest 用戶端」是以 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 用戶端介面。@RegisterRestClient 註釋會告知 MicroProfile Rest 用戶端實作動態實作介面。@RegisterProvider 註釋會告知 MicroProfile Rest 用戶端實作程式碼登錄指定的提供者類別。您可以針對您需要的提供者(數目不限),在相同介面上重複 @RegisterProvider 註釋。@Path("/playlist") @Consumes("application/json") @Dependent @RegisterRestClient @RegisterProvider(PlaylistResponseExceptionMapper.class) public interface MusicPlaylistService { ...
- 將用戶端注入至另一個受管理物件。將 @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(); ...
- 使用「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 用於正式作業,而不需變更程式碼。
上層主題: 將 Web 服務應用程式部署到 Liberty

檔名:twlp_mp_restclient.html