English | 繁體中文

WWNetworkClient

WWNetworkClient 是一個專為 iOS 17+ / Swift 6.0+ 打造的極輕量、純化、強型別網路連線核心。

Example.mp4

它是功能完整的企業級網路庫 WWNetworking 的精簡/輕量（Lightweight）版本。移除了複雜的架構冗餘與膠水代碼（Boilerplate Code），僅保留最核心的 async/await 連線能力，讓您在不需要搬出大型框架（如 Alamofire）或複雜 Protocol-based 架構時，能以最直覺的參數化方式快速發送網路請求。

---

✨ 核心特色

• 🚀 iOS 17+ 頂配純化：全面引進現代化 URL API，彻底捨棄傳統且容易因特殊字元引發解析崩潰的 URLComponents。
• 🔠 自動百分比編碼：直接利用系統底層在 URL 拼接時處理中文、空白與特殊符號（例如 & 或 =），防禦性滿分。
• 🛡️ 強型別防呆 (Strongly Typed)：自訂 HTTPMethod、HTTPHeaderField 與 ContentType 列舉，完全終結因手打字串拼錯而導致的 API 連線失敗。
• 🪶 極致輕量：沒有過度封裝，底層直接回傳 ResponseResult（包含 HTTPURLResponse 與 Data），將「網路層成功」與「業務邏輯解碼」完美分離。
• ⚡ Swift 現代並發：原生支持 async/await，與 SwiftUI 的 .task 生命週期機制 100% 完美契合。

---

🛠️ 架構組成

本輕量庫由以下四個核心元素緊密組裝而成：

1. HTTPMethod：限制並定義標準 HTTP 動詞（GET, POST, PATCH 等）。
2. HTTPHeaderField：封裝常用的標頭名稱，支援自訂擴充 .custom("X-Header")。
3. ContentType：封裝常用的 MIME 類型（JSON, FormData, JPEG 等），內建智慧型 find(by:) 標頭反向比對解析功能。
4. WWNetworkClient：核心連線結構體，負責驅動 URLSession 並產出連線結果。

---

🧩 可用API

方法	說明
request(_:url:contentType:parameters:headers:httpBody:)	發送網路請求（核心方法：使用標準 URL 物件發送）。
request(_:urlString:contentType:parameters:headers:httpBody:)	發送網路請求（便利型方法：支援直接傳入網址字串）。
request(_:urlString:as:parameters:headers:httpBody:)	發送網路請求並自動解碼。

---

💻 快速上手範例

1. 發送直覺的參數化 GET 請求（自動處理中文編碼）

import Foundation
import WWNetworkClient

let client = WWNetworkClient()

do {
    let result = try await client.request(
        .get,
        urlString: "https://httpbin.org",
        parameters: ["query": "蘋果 ＆ iPhone", "page": "1"]
    )
    
    print("HTTP 狀態碼: \(result.response.statusCode)")
    print("原始 Data 大小: \(result.data.count) bytes")
} catch {
    print("連線發生錯誤: \(error)")
}

2. 在 SwiftUI 中結合 .task 完美協同

import SwiftUI
import WWNetworkClient

struct ContentView: View {
    
    private let client = WWNetworkClient()
    @State private var logMessage: String = "正在連線..."
    
    var body: some View {
        Text(logMessage)
            .padding()
            .task {
                do {
                    let result = try await client.request(url: URL(string: "https://google.com")!)
                    logMessage = result.response.description
                } catch {
                    logMessage = "連線失敗: \(error.localizedDescription)"
                }
            }
    }
}

3. 完整範例

import SwiftUI
import WWNetworkClient

struct ContentView: View {
    
    private let urlString = "https://www.google.com/"
    private let client: WWNetworkClient = .init()
    
    @State private var message: String = ""
    @State private var isLoading: Bool = true
    
    var body: some View {
        
        NavigationStack {
            Group {
                if isLoading {
                    ProgressView("Loading...")
                        .controlSize(.large)
                } else {
                    ScrollView {
                        VStack(alignment: .leading, spacing: 12) {
                            Text("Response Description:")
                                .font(.headline)
                                .foregroundColor(.secondary)
                            
                            Divider()
                            
                            Text(message)
                                .font(.system(.body, design: .monospaced))
                                .multilineTextAlignment(.leading)
                        }
                        .padding()
                    }
                }
            }
            .navigationTitle("WWNetworkClient")
            .task {
                do {
                    let result = try await client.request(url: URL(string: urlString)!)
                    message = result.response.description
                } catch {
                    message = "error: \(error.localizedDescription)"
                }
                
                isLoading = false
            }
        }
    }
}

#Preview {
    ContentView()
}