范實(shí)戰(zhàn)：CLAUDE.md 指南、ESLint 自動化與源碼級工程約定)
Joplin 編碼規(guī)范實(shí)戰(zhàn)CLAUDE.md 指南、ESLint 自動化與源碼級工程約定【免費(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 倉庫根目錄的CLAUDE.md是一份面向 AI 編碼助手與人類貢獻(xiàn)者的簡明工程守則Joplin Guidelines它把項(xiàng)目最核心的代碼風(fēng)格、測試、樣式與工具鏈約定濃縮為一個“快速參考”。本篇以該文檔為骨架逐條解讀其規(guī)則并結(jié)合倉庫中的eslint配置、pre-commit 鉤子、cspell拼寫檢查與 coding_style.md 等配套文檔說明每條規(guī)則背后的自動化支撐與源碼級落地方式幫助你在提交任何修改前做到與項(xiàng)目慣例完全一致。快速參考Quick Reference總覽CLAUDE.md 的第一部分列出了 18 條高頻規(guī)則覆蓋格式、類型、注釋、測試、工具鏈與文檔六大方面。下面按主題分組逐條展開。格式與 TypeScript 類型制表符縮進(jìn)整個倉庫統(tǒng)一使用 Tab 縮進(jìn)而非空格。字符串使用單引號與多數(shù) JS 項(xiàng)目偏好雙引號不同Joplin 規(guī)定字符串一律使用單引號。使用規(guī)范的 TypeScript 類型避免any這是硬性要求any會繞過類型檢查削弱整個 monorepo 的類型安全。不要標(biāo)注可推斷的類型當(dāng) TypeScript 能從上下文推斷出類型時例如const x foo推斷為string不要顯式寫出返回類型或const類型只有在 TS 會推斷出any時才需要顯式標(biāo)注。這一點(diǎn)與 coding_style.md 中“Dont set the type when it can be inferred”一節(jié)完全對應(yīng)后者指出 ESLint 的no-inferable-types規(guī)則只覆蓋簡單類型函數(shù)調(diào)用等場景仍需自覺避免冗余標(biāo)注。Markdown 文件不要硬換行段落內(nèi)不手動折行交給渲染器自動換行只有在真正的段落或列表分隔處才插入換行符。注釋與代碼復(fù)用注釋只用//不要寫 JSDoc 語法項(xiàng)目不采用/** ... */塊注釋風(fēng)格。默認(rèn)不寫注釋僅在“為什么這樣做”不明顯時才加注釋例如 workaround、隱藏約束、微妙不變量且盡量控制在一兩行永遠(yuǎn)不要解釋代碼“做了什么”——變量名和函數(shù)名已經(jīng)承擔(dān)了這一職責(zé)。復(fù)制大段代碼時必須聲明如果你復(fù)制了一塊可觀的代碼需在復(fù)制處上方加注釋注明這是重復(fù)代碼并給出原始位置的文件/路徑引用以便日后同步維護(hù)。Jest 測試約定每個測試文件只允許一個頂層describe()保持文件結(jié)構(gòu)單一便于瀏覽與定位。聚焦核心行為與邊界情況不要為每個細(xì)枝末節(jié)添加瑣碎測試測試應(yīng)覆蓋關(guān)鍵行為與 edge case。避免測試中的重復(fù)代碼當(dāng)同一邏輯用不同輸入測試時使用test.each或共享 helper而不是復(fù)制相似的測試塊。這與 coding_style.md 的“Test units”一節(jié)互為補(bǔ)充該項(xiàng)目還主張避免 mock 對象與 spy——優(yōu)先測試真實(shí)輸入輸出例如真實(shí)寫臨時文件、真實(shí)建庫寫行只在別無選擇時才使用jest.spyOn/mockImplementation因?yàn)檫^度打樁實(shí)際上是在測“假實(shí)現(xiàn)”。工具鏈與架構(gòu)約束新增 TypeScript 文件后運(yùn)行yarn updateIgnored在倉庫根目錄執(zhí)行這條規(guī)則背后是一個自動生成機(jī)制下文“自動化落地”一節(jié)會展開。遇到 cSpell 未知單詞時按 readme/dev/spellcheck.md 的規(guī)定處理加入詞表或使用cSpell:disable注釋塊詳見后文。編譯 TypeScript 使用yarn tsc只做類型檢查不產(chǎn)出文件時用yarn tsc --noEmitpackage.json 中tsc腳本實(shí)際是yarn workspaces foreach --worktree --parallel --verbose --interlaced run tsc即按 workspace 并行分發(fā)到各個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、移動端React Native三端共用的數(shù)據(jù)層所有數(shù)據(jù)訪問必須收斂到packages/lib/models/下的模型類如BaseItem.ts、Note.ts等禁止在 service、命令或其他任意位置直接拼接 SQL從而保證三端數(shù)據(jù)庫驅(qū)動SQLite / better-sqlite / 移動端存儲下的行為一致。桌面端樣式規(guī)范StylingCLAUDE.md 的“Styling (desktop app)”一節(jié)規(guī)定桌面端只使用 RSCSS SCSS 文件組織樣式禁止內(nèi)聯(lián)style{{...}}和 styled-components例外內(nèi)聯(lián)style只用于“真正的逐實(shí)例動態(tài)值”例如計(jì)算出來的寬度、坐標(biāo)位置主題色一律使用var(--joplin-*)CSS 變量而不是在 JS 中讀取主題對象再傳顏色值。這些規(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生成新建組件時應(yīng)同時新建一個樣式文件如MyComponent/style.scss并在根style.scss中引入全局樣式放根 main.scss每次構(gòu)建會把style.scss編譯為最終的style.css打進(jìn)應(yīng)用。類名組織遵循RSCSS 約定需要記住的要點(diǎn)組件類名至少兩個詞如.search-form組件內(nèi)元素類名只用一個詞如.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; }若某個元素如slider-box既是獨(dú)立組件又是父組件的子元素不要寫.order-form .slider-box而是給它額外命名如quantityslider后選擇.order-form .quantityslider目標(biāo)是“精準(zhǔn)命中標(biāo)定的元素不多不少”。自動化落地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時自動安裝若鉤子缺失在倉庫根目錄重新執(zhí)行yarn install即可恢復(fù)。倉庫中可驗(yàn)證的對應(yīng)物.husky/pre-commit 的內(nèi)容只有一行corepack yarn lint-staged即提交前對暫存文件運(yùn)行 lint-staged根目錄 lint-staged.config.js 定義了對待提交文件執(zhí)行檢查的具體命令package.json 的postinstall腳本為husky gulp build解釋了“yarn install之后鉤子即生效”的原因手動運(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 配置后老代碼往往會大面積報(bào)錯此時二選一——文件不多且改動簡單就直接逐一修復(fù)首選或者運(yùn)行yarn linter-interactive ./交互式為存量違規(guī)行逐條添加eslint-disable-next-line注釋并統(tǒng)一標(biāo)注 “Old code before rule was applied” 以便日后檢索。這樣存量代碼保持不動、新代碼強(qiáng)制遵守規(guī)則。yarn updateIgnored背后的生成機(jī)制CLAUDE.md 要求“新增.ts文件后運(yùn)行yarn updateIgnored”其實(shí)現(xiàn)是 packages/tools/gulp/tasks/updateIgnoredTypeScriptBuild.js以 glob 掃描全倉庫的**/*.ts與**/*.tsx排除node_modules、各包構(gòu)建產(chǎn)物、測試夾具、packages/server、packages/utils等目錄并過濾掉.d.ts為每個.ts文件推導(dǎo)對應(yīng)編譯產(chǎn)物.js的文件名用正則定位.gitignore與.ignore.eslint中由# AUTO-GENERATED - EXCLUDED TYPESCRIPT BUILD標(biāo)記的自動生成分區(qū)把最新列表整塊替換進(jìn)去。原理是TypeScript 編譯會產(chǎn)出.js文件這些本地產(chǎn)物既不能進(jìn)版本庫也不能參與 lint所以每次源碼文件增刪后都要重新生成這兩處忽略清單——yarn updateIgnored對應(yīng)node packages/tools/gulp/tasks/updateIgnoredTypeScriptBuildRun.js就是把這一機(jī)械步驟自動化。拼寫檢查cSpellCLAUDE.md 引用了 readme/dev/spellcheck.md倉庫中的 Markdown 與 TypeScript 文件會被 cspell.json 配置的 CSpell 自動檢查。實(shí)操要點(diǎn)全量檢查yarn spellcheck --all單文件yarn spellcheck /path/to/filepre-commit 鉤子會自動檢查新提交文件中的拼寫忽略詞兩種途徑追加到packages/tools/cspell/下的詞表文件每個詞表不超過約 400 詞超出會導(dǎo)致 CSpell 加載失敗需另建詞表并在cspell.json中注冊或?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ì)則對實(shí)際寫代碼影響最大。文件命名與導(dǎo)入導(dǎo)出多個東西的文件用camelCase.ts僅當(dāng)文件包含單一類且為默認(rèn)導(dǎo)出時才用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以便享受類型檢查老包沒有類型聲明時才退回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且對this的誤用會被 TypeScript 直接報(bào)錯盡量避免默認(rèn)參數(shù)與可選字段所有參數(shù)都必填時重構(gòu)代碼編譯器會自動幫你發(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ù)庫約定表名與列名一律snake_case所有列NOT NULL可帶默認(rèn)值避免查詢中同時處理NULL/0/ 空串默認(rèn)值要克制——多數(shù)情況應(yīng)要求調(diào)用方顯式傳值枚舉值用 integer 列 TypeScript enum表達(dá)不用數(shù)據(jù)庫內(nèi)置 enum遷移困難布爾語義優(yōu)先tinyint(1)而非boolSQLite/MySQL 中布爾本就不是獨(dú)立類型。React 與 GitHub Actions新組件一律函數(shù)組件 Hooks不寫extends Component類組件長邏輯抽成自定義 hook注意 hook 必須以use開頭否則 eslint 會報(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”給出了兩個權(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)建排錯 以及 readme/dev/spec/ 下數(shù)十篇子系統(tǒng)規(guī)格文檔同步、服務(wù)器、編輯器、插件等。適用前提小結(jié)本文所述約定均以當(dāng)前倉庫實(shí)際內(nèi)容為準(zhǔn)Node 引擎要求22.12、Yarn 版本鎖定engines 聲明4.12.0packageManager聲明yarn4.16.0見 package.json。如果你要在 Joplin 倉庫內(nèi)提交代碼最短執(zhí)行路徑是寫完代碼后先跑yarn tsc --noEmit做類型檢查、yarn linter ./修風(fēng)格問題、新增.ts文件后執(zhí)行yarn updateIgnored、遇到拼寫告警按 readme/dev/spellcheck.md 處理詞表——pre-commit 鉤子會在提交時兜底攔截不符合 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），僅供參考 Joplin 編碼規(guī)范實(shí)戰(zhàn)：CLAUDE.md 指南、ESLint 自動化與源碼級工程約定
Joplin 編碼規(guī)范實(shí)戰(zhàn)CLAUDE.md 指南、ESLint 自動化與源碼級工程約定【免費(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 倉庫根目錄的CLAUDE.md是一份面向 AI 編碼助手與人類貢獻(xiàn)者的簡明工程守則Joplin Guidelines它把項(xiàng)目最核心的代碼風(fēng)格、測試、樣式與工具鏈約定濃縮為一個“快速參考”。本篇以該文檔為骨架逐條解讀其規(guī)則并結(jié)合倉庫中的eslint配置、pre-commit 鉤子、cspell拼寫檢查與 coding_style.md 等配套文檔說明每條規(guī)則背后的自動化支撐與源碼級落地方式幫助你在提交任何修改前做到與項(xiàng)目慣例完全一致。快速參考Quick Reference總覽CLAUDE.md 的第一部分列出了 18 條高頻規(guī)則覆蓋格式、類型、注釋、測試、工具鏈與文檔六大方面。下面按主題分組逐條展開。格式與 TypeScript 類型制表符縮進(jìn)整個倉庫統(tǒng)一使用 Tab 縮進(jìn)而非空格。字符串使用單引號與多數(shù) JS 項(xiàng)目偏好雙引號不同Joplin 規(guī)定字符串一律使用單引號。使用規(guī)范的 TypeScript 類型避免any這是硬性要求any會繞過類型檢查削弱整個 monorepo 的類型安全。不要標(biāo)注可推斷的類型當(dāng) TypeScript 能從上下文推斷出類型時例如const x foo推斷為string不要顯式寫出返回類型或const類型只有在 TS 會推斷出any時才需要顯式標(biāo)注。這一點(diǎn)與 coding_style.md 中“Dont set the type when it can be inferred”一節(jié)完全對應(yīng)后者指出 ESLint 的no-inferable-types規(guī)則只覆蓋簡單類型函數(shù)調(diào)用等場景仍需自覺避免冗余標(biāo)注。Markdown 文件不要硬換行段落內(nèi)不手動折行交給渲染器自動換行只有在真正的段落或列表分隔處才插入換行符。注釋與代碼復(fù)用注釋只用//不要寫 JSDoc 語法項(xiàng)目不采用/** ... */塊注釋風(fēng)格。默認(rèn)不寫注釋僅在“為什么這樣做”不明顯時才加注釋例如 workaround、隱藏約束、微妙不變量且盡量控制在一兩行永遠(yuǎn)不要解釋代碼“做了什么”——變量名和函數(shù)名已經(jīng)承擔(dān)了這一職責(zé)。復(fù)制大段代碼時必須聲明如果你復(fù)制了一塊可觀的代碼需在復(fù)制處上方加注釋注明這是重復(fù)代碼并給出原始位置的文件/路徑引用以便日后同步維護(hù)。Jest 測試約定每個測試文件只允許一個頂層describe()保持文件結(jié)構(gòu)單一便于瀏覽與定位。聚焦核心行為與邊界情況不要為每個細(xì)枝末節(jié)添加瑣碎測試測試應(yīng)覆蓋關(guān)鍵行為與 edge case。避免測試中的重復(fù)代碼當(dāng)同一邏輯用不同輸入測試時使用test.each或共享 helper而不是復(fù)制相似的測試塊。這與 coding_style.md 的“Test units”一節(jié)互為補(bǔ)充該項(xiàng)目還主張避免 mock 對象與 spy——優(yōu)先測試真實(shí)輸入輸出例如真實(shí)寫臨時文件、真實(shí)建庫寫行只在別無選擇時才使用jest.spyOn/mockImplementation因?yàn)檫^度打樁實(shí)際上是在測“假實(shí)現(xiàn)”。工具鏈與架構(gòu)約束新增 TypeScript 文件后運(yùn)行yarn updateIgnored在倉庫根目錄執(zhí)行這條規(guī)則背后是一個自動生成機(jī)制下文“自動化落地”一節(jié)會展開。遇到 cSpell 未知單詞時按 readme/dev/spellcheck.md 的規(guī)定處理加入詞表或使用cSpell:disable注釋塊詳見后文。編譯 TypeScript 使用yarn tsc只做類型檢查不產(chǎn)出文件時用yarn tsc --noEmitpackage.json 中tsc腳本實(shí)際是yarn workspaces foreach --worktree --parallel --verbose --interlaced run tsc即按 workspace 并行分發(fā)到各個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、移動端React Native三端共用的數(shù)據(jù)層所有數(shù)據(jù)訪問必須收斂到packages/lib/models/下的模型類如BaseItem.ts、Note.ts等禁止在 service、命令或其他任意位置直接拼接 SQL從而保證三端數(shù)據(jù)庫驅(qū)動SQLite / better-sqlite / 移動端存儲下的行為一致。桌面端樣式規(guī)范StylingCLAUDE.md 的“Styling (desktop app)”一節(jié)規(guī)定桌面端只使用 RSCSS SCSS 文件組織樣式禁止內(nèi)聯(lián)style{{...}}和 styled-components例外內(nèi)聯(lián)style只用于“真正的逐實(shí)例動態(tài)值”例如計(jì)算出來的寬度、坐標(biāo)位置主題色一律使用var(--joplin-*)CSS 變量而不是在 JS 中讀取主題對象再傳顏色值。這些規(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生成新建組件時應(yīng)同時新建一個樣式文件如MyComponent/style.scss并在根style.scss中引入全局樣式放根 main.scss每次構(gòu)建會把style.scss編譯為最終的style.css打進(jìn)應(yīng)用。類名組織遵循RSCSS 約定需要記住的要點(diǎn)組件類名至少兩個詞如.search-form組件內(nèi)元素類名只用一個詞如.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; }若某個元素如slider-box既是獨(dú)立組件又是父組件的子元素不要寫.order-form .slider-box而是給它額外命名如quantityslider后選擇.order-form .quantityslider目標(biāo)是“精準(zhǔn)命中標(biāo)定的元素不多不少”。自動化落地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時自動安裝若鉤子缺失在倉庫根目錄重新執(zhí)行yarn install即可恢復(fù)。倉庫中可驗(yàn)證的對應(yīng)物.husky/pre-commit 的內(nèi)容只有一行corepack yarn lint-staged即提交前對暫存文件運(yùn)行 lint-staged根目錄 lint-staged.config.js 定義了對待提交文件執(zhí)行檢查的具體命令package.json 的postinstall腳本為husky gulp build解釋了“yarn install之后鉤子即生效”的原因手動運(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 配置后老代碼往往會大面積報(bào)錯此時二選一——文件不多且改動簡單就直接逐一修復(fù)首選或者運(yùn)行yarn linter-interactive ./交互式為存量違規(guī)行逐條添加eslint-disable-next-line注釋并統(tǒng)一標(biāo)注 “Old code before rule was applied” 以便日后檢索。這樣存量代碼保持不動、新代碼強(qiáng)制遵守規(guī)則。yarn updateIgnored背后的生成機(jī)制CLAUDE.md 要求“新增.ts文件后運(yùn)行yarn updateIgnored”其實(shí)現(xiàn)是 packages/tools/gulp/tasks/updateIgnoredTypeScriptBuild.js以 glob 掃描全倉庫的**/*.ts與**/*.tsx排除node_modules、各包構(gòu)建產(chǎn)物、測試夾具、packages/server、packages/utils等目錄并過濾掉.d.ts為每個.ts文件推導(dǎo)對應(yīng)編譯產(chǎn)物.js的文件名用正則定位.gitignore與.ignore.eslint中由# AUTO-GENERATED - EXCLUDED TYPESCRIPT BUILD標(biāo)記的自動生成分區(qū)把最新列表整塊替換進(jìn)去。原理是TypeScript 編譯會產(chǎn)出.js文件這些本地產(chǎn)物既不能進(jìn)版本庫也不能參與 lint所以每次源碼文件增刪后都要重新生成這兩處忽略清單——yarn updateIgnored對應(yīng)node packages/tools/gulp/tasks/updateIgnoredTypeScriptBuildRun.js就是把這一機(jī)械步驟自動化。拼寫檢查cSpellCLAUDE.md 引用了 readme/dev/spellcheck.md倉庫中的 Markdown 與 TypeScript 文件會被 cspell.json 配置的 CSpell 自動檢查。實(shí)操要點(diǎn)全量檢查yarn spellcheck --all單文件yarn spellcheck /path/to/filepre-commit 鉤子會自動檢查新提交文件中的拼寫忽略詞兩種途徑追加到packages/tools/cspell/下的詞表文件每個詞表不超過約 400 詞超出會導(dǎo)致 CSpell 加載失敗需另建詞表并在cspell.json中注冊或?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ì)則對實(shí)際寫代碼影響最大。文件命名與導(dǎo)入導(dǎo)出多個東西的文件用camelCase.ts僅當(dāng)文件包含單一類且為默認(rèn)導(dǎo)出時才用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以便享受類型檢查老包沒有類型聲明時才退回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且對this的誤用會被 TypeScript 直接報(bào)錯盡量避免默認(rèn)參數(shù)與可選字段所有參數(shù)都必填時重構(gòu)代碼編譯器會自動幫你發(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ù)庫約定表名與列名一律snake_case所有列NOT NULL可帶默認(rèn)值避免查詢中同時處理NULL/0/ 空串默認(rèn)值要克制——多數(shù)情況應(yīng)要求調(diào)用方顯式傳值枚舉值用 integer 列 TypeScript enum表達(dá)不用數(shù)據(jù)庫內(nèi)置 enum遷移困難布爾語義優(yōu)先tinyint(1)而非boolSQLite/MySQL 中布爾本就不是獨(dú)立類型。React 與 GitHub Actions新組件一律函數(shù)組件 Hooks不寫extends Component類組件長邏輯抽成自定義 hook注意 hook 必須以use開頭否則 eslint 會報(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”給出了兩個權(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)建排錯 以及 readme/dev/spec/ 下數(shù)十篇子系統(tǒng)規(guī)格文檔同步、服務(wù)器、編輯器、插件等。適用前提小結(jié)本文所述約定均以當(dāng)前倉庫實(shí)際內(nèi)容為準(zhǔn)Node 引擎要求22.12、Yarn 版本鎖定engines 聲明4.12.0packageManager聲明yarn4.16.0見 package.json。如果你要在 Joplin 倉庫內(nèi)提交代碼最短執(zhí)行路徑是寫完代碼后先跑yarn tsc --noEmit做類型檢查、yarn linter ./修風(fēng)格問題、新增.ts文件后執(zhí)行yarn updateIgnored、遇到拼寫告警按 readme/dev/spellcheck.md 處理詞表——pre-commit 鉤子會在提交時兜底攔截不符合 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），僅供參考