swift-nio

swift-nio 技能概覽

swift-nio 是用來做什麼的

swift-nio 技能可幫助你推理 SwiftNIO 在後端開發中的用法：伺服器、用戶端、編解碼器、管線、緩衝區，以及符合 EventLoop 安全的非同步程式碼。當你需要的不只是一般化提示，而是要貼近框架真實限制的建議時，這個技能特別有用，尤其是在處理 EventLoopFuture、ChannelPipeline 和 ByteBuffer 時。

最適合的讀者與工作

如果你符合以下情境，就適合使用 swift-nio 技能：

• 建置 TCP/UDP 服務或協定轉接器
• 排查 EventLoop 上的阻塞工作
• 實作 ByteToMessageDecoder / MessageToByteEncoder
• 在 Swift Concurrency 與舊式 NIO futures 之間做選擇
• 在新程式碼中整合 NIOAsyncChannel

它的不同之處

這個技能不只是「寫 Swift 程式碼」而已。它對安全使用 SwiftNIO 有明確立場：避免阻塞、在適當情況下優先採用結構化並行，並把緩衝區所有權與管線順序視為第一等級的考量。當導入風險來自架構，而不是語法時，它會是更合適的選擇。

如何使用 swift-nio 技能

安裝並確認上下文正確

先用目錄的標準技能指令執行 swift-nio install 流程，接著先閱讀這個技能自己的 SKILL.md。為了得到最吻合的建議，在提問前先檢查你的目標套件：

• Package.swift：確認實際有哪些 NIO 模組
• references/Channels.md：伺服器／用戶端與管線基礎
• references/EventLoops.md：當效能或阻塞是問題時
• references/ByteToMessageCodecs.md：協定解析與封包邊界處理
• references/NIOAsyncChannel.md：非同步／await 整合
• references/patterns.md：更高層級的伺服器包裝模式

把粗略需求轉成有用的提示

swift-nio 指南在你提供網路形狀時最有效，而不只是描述 bug。好的提示會包含：

• 協定類型：TCP、UDP、Unix domain socket、檔案 I/O，或 HTTP 周邊
• 目前 API 風格：EventLoopFuture 或 async/await
• 訊息形狀：位元組、frame、標頭，或型別化負載
• 失敗模式：停住不動、部分讀取、backpressure、解碼錯誤，或 EventLoop 阻塞

範例：

“Help me design a SwiftNIO backend for a length-prefixed binary protocol. I am using NIOPosix and want async/await where possible, but I still need a ByteToMessageDecoder for framing. Show the pipeline order, what should stay on the EventLoop, and what should move to background work.”

讓輸出更好的實作流程

先從最小且真正重要的工件開始：解碼器、channel bootstrap，或管線修改。接著要求三種輸出其中之一：

1. 修正後的實作
2. 兩種設計之間的取捨
3. 針對特定執行期症狀的除錯計畫

這樣能讓 swift-nio 的使用始終對準實際程式路徑，避免落入只談一般網路概念、卻忽略 NIO 特有規則的空泛建議。

swift-nio 技能 FAQ

swift-nio 只適用於後端開發嗎？

大致上是。swift-nio 技能最擅長的是後端網路與協定工作，但只要你的程式碼使用 Channel、ByteBuffer 或 EventLoop 驅動的 I/O，它也能派上用場。若你的問題與非阻塞傳輸無關，這大概率不是正確的技能。

我需要先懂 SwiftNIO 嗎？

不需要，但你應該知道自己要解決的是什麼問題。只要能描述傳輸方式、資料形狀與目前程式碼，這個技能對初學者也很有幫助。若你的需求只是「從零教我 SwiftNIO」，它就沒那麼有用。

為什麼不用一般提示就好？

一般提示常常會忽略 SwiftNIO 的硬限制，尤其是「不要阻塞 EventLoop」、緩衝區生命週期問題，以及 async/await 要在何處安全銜接。當輸出必須在高負載下仍然正確，而不只是語法正確時，swift-nio 技能會更合適。

什麼情況下不該用它？

如果你寫的是可以依賴更高階網路 API 的簡單應用程式，或者你的問題純粹是與 channels、pipelines、decoding 或 concurrency 邊界無關的應用邏輯，就不要使用這個技能。

如何改進 swift-nio 技能

提供會改變答案的限制條件

最好的 swift-nio 結果來自會影響架構的上下文：

• 預期吞吐量或延遲目標
• 程式碼是否必須完全非同步
• 是否可以修改 wire protocol
• 是否需要與既有 handlers 或 codecs 相容
• 問題發生在 connect、read、write，還是 shutdown

如果你省略這些資訊，答案可能是對的，但會太泛，無法安全落地實作。

分享最小的失敗形狀

除錯時，貼出最小且相關的片段：

• ChannelPipeline 設定
• decoder 或 handler 方法
• bootstrap 設定
• 精確的錯誤、停滯，或不預期的 frame 邊界

這樣更容易找出常見的 swift-nio 失敗模式，例如部分解碼處理、handler 順序錯誤，或不該在 EventLoop 上執行的工作。

要求迭代計畫

如果第一版答案已經接近但還不夠，請直接要求下一步：

• “show the minimal patch”
• “rewrite this for NIOAsyncChannel”
• “identify which work can move off the EventLoop”
• “explain how to test this decoder with fragmented input”

這對 swift-nio 尤其有幫助，因為小小的設計變更就可能對執行期造成很大影響，而最佳建議通常取決於你是在優先追求正確性、簡潔性，還是非同步遷移。