---
title: william-weng/wwnetworkclient
framework: Swift Package Catalog
role: article
path: packages/william-weng/wwnetworkclient
---

# william-weng/wwnetworkclient

[English](./README.en.md) | [繁體中文](./README.md)

## ✨ [核心特色](https://peterpanswift.github.io/iphone-bezels/)

* 🚀 **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 請求（自動處理中文編碼）

```swift 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` 完美協同

```swift 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. 完整範例

```swift 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() } ```

## Package Metadata

Repository: william-weng/wwnetworkclient

Default branch: main

README: README.md