范實踐：kebab-case 文件命名、按構(gòu)建目標劃分的別名體系與 Zod 共享 Schema)
Motrix TypeScript 代碼規(guī)范實踐kebab-case 文件命名、按構(gòu)建目標劃分的別名體系與 Zod 共享 Schema【免費下載鏈接】MotrixA full-featured download manager.項目地址: https://gitcode.com/GitHub_Trending/mo/Motrix本文基于 Motrix 倉庫中的 代碼風格規(guī)則 展開系統(tǒng)講解該下載管理器的文件命名約定、TypeScript 導入與路徑別名規(guī)則以及跨層數(shù)據(jù)的 Zod 共享 Schema 契約。讀完之后你可以在 Motrix 代碼庫中正確創(chuàng)建/重命名文件、安全使用各構(gòu)建目標Electron 主進程、渲染進程、服務(wù)器、QuickJS 插件 Worker、Vitest 測試暴露的路徑別名并知道哪些運行時契約必須收斂為單一 Zod schema從而避免常見的跨層類型漂移與別名跨目標誤用。Biome 是格式與通用 Lint 的唯一歸屬規(guī)則文檔開篇就明確了一條分工原則Biome 負責格式化和通用 lint 規(guī)則倉庫級規(guī)則文檔不重復這些設(shè)置只補充 Biome 覆蓋不到的倉庫特定邊界。這條分工在倉庫根目錄的 biome.json 中可以得到完整印證其中與代碼風格直接相關(guān)的配置包括文件命名強制 kebab-caselinter.rules.style.useFilenamingConvention被設(shè)為error級別filenameCases僅允許kebab-casebiome.json。也就是說命名錯誤不只是風格問題而是會讓pnpm run lint即biome check .直接失敗的硬錯誤。格式化基線2 空格縮進、80 字符行寬、LF 換行formatter段biome.json。引號與分號單引號、asNeeded分號、JSX 雙引號、ES5 尾逗號javascript.formatter段biome.json。測試文件寬松區(qū)**/*.test.{ts,tsx}、**/*.spec.{ts,tsx}、**/test/**、**/__tests__/**等路徑下的代碼關(guān)閉了noNonNullAssertion與noExplicitAnyoverrides段biome.json與后文文件命名中.test、.spec等約定后綴形成配套。導入自動整理assist.actions.source.organizeImports開啟Biome 會按源碼順序自動組織 import 語句。理解這一分工的實際意義在于當你覺得引號風格分號import 排序這類問題時答案永遠在 biome.json 里跑pnpm run lint:fix即可而.claude/rules/code-style.md承載的是 Biome 管不了的倉庫邊界——命名后綴語義、別名可用性和 Schema 歸屬。文件命名規(guī)范命名規(guī)則總覽規(guī)則文檔.claude/rules/code-style.md對命名給出的約定可歸納為四條對象約定說明JavaScript、TypeScript、TSX 與樣式文件kebab-case如task-manager.ts、use-add-task-form.ts約定性限定后綴保持小寫.test、.spec、.e2e、.integration、.darwin、.win32導出的類與 React 組件PascalCase文件名仍是 kebab-case僅導出符號用 PascalCaseRust 與 Pythonsnake_caseCargo 二進制入口可用 kebab-case 以匹配可執(zhí)行文件名這里有一個容易混淆的點文件命名與符號命名是兩套體系。倉庫中大量文件形如src/core/task/task-manager.ts、src/core/engine/engine-supervisor.ts文件名全部是 kebab-case但文件內(nèi)部導出的類、組件保持 PascalCase——規(guī)則文檔專門用一條約定鎖死了這一點避免文件名是連字符、導出名也跟著變成 kebab的漂移。后綴語義也有明確劃分.test/.spec對應單元測試Vitest 的include模式為src/**/*.test.{ts,tsx}見 vitest.config.ts.e2e/.integration對應端到端與集成測試如tests/e2e/nat-main.e2e.test.ts.darwin/.win32對應平臺專屬實現(xiàn)如src/core/probe/disk-probe-darwin.ts、src/core/probe/disk-probe-win32.ts全部保持小寫以與主文件干并列識別。pnpm run check:file-names的實際校驗邏輯規(guī)則要求新增或重命名文件后運行pnpm run check:file-names。該腳本在 package.json 中注冊為node scripts/check-file-names.mjs其實現(xiàn)scripts/check-file-names.mjs值得細看它把規(guī)則文檔中的每一條命名約定翻譯成了可執(zhí)行的檢查kebab-case 擴展名集合scripts/check-file-names.mjs.cjs、.css、.cts、.js、.jsx、.mjs、.mts、.scss、.ts、.tsx共 10 種均要求文件干匹配^[a-z0-9](?:-[a-z0-9])*$snake_case 擴展名集合scripts/check-file-names.mjs.py、.rs匹配^[a-z0-9](?:_[a-z0-9])*$Cargo 二進制例外位于src/bin/下的.rs文件放寬為snake_case 或 kebab-case正則^[a-z0-9](?:[-_][a-z0-9])*$scripts/check-file-names.mjs。這正是規(guī)則文檔中Cargo binary entrypoints may use kebab-case to match the executable name一條的執(zhí)行依據(jù)——例如packages/native-host這類 Rust 子包的main.rs與src/bin/下的入口文件名可以帶連字符以便產(chǎn)物可執(zhí)行名可讀排除前綴docs/與graphify-out/不參與檢查scripts/check-file-names.mjs掃描范圍通過git ls-files --cached --others --exclude-standard枚舉所有 Git 可見文件含未跟蹤的新文件意味著新建文件也會被掃到而不是只對已提交代碼生效失敗行為任何違例都會逐條打印Invalid code file names并令進程以非零碼退出因此可以安全接入 CI 或 pre-commit 流程。換言之規(guī)則文檔中的命名約定在倉庫里有三重執(zhí)行保障Biome 的useFilenamingConvention編輯器與 lint 階段、check:file-names腳本全倉庫文件干級別含 Biome 不覆蓋的 Rust/Python 與 Cargo 例外、以及約定性后綴與 Biome overrides 的測試目錄匹配*.test.*/*.spec.*的 lint 寬松規(guī)則依賴這些后綴。導入與路徑別名import type與node:前綴兩條導入層面的硬性約定類型專用導入必須使用import type。這與 tsconfig.json 中開啟的verbatimModuleSyntax: true是配套的——該編譯選項要求模塊語句所見即所得不寫type修飾的類型導入會在構(gòu)建時保留下來導致運行時因目標模塊沒有該值導出而失敗。Node 內(nèi)建模塊必須使用node:前綴如import path from node:path。倉庫源碼與腳本中普遍如此例如 scripts/check-file-names.mjs 開頭的node:child_process、node:path。別名優(yōu)先但相對導入有豁免規(guī)則約定優(yōu)先使用已配置的別名而非深層相對導入例如../../shared/...這類跨越目錄層的引用但同目錄sibling或上一級parent的本地導入可以保持相對路徑。這是一個務(wù)實的取舍別名解決跨層/跨目錄的可讀性與穩(wěn)定性而相鄰文件之間./xxx既短又清晰強制走別名反而降低信息量。別名可用性按構(gòu)建目標劃分這是規(guī)則文檔中最容易踩坑的部分。Motrix 是 Electron 服務(wù)器 插件 Worker 的多目標工程tsconfig.json聲明了全部五個別名但每個構(gòu)建目標只暴露其中一個子集這一點在各 Vite 配置的resolve.alias中得到逐字印證目標配置文件實際暴露的別名Electron 主進程vite.main.config.tsshared、core、main渲染進程vite.renderer.config.tsshared、rendererpreload 橋vite.preload.config.ts僅shared服務(wù)器無 Electron 依賴vite.server.config.tsshared、core、serverQuickJS 插件 Workervite.worker.config.ts僅shared、coreVitest 單元測試vitest.config.tsshared、core、renderer、server、test-utils故意沒有maintsconfig.json 中的paths則同時聲明了shared/*、core/*、renderer/*、main/*、test-utils/*五個別名服務(wù)于編輯器智能提示與類型檢查并不代表運行時處處可用。規(guī)則文檔特別點出兩個典型陷阱均可從配置中直接驗證Vitest 故意不暴露mainvitest.config.ts 的別名表確實只有shared、core、renderer、server、test-utils五項。這意味著測試代碼若引用main/...類型檢查會通過但測試運行時會解析失敗——因為src/main深度依賴 Electron API本就不該被測試直接導入。QuickJS Worker 只暴露shared與corevite.worker.config.ts 印證了這一點。插件宿主入口src/core/plugin/host/quick-js-worker.ts見 vite.worker.config.ts運行在受限的 QuickJS 沙箱環(huán)境中只能引用跨層共享代碼與核心邏輯main、renderer、server均不可用。使用別名前先查目標配置這條建議的必要性還可以從 scripts/check-boundaries.mjs 的分層邊界規(guī)則中讀出它強制src/core不得導入electron與fastify、src/shared不得使用任何node:API 與 Node 全局對象、src/renderer不得導入 core/main 層、src/server不得導入electron與mainscripts/check-boundaries.mjs。別名按目標裁剪本質(zhì)上就是這些分層依賴規(guī)則在模塊解析層面的投影——shared之所以在所有目標都可用正是因為它被設(shè)計成唯一不觸碰 Node/Electron 特定 API 的層。共享運行時契約Zod 是唯一事實源規(guī)則文檔最后一節(jié)規(guī)定對不受信任的外部數(shù)據(jù)與跨層載荷一律使用zod的 Zod schema。具體約束有三條共享 schema 是其運行時約束、推斷類型與默認值的唯一事實源——不允許為同一契約再創(chuàng)建平行接口parallel interface或手寫校驗器純跨層 schema 放在src/shared/schemas/倉庫中該目錄已積累約 35 個文件如registry、conformance相關(guān)契約biome.json 的 overrides 里專門提到了registry.fixture.json與registry.conformance.json兩個 schema 數(shù)據(jù)文件宿主特定的校驗留在其所屬層內(nèi)——例如僅 Electron 端關(guān)心的窗口/平臺字段校驗不應下沉到src/shared/schemas/僅服務(wù)器端關(guān)心的配置校驗也不應上浮。這一約定與倉庫的邊界檢查是互相咬合的scripts/check-boundaries.mjs 禁止src/shared引入任何 Node 特性因此 shared 層的 schema 必須保持運行時無關(guān)而類型契約收斂到 Zod 之后check:schema-paritypackage.json 中的node scripts/check-schema-parity.mjs腳本等校驗才有明確的比對對象——推斷類型與運行時約束出自同一個 schema就不會出現(xiàn)類型上說有、運行時校驗不攔的錯位。落地自查清單在 Motrix 中提交代碼前可以按以下順序自檢新增/重命名文件后運行pnpm run check:file-names確認文件干符合 kebab-caseRust/Python 為 snake_caseCargo 二進制入口除外確認類型導入帶type修飾、Node 內(nèi)建模塊帶node:前綴然后運行pnpm run lint交由 Biome 統(tǒng)一格式與 import 排序使用任何shared/core/main/renderer/server/test-utils別名前先確認當前所在文件所屬構(gòu)建目標的 Vite/Vitest 配置確實暴露了該別名新增跨層數(shù)據(jù)結(jié)構(gòu)時直接在src/shared/schemas/建立 Zod schema禁止手寫平行校驗邏輯。以上四條分別對應 scripts/check-file-names.mjs、biome.json、各vite.*.config.ts與 tsconfig.json 中可驗證的實現(xiàn)構(gòu)成 Motrix 代碼風格規(guī)則從文檔約定到工具執(zhí)行的完整閉環(huán)?！久赓M下載鏈接】MotrixA full-featured download manager.項目地址: https://gitcode.com/GitHub_Trending/mo/Motrix創(chuàng)作聲明：本文部分內(nèi)容由AI輔助生成（AIGC），僅供參考 Motrix TypeScript 代碼規(guī)范實踐：kebab-case 文件命名、按構(gòu)建目標劃分的別名體系與 Zod 共享 Schema
Motrix TypeScript 代碼規(guī)范實踐kebab-case 文件命名、按構(gòu)建目標劃分的別名體系與 Zod 共享 Schema【免費下載鏈接】MotrixA full-featured download manager.項目地址: https://gitcode.com/GitHub_Trending/mo/Motrix本文基于 Motrix 倉庫中的 代碼風格規(guī)則 展開系統(tǒng)講解該下載管理器的文件命名約定、TypeScript 導入與路徑別名規(guī)則以及跨層數(shù)據(jù)的 Zod 共享 Schema 契約。讀完之后你可以在 Motrix 代碼庫中正確創(chuàng)建/重命名文件、安全使用各構(gòu)建目標Electron 主進程、渲染進程、服務(wù)器、QuickJS 插件 Worker、Vitest 測試暴露的路徑別名并知道哪些運行時契約必須收斂為單一 Zod schema從而避免常見的跨層類型漂移與別名跨目標誤用。Biome 是格式與通用 Lint 的唯一歸屬規(guī)則文檔開篇就明確了一條分工原則Biome 負責格式化和通用 lint 規(guī)則倉庫級規(guī)則文檔不重復這些設(shè)置只補充 Biome 覆蓋不到的倉庫特定邊界。這條分工在倉庫根目錄的 biome.json 中可以得到完整印證其中與代碼風格直接相關(guān)的配置包括文件命名強制 kebab-caselinter.rules.style.useFilenamingConvention被設(shè)為error級別filenameCases僅允許kebab-casebiome.json。也就是說命名錯誤不只是風格問題而是會讓pnpm run lint即biome check .直接失敗的硬錯誤。格式化基線2 空格縮進、80 字符行寬、LF 換行formatter段biome.json。引號與分號單引號、asNeeded分號、JSX 雙引號、ES5 尾逗號javascript.formatter段biome.json。測試文件寬松區(qū)**/*.test.{ts,tsx}、**/*.spec.{ts,tsx}、**/test/**、**/__tests__/**等路徑下的代碼關(guān)閉了noNonNullAssertion與noExplicitAnyoverrides段biome.json與后文文件命名中.test、.spec等約定后綴形成配套。導入自動整理assist.actions.source.organizeImports開啟Biome 會按源碼順序自動組織 import 語句。理解這一分工的實際意義在于當你覺得引號風格分號import 排序這類問題時答案永遠在 biome.json 里跑pnpm run lint:fix即可而.claude/rules/code-style.md承載的是 Biome 管不了的倉庫邊界——命名后綴語義、別名可用性和 Schema 歸屬。文件命名規(guī)范命名規(guī)則總覽規(guī)則文檔.claude/rules/code-style.md對命名給出的約定可歸納為四條對象約定說明JavaScript、TypeScript、TSX 與樣式文件kebab-case如task-manager.ts、use-add-task-form.ts約定性限定后綴保持小寫.test、.spec、.e2e、.integration、.darwin、.win32導出的類與 React 組件PascalCase文件名仍是 kebab-case僅導出符號用 PascalCaseRust 與 Pythonsnake_caseCargo 二進制入口可用 kebab-case 以匹配可執(zhí)行文件名這里有一個容易混淆的點文件命名與符號命名是兩套體系。倉庫中大量文件形如src/core/task/task-manager.ts、src/core/engine/engine-supervisor.ts文件名全部是 kebab-case但文件內(nèi)部導出的類、組件保持 PascalCase——規(guī)則文檔專門用一條約定鎖死了這一點避免文件名是連字符、導出名也跟著變成 kebab的漂移。后綴語義也有明確劃分.test/.spec對應單元測試Vitest 的include模式為src/**/*.test.{ts,tsx}見 vitest.config.ts.e2e/.integration對應端到端與集成測試如tests/e2e/nat-main.e2e.test.ts.darwin/.win32對應平臺專屬實現(xiàn)如src/core/probe/disk-probe-darwin.ts、src/core/probe/disk-probe-win32.ts全部保持小寫以與主文件干并列識別。pnpm run check:file-names的實際校驗邏輯規(guī)則要求新增或重命名文件后運行pnpm run check:file-names。該腳本在 package.json 中注冊為node scripts/check-file-names.mjs其實現(xiàn)scripts/check-file-names.mjs值得細看它把規(guī)則文檔中的每一條命名約定翻譯成了可執(zhí)行的檢查kebab-case 擴展名集合scripts/check-file-names.mjs.cjs、.css、.cts、.js、.jsx、.mjs、.mts、.scss、.ts、.tsx共 10 種均要求文件干匹配^[a-z0-9](?:-[a-z0-9])*$snake_case 擴展名集合scripts/check-file-names.mjs.py、.rs匹配^[a-z0-9](?:_[a-z0-9])*$Cargo 二進制例外位于src/bin/下的.rs文件放寬為snake_case 或 kebab-case正則^[a-z0-9](?:[-_][a-z0-9])*$scripts/check-file-names.mjs。這正是規(guī)則文檔中Cargo binary entrypoints may use kebab-case to match the executable name一條的執(zhí)行依據(jù)——例如packages/native-host這類 Rust 子包的main.rs與src/bin/下的入口文件名可以帶連字符以便產(chǎn)物可執(zhí)行名可讀排除前綴docs/與graphify-out/不參與檢查scripts/check-file-names.mjs掃描范圍通過git ls-files --cached --others --exclude-standard枚舉所有 Git 可見文件含未跟蹤的新文件意味著新建文件也會被掃到而不是只對已提交代碼生效失敗行為任何違例都會逐條打印Invalid code file names并令進程以非零碼退出因此可以安全接入 CI 或 pre-commit 流程。換言之規(guī)則文檔中的命名約定在倉庫里有三重執(zhí)行保障Biome 的useFilenamingConvention編輯器與 lint 階段、check:file-names腳本全倉庫文件干級別含 Biome 不覆蓋的 Rust/Python 與 Cargo 例外、以及約定性后綴與 Biome overrides 的測試目錄匹配*.test.*/*.spec.*的 lint 寬松規(guī)則依賴這些后綴。導入與路徑別名import type與node:前綴兩條導入層面的硬性約定類型專用導入必須使用import type。這與 tsconfig.json 中開啟的verbatimModuleSyntax: true是配套的——該編譯選項要求模塊語句所見即所得不寫type修飾的類型導入會在構(gòu)建時保留下來導致運行時因目標模塊沒有該值導出而失敗。Node 內(nèi)建模塊必須使用node:前綴如import path from node:path。倉庫源碼與腳本中普遍如此例如 scripts/check-file-names.mjs 開頭的node:child_process、node:path。別名優(yōu)先但相對導入有豁免規(guī)則約定優(yōu)先使用已配置的別名而非深層相對導入例如../../shared/...這類跨越目錄層的引用但同目錄sibling或上一級parent的本地導入可以保持相對路徑。這是一個務(wù)實的取舍別名解決跨層/跨目錄的可讀性與穩(wěn)定性而相鄰文件之間./xxx既短又清晰強制走別名反而降低信息量。別名可用性按構(gòu)建目標劃分這是規(guī)則文檔中最容易踩坑的部分。Motrix 是 Electron 服務(wù)器 插件 Worker 的多目標工程tsconfig.json聲明了全部五個別名但每個構(gòu)建目標只暴露其中一個子集這一點在各 Vite 配置的resolve.alias中得到逐字印證目標配置文件實際暴露的別名Electron 主進程vite.main.config.tsshared、core、main渲染進程vite.renderer.config.tsshared、rendererpreload 橋vite.preload.config.ts僅shared服務(wù)器無 Electron 依賴vite.server.config.tsshared、core、serverQuickJS 插件 Workervite.worker.config.ts僅shared、coreVitest 單元測試vitest.config.tsshared、core、renderer、server、test-utils故意沒有maintsconfig.json 中的paths則同時聲明了shared/*、core/*、renderer/*、main/*、test-utils/*五個別名服務(wù)于編輯器智能提示與類型檢查并不代表運行時處處可用。規(guī)則文檔特別點出兩個典型陷阱均可從配置中直接驗證Vitest 故意不暴露mainvitest.config.ts 的別名表確實只有shared、core、renderer、server、test-utils五項。這意味著測試代碼若引用main/...類型檢查會通過但測試運行時會解析失敗——因為src/main深度依賴 Electron API本就不該被測試直接導入。QuickJS Worker 只暴露shared與corevite.worker.config.ts 印證了這一點。插件宿主入口src/core/plugin/host/quick-js-worker.ts見 vite.worker.config.ts運行在受限的 QuickJS 沙箱環(huán)境中只能引用跨層共享代碼與核心邏輯main、renderer、server均不可用。使用別名前先查目標配置這條建議的必要性還可以從 scripts/check-boundaries.mjs 的分層邊界規(guī)則中讀出它強制src/core不得導入electron與fastify、src/shared不得使用任何node:API 與 Node 全局對象、src/renderer不得導入 core/main 層、src/server不得導入electron與mainscripts/check-boundaries.mjs。別名按目標裁剪本質(zhì)上就是這些分層依賴規(guī)則在模塊解析層面的投影——shared之所以在所有目標都可用正是因為它被設(shè)計成唯一不觸碰 Node/Electron 特定 API 的層。共享運行時契約Zod 是唯一事實源規(guī)則文檔最后一節(jié)規(guī)定對不受信任的外部數(shù)據(jù)與跨層載荷一律使用zod的 Zod schema。具體約束有三條共享 schema 是其運行時約束、推斷類型與默認值的唯一事實源——不允許為同一契約再創(chuàng)建平行接口parallel interface或手寫校驗器純跨層 schema 放在src/shared/schemas/倉庫中該目錄已積累約 35 個文件如registry、conformance相關(guān)契約biome.json 的 overrides 里專門提到了registry.fixture.json與registry.conformance.json兩個 schema 數(shù)據(jù)文件宿主特定的校驗留在其所屬層內(nèi)——例如僅 Electron 端關(guān)心的窗口/平臺字段校驗不應下沉到src/shared/schemas/僅服務(wù)器端關(guān)心的配置校驗也不應上浮。這一約定與倉庫的邊界檢查是互相咬合的scripts/check-boundaries.mjs 禁止src/shared引入任何 Node 特性因此 shared 層的 schema 必須保持運行時無關(guān)而類型契約收斂到 Zod 之后check:schema-paritypackage.json 中的node scripts/check-schema-parity.mjs腳本等校驗才有明確的比對對象——推斷類型與運行時約束出自同一個 schema就不會出現(xiàn)類型上說有、運行時校驗不攔的錯位。落地自查清單在 Motrix 中提交代碼前可以按以下順序自檢新增/重命名文件后運行pnpm run check:file-names確認文件干符合 kebab-caseRust/Python 為 snake_caseCargo 二進制入口除外確認類型導入帶type修飾、Node 內(nèi)建模塊帶node:前綴然后運行pnpm run lint交由 Biome 統(tǒng)一格式與 import 排序使用任何shared/core/main/renderer/server/test-utils別名前先確認當前所在文件所屬構(gòu)建目標的 Vite/Vitest 配置確實暴露了該別名新增跨層數(shù)據(jù)結(jié)構(gòu)時直接在src/shared/schemas/建立 Zod schema禁止手寫平行校驗邏輯。以上四條分別對應 scripts/check-file-names.mjs、biome.json、各vite.*.config.ts與 tsconfig.json 中可驗證的實現(xiàn)構(gòu)成 Motrix 代碼風格規(guī)則從文檔約定到工具執(zhí)行的完整閉環(huán)?！久赓M下載鏈接】MotrixA full-featured download manager.項目地址: https://gitcode.com/GitHub_Trending/mo/Motrix創(chuàng)作聲明：本文部分內(nèi)容由AI輔助生成（AIGC），僅供參考