「我30分鐘加了聊天界面，結(jié)果花了三周做基礎(chǔ)設(shè)施?！埂@是每個踩過坑的工程師都會說的同一句話。

聊天框本身 trivial：一個文本域、一個流式輸出區(qū)域、消息氣泡列表。但真用戶進來后，你會發(fā)現(xiàn)這東西要變成"產(chǎn)品"，還差著十萬八千里。

本文按崩潰順序，拆解那些沒人提前告訴你的坑，以及如果重來一次怎么抄近路。

第一坑：網(wǎng)絡(luò)抖動時的流式重組

你的第一個 beta 用戶合上筆記本，十分鐘后打開。對話停在"因此，最優(yōu)策略是——"，后半截沒了。刷新頁面，半截消息徹底消失，無恢復、無續(xù)傳。

問題根源：你只是"轉(zhuǎn)發(fā)"流，沒有"緩沖"流。

真正的解法需要服務(wù)端緩沖：接收上游模型的分塊、轉(zhuǎn)發(fā)給客戶端的同時寫入持久存儲?？蛻舳酥剡B時，重放已緩沖內(nèi)容+繼續(xù)實時流。

這不是玩具代碼。Cloudflare Durable Objects 能搞定（單寫入者，跨重連復制）。Postgres + Listen/Notify 也行，但得自己管連接池。AWS 的方案是 API Gateway WebSockets + DynamoDB 流。

選錯這里，六個月后規(guī)模上來、重連邏輯崩了，你得重構(gòu)熱路徑上的核心基礎(chǔ)設(shè)施。

第二坑：持久化 schema 的陷阱

好，現(xiàn)在存消息了。schema 怎么設(shè)計？

最直觀的版本：id、thread_id、role、content、created_at。五分鐘后你就會發(fā)現(xiàn)不夠用。

工具調(diào)用往哪放？模型返回的是結(jié)構(gòu)化數(shù)據(jù)，不是純文本。多模態(tài)消息呢？圖片、文件引用存在哪？不同模型的輸出格式完全不同，有的給你 JSON，有的給你 XML 包裹的函數(shù)調(diào)用。

更隱蔽的問題：版本遷移。你加了新字段，舊消息怎么兼容？查詢性能呢？按時間分頁時，刪除消息會不會導致游標漂移？

每個選擇都在鎖定未來的重構(gòu)成本。schema 設(shè)計是這里最慢、最痛苦的決策，因為改起來牽一發(fā)而動全身。

第三坑：用戶重試時的去重噩夢

上游返回 5xx，用戶狂點重試?，F(xiàn)在對話里有三條一模一樣的用戶消息，助理也回復了三次。

簡單的客戶端防抖不夠。網(wǎng)絡(luò)層超時、服務(wù)端處理成功但響應(yīng)丟失、用戶刷新后再次提交——這些場景都會繞過前端防護。

你需要冪等鍵（idempotency key）：用戶首次點擊生成唯一標識，服務(wù)端用該鍵檢測重復請求。但鍵存在哪？客戶端本地存儲？URL 參數(shù)？如果用戶換設(shè)備呢？

更麻煩的是部分成功：模型流式輸出到一半失敗了，重試時該從哪恢復？重新生成完整回復，還是續(xù)接半截內(nèi)容？兩種選擇都有用戶體驗代價。

第四坑：工具調(diào)用的審計鏈條

助理說"我?guī)湍悴橐幌绿鞖?，背后調(diào)了 API。用戶一個月后回來問"你為什么給我推薦帶傘？"你需要還原當時的完整上下文。

這意味著存儲：工具名稱、輸入?yún)?shù)、原始輸出、執(zhí)行時間戳、是否成功、失敗原因。有些工具調(diào)用是鏈式的——A 的輸出作為 B 的輸入，整個鏈條都要可追溯。

但存儲只是開始。展示層怎么渲染？用戶看到"工具調(diào)用中..."的加載態(tài)，還是直接看到結(jié)果？如果工具執(zhí)行 30 秒，這段時間對話狀態(tài)是什么？

合規(guī)場景更頭疼。某些行業(yè)要求保留工具調(diào)用日志 7 年，且不可篡改。你的 schema 設(shè)計之初考慮審計字段了嗎？

第五坑：多設(shè)備同步的時序地獄

用戶手機和電腦同時開著同一對話。手機發(fā)了消息，電腦上的對話該怎么更新？

最簡單的輪詢方案：每秒查一次新消息。電池殺手，且延遲明顯。

WebSocket 實時推送？現(xiàn)在你要維護連接狀態(tài)、心跳檢測、斷線重連。兩個設(shè)備同時發(fā)送消息呢？需要全局序列號保證最終一致性。

最惡心的場景：設(shè)備 A 發(fā)送消息，設(shè)備 B 在收到推送前也發(fā)送了消息。兩條消息的服務(wù)端到達順序，與用戶感知的順序可能完全不同。對話歷史變成亂序拼圖。

第六坑：歷史接口的隱形復雜度

對話要支持分頁加載、關(guān)鍵詞搜索、按時間排序。聽起來像標準 CRUD？

實際約束：長對話可能上千條消息，不能一次性返回。游標分頁 vs 偏移分頁？游標更穩(wěn)，但實現(xiàn)復雜。搜索要支持內(nèi)容+工具調(diào)用結(jié)果+元數(shù)據(jù)，索引怎么建？

背壓（backpressure）問題：用戶瘋狂滾動歷史，你的數(shù)據(jù)庫扛得住嗎？需要緩存層、限流、甚至預(yù)加載策略。

還有刪除的麻煩。用戶刪了一條消息，后續(xù)消息的工具調(diào)用可能依賴它的輸出。物理刪除還是軟刪除？軟刪除影響查詢性能，物理刪除破壞審計鏈條。

第七坑：懸掛流的資源泄漏

客戶端打開流式連接，然后關(guān)了瀏覽器標簽。服務(wù)端還在往一個已斷開的連接寫數(shù)據(jù)。

TCP 連接不會立即感知對端消失。你可能要等幾分鐘的超時，期間占用內(nèi)存、數(shù)據(jù)庫連接、上游模型的生成資源。

需要心跳機制檢測存活，但心跳頻率和超時閾值是 trade-off：太激進誤殺慢連接，太保守資源泄漏。

更隱蔽的是"僵尸流"：連接名義上活著，但客戶端實際已崩潰。服務(wù)端持續(xù)緩沖數(shù)據(jù)，內(nèi)存無限增長。

第八坑：多模型支持的 schema 爆炸

一開始只接 OpenAI，schema 按它的格式設(shè)計?，F(xiàn)在要加 Claude，發(fā)現(xiàn)消息結(jié)構(gòu)完全不同：system 角色位置、工具調(diào)用格式、thinking 塊的特殊處理。

抽象層怎么設(shè)計？統(tǒng)一格式轉(zhuǎn)換會丟失模型特有功能（比如 Claude 的 artifacts）。保留原生格式則查詢、渲染、審計邏輯都要分支處理。

新模型還在快速迭代。你剛適配完 GPT-4 Turbo，GPT-4o 的多模態(tài)格式又變了。schema 的"通用性"是個移動靶子。

如果重來一次：抄近路的優(yōu)先級

三周填完這些坑后，作者給出的實戰(zhàn)排序：

第一，直接用托管方案。Vercel AI SDK、LangChain 的流式抽象、或者 Cloudflare 的 Durable Objects 模板——別從零寫緩沖和重連邏輯。這些方案已經(jīng)踩過你即將踩的坑。

第二，schema 預(yù)留擴展字段。用 JSONB 存模型原生輸出，別急著規(guī)范化。查詢性能問題等真有性能問題時再優(yōu)化，過早優(yōu)化是陷阱。

第三，冪等鍵從第一天就加。用戶重試是 100% 會發(fā)生的事件，不是邊緣 case。鍵的生成策略要跨設(shè)備一致，建議用用戶ID+時間戳+內(nèi)容哈希。

第四，工具調(diào)用存儲原始請求/響應(yīng)。別只存摘要，審計時你會需要完整上下文。渲染層單獨處理，存儲層保持誠實。

第五，多設(shè)備同步用樂觀更新+最終一致。別追求實時強一致，成本太高。本地先顯示，服務(wù)端確認后微調(diào)。

第六，歷史接口先上游標分頁+簡單緩存。搜索和復雜過濾延后，大多數(shù)用戶不會翻到第 50 頁。

第七，流超時設(shè)激進一點。30 秒無數(shù)據(jù)直接斷，重連成本低于資源泄漏。監(jiān)控懸掛流數(shù)量，設(shè)告警。

第八，模型抽象層只做最小轉(zhuǎn)換。保留原始消息格式，查詢和渲染時按需解析。別幻想"通用格式"能一勞永逸。

為什么這些坑被低估

每個單獨問題都有現(xiàn)成解法，Stack Overflow 上能搜到。但八個問題交織時，解法互相沖突：為了審計存原始格式，查詢性能就崩；為了實時性用 WebSocket，懸掛流就 leak。

更深層的原因：Demo 文化和產(chǎn)品文化的鴻溝。30 分鐘的聊天框能騙過投資人、騙過老板、甚至騙過你自己——直到真用戶進來。

作者的原話很直白：「如果你 ship 過 AI 聊天，你知道我在說什么。如果你還沒 ship，這是我希望先讀到的東西?！?/p>

這行字值得貼在你顯示器邊框上。

（冷知識：Cloudflare 的 Durable Objects 文檔里有個"聊天應(yīng)用"示例，點進去看源碼——它處理了本文提到的 6 個坑，但另外 2 個被標記為"讀者練習"。）