Class AddressService

java.lang.Object
io.leandev.appfuse.almanac.address.AddressService
public class AddressService extends Object

台灣地址（縣市 / 鄉鎮市區 / 村里）服務

提供與上一代 appfuse-common AddressService 等價的查找能力，差別在於資料來源 由直接連接內政部國土測繪中心（NLSC）改為連接 almanac （GET /api/v1/address/...）。各層清單以檔案型快取保存——這類資料總量大、存取 零散，特別適合放磁碟層。

Since:
4.0

  • Constructor Details

    • AddressService

      public AddressService(AlmanacClient client, CacheManager cacheManager, Duration ttl)
      建立服務
      Parameters:
      client - almanac 客戶端
      cacheManager - 快取管理器
      ttl - 快取存活時間

  • Method Details

    • findAllCities

      public List<City> findAllCities()
      取得所有縣市
      Returns:
      縣市清單

    • findAllTownsByCity

      public List<Town> findAllTownsByCity(String cityCode)
      取得指定縣市的所有鄉鎮市區
      Parameters:
      cityCode - 縣市代碼
      Returns:
      鄉鎮市區清單

    • findAllVillagesByTown

      public List<Village> findAllVillagesByTown(String cityCode, String townCode)
      取得指定鄉鎮市區的所有村里
      Parameters:
      cityCode - 縣市代碼
      townCode - 鄉鎮市區代碼
      Returns:
      村里清單

    • findAllRoadsByTown

      public List<String> findAllRoadsByTown(String cityCode, String townCode)

      取得指定鄉鎮市區的所有道路

      almanac 目前未提供道路端點（對齊上一代 NLSC 亦未實作），固定回空清單。

      Parameters:
      cityCode - 縣市代碼
      townCode - 鄉鎮市區代碼
      Returns:
      空清單

    • findCity

      public Optional<City> findCity(String cityCode)
      依代碼查找縣市
      Parameters:
      cityCode - 縣市代碼
      Returns:
      縣市（查無則為空）

    • findCityByName

      public Optional<City> findCityByName(String name)

      依名稱查找縣市

      查詢前先以 normalize(String) 把俗寫「台」正規化為 almanac 官方用字「臺」，故傳入 台北市 或 臺北市 皆可命中。此方法為所有以縣市名查詢的入口（towns / villages / findTownByName(String, String)），正規化集中於此即全面覆蓋。

      Parameters:
      name - 縣市名稱（接受官方「臺」或俗寫「台」）
      Returns:
      縣市（查無則為空）

    • findTown

      public Optional<Town> findTown(String cityCode, String townCode)
      依代碼查找鄉鎮市區
      Parameters:
      cityCode - 縣市代碼
      townCode - 鄉鎮市區代碼
      Returns:
      鄉鎮市區（查無則為空）

    • findTownByName

      public Optional<Town> findTownByName(String cityName, String townName)
      依名稱查找鄉鎮市區
      Parameters:
      cityName - 縣市名稱
      townName - 鄉鎮市區名稱
      Returns:
      鄉鎮市區（查無則為空）

    • findAllTownsByCityName

      public List<Town> findAllTownsByCityName(String cityName)

      依縣市名稱取得所有鄉鎮市區（名稱版，免代碼）

      消費端通常以名稱（而非 NLSC 代碼）操作地址；本方法內部以 findCityByName(String) 解析代碼後委派 findAllTownsByCity(String)，查無該縣市時回空清單。

      Parameters:
      cityName - 縣市名稱（如 臺北市）
      Returns:
      鄉鎮市區清單（查無縣市則為空）

    • findAllVillagesByTownName

      public List<Village> findAllVillagesByTownName(String cityName, String townName)

      依縣市與鄉鎮市區名稱取得所有村里（名稱版，免代碼）

      內部以 findTownByName(String, String) 解析鄉鎮市區（其 cityCode 已含所屬縣市代碼）後委派 findAllVillagesByTown(String, String)，查無該縣市或鄉鎮市區時回空清單。

      Parameters:
      cityName - 縣市名稱（如 臺北市）
      townName - 鄉鎮市區名稱（如 松山區）
      Returns:
      村里清單（查無則為空）