從固定資料,走到 API 串接
SHM 平台收集建築物感測器資料。手機 App 的工作,是讓站點、裝置狀態和量測時間,變成容易閱讀與操作的畫面。
這次先建立裝置列表與詳情,再加入登入。把畫面和資料來源分開後,即使測試 API 尚未就緒,也能用固定資料持續實作。
列表與詳情先共用同一筆資料,登入狀態可先用本機模擬。
先讀懂一筆裝置資料
總覽回應以站點分組,每個站點包含一個 devices 陣列。先找出裝置名稱、狀態與最後量測時間,對應到列表上的三個位置。
{
"id": "demo-device-01",
"name": "示範加速度計 A",
"status": "normal",
"lastMeasurementAt": "2026-10-15T01:00:00.000Z",
"currentValue": { "ax": 0.01, "ay": -0.02, "az": 0.03 }
}合成資料與欄位子集,並非真實站點量測。完整範例可在文末下載。
- 名稱與狀態
name顯示裝置名稱;狀態搭配文字和顏色,不只靠顏色區分。- 量測時間
lastMeasurementAt是 ISO 時間或null。顯示時轉為本機時區,沒有時間則標示「尚無量測資料」。- 缺值與零值
currentValue: null表示沒有量測值,和數值為零不同。單位等正式裝置設定確認後再標示。
資料改變時,畫面怎麼回應?
列表不是只有「有資料」一種情況。讓資料來源回傳空列表、延遲或錯誤,就能先把畫面行為整理好,再處理真實網路。
切換資料狀態
把資料存取包在獨立介面,畫面只處理載入、內容、空列表與錯誤。未來從 JSON 換成 HTTP 時,就能沿用已經建立的畫面邏輯。
走一次登入與查詢流程
登入不是只切換頁面。帳密送到後端後會取得 token,之後的受保護請求再帶上這份登入資訊。下面把三個請求放進同一條路徑。
送出 userName、password
API 回應:token 與登入資訊帶上 Bearer token
API 回應:sub、userId、role帶上 Bearer token
API 回應:站點與裝置陣列{
"userName": "<測試帳號>",
"password": "<測試密碼>"
}登入回應的 user 包含 id、name、role;/auth/me 則直接回傳 sub、userId、role。兩者的資料模型不同。
缺少必要欄位時,提示補齊。
登入失敗顯示錯誤;查詢時收到則重新登入。
呈現權限訊息,不當成密碼錯誤。
測試入口與帳號尚待提供。這份網頁只展示流程,不接收帳密、不連線到正式 API。
把相同概念,放進各自的平台
資料結構與畫面行為相同,UI 元件和網路工具則沿用平台習慣。選擇一條路線閱讀。
用 Compose 呈現裝置資料
以 Kotlin 資料類別表示站點與裝置,將可能為空的時間與量測值保留為可空型別。用 LazyColumn 顯示站點與裝置列,再把選取的裝置帶到詳情。
- 固定資料先上畫面將範例 JSON 轉成畫面使用的資料模型。
- 加入狀態變化集中管理載入、內容、空列表與錯誤,畫面依狀態繪製。
- 替換成 HTTP 來源確認網路權限,以非同步方式發出請求,避免在主執行緒等待。
用 SwiftUI 呈現裝置資料
使用 Codable 定義資料模型,將 JSON 加入 app bundle,透過 JSONDecoder 讀取。可能為空的欄位使用 Optional。
- 固定資料先上畫面用 List 與 Section 建立列表,再顯示選取裝置的詳情。
- 加入狀態變化區分載入、內容、空列表與錯誤,避免把尚未讀完當成沒有資料。
- 替換成 HTTP 來源透過 URLSession 發出請求,先處理 HTTP 狀態碼,再解析 JSON。
導覽元件依 Xcode 與 deployment target 選擇。token 可先保留在記憶體;若要跨啟動保存,再使用 Keychain 等安全儲存方式。
閱讀 SwiftUI List 文件 ↗把練習帶進開發環境
兩份 JSON 可直接用來練習列表狀態。Postman 範本包含登入、查身分與總覽三個請求,待測試入口就緒後使用。
匯入 Postman 後怎麼設定?
- 匯入 collection,建立個人的本機 environment。
- 設定
baseUrl、userName、password、token。baseUrl 是服務根網址,不含尾端/api。 - 執行登入,把回應的 token 填到本機變數,再執行身分與總覽請求。
帳密與 token 保留在本機私有值,不同步到共用 workspace,也不隨檔案匯出。範本尚未對實際服務執行。
畫面先走通,資料再接上。
固定 JSON 建立列表與詳情,模擬狀態整理畫面行為,再將資料來源換成 API。每一次小實驗,都留下能在下一步沿用的成果。
回到學習路線 ↑