Day20 - 天氣API實作：打造資料模型

昨天我們完成了鬧鐘功能的基礎實作，今天開始進入全新的篇章 —— 天氣 API 實作。
在這個系列中，我們會學習如何串接 中央氣象局 Open Data API，並將取得的天氣資料呈現在 App 畫面中。

本日的主題是：資料模型建立。
我們會先分析 API 回傳的 JSON，再將它轉換成 Swift 的 Struct，讓後續處理資料更直觀。

1.觀察 API JSON

以中央氣象局提供的 API 為例（F-C0032-001 一般天氣預報）：
回傳的資料大致長這樣：

{
  "records": {
    "location": [
      {
        "locationName": "臺北市",
        "weatherElement": [
          {
            "elementName": "Wx",
            "time": [
              {
                "startTime": "2025-09-20 06:00:00",
                "endTime": "2025-09-20 12:00:00",
                "parameter": {
                  "parameterName": "多雲時晴",
                  "parameterValue": "2"
                }
              }
            ]
          }
        ]
      }
    ]
  }
}

可以看到層級很深：

• records → location → weatherElement → time → parameter

因此，我們需要設計一組對應的 Struct 來解析它。

2.建立資料模型 Data.swift

在 Xcode 專案中新建一個 Data.swift 檔案，專門放置 API 的資料結構。

//
//  Data.swift
//  WeatherAPI
//
//  Created by imac-3282 on 2025/7/15.
//

import Foundation

// MARK: - 最外層
struct WeatherResponse: Codable {
    let records: Records
}

struct Records: Codable {
    let location: [Location]
}

// MARK: - 城市
struct Location: Codable {
    let locationName: String
    let weatherElement: [WeatherElement]
}

// MARK: - 天氣元素（Wx, PoP, MinT, MaxT ...）
struct WeatherElement: Codable {
    let elementName: String
    let time: [TimeData]
}

// MARK: - 時間區間的資料
struct TimeData: Codable {
    let startTime: String
    let endTime: String
    let parameter: Parameter
}

// MARK: - 參數內容（文字、數值）
struct Parameter: Codable {
    let parameterName: String
    let parameterValue: String?
}

3.為什麼要用 Codable？

Codable 是 Swift 提供的協定，它同時包含了：

• Decodable → 可以把 JSON 轉成 Swift Struct
• Encodable → 可以把 Swift Struct 轉回 JSON

這樣我們就能直接透過 JSONDecoder() 解析 API 回傳的資料，非常方便！

4.測試解析 JSON

在之後的 Controller 中，我們可以這樣測試 API：

let url = URL(string: "https://opendata.cwa.gov.tw/api/v1/rest/datastore/F-C0032-001?Authorization=你的API金鑰&locationName=臺北市")!

URLSession.shared.dataTask(with: url) { data, response, error in
    if let data = data {
        do {
            let result = try JSONDecoder().decode(WeatherResponse.self, from: data)
            print(result.records.location.first?.locationName ?? "無資料")
        } catch {
            print("解析失敗：\(error)")
        }
    }
}.resume()

這樣就能把 JSON 成功轉換成 Swift Struct，並且拿到城市名稱！

5.小結

今天我們完成了 天氣 API 的資料模型設計，重點如下：

1. 觀察 JSON 結構 → 找出層級，設計對應的 Struct。
2. 使用 Codable → 讓 JSON 和 Swift Struct 自動轉換。
3. 實際測試 API → 成功取出城市名稱，確保模型正確。

在明天的文章，我們會進一步 串接 API 並顯示資料，讓天氣預報出現在 App 畫面中。