JSON 轉 Swift

相關推薦

關於 JSON 轉 Swift：把 JSON 資料變成 Apple 生態原生類型

適用場景

• iOS 開發：把後端 REST API 回傳的 JSON 轉成 Swift struct，用於 SwiftUI 或 UIKit 網路層建模與 JSONDecoder 解碼
• macOS 開發：把應用設定 JSON 轉成 Swift 類型，在 AppKit 專案中做類型安全的設定讀取，避免拼寫錯誤
• watchOS 開發：為 Apple Watch 應用把健康、運動資料 JSON 轉成 Swift 模型並接入 SwiftUI 與 HealthKit
• tvOS 開發：把內容推薦介面 JSON 轉成 Swift 類型，用於電視應用首頁資料展示與焦點導航
• SwiftUI MVVM 建模：把 API 資料模型直接作為 @Published 屬性綁定到 ViewModel，再驅動介面檢視
• Combine 響應式資料流：將 JSON 回應類型作為 Publisher 的輸出類型，配合 JSONDecoder 做響應式解析
• SwiftData / Core Data 前置建模：先生成 Swift struct，再手動新增 @Model 或 @NSManaged 標記進行實體對應
• 第三方 SDK 對接：把 SDK 文件中的 JSON 回應範例轉成 Swift 類型，快速接入登入、支付、推播、地圖等 SDK
• 單元測試準備：把介面 mock JSON 轉成 Swift 類型後用於 XCTest 測試資料與斷言，提升測試可維護性
• 程式碼評審：把 API 回傳 JSON 轉成 Swift 類型，便於團隊 Code Review 時討論欄位命名與可選性
• Flutter / React Native 混合開發：為呼叫原生 Swift 模組準備資料模型，減少 bridge 層的類型轉換錯誤
• 後端介面遷移：從 REST 介面文件或 Postman 範例 JSON 生成 Swift 用戶端模型，跨版本升級時快速同步
• 教學培訓：Swift / iOS 課程中示範 JSON 到類型系統的對應，幫助學生理解 API 資料建模與類型安全
• 健康與健身應用：把 HealthKit / Fitbit 等介面回傳的 JSON 轉成 Swift 類型，用於 Apple Health 資料建模
• 支付與金融應用：把支付閘道的介面回應 JSON 轉成 Swift 模型，便於對帳和異常處理
• 電商訂單系統：把訂單、商品、地址等 JSON 轉成 Swift struct，配合 SwiftUI 列表與詳情頁展示
• 新聞與內容應用：把內容管理系統的 JSON 回應轉成 Swift 類型，用於 TableView / SwiftUI 列表 / 詳情頁
• Vapor 服務端開發：把後端 API 的請求/回應 JSON 轉成 Swift 結構體，用於服務端模型定義與 Codable 編解碼
• MapKit 與地理資料：把地圖介面回傳的 JSON 轉成 Swift struct，用於地點檢索、路線規劃、地理編碼結果建模

使用方法

1. 在左側編輯器貼上 JSON 內容，或點擊上傳按鈕選擇 .json / .txt 檔案，也可載入內建範例資料
2. 工具會在 400ms 防抖後自動呼叫 quicktype-core 轉換，右側顯示生成的 Swift struct / class 程式碼
3. 如果 JSON 格式錯誤，點擊「修復 JSON」按鈕自動修復常見語法問題（尾隨逗號、單引號、缺引號等）
4. 檢查生成結果，可根據專案需要手動新增 Codable / Equatable / Identifiable 等協定；點擊「複製」貼到 Xcode，或點擊「下載」儲存為 .swift 檔案

功能特點

• 純瀏覽器本機轉換：JSON 解析與 Swift 程式碼生成全部在瀏覽器內透過 quicktype-core 完成，原始 JSON 和生成程式碼均不上傳任何伺服器
• quicktype-core just-types 模式：輸出為乾淨的 Swift struct / class 屬性宣告，無 import、無 Codable / CodingKeys 等註解，方便按專案需要再加工
• 400ms 防抖自動轉換：貼上或修改 JSON 後幾乎即時生成 Swift 類型，無需反覆點擊轉換按鈕，轉換過程完全非同步不阻塞 UI
• Web Worker 背景執行：quicktype-core 在瀏覽器 Web Worker 中執行，避免大 JSON 轉換時凍結主執行緒與編輯卡頓
• 智慧類型推斷：自動對應 String、Int、Double、Bool、[T]、自訂類型，陣列按首項類型推斷，不需要手寫欄位類型
• 巢狀物件自動展開：遞迴為每個巢狀物件生成獨立的 Swift 類型，按欄位名首字母大寫命名，避免類型重複定義
• 陣列類型自動推斷：JSON 陣列自動轉換為 [String] / [Int] / [Double] / [自訂類型]，空陣列預設生成 [Any]
• 一鍵 JSON 錯誤修復：遇到尾隨逗號、單引號、缺引號、註解等常見格式錯誤時，可一鍵自動修復並繼續轉換
• 一鍵複製 + .swift 下載：把生成的 Swift 程式碼一鍵複製到剪貼簿，或下載為 .swift 檔案直接拖入 Xcode 專案
• 範例資料 + 檔案上傳：內建 Swift 風格的範例 JSON（含巢狀 address / company / tags），支援拖曳或點擊上傳 .json / .txt 檔案
• localStorage 輸入歷史：自動儲存最近輸入，重新整理或誤關頁面後可快速恢復繼續編輯，不用擔心內容遺失
• 響應式分屏編輯器：左右分屏即時預覽，桌面與行動裝置自適應，小螢幕也能順暢操作

程式碼範例

import Foundation

// 1) 本工具生成的根類型（補上 Codable 協定）
struct User: Codable {
    let id: Int
    let name: String
    let email: String
    let isActive: Bool
    let tags: [String]
}

// 2) URLSession 非同步取得並解碼
func fetchUser(id: Int) async throws -> User {
    let url = URL(string: "https://api.example.com/users/\(id)")!
    let (data, response) = try await URLSession.shared.data(from: url)
    guard
        let http = response as? HTTPURLResponse,
        (200..<300).contains(http.statusCode)
    else {
        throw URLError(.badServerResponse)
    }
    return try JSONDecoder().decode(User.self, from: data)
}

// 3) 使用範例（Swift 5.5+ async/await）
Task {
    do {
        let user = try await fetchUser(id: 42)
        print("User: \(user.name), tags: \(user.tags)")
    } catch {
        print("Failed to decode:", error)
    }
}

import Foundation
import Alamofire

// 本工具生成的類型，新增 Codable 後直接可用
struct Product: Codable {
    let id: Int
    let title: String
    let price: Double
    let inStock: Bool
    let images: [String]
}

final class ProductService {
    private let session: Session

    init(session: Session = .default) {
        self.session = session
    }

    /// Alamofire 5 async/await 風格的 responseDecodable
    func loadProduct(id: Int) async throws -> Product {
        let url = "https://api.example.com/products/\(id)"
        return try await withCheckedThrowingContinuation { continuation in
            session.request(url)
                .validate(statusCode: 200..<300)
                .responseDecodable(of: Product.self) { response in
                    switch response.result {
                    case .success(let product):
                        continuation.resume(returning: product)
                    case .failure(let error):
                        continuation.resume(throwing: error)
                    }
                }
        }
    }
}

// Moya 風格呼叫範例
// provider.request(.product(id: 1)).map(Product.self)
// let product: Product = try await provider.request(.product(id: 1)).map(Product.self)

import Foundation
import Combine

// 本工具生成的根類型
struct Article: Codable, Identifiable {
    let id: Int
    let title: String
    let body: String
    let publishedAt: Date
}

final class ArticleRepository {
    private let session: URLSession
    private var cancellables = Set<AnyCancellable>()

    init(session: URLSession = .shared) {
        self.session = session
    }

    /// 用 Combine 暴露資料流
    func articlePublisher(id: Int) -> AnyPublisher<Article, Error> {
        let url = URL(string: "https://api.example.com/articles/\(id)")!
        let decoder = JSONDecoder()
        decoder.dateDecodingStrategy = .iso8601

        return session.dataTaskPublisher(for: url)
            .map(\.data)
            .decode(type: Article.self, decoder: decoder)
            .receive(on: DispatchQueue.main)
            .eraseToAnyPublisher()
    }

    /// 在 SwiftUI ViewModel 中訂閱
    func bind(to viewModel: ArticleViewModel, articleId: Int) {
        articlePublisher(id: articleId)
            .sink(
                receiveCompletion: { completion in
                    if case .failure(let err) = completion {
                        viewModel.errorMessage = err.localizedDescription
                    }
                },
                receiveValue: { article in
                    viewModel.article = article
                }
            )
            .store(in: &cancellables)
    }
}

final class ArticleViewModel: ObservableObject {
    @Published var article: Article?
    @Published var errorMessage: String?
}

最佳实践

常見問題

故障排查

術語表

struct

Swift 中的值類型。預設適合表示不可變資料模型，賦值時會被複製。本工具預設生成 struct 用於表示 JSON 物件。

class

Swift 中的參考類型。適合需要共享狀態、繼承或身分標識（===）的場景。本工具在某些設定底下可生成 class。

Optional（?）

Swift 中表示值可能為 nil 的類型修飾符，如 var name: String?。本工具生成的欄位預設非 Optional，生成後可根據 JSON 欄位是否可缺失手動新增 ?。

Array（[T]）

Swift 中的陣列類型簡寫。本工具把 JSON 陣列轉換為 [T]，T 按陣列元素類型推斷，如 [String]、[Int] 或 [自訂類型]。

Codable

Swift 中 Decodable 與 Encodable 的協定組合。實作 Codable 後可用 JSONDecoder 把 JSON 資料解析為類型實例。本工具預設不生成 Codable，需手動新增。

JSONDecoder

Foundation 框架中的 JSON 解析器。配合 Codable 協定使用，可把 Data 轉換為 Swift 類型實例。本工具輸出純類型後，開發者可自行用 JSONDecoder 解析。

URLSession

Apple 平台 Foundation 框架中的網路請求 API。常見用法是 URLSession.shared.data(from: url)，與 JSONDecoder 配合完成介面串接。

Alamofire

Swift 社群最流行的第三方 HTTP 網路程式庫。基於 URLSession 封裝，支援 responseDecodable 直接反序列化為 Swift 類型。

Moya

Swift 網路抽象層，通常與 Alamofire 搭配。Moya 配合 Codable 類型可大幅簡化 API 呼叫樣板程式碼。

Vapor

Swift 主流的服務端框架，使用 Swift 在 macOS / Linux 上建構 Web 應用。本工具生成的 Swift 結構體同樣可以用於 Vapor 的路由模型。

quicktype

支援多語言的類型生成器開源工具，本工具透過 quicktype-core 在瀏覽器 Web Worker 中完成 JSON 到 Swift 的轉換。

Property

Swift 類型中的屬性宣告。本工具把 JSON 的每個 key 對應為一個 Swift property，例如 "name": "Alice" 對應為 var name: String。

Type Inference

根據 JSON 值的字面值形式自動推斷 Swift 類型的過程。本工具依據 null、boolean、number、string、array、object 做對應。

localStorage

瀏覽器本機鍵值儲存。本工具用 localStorage 儲存最近輸入歷史，重新整理或誤關頁面後可恢復。

Web Worker

瀏覽器提供的背景執行緒機制。本工具透過 Web Worker 載入和執行 quicktype-core，避免大 JSON 轉換阻塞主執行緒。

SwiftUI

Apple 推出的宣告式 UI 框架。本工具生成的 Swift 類型可作為 SwiftUI 檢視的資料模型，配合 @State / @ObservedObject 驅動介面。

Combine

Apple 的響應式程式設計框架。生成的 Swift 類型結合 JSONDecoder 可建構 dataTaskPublisher 響應式資料流。

SwiftData

Apple 2023 年推出的資料持久化框架。本工具生成的類型可作為 SwiftData 模型基礎類別，新增 @Model 後即可被 SwiftData 管理。

Value Type / Reference Type

Swift 中 struct 是值類型，class 是參考類型。本工具預設生成 struct，賦值時被複製；如需參考語意可手動改為 class。

Field Naming

本工具預設保留 JSON 原欄位名。若源 JSON 為 snake_case 而專案要求 camelCase，需要手動 rename 或自訂 quicktype 渲染器。

ISO 8601 日期

常見 JSON 日期格式，如 2026-07-14T10:00:00Z。需要配套 JSONDecoder.dateDecodingStrategy = .iso8601 才能正確解析到 Date 類型。

JSON 類型到 Swift 類型對應速查表

工具根據 JSON 值的形式自動推斷對應的 Swift 類型：

JSON 轉 Swift 在 Apple 生態中的常見使用場景

生成的 Swift 類型可以直接用於 Apple 平台 / 第三方框架的不同場景：

Privacy & Security

本 JSON 轉 Swift 工具所有 JSON 解析、Swift 類型生成操作完全在你的瀏覽器本機透過 JavaScript（quicktype-core / Web Worker）完成，輸入的 JSON 資料和生成的 Swift 程式碼都不會被上傳到任何伺服器，也不會被記錄、快取或儲存到雲端。包含內部介面欄位、API key、token、使用者隱私資料、未公開業務結構的敏感 JSON 都可以放心使用，關閉或重新整理頁面後所有輸入和輸出內容自動從記憶體清除，不依賴任何第三方網路服務。

Authoritative References

• AppleApple Developer - Swift Codable 官方文件
• Swift.orgSwift.org - 官方文件
• AppleApple Developer - JSONDecoder 文件
• AlamofireAlamofire GitHub 倉庫
• quicktypequicktype GitHub 倉庫