跳到正文

我所理解的前端框架最佳实践(5):按入口和依赖组织大型模块

我所理解的前端框架最佳实践

  1. 用表格组件减少通用渲染和交互的维护成本
  2. 利用派生值减少维护成本和心智负担
  3. 正确拆分组件
  4. 抽取业务逻辑后,谁持有状态和副作用
  5. 按入口和依赖组织大型模块(当前)
  6. 用 kebab-case 格式统一文件名
  7. 合理使用全局状态

一个项目里,管理后台和公开页面可以由两份 HTML 分别启动,后台的单测也可以在没有页面的环境里运行。文件该放在哪,先看谁负责启动这块代码、谁会调用它、这些调用方在哪运行。只服务一个模块的实现跟着模块走。多个模块确实要遵循同一个规则,再把那条规则放到它们都能依赖的地方。

运行入口负责接入宿主,模块公开入口负责提供能力

运行入口由 HTML、构建配置、框架约定或测试运行器选中。它负责把实现接到宿主上,例如挂载应用、注册事件或开始监听消息。模块公开入口供其他代码导入,例如目录的 index.ts 转导出调用方需要的函数,或由包的 exports 声明哪些路径可以使用。它们都可能叫 index,用途要顺着加载关系判断。测试想验证一条规则时,可以导入实现该规则的模块,省去启动整个应用的准备工作。

应用下面也可以有自己的大型业务模块。比如报表和权限都挂在同一个后台入口下,但两块各自拥有页面、请求和业务规则。报表导出留在报表模块里。报表模块需要判断当前用户能否导出时,通过权限模块的公开接口查询。把两块代码都移进顶层 utils 后,目录反而看不出谁负责改规则,谁只负责调用。

多页面项目让专用实现跟着各自的页面

以用 Vite 构建的项目为例,公开站点和管理后台如果各有一份 HTML,就在生产构建配置里声明两份 HTML 入口。每份 HTML 加载自己的启动模块。用 React 时,启动模块通常负责挂载根组件。用 Vue 时,它负责创建并挂载应用实例。单页应用里由路由器切换的多个页面可以继续共用同一个 HTML 和应用入口,各路由的专用实现仍可以按业务归属存放。构建配置见 Vite 多页面构建文档。

index.html
admin/index.html
src/
  site/
    main.ts
    search/
  admin/
    main.ts
    reports/
  shared/
    date-range.ts

两份 HTML 分别加载 site/main.ts 和 admin/main.ts。搜索交互留在公开站点,报表导出留在后台。两边如果遵循同一套日期范围规则,可以共享 date-range.ts。后台从表单取值,站点从查询参数取值。校验函数只接收日期,所以 Node 单测也可以直接调用。

两份 HTML 分别启动各自的页面模块,两个页面和 Node 单测共用日期校验规则

测试入口只加载需要验证的范围

日期范围校验的测试可以放在实现旁边,直接导入被测模块。用 Vitest 时,按约定把测试命名为 date-range.test.ts,就能交给运行器发现。文件名约定见 Vitest 的测试编写指南。

验证多页面跳转或权限接入时,可以由浏览器测试打开实际页面。跨模块的集成测试可以放在应用的 tests/ 下,测试夹具和启动脚本也随测试维护。

把日期校验和会在加载时读取 window 的初始化模块放进同一个 barrel 后,Node 只导入校验函数也可能遇到 window is not defined。独立的校验模块可以同时供页面和 Node 测试调用。包内单测可覆盖内部实现,消费端测试通过包的公开入口核对调用约定。

Monorepo 让每个应用和包声明自己的依赖

沿用公开站点和管理后台的例子。如果两边要分别部署或使用各自的构建配置,可以组织为 apps/site 和 apps/admin。假如两边都要遵守同一套日期范围规则,而且希望作为独立包检查和构建,可以提到 packages/date-range。后台的报表导出仍放在 apps/admin,共享包无需导入任意一个应用。

在 pnpm 工作区里,两个应用各自在 package.json 声明 "@example/date-range": "workspace:*",用包名导入。共享包可以用 exports 给出公开入口,测试专用依赖则由拥有测试的应用或包声明。配置细节见 pnpm 工作区协议和 Node.js 包入口文档。

直接用相对路径跨进另一个包的 src/ 会绕开包的入口约定。新增消费者时,可以先检查它能否按包名加载所需入口,再单独跑它的构建或测试。

Marker 把主进程、预加载和索引线程放在各自的目录

Markdown 批注工具 Marker 有三个运行职责不同的 TS 入口。Electron 主进程负责窗口和文件访问,预加载脚本把允许的 IPC 方法交给页面,索引线程由主进程启动,负责扫描和查询。下面的目录只列出与依赖归属有关的文件。

src/
  main/
    index.ts
    utils/
      index.ts
      document-path/index.ts
      document-review/index.ts
  preload/
    index.ts
  library-worker/
    index.ts
    utils/index.ts
  global-utils/
    index.ts
    markdown-path.ts
  shared/
    library-worker-protocol.ts

主进程要检查用户打开的文件,索引线程也要筛出 Markdown 文件,两边共用 global-utils 里的 isMarkdownPath。给剪贴板生成相对路径或 Markdown 链接只发生在主进程,formatDocumentPath 就留在 main/utils/document-path。索引请求和响应的类型放在 shared,主进程和线程都依赖这份契约。

main/utils/index.ts 汇总主进程启动代码需要的能力,其中有依赖 Electron 或构建工具的实现。审阅写回测试直接导入 main/utils/document-review,用 Node 验证被测逻辑可以独立加载。要验收索引线程的启动链路,则从主进程实际引用的构建产物启动线程,检查它能否完成扫描、查询和退出。各个宿主怎样执行或转换 TS,可以接着读《按运行环境处理 TypeScript 代码》。