Class AlmanacClient

java.lang.Object
io.leandev.appfuse.almanac.AlmanacClient
All Implemented Interfaces:
AutoCloseable
public class AlmanacClient extends Object implements AutoCloseable

almanac 服務的低階 HTTP 客戶端

封裝 StandardHttpClient，負責組裝 almanac 的 REST 端點 URL、套用認證 （AlmanacCredentials）、發送 GET 請求並將 JSON 回應反序列化為物件 / 物件清單。

almanac 的端點皆位於 {baseUrl}/api/v1 之下；baseUrl 預設指向正式環境 (DEFAULT_BASE_URL)，可於建構時覆寫（如指向測試或其他環境）。

高階的領域服務（CalendarService / LocationService / AddressService）透過本類別 取得資料，並各自負責快取。

Since:
4.0

  • Field Details

    • DEFAULT_BASE_URL

      public static final String DEFAULT_BASE_URL

      almanac 正式環境 base URL

      正式環境經反向代理以 root context 對外服務（context-path 已被 strip），故 base URL 為網域本身、端點直接位於 /api/v1 之下。

      See Also:

    • API_PREFIX

      public static final String API_PREFIX
      API 版本前綴
      See Also:

  • Constructor Details

    • AlmanacClient

      public AlmanacClient(AlmanacCredentials credentials)
      以預設 base URL 建立
      Parameters:
      credentials - 認證策略（可為 null 表示不帶認證）

    • AlmanacClient

      public AlmanacClient(String baseUrl, AlmanacCredentials credentials)
      以指定 base URL 建立
      Parameters:
      baseUrl - almanac base URL（含 context-path，如 https://almanac.leandev.io/almanac-server）
      credentials - 認證策略（可為 null 表示不帶認證）

    • AlmanacClient

      public AlmanacClient(String baseUrl, AlmanacCredentials credentials, int retries, StandardHttpClient httpClient)
      完整建構（供進階使用 / 測試注入自訂 HTTP 客戶端）
      Parameters:
      baseUrl - almanac base URL
      credentials - 認證策略
      retries - 重試次數
      httpClient - 底層 HTTP 客戶端（由本類別於 close() 時關閉）

  • Method Details

    • getList

      public <R> List<R> getList(String path, Class<R> type)
      GET 端點並反序列化為物件清單
      Type Parameters:
      R - 清單元素型別
      Parameters:
      path - 相對於 {baseUrl}/api/v1 的路徑（以 / 開頭）
      type - 清單元素型別
      Returns:
      反序列化後的清單
      Throws:
      AlmanacException - 連線或解析失敗時

    • get

      public <R> R get(String path, Class<R> type)
      GET 端點並反序列化為單一物件
      Type Parameters:
      R - 目標型別
      Parameters:
      path - 相對於 {baseUrl}/api/v1 的路徑（以 / 開頭）
      type - 目標型別
      Returns:
      反序列化後的物件
      Throws:
      AlmanacException - 連線或解析失敗時

    • close

      public void close() throws Exception
      Specified by:
      close in interface AutoCloseable
      Throws:
      Exception