SwiftNIO

SwiftNIO 是一个跨平台的异步事件驱动网络应用程序框架，用于快速开发可维护的高性能协议服务器和客户端。

它就像 Netty，但使用 Swift 编写。

SwiftNIO 项目被拆分到多个仓库中

NIO 2.29.0 及更早版本支持 Swift 5.0+，NIO 2.39.0 及更早版本支持 Swift 5.2+。

在此仓库中，我们有许多产品提供不同的功能。 该软件包包含以下产品

• NIO。 这是一个总括模块，导出了 NIOCore，NIOEmbedded 和 NIOPosix。
• NIOCore。 这提供了使用 SwiftNIO 的核心抽象和类型（有关更多详细信息，请参见“概念概述”）。 大多数 NIO 扩展项目，例如提供新的 EventLoop 和 Channel 或新的协议实现，只需要依赖于 NIOCore。
• NIOPosix。 这提供了主要的 [EventLoopGroup]，EventLoop 和 Channel，用于基于 POSIX 的系统。 这是我们的高性能核心 I/O 层。 通常，只有计划进行实际 I/O 的项目（例如高级协议实现或应用程序）才应导入此内容。
• NIOEmbedded。 这提供了 EmbeddedChannel 和 EmbeddedEventLoop，它们是 NIOCore 抽象的实现，可以对其执行进行细粒度控制。 这些最常用于测试，但也可以用于以与网络完全分离的方式驱动协议实现。
• NIOConcurrencyHelpers。 这提供了一些 NIO 实现使用的底层并发原语，例如锁和原子。
• NIOFoundationCompat。 这扩展了许多 NIO 类型，以更好地与 Foundation 数据类型进行互操作。 如果您正在使用诸如 Data 之类的 Foundation 数据类型，则应导入此内容。
• NIOTLS。 这为使用多个 TLS 实现提供了一些常见的抽象类型。 请注意，这本身不提供 TLS：请研究 swift-nio-ssl 和 swift-nio-transport-services 以获得具体的实现。
• NIOHTTP1。 这提供了底层的 HTTP/1.1 协议实现。
• NIOWebSocket。 这提供了底层的 WebSocket 协议实现。
• NIOTestUtils。 这为使用 SwiftNIO 的测试项目提供了一些助手。
• NIOFileSystem。 这提供了用于与文件系统交互的 async API。

在下面，您可以找到一些使用 SwiftNIO 完成的协议实现的列表。 这是 SwiftNIO 项目的一部分或被接受到 SSWG 的孵化过程中的协议的不详尽列表。 下面列出的所有库都以非阻塞方式使用 SwiftNIO 执行所有 I/O。

底层协议实现通常是 ChannelHandler 的集合，它们实现一个协议，但仍然要求用户对 SwiftNIO 有很好的了解。 通常，底层协议实现将被包装在具有更好，更用户友好的 API 的高级库中。

高级实现通常是带有 API 的库，该 API 不会公开 SwiftNIO 的 ChannelPipeline，因此可以在几乎没有（或没有）SwiftNIO 特定知识的情况下使用。 下面列出的实现仍然在 SwiftNIO 中执行所有 I/O，并且与 SwiftNIO 生态系统集成得非常好。

这是当前版本的 SwiftNIO，并且将在可预见的将来得到支持。

我们承诺支持最新发布的 Swift 版本（当前为 5.10）以及之前的两个次要版本，除非在一个代码库中无法做到这一点。 此外，还会针对最新的 beta 版本（如果有）以及夜间 Swift 构建运行检查，目的是使这些检查通过。

SwiftNIO 的最新版本支持 Swift 5.9 及更高版本。 以下详细说明了 SwiftNIO 版本支持的最低 Swift 版本

SwiftNIO 1 被认为是生命周期结束 - 强烈建议您迁移到更新的版本。 核心 NIO 团队不积极研究此版本。 此版本将不会添加任何新功能，但是修复错误或安全漏洞的 PR 将被接受，直到 2022 年 5 月底。

如果您有一个想要迁移到 SwiftNIO 2 的 SwiftNIO 1 应用程序或库，请查看我们为您准备的迁移指南。

最新发布的 SwiftNIO 1 版本支持 Swift 4.0、4.1、4.2 和 5.0。

SwiftNIO 旨在支持所有支持 Swift 的平台。 当前，它在 macOS 和 Linux 上进行开发和测试，并且已知支持以下操作系统版本

• Ubuntu 18.04+
• macOS 10.9+，iOS 7+; (macOS 10.14+，iOS 12+，tvOS 12+ 或 watchOS 6+ 与 swift-nio-transport-services)

SwiftNIO 遵循 SemVer 2.0.0，并提供单独的文档声明 SwiftNIO 的公共 API。

这对您意味着，您应该依赖 SwiftNIO，其版本范围涵盖从您需要的最低 SwiftNIO 版本到下一个主要版本的所有内容。 在 SwiftPM 中，可以通过指定例如 from: "2.0.0" 轻松完成，这意味着您支持从 2.0.0 到 (不包括) 3.0.0 的每个版本的 SwiftNIO。 SemVer 和 SwiftNIO 的公共 API 保证应导致一个可以正常工作的程序，而无需担心测试每个版本的兼容性。

SwiftNIO 从根本上来说是用于在 Swift 中构建高性能网络应用程序的底层工具。 它特别针对那些使用“每个连接一个线程”的并发模型效率低下或站不住脚的用例。 这是构建使用大量相对低利用率的连接的服务器（例如 HTTP 服务器）时的常见限制。

为了实现其目标，SwiftNIO 广泛使用了“非阻塞 I/O”：因此得名！ 非阻塞 I/O 与更常见的阻塞 I/O 模型不同，因为应用程序不等待将数据发送到网络或从网络接收数据：相反，SwiftNIO 请求内核在无需等待的情况下可以执行 I/O 操作时通知它。

SwiftNIO 的目标不是提供高级解决方案，例如 Web 框架。 相反，SwiftNIO 专注于为这些更高级别的应用程序提供底层构建块。 在构建 Web 应用程序时，大多数用户都不希望直接使用 SwiftNIO：相反，他们希望使用 Swift 生态系统中可用的许多出色的 Web 框架之一。 但是，这些 Web 框架可能会选择在底层使用 SwiftNIO 来提供其网络支持。

以下各节将描述 SwiftNIO 提供的底层工具，并快速概述如何使用它们。 如果您对这些概念感到满意，则可以直接跳到本 README 的其他部分。

SwiftNIO 的基本构建块是以下 8 种类型的对象

• EventLoopGroup，一个协议，由 NIOCore 提供。
• EventLoop，一个协议，由 NIOCore 提供。
• Channel，一个协议，由 NIOCore 提供。
• ChannelHandler，一个协议，由 NIOCore 提供。
• Bootstrap，由 NIOCore 提供的几个相关结构。
• ByteBuffer，一个结构体，由 NIOCore 提供。
• EventLoopFuture，一个泛型类，由 NIOCore 提供。
• EventLoopPromise，一个泛型结构体，由 NIOCore 提供。

所有 SwiftNIO 应用程序最终都由这些各种组件构成。

SwiftNIO 的基本 I/O 原语是事件循环 (event loop)。事件循环是一个对象，它等待事件发生（通常是与 I/O 相关的事件，例如“接收到数据”），然后在事件发生时触发某种回调。在几乎所有 SwiftNIO 应用程序中，事件循环的数量相对较少：通常每个应用程序想要使用的 CPU 核心只有一到两个。一般来说，事件循环在应用程序的整个生命周期内运行，在一个无限循环中分发事件。

事件循环被汇集到事件循环组 (event loop *groups*) 中。这些组提供了一种机制，用于在事件循环之间分配工作。例如，在监听入站连接时，监听套接字将在一个事件循环上注册。但是，我们不希望在该监听套接字上接受的所有连接都注册到同一个事件循环，因为这可能会使一个事件循环过载，而其他事件循环则空闲。因此，事件循环组提供了在多个事件循环之间分散负载的能力。

在目前的 SwiftNIO 中，有一个 EventLoopGroup 实现和两个 EventLoop 实现。对于生产应用程序，有 MultiThreadedEventLoopGroup，这是一个 EventLoopGroup，它创建多个线程（使用 POSIX pthreads 库）并在每个线程上放置一个 SelectableEventLoop。SelectableEventLoop 是一个事件循环，它使用选择器（根据目标系统，可以是 kqueue 或 epoll）来管理来自文件描述符的 I/O 事件并分发工作。这些 EventLoop 和 EventLoopGroup 由 NIOPosix 模块提供。此外，还有一个 EmbeddedEventLoop，这是一个虚拟事件循环，主要用于测试目的，由 NIOEmbedded 模块提供。

EventLoop 具有许多重要的属性。最重要的是，它们是 SwiftNIO 应用程序中完成所有工作的方式。为了确保线程安全，任何想要在 SwiftNIO 中的几乎任何其他对象上完成的工作都必须通过 EventLoop 进行分发。EventLoop 对象拥有 SwiftNIO 应用程序中的几乎所有其他对象，并且了解它们的执行模型对于构建高性能 SwiftNIO 应用程序至关重要。

虽然 EventLoop 对于 SwiftNIO 的工作方式至关重要，但大多数用户与它们的交互不会超过请求它们创建 EventLoopPromise 并安排工作。SwiftNIO 应用程序中大多数用户花费最多时间交互的部分是 Channel 和 ChannelHandler。

用户在 SwiftNIO 程序中交互的几乎每个文件描述符都与单个 Channel 相关联。Channel 拥有此文件描述符，并负责管理其生命周期。它还负责处理该文件描述符上的入站和出站事件：每当事件循环具有与文件描述符相对应的事件时，它将通知拥有该文件描述符的 Channel。

然而，Channel 本身并没有什么用处。毕竟，很少有应用程序不想对它在套接字上发送或接收的数据做任何事情！因此，Channel 的另一个重要部分是 ChannelPipeline。

ChannelPipeline 是一个对象序列，称为 ChannelHandler，它们处理 Channel 上的事件。ChannelHandler 按照顺序一个接一个地处理这些事件，并在处理过程中对事件进行修改和转换。这可以被认为是数据处理管道；因此得名 ChannelPipeline。

所有 ChannelHandler 都是入站或出站处理器，或者两者都是。入站处理器处理“入站”事件：例如从套接字读取数据、读取套接字关闭或由远程对等方发起的其他类型的事件。出站处理器处理“出站”事件，例如写入、连接尝试和本地套接字关闭。

每个处理器按顺序处理事件。例如，读取事件从管道的前面传递到后面，一次一个处理器，而写入事件从管道的后面传递到前面。每个处理器都可以随时生成入站或出站事件，这些事件将被发送到适当方向的下一个处理器。这允许处理器拆分读取、合并写入、延迟连接尝试以及通常执行事件的任意转换。

一般来说，ChannelHandler 被设计为高度可重用的组件。这意味着它们往往被设计成尽可能小，执行一个特定的数据转换。这允许处理器以新颖和灵活的方式组合在一起，这有助于代码重用和封装。

ChannelHandler 能够通过使用 ChannelHandlerContext 来跟踪它们在 ChannelPipeline 中的位置。这些对象包含对管道中上一个和下一个通道处理器的引用，确保 ChannelHandler 始终可以在管道中发出事件。

SwiftNIO 附带了许多内置的 ChannelHandler，它们提供了有用的功能，例如 HTTP 解析。此外，高性能应用程序希望在 ChannelHandler 中提供尽可能多的逻辑，因为它有助于避免上下文切换的问题。

此外，SwiftNIO 附带了一些 Channel 实现。特别是，它附带了 ServerSocketChannel，一个用于接受入站连接的套接字的 Channel；SocketChannel，一个用于 TCP 连接的 Channel；和 DatagramChannel，一个用于 UDP 套接字的 Channel。所有这些都由 NIOPosix 模块提供。它还提供 EmbeddedChannel，一个主要用于测试的 Channel，由 NIOEmbedded 模块提供。

关于 ChannelPipeline 的一个重要说明是它们是线程安全的。这对于编写 SwiftNIO 应用程序非常重要，因为它允许您编写更简单的 ChannelHandler，因为您知道它们不需要同步。

然而，这是通过在与 EventLoop 相同的线程上分发 ChannelPipeline 上的所有代码来实现的。这意味着，作为一般规则，ChannelHandler **不得** 在不将其分发到后台线程的情况下调用阻塞代码。如果 ChannelHandler 由于任何原因而阻塞，则连接到父 EventLoop 的所有 Channel 都将无法继续，直到阻塞调用完成。

这是编写 SwiftNIO 应用程序时常见的问题。如果在阻塞样式中编写代码很有用，强烈建议您在管道中完成工作后将其分发到不同的线程。

虽然可以直接配置 Channel 并将其注册到 EventLoop，但通常使用更高级别的抽象来处理此工作更有用。

因此，SwiftNIO 附带了许多 Bootstrap 对象，其目的是简化通道的创建。一些 Bootstrap 对象还提供其他功能，例如支持 Happy Eyeballs 来进行 TCP 连接尝试。

目前，SwiftNIO 在 NIOPosix 模块中提供了三个 Bootstrap 对象：ServerBootstrap，用于引导监听通道；ClientBootstrap，用于引导客户端 TCP 通道；以及 DatagramBootstrap，用于引导 UDP 通道。

SwiftNIO 应用程序中的大部分工作都涉及字节缓冲区的传递。至少，数据以字节缓冲区形式在网络上发送和接收。因此，拥有一个针对 SwiftNIO 应用程序执行的这类工作进行优化的，高性能数据结构至关重要。

为此，SwiftNIO 提供了 ByteBuffer，这是一个快速的写时复制字节缓冲区，构成了大多数 SwiftNIO 应用程序的关键构建块。此类型由 NIOCore 模块提供。

ByteBuffer 提供了许多有用的功能，此外还提供了许多钩子，可在“不安全”模式下使用它。 这会关闭边界检查以提高性能，但代价是可能会使您的应用程序出现内存正确性问题。

一般来说，强烈建议您始终在安全模式下使用 ByteBuffer。

有关 ByteBuffer 的 API 的更多详细信息，请参见下面的 API 文档链接。

编写并发代码和编写同步代码之间的主要区别在于，并非所有操作都会立即完成。 例如，当您在通道上写入数据时，事件循环可能无法立即将该写入刷新到网络。 因此，SwiftNIO 提供了 EventLoopPromise<T> 和 EventLoopFuture<T> 来管理异步完成的操作。 这些类型由 NIOCore 模块提供。

EventLoopFuture<T> 本质上是一个容器，用于保存将在未来的某个时间填充的函数的返回值。 每个 EventLoopFuture<T> 都有一个对应的 EventLoopPromise<T>，这是将放置结果的对象。 当 promise 成功时，future 将被实现。

如果必须轮询 future 以检测它何时完成，那将非常低效，因此 EventLoopFuture<T> 被设计为具有托管回调。 本质上，您可以链接 future 的回调，这些回调将在结果可用时执行。 EventLoopFuture<T> 甚至会仔细安排调度，以确保这些回调始终在最初创建 promise 的事件循环上执行，这有助于确保您不需要围绕 EventLoopFuture<T> 回调进行过多的同步。

另一个需要考虑的重要主题是传递给 close 的 promise 的工作方式与 Channel 上的 closeFuture 的工作方式之间的差异。 例如，传入 close 的 promise 将在 Channel 关闭之后，但在 ChannelPipeline 完全清除之前成功。 这将允许您在 ChannelPipeline 完全清除之前对其执行操作（如果需要）。 如果希望在不采取任何进一步操作的情况下，等待 Channel 关闭并且 ChannelPipeline 被清除，那么更好的选择是等待 closeFuture 成功。

有几个函数可用于将回调应用于 EventLoopFuture<T>，具体取决于您希望它们如何以及何时执行。 这些函数的详细信息留给 API 文档。

SwiftNIO 旨在成为构建联网应用程序和框架的强大工具，但不打算成为所有抽象级别的完美解决方案。 SwiftNIO 紧密专注于在较低抽象级别提供基本的 I/O 原语和协议实现，从而将更具表现力但速度较慢的抽象留给更广泛的社区来构建。 其目的是 SwiftNIO 将成为服务器端应用程序的构建块，而不是这些应用程序将直接使用的框架。

需要其网络堆栈提供极高性能的应用程序可能会选择直接使用 SwiftNIO，以减少其抽象的开销。 这些应用程序应该能够以相对较少的维护成本保持极高的性能。 SwiftNIO 还侧重于为此用例提供有用的抽象，以便可以直接构建极高性能的网络服务器。

核心 SwiftNIO 存储库将直接在树中包含一些极其重要的协议实现，例如 HTTP。 但是，我们认为大多数协议实现应该与底层网络堆栈的发布周期分离，因为发布节奏可能会非常不同（更快或更慢）。 因此，我们积极鼓励社区在树外开发和维护其协议实现。 实际上，某些第一方 SwiftNIO 协议实现（包括我们的 TLS 和 HTTP/2 绑定）是在树外开发的！

• API 文档

目前有几个示例项目演示了如何使用 SwiftNIO。

• 聊天客户端 https://github.com/apple/swift-nio/tree/main/Sources/NIOChatClient
• 聊天服务器 https://github.com/apple/swift-nio/tree/main/Sources/NIOChatServer
• 回显客户端 https://github.com/apple/swift-nio/tree/main/Sources/NIOEchoClient
• 回显服务器 https://github.com/apple/swift-nio/tree/main/Sources/NIOEchoServer
• UDP 回显客户端 https://github.com/apple/swift-nio/tree/main/Sources/NIOUDPEchoClient
• UDP 回显服务器 https://github.com/apple/swift-nio/tree/main/Sources/NIOUDPEchoServer
• HTTP 客户端 https://github.com/apple/swift-nio/tree/main/Sources/NIOHTTP1Client
• HTTP 服务器 https://github.com/apple/swift-nio/tree/main/Sources/NIOHTTP1Server
• WebSocket 客户端 https://github.com/apple/swift-nio/tree/main/Sources/NIOWebSocketClient
• WebSocket 服务器 https://github.com/apple/swift-nio/tree/main/Sources/NIOWebSocketServer

要构建和运行它们，请运行以下命令，将 TARGET_NAME 替换为 ./Sources 下的文件夹名称

swift run TARGET_NAME

例如，要运行 NIOHTTP1Server，请运行以下命令

swift run NIOHTTP1Server

SwiftNIO 主要使用 SwiftPM 作为其构建工具，因此我们也建议使用它。 如果你想在自己的项目中依赖 SwiftNIO，只需在你的 Package.swift 中添加一个 dependencies 子句即可

dependencies: [
    .package(url: "https://github.com/apple/swift-nio.git", from: "2.0.0")
]

然后将适当的 SwiftNIO 模块添加到你的目标依赖项中。 添加目标依赖项的语法在 Swift 版本之间略有不同。 例如，如果你想依赖 NIOCore、NIOPosix 和 NIOHTTP1 模块，请指定以下依赖项

dependencies: [.product(name: "NIOCore", package: "swift-nio"),
               .product(name: "NIOPosix", package: "swift-nio"),
               .product(name: "NIOHTTP1", package: "swift-nio")]

如果你的项目设置为 Xcode 项目，并且你使用的是 Xcode 11+，你可以通过单击 File -> Swift Packages -> Add Package Dependency 将 SwiftNIO 添加为 Xcode 项目的依赖项。 在即将出现的对话框中，请输入 https://github.com/apple/swift-nio.git，然后单击两次 Next。 最后，选择你计划使用的目标（例如 NIOCore、NIOHTTP1 和 NIOFoundationCompat），然后单击完成。 现在你将能够在你的项目中 import NIOCore（以及你已选择的所有其他目标）。

要处理 SwiftNIO 本身，或者要研究一些演示应用程序，你可以直接克隆存储库并使用 SwiftPM 来帮助构建它。 例如，你可以运行以下命令来编译和运行示例回显服务器

swift build
swift test
swift run NIOEchoServer

要验证它是否正常工作，你可以使用另一个 shell 尝试连接到它

echo "Hello SwiftNIO" | nc localhost 9999

如果一切顺利，你将看到消息回显给你。

要在 Xcode 中使用 SwiftNIO，你可以直接在 Xcode 中打开 Package.swift 文件，并使用 Xcode 对 SwiftPM Packages 的支持。

或者，你可能希望使用 docker-compose 进行开发或测试。

首先确保你已安装 Docker，然后运行以下命令

• docker-compose -f docker/docker-compose.yaml run test

  将创建一个具有 Swift 运行时和其他构建和测试依赖项的基本镜像，编译 SwiftNIO 并运行单元和集成测试

• docker-compose -f docker/docker-compose.yaml up echo

  将创建一个基本镜像，编译 SwiftNIO，并在 localhost:9999 上运行示例 NIOEchoServer。 通过 echo Hello SwiftNIO | nc localhost 9999 进行测试。

• docker-compose -f docker/docker-compose.yaml up http

  将创建一个基本镜像，编译 SwiftNIO，并在 localhost:8888 上运行示例 NIOHTTP1Server。 通过 curl https://:8888 进行测试

• docker-compose -f docker/docker-compose.yaml -f docker/docker-compose.2204.57.yaml run test

  将创建一个使用 Ubuntu 22.04 和 Swift 5.7 的基本镜像，编译 SwiftNIO 并运行单元和集成测试。 docker 目录中存在用于其他 Ubuntu 和 swift 版本的文件。

注意：本节仅在您想自己开发 SwiftNIO 时才相关。 如果你只想将 SwiftNIO 用作 SwiftPM 包，则可以忽略此处的信息。

在大多数情况下，SwiftNIO 的开发与任何其他 SwiftPM 项目一样简单。 也就是说，我们确实有一些流程值得您在贡献之前了解。 有关详细信息，请参见此存储库中的 CONTRIBUTING.md。

SwiftNIO 的 main 分支是 SwiftNIO 2 的下一个版本的开发分支，它仅支持 Swift 5。

为了能够编译和运行 SwiftNIO 以及集成测试，您需要在您的系统上安装一些先决条件。

• Xcode 11.4 或更高版本，建议使用 Xcode 12。

• 来自 swift.org/download 的 Swift 5.7 或更高版本。 我们始终建议使用最新的发布版本。
• netcat (仅用于集成测试)
• lsof (仅用于集成测试)
• shasum (仅用于集成测试)

# install swift tarball from https://swiftlang.cn/downloads
apt-get install -y git curl libatomic1 libxml2 netcat-openbsd lsof perl

dnf install swift-lang /usr/bin/nc /usr/bin/lsof /usr/bin/shasum

swift-nio 的基准测试位于此存储库的 Benchmarks 子文件夹中的一个单独的 Swift Package 中。 它们使用 package-benchmark 插件。 基准测试依赖于 jemalloc 内存分配库，package-benchmark 使用它来捕获内存分配统计信息。 可以在 package-benchmark 的 入门文章 中找到安装指南。 之后，您可以通过转到 Benchmarks 子文件夹（例如 cd Benchmarks）并调用以下命令，从 CLI 运行基准测试

swift package benchmark

有关更多信息，请参阅 swift package benchmark --help 或 package-benchmark 的文档。