文章

Apple Network 框架新旧 API 对比

发表于
作者 CodeSwift
27 分钟阅读
Apple Network 框架新旧 API 对比

1. 新旧 Network API 设计差异

Apple 在 2018 年引入了 Network.framework（iOS 12+/macOS 10.14+），提供了如 NWConnection、NWListener、NWBrowser 等类，用于建立网络连接、监听端口和浏览网络服务。这套旧 API 采用 NW 前缀，以面向对象和基于闭包回调的方式工作。例如，NWConnection 通过回调 (stateUpdateHandler 等) 通知状态变化，通过提供闭包的 receive 方法获取数据。开发者需要手动调用 start(queue:) 来启动连接，并在相应的 Dispatch 队列上处理异步事件。

在 iOS/iPadOS/macOS 26（WWDC 2025 发布的系统）中，Apple 为 Network.framework 重新设计了一套 API，引入了 NetworkConnection、NetworkListener、NetworkBrowser 等类。新 API 直接使用 Network 命名空间而非 NW 前缀，充分利用 Swift 异步/并发 (Swift Concurrency) 特性，使网络代码与 Swift 原生的 async/await 模式紧密结合。最显著的区别是设计范式的转变：从旧 API 的回调/委托模型转向新 API 的结构化并发模型。这意味着新的 NetworkConnection 提供 async 的 send、receive 函数，返回值和错误通过挂起/抛异常传递，而不再依赖嵌套回调。例如，调用 connection.send() 会挂起当前任务直到数据发送完成，而 connection.receive() 可以使用 await 获取结果或抛出错误。

为什么不直接在旧 API 上添加 async 方法？

Apple 并没有简单地给 NWConnection 添加 async 函数，而是大幅度重构了 API，这是因为旧架构存在多方面限制，使其难以直接适配 Swift Concurrency：

  • 线程上下文与并发兼容性
    旧的 NWConnection 依赖底层的 DispatchQueue 来处理回调，调用者需要保证在适当线程调用 .start() 并循环调用 .receive。如果仅添加 async 方法，依然需要在内部维护回调和队列的关系，难以充分利用 Swift 并发的机制。Apple 选择重新设计，使 NetworkConnection 自动管理任务和子任务，让开发者编写的网络逻辑可以像普通 async 函数一样顺序书写，同时由系统确保并发安全。

  • API 易用性与 DSL
    新 API 采用声明式 DSL 定义协议栈，而旧 API 需要通过 NWParameters 手动配置协议。比如，新 API 可以使用简洁的闭包语法来构建 TLS over TCP/IP 栈：

    1
2
3
4
5
6
7

    let connection = NetworkConnection(to: .hostPort(host: "example.com", port: 1029)) {
    TLS {
        TCP {
            IP().fragmentationEnabled(false)
        }
    }
}

上述代码利用 result builder 声明了协议栈并禁用 IP 分片，语法直观。旧 API 实现相同配置则繁琐得多，需要构造 NWParameters 对象并逐级修改其子协议选项。这种 DSL 难以通过在原有 NWConnection 基础上添加方法实现，因此 Apple 通过全新类型实现了声明式的协议栈配置。

  • 类型安全的消息传递 新框架引入了 TLV Framer 和 Codable 支持，允许 NetworkConnection 直接发送/接收结构化消息（如 Codable 对象）而非生字节流。为了实现这一点，新 API 在设计上使用了泛型或关联类型来绑定应用层协议的数据类型。例如，当协议栈中包含 Coder(GameMessage.self) 时，NetworkConnection 可以直接 send 和 receive GameMessage 类型，无需手工序列化。旧 NWConnection 并非为这种强类型消息设计，仅提供不透明的 Data/ContentContext，需要开发者自行序列化，无法简单加上泛型。因此用新类重新设计更符合 Swift 类型系统和并发模型。

综上，旧 API 的架构（基于回调的异步、繁琐的参数配置）不利于直接融入 Swift Concurrency。而新 Network API 通过从零设计，提供了更现代化、Swift 风格的接口，大幅降低网络编程的复杂度和易错点。正如 Apple 所说，新框架“与 Swift 的异步操作和结构化并发紧密集成”，让网络代码可以顺滑地融入 Swift 代码，避免旧框架那样大量的样板代码。

2. 新旧 API 用法对比

2.1 建立连接与发送/接收数据

旧 API 示例 (NWConnection)：

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37

import Network

// OLD API: NWConnection
let nwConnection = NWConnection(host: "example.com", port: 1029, using: .tcp)

// 设置状态变化回调
nwConnection.stateUpdateHandler = { newState in
    if case .ready = newState {
        print("Connection ready")
    }
}

// 启动连接
nwConnection.start(queue: .global())

// 发送数据
let payload = "Hello".data(using: .utf8)!
nwConnection.send(content: payload, completion: .contentProcessed { error in
    if let e = error {
        print("Send error: \(e)")
    } else {
        print("Send succeeded")
    }
})

// 接收数据（一次接收固定最大长度）
nwConnection.receive(minimumIncompleteLength: 1, maximumLength: 1024) { data, context, isComplete, error in
    if let data = data {
        print("Received \(data.count) bytes")
    }
    if isComplete {
        print("Receive completed")
    }
    if let e = error {
        print("Receive error: \(e)")
    }
}

要点：在调用 start() 后，通过闭包异步获取连接状态；发送需要在回调中检查结果；接收需要反复调用 receive（例如在回调结尾递归调用自身以持续读取）。开发者必须处理 contentContext、isComplete 等参数来判断消息边界或流结束。

新 API 示例 (NetworkConnection)：

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16

import Network

// NEW API: NetworkConnection
// 声明一个到 example.com:1029 的连接，使用默认的 TLS over TCP 协议栈
let connection = NetworkConnection(to: .hostPort(host: "example.com", port: 1029)) {
    TLS()  // Protocol stack: TLS (over TCP/IP by default)
}

// 发送数据（挂起等待发送完成）
let payload = Data("Hello".utf8)
try await connection.send(payload)
print("Send succeeded")

// 接收固定大小的数据（精确接收1024字节）
let receivedData = try await connection.receive(exactly: 1024).content
print("Received \(receivedData.count) bytes")

在新 API 中，不需要显式调用 .start() —— 调用 send 或 receive 会自动触发连接建立。send 和 receive 方法本身是异步函数，会等待操作完成或抛出错误，因此可以直接用 try/await 捕获错误。对于基于流的协议（如 TCP/TLS），receive(exactly: N) 允许一次读取固定 N 字节，而旧 API 需要自己缓存数据才能确定边界。进一步比较：旧 NWConnection 中，通过 NWConnection.ContentContext 和 isComplete 来标识消息边界或结束，而新 NetworkConnection 针对不同协议提供了更直观的方法。例如，对于流协议，可以使用 receive(min:atMost:) 指定最小/最大读取字节数；对于消息协议（datagram 或加入 TLV Framer 的连接），receive() 不需要参数即可获取完整消息。总的来说，新 API 简化了发送接收流程，开发者无需处理大量样板代码或状态判断。

2.2 监听服务端口并接受连接

旧 API 示例 (NWListener)：

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17

import Network

let listener = try NWListener(using: .tcp, on: 8888)
listener.stateUpdateHandler = { state in
    if case .ready = state {
        print("Listener ready on port \(listener.port!)")
    }
}
listener.newConnectionHandler = { nwConnection in
    // 接受到一个新的连接
    nwConnection.stateUpdateHandler = { state in 
        // 可以监控新连接状态
    }
    nwConnection.start(queue: .main)
    // 可以继续对 nwConnection 调用 receive/send 设置处理...
}
listener.start(queue: .main)

旧 API 中，每当有客户端连接进来，开发者需要在 newConnectionHandler 中对新的 NWConnection 进行 .start(queue:)，并创建自己的读写处理。同时必须注意不要阻塞 newConnectionHandler，否则监听无法继续接受其他连接。

新 API 示例 (NetworkListener)：

1
2
3
4
5
6
7
8
9
10
11
12

import Network

try await NetworkListener {
    TLS()  // 声明监听接受 TLS (底层TCP/IP) 协议的连接
}.run { connection in
    // 对每个接入的 NetworkConnection，系统已在子任务中调用该闭包
    for try await (data, context) in connection.messages {
        // 异步序列获取客户端发送的每条消息 (data及元信息)
        print("Received message of \(data.count) bytes")
        // 可以在此处理消息并用 connection.send() 回复
    }
}

上面代码说明：NetworkListener 用声明式语法指定协议栈（如 TLS），然后调用 .run { connection in … } 开始监听。每当有新客户端连接，run 传入的闭包会在新的异步子任务中执行，参数即新建立的 NetworkConnection。在闭包内部，可以直接使用 for await 从 connection.messages 异步序列中获取客户端发来的每条消息。框架确保每个连接独立处理，不用担心阻塞主监听。同时，NetworkConnection 本身也提供了 messages 异步序列属性，极大方便了连续收发消息的场景。相比之下，旧 NWListener 需要开发者自行确保每个连接在不同线程或队列处理，增加了同步负担。

2.3 浏览网络服务/设备

旧 API 示例 (NWBrowser)：

1
2
3
4
5
6
7
8
9

let browser = NWBrowser(for: .bonjour(type: "_http._tcp", domain: nil), using: .udp)
browser.browseResultsChangedHandler = { results, changes in
    for result in results {
        if let endpoint = result.endpoint as? NWEndpoint.HostPort {
            print("Found service at \(endpoint)")
        }
    }
}
browser.start(queue: .main)

开发者需处理每次结果变化，通过 browseResultsChangedHandler 获取当前发现的服务列表。要选定一个服务进行连接，需要手动停止浏览并提取 NWEndpoint。

新 API 示例 (NetworkBrowser)：

1
2
3
4
5
6
7
8
9
10
11
12
13

import Network
import WiFiAware

// 使用 NetworkBrowser 查找附近的 Wi-Fi Aware 设备（示例服务 ticTacToeService）
let endpoint = try await NetworkBrowser(for: .wifiAware(.connecting(to: .allPairedDevices, from: .ticTacToeService))).run { endpoints in
    // 处理发现的端点集合，选择第一个并结束浏览
    .finish(endpoints.first!)
}

// 拿到 endpoint 后可以建立连接
let connection = NetworkConnection(to: endpoint) {
    TLS()
}

上述代码中，NetworkBrowser(run:) 的闭包会多次调用提供发现结果（endpoints 集合），我们通过返回 .finish(选定端点) 来停止浏览并获得该端点。整个调用本身是 async 的，因而可以用 try await 等到浏览完成返回结果。新 API 将之前需要在回调中处理的逻辑转为同步流程，使代码更直观。NetworkBrowser 同样可以用于 Bonjour 服务发现，只需更换 .bonjour(type:domain:) 描述符。

综上，新的 Network.framework API 在用法上更加简洁、符合直觉。无论是建立连接、数据传输，还是监听和服务发现，新 API 都充分运用了 Swift async/await，将过去分散在回调里的逻辑串联到可读性更高的顺序代码中。这不仅减少了样板代码和状态管理，也降低了出错概率，提高了开发效率。

3. 新 Network 框架的新功能与特性

  • 内置 TLV 消息封装 新框架内置了 Type-Length-Value (TLV) Framer 协议支持，可以自动将字节流封装为离散消息进行传输。使用方法很简单，只需在协议栈中加入 TLV：

    1
2
3
4
5
6

    // 在协议栈中插入 TLV 协议
let conn = NetworkConnection(to: endpoint) {
    TLV {
       TLS()  // 其下承载TLS等
    }
}

    加入 TLV 后，send 接口会提供额外的参数让你指定消息类型（type），而 receive 将直接按消息边界返回数据和元数据（包含消息 type）。开发者不再需要自己处理粘包、拆包逻辑，极大简化了以消息为单位通信的代码。这对需要与现有使用 TLV 格式协议的服务器交互时特别有用，可以直接互通。

  • 直接发送/接收 Codable 对象 新 Network 框架支持直接在连接上发送和接收 Swift 的 Codable 类型对象。通过在协议栈中加入 Coder 协议并指定模型类型和编码方式（JSON 或 plist），NetworkConnection 能自动将对象序列化发送、接收后自动解码成对象。例如：

    1
2
3
4
5
6
7
8

    // 在协议栈中加入Coder协议以发送/接收GameMessage枚举，使用JSON编码
let conn = NetworkConnection(to: endpoint) {
    Coder(GameMessage.self, using: .json) {
        TLS()
    }
}
try await conn.send(GameMessage.move(row: 1, column: 2))
let message = try await conn.receive().content  // 直接得到 GameMessage 对象

    上例中，GameMessage 是 Codable 的 Swift 枚举/结构。通过 Coder 协议，框架自动完成 JSON 编码发送和解码接收。开发者无需再手动调用 JSONEncoder/Decoder，显著减少了样板代码和错误机会。这项功能可以让您像调用本地函数一样发送对象，底层序列化过程完全透明，非常适合在客户端/服务器之间传输结构化数据。

  • 异步序列化消息接口 新 API 引入了 connection.messages 属性，其类型是一个 AsyncSequence。对于基于消息的连接（如包含 TLV 或 Coder 层），for await … in connection.messages 可以方便地逐条获取消息。相比旧 API 要循环调用 receive 并自己管理缓冲，新接口利用 Swift AsyncSequence 提供背压管理和简洁语法，让收发循环清晰明了。

  • Wi-Fi Aware 支持 iOS 26 引入了全新的 Wi-Fi Aware 点对点通信技术，Network.framework 也相应支持使用 Wi-Fi Aware 发现和连接附近设备。通过新的 NetworkBrowser，可以使用 .wifiAware 浏览描述符搜索附近支持 Wi-Fi Aware 的设备或服务。例如 Apple 提供了 DeviceDiscoveryUI 框架配合 Wi-Fi Aware，实现附近设备配对和连接。NetworkBrowser 可直接发现由 Wi-Fi Aware 广播的端点，然后像普通 endpoint 一样建立 NetworkConnection。这一功能拓展了 Network.framework 在无基础网络基础设施下（无 AP 直连）的应用场景，适合近距离设备通信。值得注意的是，Wi-Fi Aware 目前需要双方设备均支持，且 Apple 也提供专门 UI 框架辅助配对。

  • QUIC 及多路复用协议 Network.framework 早先已支持现代传输协议如 QUIC。新 API 同样支持通过声明协议栈来使用 QUIC。例如可以将协议栈声明为 QUIC 或 QUIC { TLS() } 等以建立 QUIC 连接。相比旧 API，新框架计划更好地支持多路复用协议的并发用法。然而，根据目前社区反馈，接受传入的 QUIC 连接在新 API 中尚未完全支持：NetworkListener.run 要求协议实现 OneToOneProtocol（一对一连接），而 QUIC 属于 MultiplexProtocol（多路复用）。Apple DTS 工程师 Quinn 已表示新 API 与多路复用协议的配合“仍在演进中”，建议开发者暂缓尝试用新 NetworkListener 接受 QUIC 连接，未来版本可能完善支持。因此，在 iOS 26 初版，新框架对 QUIC 的支持在被动连接场景下还有所欠缺，但积极的连接(作为客户端)应是支持的。

  • 其他改进 新 Network API 还改进了一些细节功能。例如，NetworkConnection 会自动处理网络路径切换、代理等环境变化，确保连接在蜂窝/Wi-Fi 切换时平滑过渡（这些能力其实旧 Network.framework 已具备，但新 API 继续沿用）。另外，TLS 方面 iOS 26 默认启用了抗量子加密的 TLS 1.3 混合模式，以提升安全性。这些底层特性的提升，对开发者是透明的，但彰显出新框架“开箱即用”的现代网络能力。总之，新 Network.framework 在 iOS/macOS 26 中提供的不仅是语法层面的改进，更包含新协议支持和更高层抽象，让开发者专注业务逻辑而非底层细节。

4. 新框架的社区评价与向后部署可能性

社区评价

苹果 Network 框架引入异步并发新 API 后，在开发者社区引发了热烈讨论。从 Apple 开发者论坛和 WWDC 反馈来看，大多数开发者对新 API 表示兴奋和认可。有开发者在论坛上称赞新 Network.framework 提供的结构化并发支持和更新的 API 设计，让网络编程更加简单直观。尤其是减少了大量样板代码、集成 Swift Concurrency，使网络调用像写同步代码一样顺畅，这一点收获了积极评价。

然而也有一些质疑和建议：由于这是重大重构，新 API 目前存在某些功能局限和未尽完善之处。例如前述对 QUIC 的支持不完整就是被提及的一个问题。对于这种情况，Apple 官方 DTS 建议暂时观望，表示这些能力“仍在演进”中。开发者理解这是新架构的初期现象，并期待后续版本改进。此外，一些论坛帖子提到在某些使用情境下新API表现出的性能或行为需要进一步观察，但总体没有发现严重的性能倒退问题，毕竟底层实现沿用了成熟的网络栈。

向后兼容和 Back-deploy：新的 NetworkConnection 等API 要求 iOS/iPadOS/macOS 26 及以上系统才能使用，这对需要支持旧系统的应用是一个现实障碍。社区中开发者自然产生了“能否向后部署（back-deploy）”的疑问，即是否有办法在旧系统上利用这些新特性。有些开发者呼吁苹果提供类似 Swift Concurrency back-deploy 那样的支持，让新网络API也能在老系统运行（比如通过 Swift Package 等）。但截至目前，Apple 没有宣布对此类框架级API进行向后部署的计划。一般而言，系统Framework的新功能通常不会官方适配旧系统，这是苹果生态的惯例。 对于需要兼容iOS 26以下设备的应用，实用的做法是在代码中有条件地采用新旧API：利用编译条件 if #available(iOS 26, *) 来在新系统上调用 NetworkConnection 等，并准备好在旧系统上回退使用 NWConnection 等旧API。由于 Swift 并发本身可以部署到更早的iOS版本，开发者也可以考虑针对旧系统封装一些 async/await 的适配。例如，有人利用 AsyncStream 封装 NWConnection.receive 实现类似的新API异步序列功能，但这些属于开发者自行实现的兼容方案。

结论

总的来看，社区非常期待新Network框架带来的开发体验提升，但也明白短期内不得不维护双套代码以适配不同系统。随着时间推移，iOS 26+ 普及后，新API有望逐渐取代旧API成为主流。Apple 在 WWDC 宣称这些新网络API是未来的发展方向，并未表示会在老系统提供支持。因此“back-deploy”的可能性很低，开发者只能通过编写兼容层或等待用户升级设备来过渡。 总结：Apple Network.framework 在iOS/macOS 26中通过全新的 NetworkConnection 等API实现了对异步并发的优雅支持，解决了旧架构的诸多痛点，设计更Swifty、功能更强大（TLV、Codable等）。这一重大更新赢得了开发者的正面评价，但也伴随着新旧过渡期的挑战。对于为何推倒重来设计新API，原因在于要深度拥抱 Swift 并发和提升易用性，这是旧框架无法通过小修补达到的。展望未来，随着框架不断演进（完善对QUIC等的支持）和新系统普及，网络开发将变得更简洁高效。开发者应根据应用支持的最低系统版本，选择合适的API或采取兼容策略，既利用新框架优势也保证对旧设备的支持。

Swift, Network
swift network apple
本文由作者按照 CC BY 4.0 进行授权

热门标签

apple network swift