swift-nio

swift-nio 技能概览

swift-nio 是做什么的

swift-nio 技能帮助你理解 SwiftNIO 在后端开发中的实际用法：服务器、客户端、编解码器、pipeline、buffer，以及适合 event loop 的异步代码。当你需要的不只是一个泛泛的提示，而是能贴合框架真实约束的指导时，它尤其有用，特别是在处理 EventLoopFuture、ChannelPipeline 和 ByteBuffer 时。

最适合哪些读者和场景

如果你正在做以下事情，swift-nio 技能会很合适：

• 构建 TCP/UDP 服务或协议适配器
• 排查 EventLoop 上的阻塞工作
• 实现 ByteToMessageDecoder / MessageToByteEncoder
• 在 Swift Concurrency 和旧版 NIO futures 之间做选择
• 在新代码中集成 NIOAsyncChannel

它的不同之处

这个技能不只是“写 Swift 代码”。它对安全使用 SwiftNIO 有明确偏好：避免阻塞，在合适的时候优先使用结构化并发，并把 buffer 所有权和 pipeline 顺序视为一等问题。也正因为如此，当 adoption 风险来自架构而不是语法时，它会更适合。

如何使用 swift-nio 技能

安装并确认上下文正确

先用目录标准的 skills 命令执行 swift-nio install 流程，然后先阅读技能自己的 SKILL.md。为了更准确匹配你的场景，在提问前先检查目标 package：

• Package.swift：确认实际包含哪些 NIO modules
• references/Channels.md：查看 server/client 和 pipeline 基础
• references/EventLoops.md：当性能或阻塞是问题时查看这里
• references/ByteToMessageCodecs.md：处理协议解析和 framing 时查看这里
• references/NIOAsyncChannel.md：做 async/await 集成时查看这里
• references/patterns.md：查看更高层的 server 包装模式

把模糊需求变成有用的提问

swift-nio 指南在你提供网络形态时效果最好，而不只是报错信息。好的提问通常会包含：

• 协议类型：TCP、UDP、Unix domain socket、文件 I/O，或 HTTP plumbing
• 当前 API 风格：EventLoopFuture 还是 async/await
• 消息形态：字节、帧、头部，或强类型 payload
• 失败模式：卡住、半包读取、backpressure、解码错误，或 event loop 阻塞

示例：

“帮我为一个长度前缀二进制协议设计 SwiftNIO 后端。我在用 NIOPosix，并且希望尽可能使用 async/await，但仍然需要一个 ByteToMessageDecoder 来做 framing。请说明 pipeline 顺序、哪些逻辑应该留在 EventLoop 上、哪些应该移到后台工作。”

让输出更实用的工作流

先从最关键、最小的那个产物开始：一个 decoder、一个 channel bootstrap，或者一次 pipeline 调整。然后再明确要求以下三种输出之一：

1. 修正后的实现
2. 两种设计之间的取舍建议
3. 针对某个运行时症状的排查方案

这种方式能让 swift-nio 的用法始终贴着真实代码路径，避免得到那种忽略 NIO 特有规则的通用网络建议。

swift-nio 技能 FAQ

swift-nio 只适合后端开发吗？

大体上是。swift-nio 技能最擅长的是后端网络和协议处理，但只要代码里涉及 Channel、ByteBuffer 或基于 EventLoop 的 I/O，它也能派上用场。如果你的问题与非阻塞传输无关，那大概率不是合适的技能。

我需要已经熟悉 SwiftNIO 吗？

不需要，但你至少要清楚自己想解决的问题。只要能描述传输方式、数据形态和现有代码，这个技能对初学者也有帮助。如果你的请求只是“从零教我 SwiftNIO”，它的效果就会差很多。

为什么不直接用普通 prompt？

普通 prompt 经常会漏掉 SwiftNIO 的硬约束，尤其是“不要阻塞 EventLoop”、buffer 生命周期问题，以及 async/await 应该安全落在哪里。swift-nio 技能更适合那些必须在高负载下依然正确的输出，而不只是语法上能通过的代码。

什么时候不应该用它？

如果你写的是一个可以直接依赖更高层网络 API 的简单应用，或者你的问题纯粹是与 Channel、pipeline、解码或并发边界无关的应用逻辑，那就不要用这个技能。

如何改进 swift-nio 技能

提供会改变答案的约束

想拿到最好的 swift-nio 结果，就要给出会影响架构的上下文：

• 预期吞吐量或延迟目标
• 代码是否必须完全 async
• 是否可以修改 wire protocol
• 是否需要兼容现有 handlers 或 codecs
• 问题发生在 connect、read、write 还是 shutdown

如果省略这些信息，答案可能是对的，但会过于笼统，难以安全落地。

共享最小的失败形态

如果是排查问题，尽量贴出最小、最相关的片段：

• ChannelPipeline 的配置
• decoder 或 handler 方法
• bootstrap 配置
• 具体的错误、卡顿，或意外的 frame 边界

这样更容易定位常见的 swift-nio 失效模式，比如半包解码处理不当、handler 顺序错误，或本不该在 EventLoop 上运行的工作。

要求一个迭代计划

如果第一版答案已经接近，但还不够，就直接明确要求下一步：

• “给我最小 patch”
• “把这个重写成 NIOAsyncChannel”
• “指出哪些工作可以移出 EventLoop”
• “解释如何用碎片化输入测试这个 decoder”

这一点对 swift-nio 尤其有用，因为很小的设计变化就可能带来很大的运行时影响，而最好的建议通常取决于你是在优化正确性、简洁性，还是 async 迁移。