Puter 后端架構(gòu)深度解析Controller–Service–Store 分層、依賴注入與可插拔擴(kuò)展機(jī)制【免費(fèi)下載鏈接】puter The Internet Computer! Free, Open-Source, and Self-Hostable.項(xiàng)目地址: https://gitcode.com/GitHub_Trending/pu/puter本文圍繞 doc/architecture.md 展開結(jié)合 Puter 開源倉庫的 后端啟動器、分層注冊表、擴(kuò)展 API、請求上下文 與 路由選項(xiàng)類型 等源碼完整拆解其分層架構(gòu)、啟動裝配流程、基于 AsyncLocalStorage 的請求上下文以及擴(kuò)展機(jī)制讓讀者既能按圖索驥地定位某類代碼應(yīng)該放哪一層也能理解一個(gè) HTTP 請求從進(jìn)入網(wǎng)關(guān)到落庫的完整鏈路并掌握編寫一個(gè)合規(guī)擴(kuò)展Extension所需的全部 API 細(xì)節(jié)。Puter 是一個(gè)自托管的開源互聯(lián)網(wǎng)計(jì)算機(jī)The Internet Computer它的后端被組織成一個(gè)每一層只依賴其下層的洋蔥狀分層棧并由PuterServer在啟動時(shí)按固定順序?qū)嵗?、通過構(gòu)造函數(shù)逐層注入依賴。這種設(shè)計(jì)與經(jīng)典 Controller–Service–Repository 模式形似而神似同時(shí)引入了一套與核心棧平行生長的擴(kuò)展體系讓非關(guān)鍵能力縮略圖、服務(wù)器信息、開發(fā)者熱重載等可以像插件一樣干凈地掛在任意一層之上。一、總體設(shè)計(jì)分層與依賴注入的基本原則文檔開宗明義整個(gè)后端松散地受 Controller–Service–Repository 模式啟發(fā)配合依賴注入DI。核心組織方式是把后端疊成一摞層stack of layers并立下兩條鐵律每一層只依賴它下面的層絕不反向引用、也絕不橫向跨層調(diào)用所有依賴都通過構(gòu)造函數(shù)注入由唯一的引導(dǎo)者PuterServer按順序?qū)嵗鲗硬严聦訉?shí)例遞給上層。這兩條規(guī)則共同保證了依賴關(guān)系是顯式、可追溯的——從 PuterServer 源碼 出發(fā)可以沿著構(gòu)造鏈完整畫出任意組件的依賴圖。1.1 七層棧全景下圖為文檔中給出的官方分層示意block-beta1.2 各層職責(zé)速查表層代碼位置職責(zé)Controllerssrc/backend/controllers/路由處理器。負(fù)責(zé)解析 校驗(yàn)輸入、施加每條路由的 gate鑒權(quán)、子域、限流、body 解析等見RouteOptions、調(diào)用 service、格式化響應(yīng)。Driverssrc/backend/drivers/可選層。暴露在/drivers/*表面的 RPC 風(fēng)格處理器puter-kvstore、puter-chat-completion等。Driver 是一層薄殼校驗(yàn) RPC 輸入后調(diào)用 services/stores當(dāng) Controller 需要在 HTTP 上復(fù)用同一邏輯時(shí)可以持有對 driver 的類型化引用。Servicessrc/backend/services/業(yè)務(wù)邏輯層。默認(rèn)調(diào)用方已完成鑒權(quán)/授權(quán)——Service 自身不再跑鑒權(quán) gate。Storessrc/backend/stores/持久化與存儲邏輯。把 Client 包裝成 Service 消費(fèi)的領(lǐng)域形態(tài)行、實(shí)體、KV 命名空間。Clientssrc/backend/clients/外部/內(nèi)部服務(wù)的適配器sql、redis、s3、dynamodb、email、事件總線……。只懂協(xié)議不懂領(lǐng)域概念。Configconfig.*.json→IConfig啟動時(shí)每個(gè)層都收到的扁平化、帶類型的配置對象倉庫內(nèi)可參考 config.template.jsonc。1.3 代碼組織上的強(qiáng)制約束每層通過構(gòu)造函數(shù)接收它下面的層因此從PuterServer出發(fā)依賴是顯式且可追蹤的Controller 不得直接伸手去夠 Client如果某個(gè) Controller 確實(shí)需要 Client 的能力正確的做法通常是經(jīng)由 ServiceService 之間不得為了代碼復(fù)用而互相調(diào)用——需要復(fù)用就向上抽取成 util/helper詳見后文約定一節(jié)。二、入口點(diǎn)PuterServer的啟動裝配流程src/backend/server.ts 中的PuterServer是整個(gè)后端的 bootstrap。其#setupServer流程清晰對應(yīng)文檔中的四步描述2.1 加載擴(kuò)展目錄在實(shí)例化之前// 從 config.extensions 讀取目錄逐個(gè) import 目錄下的入口文件 const extensionDirs this.#config.extensions; await this.#importExtensions(extensionDirs);config.extensions是字符串?dāng)?shù)組例如 config.template.jsonc 中默認(rèn)配置// ── Extensions ────────────────────────────────────────────────────── // Directories scanned for extension entrypoints (*.ts / subdirs). extensions: [ ./extensions ],#importExtensionsserver.ts的掃描規(guī)則值得注意目錄下單個(gè).ts/.js文件直接動態(tài)import()但會跳過*.test.*與*.d.ts子目錄優(yōu)先讀其package.json的main字段否則回退到index.js/index.mjs/index.cjs兩者都沒有的數(shù)據(jù)型 sidecar 目錄會被靜默跳過不會導(dǎo)致啟動崩潰之所以必須先于實(shí)例化加載是因?yàn)閿U(kuò)展通過模塊級副作用把注冊內(nèi)容寫入內(nèi)存注冊表隨后PuterServer裝配各層時(shí)要把這些注冊內(nèi)容合并進(jìn)對應(yīng)層見下一節(jié)。倉庫內(nèi) extensions/package.json 只有一行{type: commonjs}說明擴(kuò)展模塊本身保持 CommonJS 形態(tài)運(yùn)行時(shí)依賴編譯產(chǎn)物。2.2 按序?qū)嵗鲗硬⒑喜U(kuò)展注冊代碼中實(shí)際執(zhí)行順序?yàn)閏lients → stores → services → rate-limiter 裝配 → drivers → controllers。每類實(shí)例的構(gòu)造參數(shù)都只給下層的引用被實(shí)例化對象構(gòu)造函數(shù)注入的依賴Client(config)Store(config, clients, stores)Service(config, clients, stores, services)Driver(config, clients, stores, services)Controller(config, clients, stores, services, drivers)源碼中對每個(gè)層都寫了兩遍循環(huán)第一遍遍歷內(nèi)置注冊表如 puterControllers第二遍遍歷extensionStore.xxx——這正是合并進(jìn)擴(kuò)展已注冊的東西的實(shí)現(xiàn)方式。此外值得留意的一個(gè)關(guān)鍵次序細(xì)節(jié)Drivers 先于 Controllers 實(shí)例化因此 Controller 構(gòu)造時(shí)就能拿到類型化的drivers引用而/drivers/*這個(gè) HTTP 表面本身由普通 Controller 中的 DriverController 承擔(dān)它從this.drivers讀取目標(biāo)——也就是文檔中不再有單獨(dú)的 driver 注冊表對象的含義。內(nèi)置 driver 注冊表見 src/backend/drivers/index.ts包含kvStoreKV 存儲、aiChat/aiImage/aiTts/aiVideo/aiSpeech2Speech/aiSpeech2Txt/aiOcr各 AI 能力、apps、subdomains、notifications、workers等。類似的services/index.ts 通過declare module聲明合并生成IPuterServiceInstances內(nèi)含auth、token、fs、metering、events、permission等stores/index.ts 同樣生成IPuterStoreInstances內(nèi)含kv、user、fsEntry、session等。2.3 裝配 Express 全局中間件實(shí)例化完成后#setupServer創(chuàng)建 Express app 并設(shè)定兩個(gè)會影響所有子域路由的關(guān)鍵 app 級選項(xiàng)server.tstrust proxy必須在任何讀取req.ip/req.ips/req.protocol的中間件之前設(shè)置。默認(rèn)false部署在反向代理鏈后面時(shí)須設(shè)為跳數(shù)如單層 Cloudflare/nginx 設(shè)1生產(chǎn)環(huán)境絕不能設(shè)true那會信任每一跳使 XFF 可被偽造subdomain offset由subdomainOffsetForDomain(config.domain)算出讓部署在puter.example.com時(shí)不會把puter誤讀為活躍子域。隨后#installGlobalMiddleware以對次序極其講究的方式掛載全局中間件其中文檔沒有展開、但源碼注釋里交代清楚的細(xì)節(jié)包括出口計(jì)量中間件最先注冊它在compression之前包裹res.write因此統(tǒng)計(jì)的是真實(shí)發(fā)出的字節(jié)而非 handler 產(chǎn)生的字節(jié)express.json必須在 auth probe 之前這樣req.body.auth_token才是可讀的authProbe永不 reject它只在存在合法 token 時(shí)填充req.actorHost 校驗(yàn)#installHostValidation維護(hù)一張由domain、static_hosting_domain、private_app_hosting_domain等拼接、帶緩存的允許域名表/healthcheck與自定義域名custom_domains_enabled例外放行CORS 中間件允許任意 Originputer.js設(shè)計(jì)上要被任意第三方站點(diǎn)消費(fèi)并僅在api子域反射 Origin 時(shí)允許攜帶憑據(jù)、為dav子域單獨(dú)暴露 WebDAV 需要的響應(yīng)頭集合認(rèn)證探測之后依次是指紋中間件打上req.networkFingerprint/req.deviceFingerprint與每請求 ALS 上下文中間件此時(shí)req.actor已被填充可安全快照進(jìn)上下文見第三節(jié)用戶自托管站點(diǎn)*.puter.site等由createPuterSiteMiddleware在路由匹配前短路處理擴(kuò)展注冊的全局中間件extensionStore.globalMiddlewares最后追加。2.4 路由裝配與終止中間件Controllers 與擴(kuò)展路由都收斂到同一個(gè)#materializeRoute細(xì)節(jié)見下節(jié)RouteOptions全部裝配完畢后最后才安裝 404 catch-all 與錯(cuò)誤處理中間件——保證 404 只對真正未匹配的請求觸發(fā)、錯(cuò)誤處理器能接住棧中任意位置拋出的錯(cuò)誤Express 5 會自動把同步/異步 throw 轉(zhuǎn)發(fā)到錯(cuò)誤處理器因此 handler 里可以直接throw new HttpError(...)無需next(err)儀式。2.5 生命周期鉤子文檔提到PuterServer會觸發(fā)onServerStart/onServerPrepareShutdown/onServerShutdown。源碼server.ts顯示這些鉤子按clients → stores → services → controllers → drivers的順序在每一層上逐一遍歷觸發(fā)#runPrepareShutdownHooks有冪等保護(hù)只跑一次attachHttpServer則在 listen 之前被調(diào)用供 socket.io 等需要裸http.Server的服務(wù)掛接。start()還支持noHttpServer模式測試用與--server的 AuthMe 瀏覽器登錄流程。三、請求上下文基于 AsyncLocalStorage 的Context為了不在每個(gè)函數(shù)簽名里都穿針引線地傳遞每請求狀態(tài)后端在 src/backend/core/context.ts 中提供了由 NodeAsyncLocalStorage支撐的Context。3.1 設(shè)計(jì)要點(diǎn)承載能力既有帶類型的已知字段KnownContextFields又有開放式的 key-value map。已知字段包括actor——auth probe 解析出的已認(rèn)證主體可能為undefinedreq——當(dāng)前 Express 請求對象requestId——每請求唯一 ID可用于結(jié)構(gòu)化日志/追蹤driverName——由 DriverController 在/drivers/call分發(fā)時(shí)寫入drivers 據(jù)此挑選 providerabortSignal——客戶端提前斷開時(shí)中止長任務(wù)長運(yùn)行 driver 輪詢它避免為沒人接收的工作繼續(xù)計(jì)量。傳播機(jī)制因?yàn)榛贏syncLocalStorage上下文能自動穿過async/await、定時(shí)器與微任務(wù)。runWithContext(initial, fn)用于開啟一個(gè)上下文作用域request-context 中間件在 auth probe 之后用它包裹整條中間件/處理器鏈。用法源碼注釋中的示例// 讀取類型化字段 const actor Context.get(actor); // 在任意位置讀取 express 請求 const req Context.get(req); // 存取臨時(shí)值 Context.set(myService.txId, txId); const txId Context.get(myService.txId);約束Context.set在請求作用域之外調(diào)用會直接拋錯(cuò)Context之外的調(diào)用無 scope取值返回undefined。3.2 使用紀(jì)律寧可顯式傳參文檔給出的工程紀(jì)律非常明確優(yōu)先顯式參數(shù)只有當(dāng)值確實(shí)是請求級、且不通過 Context 就得穿透很多層函數(shù)簽名時(shí)才使用Context。它被設(shè)計(jì)為有節(jié)制地使用mostly foractorandreq而不是一條隨手可用的隱形全局通道——濫用會悄悄破壞函數(shù)的純度與可測試性。一個(gè)真實(shí)的消費(fèi)端示例是 extensions/whoami.ts 的handleWhoamihandler 里直接Context.get(actor)取出當(dāng)前主體并據(jù)此判斷是否返回 401——這正是文檔任何請求 handler 內(nèi)可用Context.get(actor)/Context.get(req)替代層層傳參的落地形態(tài)。四、擴(kuò)展Extensions與核心棧平行的插件體系擴(kuò)展代碼放在倉庫根的 extensions/文檔中的packages/puter/extensions/即該目錄中與分層棧平行。它們服務(wù)于系統(tǒng)中**非關(guān)鍵non-crucial**的部分——移除后 Puter 仍然能工作的功能。這是判斷該不該做成擴(kuò)展的第一把尺子。4.1 文檔給出的分類示范適合做擴(kuò)展thumbnails、serverInfo、devWatcher——干凈的外掛式可選功能其實(shí)更該進(jìn)核心metering、appTelemetry——客戶端已默認(rèn)它們存在擴(kuò)展的框架反而誤導(dǎo)人本不該做成擴(kuò)展whoami——它對每一個(gè)已認(rèn)證客戶端都是承重墻。文檔特意把它列為警世案例當(dāng)你猶豫某個(gè)東西是否屬于擴(kuò)展時(shí)想想 whoami。以 serverInfo 為例它就是一個(gè)典型的薄殼擴(kuò)展讀取os/fs系統(tǒng)信息后用extension.get注冊一個(gè)僅管理員可訪問的端點(diǎn)extension.get( /serverInfo, { subdomain: api, adminOnly: true }, handleServerInfo, );而 thumbnails 則展示了另一種形態(tài)——不注冊路由而是通過extension.on訂閱文件系統(tǒng)事件thumbnail.created、thumbnail.upload.prepare、thumbnail.read、fs.copy.node、fs.remove.node把縮略圖落盤為帶thumbnails/前綴的 S3 對象并簽發(fā)預(yù)簽名 URL全程不碰核心棧的任何一行。4.2 擴(kuò)展 API 全貌extension全局對象定義在 src/backend/extensions.ts其底層是一個(gè)內(nèi)存注冊表extensionStoreextensions.ts擴(kuò)展模塊在模塊作用域執(zhí)行時(shí)把注冊寫入其中PuterServer啟動時(shí)再排干它。API 分三類1. 一等公民式的層注冊Layer registrationextension.registerClient(name, ClientClass)extension.registerStore(name, StoreClass)extension.registerService(name, ServiceClass)extension.registerDriver(name, DriverClass)extension.registerController(name, ControllerClass)另有extension.registerGlobalMiddleware(mw)追加全局中間件2. 輕量包裝Lightweight wrappers——當(dāng)為一個(gè)常用場景單獨(dú)寫一個(gè)完整類不值得時(shí)extension.on(event, handler)——訂閱事件總線事件extension.get(path, opts?, handler)/.post/.put/.delete/.patch/.head/.options/.all/.use——注冊路由。opts就是 Controller 用的同一套RouteOptions所以subdomain、requireAuth、adminOnly、body 解析器等在擴(kuò)展路由上完全等價(jià)地生效兩種調(diào)用形態(tài)extension.get(/path, handler)與extension.get(/path, options, handler)實(shí)現(xiàn)見 extensions.ts。3. 跨層訪問Cross-layer accessextension.import(client | store | service | controller | driver)——返回對已實(shí)例化對象的惰性代理lazy proxyextension.config——暴露實(shí)時(shí)配置。import代理有兩處實(shí)現(xiàn)細(xì)節(jié)值得展開extensions.ts惰性解析擴(kuò)展模塊在層實(shí)例化之前就被 import模塊頂層讀到名字通常是空的因此代理在每次屬性訪問時(shí)都重新查容器模塊 import 時(shí)捕獲的extension.import(client).db在真正實(shí)例落地后依然可用方法綁定bindLayerMethods用 Proxy 讓取出即被 bind 到實(shí)例這樣const w svc.fs.write; w(...)這種剝離式調(diào)用不會因this丟失而在訪問私有字段時(shí)炸掉代價(jià)是每次方法訪問都返回新函數(shù)引用同一性不穩(wěn)定——對取一次、調(diào)用多次的 import 場景可接受代理對從未注冊的名字在首次屬性讀取時(shí)拋錯(cuò)而非返回undefined因此拼寫錯(cuò)誤會在訪問點(diǎn)立刻暴露而不是靜默變成 no-op想探測可選層條目需要 try/catch。文檔給出的示例代碼正是把上面三類 API 串起來的完整最小擴(kuò)展import { extension } from heyputer/backend/src/extensions; const services extension.import(service); extension.get(/healthcheck/deep, { subdomain: api, adminOnly: true }, async (_req, res) { res.json({ ok: await services.health.runDeepCheck() }); }); extension.on(user.signup, (_key, data) { console.log(new user, data.user.username); });真實(shí)倉庫里可以對照 whoami 的完整路由聲明來驗(yàn)證它同時(shí)使用了subdomain: api、requireAuth: true、allowUnconfirmed: true以及一個(gè)key: user、scope: whoami、limit: 1_800、window: 60_000的限流配置——GUI 輪詢該端點(diǎn)、且每次調(diào)用會扇出到所有whoami事件監(jiān)聽器因此限流上限必須清掉最忙會話在做什么而不是按人點(diǎn)擊的節(jié)奏來定。extension.config的用法也出現(xiàn)在其中讀取feature_flags后按白名單CLIENT_VISIBLE_FEATURE_FLAGS過濾避免內(nèi)部標(biāo)記payment_bypass、staff_only_*等經(jīng)/whoami泄漏到客戶端。五、RouteOptions一條路由可聲明的全部護(hù)欄文檔把per-route gates歸入 Controllers 的職責(zé)而承載這些聲明的類型就是 src/backend/core/http/types.ts 中的RouteOptions。理解它就能理解Controller 層做輸入校驗(yàn)與 I/O 塑形究竟意味著什么。RouteMethod除了標(biāo)準(zhǔn)的 REST 動詞還包含lock、unlock、propfind、proppatch、mkcol、copy、move等 WebDAV 動詞對應(yīng) WebDAVController 的需求RoutePath接受字符串/正則/數(shù)組。RouteOptions的可聲明項(xiàng)含義見類型源碼中的長注釋概覽如下類別選項(xiàng)說明子域subdomain字符串或數(shù)組省略時(shí) verb 路由只匹配根域*顯式匹配任意子域use中間件默認(rèn)不加此閘門認(rèn)證requireAuth拒絕匿名與被封禁用戶僅放行 user 與 app 主體requireUserActor拒絕 app/access-token 主體蘊(yùn)含requireAuthnoUserSession拒絕裸會話 token要求委托憑據(jù)app/worker/API tokenworker 會話恒通過allowFullAccessToken配合requireUserActor放行用戶本人的全權(quán) PAT默認(rèn)拒絕adminOnly用戶名白名單默認(rèn)admin/system可加數(shù)組擴(kuò)展要求根 token且需 step-up 二次認(rèn)證可疊加allowedAppIdsallowedAppIdsapp-under-user 白名單蘊(yùn)含requireAuth驗(yàn)證allowUnconfirmed放行尚未完成注冊期驗(yàn)證郵箱/短信/卡片的賬號供登出、whoami、確認(rèn)類核心流使用requireVerified要求郵箱已驗(yàn)證是否生效取決于config.strict_email_verification_requiredrequirePhoneVerified/requireCardVerified各自要求確實(shí)完成過對應(yīng)因子驗(yàn)證captcha/antiCsrf驗(yàn)證碼閘門 / 一次性 anti-CSRF token 消費(fèi)guiOriginOnly僅限本部署 GUI origin 的瀏覽器頁面用于發(fā)放會話憑據(jù)的路由配額與防護(hù)rateLimit單/數(shù)組key可為fingerprint默認(rèn)/ip/user/自定義函數(shù)scope隔離計(jì)數(shù)器backend選memory/redis/kvconcurrent并發(fā)在飛限制可bySubscription按訂閱檔覆蓋額度requireCredits余額不足 402insufficient_funds只用于替你花錢的路由requireSubscription計(jì)劃門檻true任一非免費(fèi)計(jì)劃數(shù)組指定SubscriptionPolicy.idrequireReputation信譽(yù)分檔位門檻檔位閾值在配置的reputationGate.tiers中定義請求體bodyJsonfalse或{limit, type}覆蓋全局 JSON 解析器bodyRaw/bodyText/bodyUrlencoded分別拿到 Buffer / string / 表單對象通用middleware額外的每路由中間件在門控與解析之后、handler 之前執(zhí)行在類型層面RouteOptions還通過AuthRequiredO與TypedRequestO做了類型收窄當(dāng)路由聲明了requireAuth或任何蘊(yùn)含它的選項(xiàng)時(shí)handler 中的req.actor會被窄化為Actor非空無需再寫非空斷言。門控鏈的落地#materializeRoute每條路由無論來自 Controller 還是擴(kuò)展最終都流入 server.ts 的#materializeRoute。它把RouteOptions翻譯成一條有序的中間件鏈源碼注釋給出的順序是subdomain → origin gate → auth gates → requireUserActor → noUserSession → adminOnly(step-up) → allowedAppIds → requireVerified → reputation → subscription → rateLimit → requireCredits → concurrent → captcha → antiCsrf → body parsers → 調(diào)用方 middleware → 生命周期事件 → handler幾個(gè)由代碼佐證的語義細(xì)節(jié)蘊(yùn)含去重adminOnly、allowedAppIds、requireUserActor等都蘊(yùn)含requireAuth實(shí)現(xiàn)中只 push 一次requireAuthGate()默認(rèn)開啟的待驗(yàn)證閘門任何需要認(rèn)證且未聲明allowUnconfirmed的路由都會被追加requireVerifiedAccount()這是讓低信譽(yù)注冊賬號在服務(wù)端就被擋在 AI/FS/driver 端點(diǎn)之外、而不只靠 GUI 彈窗的機(jī)制默認(rèn)拒絕 access token需要認(rèn)證且未聲明allowAccessToken的路由會追加requireNonAccessTokenGate()adminOnly疊加 step-up管理路由還要求最近的重認(rèn)證createStepUpGate除非 token 攜帶路由白名單中的 app idWebDAV 特例OPTIONS預(yù)檢對dav子域放行DAV 客戶端要靠它發(fā)現(xiàn)服務(wù)器能力其余子域直接回 200路由級生命周期每個(gè)端點(diǎn)use除外最后會注入createRouteLifecycleMiddleware使before/after鉤子在完整認(rèn)證的請求上觸發(fā)。Controller 端的聲明式注冊走的是同一套物料化管道PuterRouter 配合裝飾器元數(shù)據(jù)Controller(/prefix)等把前綴/路由存在 prototype 的PREFIX_METADATA_KEY/ROUTES_METADATA_KEY上#registerControllerRoutes在裝配時(shí)讀出并批量registerRoutes(router)同時(shí)支持 Controller 用isEnabled()在 config 層面關(guān)閉整組路由——關(guān)閉后其路徑表現(xiàn)為 404 而非存在但拒絕。六、架構(gòu)約定Conventions文檔在最后給出了四條團(tuán)隊(duì)編碼約定它們也是審閱任何 Puter 后端改動時(shí)的檢查清單新代碼優(yōu)先 TypeScript在可行處存量 JS 可保留動到該文件時(shí)順帶機(jī)會式遷移命名變量/函數(shù)用camelCase類、以及內(nèi)含類的文件AuthService.ts、KVStoreDriver.ts用PascalCase去重優(yōu)先兩個(gè) Service 需要同一段邏輯時(shí)把它提升到 util/helper而不是在同一層內(nèi)橫向互調(diào)——Service 不應(yīng)為復(fù)用代碼而依賴其他 Service絕不跨層伸手Controller 不直接捅 ClientService 不注冊路由。一旦發(fā)現(xiàn)自己想這么做通常意味著抽象本身出了問題。七、快速定位指南想找某個(gè) HTTP 端點(diǎn)由誰處理→ 從 controllers/index.ts 的puterControllers表出發(fā)再按需看對應(yīng) Controller 的registerRoutes想確認(rèn)某個(gè) driver 暴露了什么 RPC→ drivers/index.ts 是完整注冊表RPC 分發(fā)在 DriverController想理解路由可聲明哪些閘門/解析器→ core/http/types.ts 的RouteOptions注釋最權(quán)威想看擴(kuò)展能注冊什么、如何跨層取實(shí)例→ src/backend/extensions.ts 的extension對象與其文檔注釋想確認(rèn)啟動順序與生命周期鉤子→ server.ts 的#setupServer、#fireOnServerStart、prepareShutdown/shutdown想寫第一個(gè)擴(kuò)展 → 以 serverInfo極簡路由型或 thumbnails事件訂閱型為模板并用 extensions/whoami.ts 對照承重型路由應(yīng)如何精細(xì)聲明RouteOptions。結(jié)語Puter 的后端不是一套玄虛的框架而是一組樸素卻強(qiáng)約束的工程決策層間只向下依賴 構(gòu)造注入 單一引導(dǎo)者按序裝配讓依賴圖完全可讀ALS 上下文只解決真正請求級狀態(tài)的穿透問題擴(kuò)展體系則把錦上添花與承重墻清楚地分成兩堆用同一套RouteOptions物料化管道保證擴(kuò)展路由與核心路由享受完全一致的鑒權(quán)/限流/解析能力。理解這四件事你就能在 Puter 倉庫中準(zhǔn)確定位任意功能的落點(diǎn)也能判斷一個(gè)新需求應(yīng)該寫進(jìn)哪一層、或是否應(yīng)該以擴(kuò)展形態(tài)獨(dú)立存在?！久赓M(fèi)下載鏈接】puter The Internet Computer! Free, Open-Source, and Self-Hostable.項(xiàng)目地址: https://gitcode.com/GitHub_Trending/pu/puter創(chuàng)作聲明：本文部分內(nèi)容由AI輔助生成（AIGC），僅供參考