Joplin 編碼規(guī)范實(shí)戰(zhàn)CLAUDE.md 指南、ESLint 自動(dòng)化與源碼級(jí)工程約定【免費(fèi)下載鏈接】joplinJoplin - the privacy-focused note taking app with sync capabilities for Windows, macOS, Linux, Android and iOS.項(xiàng)目地址: https://gitcode.com/GitHub_Trending/jo/joplinJoplin 倉(cāng)庫(kù)根目錄的CLAUDE.md是一份面向 AI 編碼助手與人類貢獻(xiàn)者的簡(jiǎn)明工程守則Joplin Guidelines它把項(xiàng)目最核心的代碼風(fēng)格、測(cè)試、樣式與工具鏈約定濃縮為一個(gè)“快速參考”。本篇以該文檔為骨架逐條解讀其規(guī)則并結(jié)合倉(cāng)庫(kù)中的eslint配置、pre-commit 鉤子、cspell拼寫檢查與 coding_style.md 等配套文檔說明每條規(guī)則背后的自動(dòng)化支撐與源碼級(jí)落地方式幫助你在提交任何修改前做到與項(xiàng)目慣例完全一致。快速參考Quick Reference總覽CLAUDE.md 的第一部分列出了 18 條高頻規(guī)則覆蓋格式、類型、注釋、測(cè)試、工具鏈與文檔六大方面。下面按主題分組逐條展開。格式與 TypeScript 類型制表符縮進(jìn)整個(gè)倉(cāng)庫(kù)統(tǒng)一使用 Tab 縮進(jìn)而非空格。字符串使用單引號(hào)與多數(shù) JS 項(xiàng)目偏好雙引號(hào)不同Joplin 規(guī)定字符串一律使用單引號(hào)。使用規(guī)范的 TypeScript 類型避免any這是硬性要求any會(huì)繞過類型檢查削弱整個(gè) monorepo 的類型安全。不要標(biāo)注可推斷的類型當(dāng) TypeScript 能從上下文推斷出類型時(shí)例如const x foo推斷為string不要顯式寫出返回類型或const類型只有在 TS 會(huì)推斷出any時(shí)才需要顯式標(biāo)注。這一點(diǎn)與 coding_style.md 中“Dont set the type when it can be inferred”一節(jié)完全對(duì)應(yīng)后者指出 ESLint 的no-inferable-types規(guī)則只覆蓋簡(jiǎn)單類型函數(shù)調(diào)用等場(chǎng)景仍需自覺避免冗余標(biāo)注。Markdown 文件不要硬換行段落內(nèi)不手動(dòng)折行交給渲染器自動(dòng)換行只有在真正的段落或列表分隔處才插入換行符。注釋與代碼復(fù)用注釋只用//不要寫 JSDoc 語(yǔ)法項(xiàng)目不采用/** ... */塊注釋風(fēng)格。默認(rèn)不寫注釋僅在“為什么這樣做”不明顯時(shí)才加注釋例如 workaround、隱藏約束、微妙不變量且盡量控制在一兩行永遠(yuǎn)不要解釋代碼“做了什么”——變量名和函數(shù)名已經(jīng)承擔(dān)了這一職責(zé)。復(fù)制大段代碼時(shí)必須聲明如果你復(fù)制了一塊可觀的代碼需在復(fù)制處上方加注釋注明這是重復(fù)代碼并給出原始位置的文件/路徑引用以便日后同步維護(hù)。Jest 測(cè)試約定每個(gè)測(cè)試文件只允許一個(gè)頂層describe()保持文件結(jié)構(gòu)單一便于瀏覽與定位。聚焦核心行為與邊界情況不要為每個(gè)細(xì)枝末節(jié)添加瑣碎測(cè)試測(cè)試應(yīng)覆蓋關(guān)鍵行為與 edge case。避免測(cè)試中的重復(fù)代碼當(dāng)同一邏輯用不同輸入測(cè)試時(shí)使用test.each或共享 helper而不是復(fù)制相似的測(cè)試塊。這與 coding_style.md 的“Test units”一節(jié)互為補(bǔ)充該項(xiàng)目還主張避免 mock 對(duì)象與 spy——優(yōu)先測(cè)試真實(shí)輸入輸出例如真實(shí)寫臨時(shí)文件、真實(shí)建庫(kù)寫行只在別無選擇時(shí)才使用jest.spyOn/mockImplementation因?yàn)檫^度打樁實(shí)際上是在測(cè)“假實(shí)現(xiàn)”。工具鏈與架構(gòu)約束新增 TypeScript 文件后運(yùn)行yarn updateIgnored在倉(cāng)庫(kù)根目錄執(zhí)行這條規(guī)則背后是一個(gè)自動(dòng)生成機(jī)制下文“自動(dòng)化落地”一節(jié)會(huì)展開。遇到 cSpell 未知單詞時(shí)按 readme/dev/spellcheck.md 的規(guī)定處理加入詞表或使用cSpell:disable注釋塊詳見后文。編譯 TypeScript 使用yarn tsc只做類型檢查不產(chǎn)出文件時(shí)用yarn tsc --noEmitpackage.json 中tsc腳本實(shí)際是yarn workspaces foreach --worktree --parallel --verbose --interlaced run tsc即按 workspace 并行分發(fā)到各個(gè)packages/*子包中執(zhí)行各自的tsc這與項(xiàng)目的 monorepo 結(jié)構(gòu)workspaces: [packages/*]一致。SQL 查詢只允許出現(xiàn)在 models 中packages/lib/models目錄這是 Joplin 的核心架構(gòu)約束——packages/lib是可被 CLI、桌面端Electron、移動(dòng)端React Native三端共用的數(shù)據(jù)層所有數(shù)據(jù)訪問必須收斂到packages/lib/models/下的模型類如BaseItem.ts、Note.ts等禁止在 service、命令或其他任意位置直接拼接 SQL從而保證三端數(shù)據(jù)庫(kù)驅(qū)動(dòng)SQLite / better-sqlite / 移動(dòng)端存儲(chǔ)下的行為一致。桌面端樣式規(guī)范StylingCLAUDE.md 的“Styling (desktop app)”一節(jié)規(guī)定桌面端只使用 RSCSS SCSS 文件組織樣式禁止內(nèi)聯(lián)style{{...}}和 styled-components例外內(nèi)聯(lián)style只用于“真正的逐實(shí)例動(dòng)態(tài)值”例如計(jì)算出來的寬度、坐標(biāo)位置主題色一律使用var(--joplin-*)CSS 變量而不是在 JS 中讀取主題對(duì)象再傳顏色值。這些規(guī)則的完整依據(jù)在 readme/dev/spec/desktop_styling.md。該文檔交代了桌面端樣式方案的三次演進(jìn)直接內(nèi)聯(lián) style缺乏靈活性、無法被自定義樣式表覆蓋→ styled-components需要為每種樣式建組件、且存在若干樣式失效的 bug→當(dāng)前的 SCSS 普通 CSS 類。工程上應(yīng)用樣式表由構(gòu)建packages/app-desktop/style.scss生成新建組件時(shí)應(yīng)同時(shí)新建一個(gè)樣式文件如MyComponent/style.scss并在根style.scss中引入全局樣式放根 main.scss每次構(gòu)建會(huì)把style.scss編譯為最終的style.css打進(jìn)應(yīng)用。類名組織遵循RSCSS 約定需要記住的要點(diǎn)組件類名至少兩個(gè)詞如.search-form組件內(nèi)元素類名只用一個(gè)詞如.field、textinput始終使用子代選擇器防止樣式在嵌套組件間“滲透”。例如form classorder-form input classfirstname typetext/ div classslider-box Select quantity: div classknob/div /div /form.order-form firstname, .order-form lastname { padding: 10px; }若某個(gè)元素如slider-box既是獨(dú)立組件又是父組件的子元素不要寫.order-form .slider-box而是給它額外命名如quantityslider后選擇.order-form .quantityslider目標(biāo)是“精準(zhǔn)命中標(biāo)定的元素不多不少”。自動(dòng)化落地pre-commit 鉤子、lint-staged 與 cSpellCLAUDE.md 末尾指向 readme/dev/coding_style.md其開篇說明了這些規(guī)范的執(zhí)行機(jī)制編碼風(fēng)格主要由運(yùn)行eslint的 pre-commit 鉤子強(qiáng)制該鉤子在任一應(yīng)用目錄執(zhí)行yarn install時(shí)自動(dòng)安裝若鉤子缺失在倉(cāng)庫(kù)根目錄重新執(zhí)行yarn install即可恢復(fù)。倉(cāng)庫(kù)中可驗(yàn)證的對(duì)應(yīng)物.husky/pre-commit 的內(nèi)容只有一行corepack yarn lint-staged即提交前對(duì)暫存文件運(yùn)行 lint-staged根目錄 lint-staged.config.js 定義了對(duì)待提交文件執(zhí)行檢查的具體命令package.json 的postinstall腳本為husky gulp build解釋了“yarn install之后鉤子即生效”的原因手動(dòng)運(yùn)行 lint 的方式為yarn linter ./即eslint --fix --quietCI 使用yarn linter-cieslint --quiet不帶--fix保證失敗即報(bào)紅。coding_style.md 還給出了新增 ESLint 規(guī)則的標(biāo)準(zhǔn)流程把規(guī)則加進(jìn) ESLint 配置后老代碼往往會(huì)大面積報(bào)錯(cuò)此時(shí)二選一——文件不多且改動(dòng)簡(jiǎn)單就直接逐一修復(fù)首選或者運(yùn)行yarn linter-interactive ./交互式為存量違規(guī)行逐條添加eslint-disable-next-line注釋并統(tǒng)一標(biāo)注 “Old code before rule was applied” 以便日后檢索。這樣存量代碼保持不動(dòng)、新代碼強(qiáng)制遵守規(guī)則。yarn updateIgnored背后的生成機(jī)制CLAUDE.md 要求“新增.ts文件后運(yùn)行yarn updateIgnored”其實(shí)現(xiàn)是 packages/tools/gulp/tasks/updateIgnoredTypeScriptBuild.js以 glob 掃描全倉(cāng)庫(kù)的**/*.ts與**/*.tsx排除node_modules、各包構(gòu)建產(chǎn)物、測(cè)試夾具、packages/server、packages/utils等目錄并過濾掉.d.ts為每個(gè).ts文件推導(dǎo)對(duì)應(yīng)編譯產(chǎn)物.js的文件名用正則定位.gitignore與.ignore.eslint中由# AUTO-GENERATED - EXCLUDED TYPESCRIPT BUILD標(biāo)記的自動(dòng)生成分區(qū)把最新列表整塊替換進(jìn)去。原理是TypeScript 編譯會(huì)產(chǎn)出.js文件這些本地產(chǎn)物既不能進(jìn)版本庫(kù)也不能參與 lint所以每次源碼文件增刪后都要重新生成這兩處忽略清單——yarn updateIgnored對(duì)應(yīng)node packages/tools/gulp/tasks/updateIgnoredTypeScriptBuildRun.js就是把這一機(jī)械步驟自動(dòng)化。拼寫檢查cSpellCLAUDE.md 引用了 readme/dev/spellcheck.md倉(cāng)庫(kù)中的 Markdown 與 TypeScript 文件會(huì)被 cspell.json 配置的 CSpell 自動(dòng)檢查。實(shí)操要點(diǎn)全量檢查yarn spellcheck --all單文件yarn spellcheck /path/to/filepre-commit 鉤子會(huì)自動(dòng)檢查新提交文件中的拼寫忽略詞兩種途徑追加到packages/tools/cspell/下的詞表文件每個(gè)詞表不超過約 400 詞超出會(huì)導(dǎo)致 CSpell 加載失敗需另建詞表并在cspell.json中注冊(cè)或?qū)罅坎豢珊雎栽~的代碼塊使用// cSpell:disable/// cSpell:enableMarkdown 中為!-- cSpell:disable --更推薦優(yōu)先用詞表以免污染代碼也可在cspell.json中用ignore屬性按路徑或正則整體跳過例如忽略 changelog 中的 GitHub 用戶名。深入配套文檔coding_style.md 的關(guān)鍵細(xì)則CLAUDE.md 的快速參考是“摘要層”readme/dev/coding_style.md 是“細(xì)則層”兩者必須結(jié)合閱讀。以下幾組細(xì)則對(duì)實(shí)際寫代碼影響最大。文件命名與導(dǎo)入導(dǎo)出多個(gè)東西的文件用camelCase.ts僅當(dāng)文件包含單一類且為默認(rèn)導(dǎo)出時(shí)才用PascalCase.ts共享類型定義放types.ts或fooTypes.ts導(dǎo)出成員與導(dǎo)入成員保持相同的命名大小寫文件、函數(shù)、導(dǎo)入名一致只導(dǎo)入需要的成員利于 tree shakingimport { writeFile } from fs-extra優(yōu)于import * as fsTypeScript 文件中優(yōu)先import而非require以便享受類型檢查老包沒有類型聲明時(shí)才退回require()避免內(nèi)聯(lián)類型類型應(yīng)單獨(dú)定義以便復(fù)用type Config Recordstring, Knex.Config; const config: Config { /* ... */ };變量與函數(shù)新代碼中的常量用camelCase不用全大寫SNAKE_CASE變量聲明盡量貼近其首次使用處避免“聲明在最頂部卻隔了很遠(yuǎn)才用”優(yōu)先const而非let優(yōu)先箭頭函數(shù)() {}而非function() {}——不用this便于日后把類組件重構(gòu)為 React Hooks且對(duì)this的誤用會(huì)被 TypeScript 直接報(bào)錯(cuò)盡量避免默認(rèn)參數(shù)與可選字段所有參數(shù)都必填時(shí)重構(gòu)代碼編譯器會(huì)自動(dòng)幫你發(fā)現(xiàn)漏傳。安全轉(zhuǎn)義用戶內(nèi)容Escape variables這是細(xì)則文檔中篇幅最大的安全章節(jié)核心原則永遠(yuǎn)不要假設(shè)輸入安全即使你認(rèn)為自己控制了輸入且盡可能晚地轉(zhuǎn)義——應(yīng)用內(nèi)部保持原始數(shù)據(jù)只在邊界處解碼/編碼避免雙重轉(zhuǎn)義。按插入位置選擇手段插入位置手段JS 腳本字符串JSON.stringify(data)HTML 字符串htmlentities來自 packages/utils/html.ts如htmlentities(content)URL 查詢參數(shù)encodeURIComponent完整 URL 用encodeURIMarkdownpackages/lib/markdownUtils.ts 提供escapeTableCell()、escapeInlineCode()、escapeTitleText()、escapeLinkUrl()文檔還提出了“Make wrong code look wrong”命名法給已轉(zhuǎn)義變量加后綴如userContentHtml讓“把未轉(zhuǎn)義變量插進(jìn) HTML”這件事在代碼審閱中一眼可見、一眼可疑。數(shù)據(jù)庫(kù)約定表名與列名一律snake_case所有列NOT NULL可帶默認(rèn)值避免查詢中同時(shí)處理NULL/0/ 空串默認(rèn)值要克制——多數(shù)情況應(yīng)要求調(diào)用方顯式傳值枚舉值用 integer 列 TypeScript enum表達(dá)不用數(shù)據(jù)庫(kù)內(nèi)置 enum遷移困難布爾語(yǔ)義優(yōu)先tinyint(1)而非boolSQLite/MySQL 中布爾本就不是獨(dú)立類型。React 與 GitHub Actions新組件一律函數(shù)組件 Hooks不寫extends Component類組件長(zhǎng)邏輯抽成自定義 hook注意 hook 必須以u(píng)se開頭否則 eslint 會(huì)報(bào) “called outside of a component”GitHub Actions 的run塊內(nèi)不要內(nèi)嵌${{ }}存在腳本注入風(fēng)險(xiǎn)應(yīng)通過env傳入后再引用環(huán)境變量。文檔引用與延伸閱讀CLAUDE.md 末尾的“Full Documentation”給出了兩個(gè)權(quán)威入口編碼風(fēng)格全文readme/dev/coding_style.md本文已大量引用貢獻(xiàn)指南CONTRIBUTING 文件其內(nèi)容指向 readme/dev/index.md 這一開發(fā)者指南總?cè)肟谠撃夸浵逻€有構(gòu)建BUILD.md、部署DEPLOY.md、技術(shù)規(guī)格technical_spec.md、本地化、構(gòu)建排錯(cuò) 以及 readme/dev/spec/ 下數(shù)十篇子系統(tǒng)規(guī)格文檔同步、服務(wù)器、編輯器、插件等。適用前提小結(jié)本文所述約定均以當(dāng)前倉(cāng)庫(kù)實(shí)際內(nèi)容為準(zhǔn)Node 引擎要求22.12、Yarn 版本鎖定engines 聲明4.12.0packageManager聲明yarn4.16.0見 package.json。如果你要在 Joplin 倉(cāng)庫(kù)內(nèi)提交代碼最短執(zhí)行路徑是寫完代碼后先跑yarn tsc --noEmit做類型檢查、yarn linter ./修風(fēng)格問題、新增.ts文件后執(zhí)行yarn updateIgnored、遇到拼寫告警按 readme/dev/spellcheck.md 處理詞表——pre-commit 鉤子會(huì)在提交時(shí)兜底攔截不符合 CLAUDE.md 約定與 ESLint 規(guī)則的代碼?！久赓M(fèi)下載鏈接】joplinJoplin - the privacy-focused note taking app with sync capabilities for Windows, macOS, Linux, Android and iOS.項(xiàng)目地址: https://gitcode.com/GitHub_Trending/jo/joplin創(chuàng)作聲明：本文部分內(nèi)容由AI輔助生成（AIGC），僅供參考