opencode HttpApi 路由模式實(shí)戰(zhàn)Effect 類型化路由樹(shù)、SSE 流與 WebSocket 升級(jí)的正確寫法【免費(fèi)下載鏈接】opencodeThe open source coding agent.項(xiàng)目地址: https://gitcode.com/GitHub_Trending/openc/opencode本文基于 opencode 倉(cāng)庫(kù)中packages/opencode實(shí)例 HTTP 服務(wù)的內(nèi)部路由規(guī)范AGENTS.md展開(kāi)講清楚該項(xiàng)目如何基于 Effect 的HttpApiBuilder組織類型化路由樹(shù)普通 JSON 端點(diǎn)、SSE 流式端點(diǎn)、WebSocket 升級(jí)路由分別應(yīng)該用哪套 API 寫法中間件、錯(cuò)誤契約與依賴注入應(yīng)該放在哪一層。讀完本篇你可以直接按照倉(cāng)庫(kù)既有風(fēng)格為 opencode 新增一個(gè) HttpApi 端點(diǎn)并理解 server.ts 中整棵路由樹(shù)是如何組裝、鑒權(quán)并對(duì)外提供 OpenAPI 文檔的。一、總覽三層路由寫法及其適用邊界規(guī)范文件 AGENTS.md 給出的核心規(guī)則可以概括為一張“寫法選擇表”路由類型推薦寫法倉(cāng)庫(kù)實(shí)例普通 HTTP 端點(diǎn)含 SSE 流式響應(yīng)HttpApiBuilder.group(...)handlers/session.ts、handlers/event.ts需要原始請(qǐng)求/響應(yīng)體的聲明式端點(diǎn)如 WebSocket 升級(jí)HttpApiBuilder.group(...)內(nèi)使用handleRaw(...)handlers/pty.ts聲明式 API 面之外的路由如 UI 兜底路由原生HttpRouter.use(...)server.ts 中的uiRoute這套分層的意義在于只要端點(diǎn)在“聲明式 API 面”內(nèi)它的中間件、路由上下文與 OpenAPI 元數(shù)據(jù)就能掛在同一棵類型化路由樹(shù)上只有真正脫離 API 面的路由才允許退化為原始HttpRouter。目錄結(jié)構(gòu)上規(guī)范所指的代碼位于 packages/opencode/src/server/routes/instance/httpapi 下分為groups/端點(diǎn)契約聲明、handlers/端點(diǎn)實(shí)現(xiàn)、middleware/中間件契約與實(shí)現(xiàn)以及api.ts/server.ts組裝邊界四個(gè)部分正好對(duì)應(yīng)規(guī)范中“聲明、實(shí)現(xiàn)、中間件、組裝”四個(gè)位置。二、普通端點(diǎn)HttpApiBuilder.group中一次性取出穩(wěn)定服務(wù)規(guī)范的第一條要求構(gòu)建 handler 層時(shí)把穩(wěn)定服務(wù)一次性yield*出來(lái)然后在各端點(diǎn)實(shí)現(xiàn)中閉包引用它們而不是在每個(gè)請(qǐng)求回調(diào)里反復(fù)構(gòu)造依賴。規(guī)范給出的最小范例export const sessionHandlers HttpApiBuilder.group(InstanceHttpApi, session, (handlers) Effect.gen(function* () { const session yield* Session.Service return handlers.handle(list, () session.list()) }), )倉(cāng)庫(kù)中真實(shí)的 sessionHandlers 是這一模式的完整體現(xiàn)export const sessionHandlers HttpApiBuilder.group(InstanceHttpApi, session, (handlers) Effect.gen(function* () { const session yield* Session.Service const shareSvc yield* SessionShare.Service const promptSvc yield* SessionPrompt.Service const revertSvc yield* SessionRevert.Service // ...共 12 個(gè)穩(wěn)定服務(wù)一次取出 const scope yield* Scope.Scope const list Effect.fn(SessionHttpApi.list)(function* (ctx: { query: typeof ListQuery.Type }) { const directory ctx.query.directory ? yield* InstanceState.directory : undefined return yield* session.list({ directory: ctx.query.scope project ? undefined : directory, scope: ctx.query.scope, // ... }) }) // ... }), )幾個(gè)值得注意的實(shí)現(xiàn)細(xì)節(jié)每個(gè)端點(diǎn)實(shí)現(xiàn)都用Effect.fn(SessionHttpApi.xxx)包一層帶上了帶作用域的函數(shù)名。從源碼結(jié)構(gòu)看這是為了在 Effect 追蹤/日志中區(qū)分各端點(diǎn)的執(zhí)行軌跡端點(diǎn)入?yún)tx的字段params/query/payload由組聲明端的 Schema 決定實(shí)現(xiàn)處直接得到解碼后的類型例如typeof ListQuery.Type錯(cuò)誤轉(zhuǎn)換發(fā)生在 handler 邊界如 session-errors.ts 中把存儲(chǔ)層的 NotFound 領(lǐng)域錯(cuò)誤映射為ApiError聲明的錯(cuò)誤類型而不是讓領(lǐng)域服務(wù)感知 HTTP。三、SSE 流式端點(diǎn)留在group內(nèi)用HttpServerResponse.stream返回規(guī)范明確要求SSE 端點(diǎn)不要改走原始路由仍然留在HttpApiBuilder.group(...)內(nèi)由 handler 返回HttpServerResponse.stream(...)同時(shí)在端點(diǎn)契約上用HttpApiSchema.asText({ contentType: text/event-stream })標(biāo)注成功 Schema讓 OpenAPI 正確記錄流的 Content-Type。opencode 的事件訂閱端點(diǎn)/event是標(biāo)準(zhǔn)實(shí)現(xiàn)。契約聲明見(jiàn) groups/event.tsHttpApiEndpoint.get(subscribe, /event, { query: WorkspaceRoutingQuery, success: Schema.String.pipe(HttpApiSchema.asText({ contentType: text/event-stream })), }) .annotateMerge(OpenApi.annotations({ identifier: event.subscribe, summary: Subscribe to events, description: Get events, }))對(duì)應(yīng) handler 在 handlers/event.ts 中通過(guò)handleRaw(subscribe, ...)實(shí)現(xiàn)核心響應(yīng)構(gòu)造過(guò)程是先注冊(cè)監(jiān)聽(tīng)再開(kāi)始發(fā)射Queue.unbounded接收EventV2Bridge的事件events.listen(...)是急切注冊(cè)保證監(jiān)聽(tīng)注冊(cè)到 HTTP 響應(yīng)體 fiber 啟動(dòng)之間不會(huì)丟事件按實(shí)例過(guò)濾流按event.location.directory instance.directory且 workspace 匹配過(guò)濾再合并一條server.instance.disposed的終止流Stream.takeUntil到 disposed 事件為止心跳?；蠲?10 秒發(fā)一個(gè)server.heartbeat事件首幀為server.connected編碼為 SSE 并掛響應(yīng)頭Stream.pipeThroughChannel(Sse.encode())之后以contentType: text/event-stream返回并附加Cache-Control: no-cache, no-transform、X-Accel-Buffering: no關(guān)閉 nginx 類代理的緩沖、X-Content-Type-Options: nosniff。這正是規(guī)范中“SSE 留在聲明式路由樹(shù)內(nèi)、用asText標(biāo)注流內(nèi)容類型”兩條規(guī)則的完整落地。四、WebSocket 升級(jí)handleRaw保留類型化路由樹(shù)規(guī)范指出聲明式端點(diǎn)如果需要原始請(qǐng)求或響應(yīng)典型即 WebSocket 升級(jí)用HttpApiBuilder.group(...)配handleRaw(...)。這樣端點(diǎn)的中間件、路由上下文和 OpenAPI 元數(shù)據(jù)仍然掛在同一棵類型化路由樹(shù)上。規(guī)范給的范例與倉(cāng)庫(kù)實(shí)現(xiàn)高度一致。groups/pty.ts 中聲明了一個(gè)獨(dú)立的PtyConnectApiconnect端點(diǎn)掛在/pty/:ptyID/connect上并掛了三組中間件InstanceContextMiddleware、WorkspaceRoutingMiddleware和專門的PtyConnectAuthorizationexport const PtyConnectApi HttpApi.make(pty-connect).add( HttpApiGroup.make(pty-connect) .add( HttpApiEndpoint.get(connect, PtyPaths.connect, { params: Params, success: described(Schema.Boolean, Connected session), error: [HttpApiError.Forbidden, HttpApiError.NotFound], }).annotateMerge(OpenApi.annotations({ identifier: pty.connect, summary: Connect to PTY session, description: Establish a WebSocket connection to interact with a pseudo-terminal (PTY) session in real-time., // transform: 手工補(bǔ)齊 directory/workspace/cursor/ticket 查詢參數(shù) // 因?yàn)檫@些參數(shù)是在 raw handler 里解碼的 transform: (operation) ({ ... }), })), ) .middleware(InstanceContextMiddleware) .middleware(WorkspaceRoutingMiddleware) .middleware(PtyConnectAuthorization), )注意一個(gè)工程細(xì)節(jié)因?yàn)?raw handler 里先檢查 PTY 是否存在再解碼查詢參數(shù)為了保持“不存在先返回空 404”的既有響應(yīng)順序這些查詢字段沒(méi)有聲明進(jìn)端點(diǎn) Schema而是通過(guò) OpenAPI 注解的transform回調(diào)手工補(bǔ)進(jìn)文檔。注釋里明確寫了這一取舍是閱讀 raw 端點(diǎn)契約時(shí)的關(guān)鍵線索。實(shí)現(xiàn)側(cè) ptyConnectHandlers 展示了 raw handler 的完整能力面從ctx.request取查詢參數(shù)中的 PTY 連接 ticket經(jīng)tickets.consume(...)校驗(yàn)一次性票據(jù)非法時(shí)返回空 403 響應(yīng)yield* Effect.orDie(ctx.request.upgrade)拿到 WebSocket 句柄進(jìn)入真正的 socket 讀寫出站幀回放幀、實(shí)時(shí)數(shù)據(jù)、關(guān)閉幀統(tǒng)一進(jìn)一個(gè)Queue.unbounded由單個(gè) drain writer 順序?qū)懗霰ＷC重放與實(shí)時(shí)輸出的順序一致用Effect.race并行跑讀attachment.write與寫drain任一側(cè)結(jié)束即整體結(jié)束并ensuring(attachment.detach())確保 PTY 附著一定釋放。五、原始HttpRouter.use只用于 API 面之外的路由規(guī)范的第四條原始HttpRouter.use(...)只允許用于聲明式 API 面之外的路由例如兜底 UI 路由。server.ts 用一段注釋把整棵路由樹(shù)說(shuō)得很清楚// Route tree: // - rootApiRoutes: typed /global/* and control routes; auth is declared by RootHttpApi. // - eventApiRoutes: typed SSE route with instance routing context and its existing API contract. // - ptyConnectApiRoutes: typed WebSocket upgrade route with ticket-aware auth. // - instanceApiRoutes: remaining typed instance routes. // - uiRoute: raw catch-all fallback; auth is router middleware so public static assets can bypass it.其中真正用到原始HttpRouter.use的只有兩個(gè)/doc延遲構(gòu)造 OpenAPI JSON 響應(yīng)見(jiàn)下文與uiRoute*, /*兜底服務(wù)內(nèi)嵌 Web UI。uiRoute特意用 router 級(jí)中間件做鑒權(quán)正是為了讓公開(kāi)靜態(tài)資源可以繞過(guò)認(rèn)證——這是規(guī)范中“raw 路由配 router 中間件”說(shuō)法的直接對(duì)應(yīng)。/doc路由還體現(xiàn)了“穩(wěn)定層一次性提供”的性能意識(shí)源碼注釋原文// OpenApi.fromApi is non-trivial; defer until /doc is actually hit so // processes that never serve it (CLI, scripts) dont pay at module load. const docResponse lazy(() HttpServerResponse.jsonUnsafe(OpenApi.fromApi(PublicApi)))OpenAPI 文檔只在首次命中/doc時(shí)惰性生成且序列化后的響應(yīng)被緩存復(fù)用避免每個(gè)請(qǐng)求重新JSON.stringify。六、依賴注入紀(jì)律層提供一次而不是每請(qǐng)求重建規(guī)范對(duì) Layer 使用有兩條明確的“避免”規(guī)則倉(cāng)庫(kù)代碼是它們的注腳規(guī)則 1避免在請(qǐng)求 handler 或 raw 路由回調(diào)內(nèi)部執(zhí)行Effect.provide(SomeLayer)。穩(wěn)定層應(yīng)在應(yīng)用/層邊界提供一次而不是每請(qǐng)求重建或按請(qǐng)求做作用域化。反面教材式的反例在規(guī)范里被直接點(diǎn)名正面做法可見(jiàn)server.ts的組裝段所有穩(wěn)定服務(wù)Session、Pty、Provider等約 50 個(gè)LayerNode先在app組中聲明再由createRoutes在Layer.provide(...)鏈上一次性提供handler 內(nèi)部只yield*服務(wù)、不提供層。規(guī)則 2避免HttpRouter.provideRequest(...)除非依賴天然是請(qǐng)求級(jí)的。穩(wěn)定的應(yīng)用服務(wù)應(yīng)走HttpRouter.use(...)。規(guī)則 3Effect.provideService(...)在中間件里只用于“由請(qǐng)求推導(dǎo)出的上下文”例如WorkspaceRouteContext派生出的InstanceRef、WorkspaceRef不要拿它把穩(wěn)定服務(wù)偷偷塞進(jìn)請(qǐng)求 effect。倉(cāng)庫(kù)中 middleware/instance-context.ts 就是規(guī)范中“請(qǐng)求派生上下文”的標(biāo)準(zhǔn)寫法function provideInstanceContextE( effect: Effect.EffectHttpServerResponse.HttpServerResponse, E, store: InstanceStore.Interface, ): Effect.EffectHttpServerResponse.HttpServerResponse, E, WorkspaceRouteContext { return Effect.gen(function* () { const route yield* WorkspaceRouteContext const ctx yield* store.load({ directory: decode(route.directory) }) return yield* effect.pipe( Effect.provideService(InstanceRef, ctx), Effect.provideService(WorkspaceRef, route.workspaceID), ) }) }這里provideService提供的是InstanceRef/WorkspaceRef兩個(gè)從路由目錄/workspace 參數(shù)推導(dǎo)出來(lái)的上下文完全符合規(guī)范第 35 行的限定而InstanceStore.Service本身是穩(wěn)定服務(wù)是在instanceContextLayer構(gòu)建時(shí)yield*出來(lái)的沒(méi)有混進(jìn)請(qǐng)求 effect。七、公開(kāi) JSON 錯(cuò)誤顯式的Schema.ErrorClass契約規(guī)范最后一段對(duì)錯(cuò)誤契約的表述是全套規(guī)范中最容易被忽視、也最影響 SDK 兼容性的部分每個(gè)端點(diǎn)的公開(kāi) JSON 錯(cuò)誤都應(yīng)該是顯式聲明在端點(diǎn)上的Schema.ErrorClass契約僅當(dāng)“空/tagged body 就是期望的線上形態(tài)”時(shí)才使用內(nèi)置HttpApiError.*如HttpApiError.BadRequest這類無(wú)字段體對(duì) SDK 可見(jiàn)、需要攜帶message的錯(cuò)誤要定義專用 API 錯(cuò)誤 Schema規(guī)范點(diǎn)名了ApiNotFoundError這類命名并以聲明的那個(gè)精確錯(cuò)誤失敗領(lǐng)域服務(wù)與存儲(chǔ)服務(wù)必須保持不含 HttpApi 類型預(yù)期領(lǐng)域錯(cuò)誤在handler 邊界翻譯為 API 錯(cuò)誤。倉(cāng)庫(kù)的 errors.ts 就是這套契約的集中定義全部用Schema.TaggedErrorClass生成、并綁定httpApiStatusexport class SessionNotFoundError extends Schema.TaggedErrorClassSessionNotFoundError()( SessionNotFoundError, { sessionID: Schema.String, message: Schema.String, }, { httpApiStatus: 404 }, ) {} export class PtyNotFoundError extends Schema.TaggedErrorClassPtyNotFoundError()( PtyNotFoundError, { ptyID: Schema.String, message: Schema.String }, { httpApiStatus: 404 }, ) {} // 另有 InvalidRequestError(400)、UnauthorizedError(401)、ForbiddenError(403)、 // ConflictError(409)、UpstreamError(502)、ServiceUnavailableError(503)、 // TimeoutError(504)、UnknownError(500) 等端點(diǎn)側(cè)的用法可在 groups/pty.ts 看到get端點(diǎn)聲明error: PtyNotFoundErrorupdate端點(diǎn)聲明error: [PtyNotFoundError, HttpApiError.BadRequest]connectToken聲明error: [PtyForbiddenError, PtyNotFoundError]。handler 側(cè)則在 catch 領(lǐng)域錯(cuò)誤時(shí)翻譯成這些聲明類例如 handlers/pty.tsEffect.catchTag( Pty.NotFoundError, (error) new ApiError.PtyNotFoundError({ ptyID: error.ptyID, message: PTY session not found: ${error.ptyID}, }), )Pty.NotFoundError是領(lǐng)域錯(cuò)誤PtyNotFoundError是 API 契約錯(cuò)誤翻譯發(fā)生在 handler 邊界——這正是規(guī)范要求的分層opencode-ai/core下的 Pty 服務(wù)不知道任何 HttpApi 類型的存在。八、中間件聲明與提供的正確位置規(guī)范最后一條新增中間件時(shí)把“端點(diǎn)契約中間件”聲明在歸屬它的HttpApiGroup上實(shí)現(xiàn)層則在server.ts的組裝邊界提供router 級(jí)中間件只留給真正 raw 的兜底路由或全局傳輸策略。倉(cāng)庫(kù)的對(duì)應(yīng)關(guān)系非常清晰聲明端各 group 在自己身上掛中間件。如 groups/event.ts 的HttpApiGroup.make(event).middleware(InstanceContextMiddleware).middleware(WorkspaceRoutingMiddleware).middleware(Authorization)PtyApi/PtyConnectApi同樣在組上聲明見(jiàn) groups/pty.ts提供端server.ts 按“路由子樹(shù)”分塊提供。instanceRoutes統(tǒng)一在實(shí)例級(jí)路由子樹(shù)掛httpApiAuthLayer workspaceRoutingLive instanceContextLayer schemaErrorLayereventApiRoutes與ptyConnectApiRoutes各自在子樹(shù)級(jí)提供對(duì)應(yīng)層。中間件契約在組上聲明一次實(shí)現(xiàn)層在組裝邊界注入一次兩端解耦A(yù)PI 聚合api.ts 展示了契約中間件的另一種聲明位置——根 API 直接在HttpApi.make鏈上掛.middleware(SchemaErrorMiddleware).middleware(Authorization)得到RootHttpApi/global 與控制面路由與InstanceHttpApiconfig、file、instance、mcp、project、pty、question、permission、provider、session、sync、tui、workspace 共 14 個(gè) group最終聚合為OpenCodeHttpApi并追加EventSchema等附加 Schema 供 OpenAPI 引用全局傳輸策略createRoutes返回的層在Layer.mergeAll(六條路由子樹(shù))之上統(tǒng)一Layer.provide了errorLayer、compressionLayer、corsVaryFix、fenceLayer與 CORS 中間件server.tsCORS 甚至以{ global: true }的 router 中間件形式提供maxAge: 86_400——這正對(duì)應(yīng)規(guī)范“router 中間件留給全局傳輸策略”的定位。server.ts末尾還有一處值得注意的組裝順序注釋Observability.layer必須放在 provide 鏈的最后“Must stay last”因?yàn)?Effect 中后 provide 的層構(gòu)建在更底層過(guò)早提供會(huì)讓急切 fork 的 fiber 捕獲默認(rèn) stdout logger 從而污染 TUI引用了 issue #34730。這說(shuō)明規(guī)范中“穩(wěn)定層在應(yīng)用邊界提供”不只是風(fēng)格要求也直接影響可觀測(cè)性正確性。九、小結(jié)新增一個(gè) HttpApi 端點(diǎn)的標(biāo)準(zhǔn)流程綜合規(guī)范與源碼在 opencode 中新增端點(diǎn)可以按以下清單執(zhí)行定契約在groups/對(duì)應(yīng)文件中用HttpApiGroup.make(...).add(HttpApiEndpoint.method(...))聲明端點(diǎn)配OpenApi.annotationsidentifier/summary/descriptionSSE 端點(diǎn)的 success Schema 用HttpApiSchema.asText({ contentType: text/event-stream })標(biāo)注錯(cuò)誤字段填 errors.ts 中已聲明的TaggedErrorClass缺失則新增并綁定httpApiStatus定中間件把端點(diǎn)契約中間件聲明在歸屬 group 上參照InstanceContextMiddleware/WorkspaceRoutingMiddleware/Authorization的三層組合實(shí)現(xiàn)層留到server.ts組裝寫 handler在handlers/對(duì)應(yīng)文件中用HttpApiBuilder.group(InstanceHttpApi, name, ...)包裹開(kāi)頭yield*全部穩(wěn)定服務(wù)端點(diǎn)實(shí)現(xiàn)里只做參數(shù)解碼后的業(yè)務(wù)編排與領(lǐng)域錯(cuò)誤翻譯需要原始請(qǐng)求/響應(yīng)socket 升級(jí)等才用handleRaw掛路由樹(shù)在api.ts把 group 并入InstanceHttpApi或獨(dú)立HttpApi.make參照PtyConnectApi的做法并在server.ts的對(duì)應(yīng)子樹(shù)instanceApiRoutes/ 新子樹(shù)中Layer.providehandler 層與中間件實(shí)現(xiàn)層自檢紀(jì)律handler 內(nèi)不Effect.provide(SomeLayer)中間件內(nèi)provideService只注入請(qǐng)求派生上下文領(lǐng)域服務(wù)保持零 HttpApi 依賴/doc的 OpenAPI 文檔會(huì)自動(dòng)反映新端點(diǎn)。遵循這套模式新端點(diǎn)天然獲得類型化的參數(shù)/響應(yīng)校驗(yàn)、統(tǒng)一的鑒權(quán)與實(shí)例上下文注入、顯式的錯(cuò)誤契約以及無(wú)需額外維護(hù)的 OpenAPI 文檔——這也是該目錄路由代碼在規(guī)模上14 個(gè)實(shí)例級(jí) group 事件流 PTY WebSocket仍能保持可組裝、可測(cè)試的根本原因?！久赓M(fèi)下載鏈接】opencodeThe open source coding agent.項(xiàng)目地址: https://gitcode.com/GitHub_Trending/openc/opencode創(chuàng)作聲明：本文部分內(nèi)容由AI輔助生成（AIGC），僅供參考