Outline 架構(gòu)指南React、MobX、Koa 與 Sequelize 構(gòu)建的三層單體倉(cāng)庫(kù)【免費(fèi)下載鏈接】outlineThe fastest knowledge base for growing teams. Beautiful, realtime collaborative, feature packed, and markdown compatible.項(xiàng)目地址: https://gitcode.com/GitHub_Trending/ou/outline本文基于倉(cāng)庫(kù)內(nèi)的 docs/ARCHITECTURE.md 展開(kāi)系統(tǒng)梳理 Outline 知識(shí)庫(kù)系統(tǒng)的前端React Vite MobX、后端Koa Sequelize Redis/Bull與共享層shared三層單體倉(cāng)庫(kù)架構(gòu)。讀完后你將能準(zhǔn)確說(shuō)出各目錄的職責(zé)邊界、請(qǐng)求與事件在服務(wù)器中的流轉(zhuǎn)方式以及前后端如何復(fù)用同一份編輯器與工具代碼?？傮w結(jié)構(gòu)一個(gè) TypeScript 單體倉(cāng)庫(kù)Outline 由后端與前端兩套代碼庫(kù)組成二者均為 TypeScript因此盡可能共享代碼并使用最新的 ES6 語(yǔ)言特性如async/await與類(lèi)型標(biāo)注。格式化工具 oxfmt 與靜態(tài)檢查工具 Oxlint 由 CI 強(qiáng)制約束對(duì)應(yīng) package.json 中的format與lint腳本。倉(cāng)庫(kù)頂層目錄可歸納為五塊目錄職責(zé)app/前端 React 應(yīng)用Vite 編譯server/Koa API 服務(wù)器、隊(duì)列、郵件模板等后端代碼shared/前后端共享的組件、編輯器與工具plugins/插件如 webhooks、oidc、notion 集成在啟動(dòng)時(shí)由后端加載public/靜態(tài)資源圖片、字體、圖標(biāo)前端架構(gòu)app/技術(shù)棧前端是一個(gè)用 Vite 編譯的 React 應(yīng)用狀態(tài)管理使用 MobX組件樣式使用 Styled Components。一個(gè)核心約定是除非是全局邏輯狀態(tài)邏輯與樣式總是與其 React 組件及其子組件同目錄放置co-located以降低組件樹(shù)的維護(hù)成本。這一點(diǎn)在 app/stores/RootStore.ts 所在的 stores 目錄中可以直觀看到——每個(gè) Store 文件自成一個(gè)模塊最終在 app/stores/index.ts 中組裝為單例const stores new RootStore();且僅在開(kāi)發(fā)環(huán)境把stores掛到window上便于調(diào)試。package.json 中可確認(rèn)的前端關(guān)鍵依賴(lài)版本React 18.3、Vite 8、MobX 6、styled-components 5、react-router-dom 5.3配合kbar命令欄、tanstack/react-virtual虛擬列表等 UI 庫(kù)。app/ 目錄結(jié)構(gòu)原文檔給出的目錄樹(shù)如下與當(dāng)前倉(cāng)庫(kù)實(shí)際結(jié)構(gòu)一致app ├── actions - Reusable actions such as navigating, opening, creating entities ├── components - React components reusable across scenes ├── editor - React components specific to the editor ├── hooks - Reusable React hooks ├── menus - Context menus, often appear in multiple places in the UI ├── models - State models using MobX observables ├── routes - Route definitions, note that chunks are async loaded with suspense ├── scenes - A scene represents a full-page view that contains several components ├── stores - Collections of models and associated fetch logic ├── types - TypeScript types └── utils - Utility methods specific to the frontend補(bǔ)充兩點(diǎn)源碼層面的細(xì)節(jié)路由是異步加載的。app/routes/index.tsx 中每個(gè)場(chǎng)景Login、Shared、Authenticated 等都通過(guò)lazy(() import(...))動(dòng)態(tài)導(dǎo)入并包裹在Suspense fallback{FullscreenLoading /}中。這正是目錄注釋里 “chunks are async loaded with suspense” 的實(shí)現(xiàn)——首屏只加載必要 chunk其余頁(yè)面按需拉取加載組件統(tǒng)一由 app/utils/lazyWithRetry.ts 提供帶重試的動(dòng)態(tài)導(dǎo)入。類(lèi)型目錄的實(shí)際命名。從源碼結(jié)構(gòu)看當(dāng)前倉(cāng)庫(kù)中該目錄實(shí)際為 app/typings/內(nèi)含全局類(lèi)型聲明如index.d.ts、prosemirror-view.d.ts等承擔(dān)文檔中 “types” 一項(xiàng)的職責(zé)。models/與stores/的分工值得注意models 是使用 MobX observable 的純狀態(tài)模型如Document.ts、Collection.ts、User.tsstores 則是模型集合 數(shù)據(jù)獲取邏輯如DocumentsStore.ts負(fù)責(zé)調(diào)用 API 并填充 Document 模型。這種分離讓模型可以在前端被獨(dú)立測(cè)試如 app/models/Collection.test.ts。后端架構(gòu)server/技術(shù)棧API 服務(wù)器由 Koa 驅(qū)動(dòng)ORM 使用 SequelizePostgreSQL隊(duì)列與異步事件管理使用 Redis 上的 Bull。package.json 中對(duì)應(yīng)依賴(lài)為koa3.x、sequelize6.x、bull4.x、ioredis。server/ 目錄結(jié)構(gòu)原文檔的目錄樹(shù)如下與當(dāng)前倉(cāng)庫(kù)一一對(duì)應(yīng)server ├── routes - All API routes are contained within here │ ├── api - API routes │ └── auth - Authentication routes ├── commands - Complex commands that perform actions across multiple models ├── config - Database configuration ├── emails - Transactional email templates │ └── templates - Classes that define each possible email template ├── middlewares - Shared Koa middlewares ├── migrations - Database migrations ├── models - Sequelize models ├── onboarding - Markdown templates for onboarding documents ├── policies - Authorization logic based on cancan ├── presenters - JSON presenters for database models, the interface between backend - frontend ├── queues - Async queue definitions │ └── processors - Processors perform jobs on events from the event bus │ └── tasks - Tasks are arbitrary async jobs not from the event bus ├── services - Services start distinct portions of the application eg api, worker ├── static - Static assets ├── test - Test helpers and fixtures, tests themselves are colocated └── utils - Utility methods specific to the backendservices一個(gè)進(jìn)程按需啟動(dòng)應(yīng)用的不同部分services/是理解后端拆分的關(guān)鍵。server/services/index.ts 以懶加載方式注冊(cè)了 6 個(gè)服務(wù)const services { websockets: () import(./websockets), collaboration: () import(./collaboration), admin: () import(./admin), web: () import(./web), worker: () import(./worker), cron: () import(./cron), } as const;注釋明確說(shuō)明懶加載的動(dòng)機(jī)worker-only 進(jìn)程不需要加載 web、collaboration 等服務(wù)的重依賴(lài)樹(shù)。啟動(dòng)邏輯在 server/main.ts遍歷env.SERVICES中聲明的服務(wù)名逐個(gè)import并初始化未知服務(wù)名會(huì)直接拋錯(cuò)。運(yùn)行入口的編排方式由 Procfile 與 npm scripts 體現(xiàn)web: yarn start --servicesweb,websockets,collaboration worker: yarn start --servicesworker即web 進(jìn)程承載 HTTP API、WebSocket 與協(xié)同編輯服務(wù)worker 進(jìn)程只跑隊(duì)列任務(wù)。本地開(kāi)發(fā)時(shí)yarn dev啟動(dòng)的則是全量組合--servicescron,collaboration,websockets,admin,web,worker見(jiàn) package.json 的dev腳本。server/main.ts 中還能看到每個(gè)服務(wù)進(jìn)程共用的基礎(chǔ)件koa-helmet安全頭、統(tǒng)一的onerror錯(cuò)誤處理、默認(rèn)全局限流defaultRateLimiter、以及每個(gè)服務(wù)都注冊(cè)的健康檢查端點(diǎn)/_health會(huì)同時(shí)探測(cè) PostgreSQL 的SELECT 1與 Redis 的PING任一失敗返回 500。協(xié)同編輯服務(wù)本身位于 server/collaboration/以一組 Extension認(rèn)證、連接數(shù)限制、持久化等的形式掛載依賴(lài)hocuspocus/server與 Yjs。routesAPI、認(rèn)證與前端 Shellserver/routes/index.ts 匯總了路由裝配托管public/下的圖片/字體等靜態(tài)資源7 天緩存生產(chǎn)環(huán)境托管app/構(gòu)建產(chǎn)物hash 文件 1 年 immutable 緩存并對(duì)/share/:shareId做 301 重定向。從源碼結(jié)構(gòu)看路由目錄實(shí)際包含api/API 路由、auth/認(rèn)證路由、oauth/OAuth 授權(quán)、mcp/MCP 服務(wù)路由以及 server/routes/app.ts、server/routes/embeds.ts 等前端 Shell 渲染入口。commands 與 presenters跨模型操作與前后端接口commands/執(zhí)行“跨越多個(gè)模型”的復(fù)雜業(yè)務(wù)動(dòng)作例如 server/commands/documentCreator.ts、server/commands/documentMover.ts。路由層保持薄重邏輯下沉到 command且每個(gè) command 都有同名 colocated 測(cè)試如documentMover.test.ts。presenters/數(shù)據(jù)庫(kù)模型到 JSON 的序列化層是后端與前端之間的“接口契約”45 個(gè) presenter 文件覆蓋各主要模型。policies基于 cancan 的授權(quán)邏輯原文檔提到授權(quán)邏輯位于 cancan policies。當(dāng)前倉(cāng)庫(kù)中 server/policies/cancan.ts 內(nèi)建了該能力框架源碼注釋寫(xiě)明它 “originally adapted from cancan npm package”即從 cancan 包移植內(nèi)置通過(guò)define/can風(fēng)格的 ability 聲明實(shí)現(xiàn)按 模型 動(dòng)作 目標(biāo) 的鑒權(quán)判定。server/policies/ 下共有 38 個(gè)策略文件覆蓋document、collection、team、comment、share等核心資源并配有document.test.ts、collection.test.ts等策略單測(cè)。queues事件驅(qū)動(dòng)的 processors 與任意任務(wù) tasksserver/queues/ 的目錄劃分是原文檔描述的重點(diǎn)實(shí)際文件印證了兩類(lèi)執(zhí)行體的區(qū)別processors/處理“事件總線”發(fā)來(lái)的事件。從源碼結(jié)構(gòu)看文件名與模型事件一一對(duì)應(yīng)如 DocumentArchivedProcessor.ts、SearchIndexProcessor.ts、EmailsProcessor.ts、WebsocketsProcessor.ts——一個(gè)模型發(fā)生歸檔/更新/刪除對(duì)應(yīng) processor 負(fù)責(zé)廣播通知、重建搜索索引、發(fā)郵件等副作用。tasks/不來(lái)自事件總線的任意異步作業(yè)如ExportHTMLZipTask、EmptyTrashTask、DocumentImportTask以及大量Cleanup*Task定期清理過(guò)期附件、舊通知、已刪除團(tuán)隊(duì)等。隊(duì)列基座位于 server/queues/queue.tsBull 之上的封裝另有HealthMonitor.ts做隊(duì)列健康探測(cè)。其余目錄速覽models/Sequelize 模型107 個(gè)文件基于sequelize-typescriptmigrations/304 個(gè)遷移腳本配合db:migrate/db:rollback等腳本package.jsonemails/emails/templates/事務(wù)郵件模板模板以組件類(lèi)形式定義35 個(gè)模板文件由 server/emails/mailer.tsx 渲染middlewares/共享 Koa 中間件認(rèn)證、CSP、apex 域名跳轉(zhuǎn)、apiContext 等onboarding/新用戶團(tuán)隊(duì)初始化文檔的 Markdown 模板test/測(cè)試輔助與 fixtures測(cè)試本身與源碼 colocated。測(cè)試通過(guò) vitest 按 project 劃分test:app、test:shared、test:server見(jiàn) package.json 與 vitest.config.ts。共享層shared/“客戶端與服務(wù)器之間共享的邏輯放在這里通常是很小的工具?！痹臋n給出的結(jié)構(gòu)如下與倉(cāng)庫(kù)一致shared ├── components - Shared React components that are used in both the frontend and backend ├── editor - The text editor, based on Prosemirror ├── i18n - Internationalization configuration │ └── locales - Language specific translation files ├── styles - Styles, colors and other global aesthetics └── utils - Shared utility methods逐項(xiàng)深入editor基于 Prosemirror 的富文本編輯器核心shared/editor/ 是整個(gè)產(chǎn)品最核心的共享代碼內(nèi)部按編輯器關(guān)注點(diǎn)組織為commands/、marks/、nodes/、extensions/、embeds/、plugins/、queries/、rules/、selection/、styles/、types/等子目錄約 239 個(gè)文件。package.json 中的大量prosemirror-*依賴(lài)、y-prosemirror與yjs表明編輯器以 Prosemirror 為底座通過(guò) y-prosemirror 橋接 Yjs 實(shí)現(xiàn)協(xié)同編輯。后端并非簡(jiǎn)單復(fù)用——server/editor/ 提供了服務(wù)端側(cè)的編輯器裝配ComponentView.tsx、nodeViews.tsx等用于在服務(wù)端把編輯器內(nèi)容渲染成 HTML例如導(dǎo)出、郵件場(chǎng)景這是 “components used in both the frontend and backend” 的典型落點(diǎn)。i18n國(guó)際化配置與語(yǔ)言文件shared/i18n/ 包含 28 個(gè) locale 翻譯文件與語(yǔ)言元數(shù)據(jù)languages.ts被 server/routes/index.ts 直接 import 用于路由。翻譯詞條由 i18next-parser 從源碼中自動(dòng)抽取i18next-parser.config.js 定義了掃描規(guī)則build:i18n腳本會(huì)掃描{shared,app,server,plugins}全部源碼并把 locale 文件拷貝進(jìn)構(gòu)建產(chǎn)物docs/TRANSLATION.md 進(jìn)一步說(shuō)明了翻譯流程。構(gòu)建與工程化約束前端構(gòu)建yarn vite:buildVite 8vite.config.ts配合vite-plugin-pwa后端構(gòu)建build.js輸出到build/server/生產(chǎn)啟動(dòng)命令為node ./build/server/index.jsstart腳本代碼質(zhì)量oxlint --type-aware app server shared plugins做類(lèi)型感知 lintoxfmt統(tǒng)一格式化均由 CI 強(qiáng)制依賴(lài)補(bǔ)丁patches/ 目錄存放patch-package補(bǔ)丁y-prosemirror、prosemirror-mathpostinstall階段自動(dòng)應(yīng)用。小結(jié)一次請(qǐng)求在架構(gòu)中的路徑以“打開(kāi)一篇文檔”為例串聯(lián)三層前端scenes/中的文檔頁(yè)經(jīng) Suspense 加載app/routes通過(guò)stores/發(fā)起 API 請(qǐng)求請(qǐng)求落到 Koaweb服務(wù)的server/routes/api/由policies/cancan判定權(quán)限commands/執(zhí)行跨模型操作presenters/序列化返回副作用通知、搜索索引、WebSocket 廣播經(jīng)queues/processors/異步處理編輯器內(nèi)容的實(shí)時(shí)協(xié)同則由shared/editor經(jīng) yjs 通過(guò)collaboration服務(wù)完成。理解這套“services 按進(jìn)程切分、commands 承載業(yè)務(wù)、queues 消化副作用、presenters 約束接口”的分層方式即可在該倉(cāng)庫(kù)中快速定位任意功能的前后端實(shí)現(xiàn)。【免費(fèi)下載鏈接】outlineThe fastest knowledge base for growing teams. Beautiful, realtime collaborative, feature packed, and markdown compatible.項(xiàng)目地址: https://gitcode.com/GitHub_Trending/ou/outline創(chuàng)作聲明：本文部分內(nèi)容由AI輔助生成（AIGC），僅供參考