最近在给 Teanary 做前端仓库治理有一件事我特别想拿出来聊聊我把一套只会被用到一次的复杂模板机制从核心代码里整个挪了出去单独开了一个仓库还配了一套完整文档。先说清楚这套模板机制是什么货色。Teanary 有个“自定义导出报告模板”的功能用户可以写一段模板配置运行时自动映射成组件渲染出报告。这个功能背后包含解析器、组件注册表、插槽系统、错误诊断代码量不小原理也相当绕。但它在整个核心仓库里只被一个页面用到——就是“报告模板”入口其余几十个页面完全碰不到它。刚接手的时候我也犹豫过既然它复杂拆出去会不会更麻烦后来我意识到真正麻烦的不是“复杂”本身而是“复杂和低频使用”叠在一起放在核心仓库里造成的那一堆问题。改核心代码要小心绕过它新同事看代码会困惑这一堆 template 文件跟主流程是什么关系发版节奏也被它拖住。与其继续在核心仓库里供着它不如拆出去让想用它、想改它、想贡献模板的人直接进对应仓库。这篇文章我就把整个拆分过程的思路、步骤、踩到的坑完整记录下来适合正在纠结“某个模块到底要不要从主仓库拆出去”的工程师参考。1. 为什么要拆复杂但低频的模板机制是核心仓库的“隐形负担”1.1 先还原现场这套模板机制到底复杂在哪我先把它在核心仓库里的样子描述一下。它不是简单的一段字符串替换而是有一套完整的执行链路模块职责复杂度来源parser把模板字符串解析成 AST语法规则、嵌套结构、错误定位registry维护“类型名 - 组件”的映射动态注册、命名冲突处理renderer递归渲染 AST 到组件树插槽、条件渲染、循环、props 转发validator配置校验与诊断信息要给出可读的错误提示而不是抛一个堆栈如果这是一个页面级的“一次性配置”那实现起来就是 if/else 拼组件非常简单。但作为“模板机制”它必须考虑通用性于是引入了解析、注册、渲染三层抽象。这类“机制级代码”和业务页面代码混在同一个仓库里认知负担一下子就上去了。新人打开目录看到src/template下十几个文件第一个反应往往是这是核心功能吗我改页面会不会碰到它答案可能是不用但光是解释这个“你不用管它”也需要花时间。1.2 留在核心代码里的三个真实痛点第一是体积和加载成本。核心 bundle 被迫带上了模板解析代码用户哪怕一辈子不用报告模板功能也得为这段逻辑买单。第二是认知负担。模板机制在主仓库里像一块“飞来石”跟业务逻辑没有强关联但它又真实存在导致每次梳理主流程的人都要先确认“这块和我有没有关系”。第三是发布节奏被绑架。模板机制的任何改动都会牵动核心包发版而这个功能实际上只有少数用户在使用。我印象最深的一次是模板的插槽规则想加一个逻辑核心包被迫跟着发了一个 patch。其他组看到 changelog 里莫名多了一条 template 相关记录问了半天才知道怎么回事。后来拆完模板仓库可以独立发版核心依赖方按自己的节奏升级再也不会因为一个边缘功能被动发版。1.3 拆出去能换来什么——不只是“干净”两个字拆完以后最直观的变化是主仓库的src/template目录整个消失调用点只剩一行 import。但更有价值的改变是模块的责任边界变得清晰了。模板机制的解析、渲染、注册、校验逻辑全部在独立仓库里自我闭环主仓库的业务代码只通过一个薄薄的适配层去调用它。模板贡献者不需要理解主项目的业务背景只需要看模板仓库的模板语法和扩展指南。模板相关的 issue 可以分流到独立仓库主仓库的 issue 列表不会再混入“模板渲染不对”这种其实跟核心无关的问题。模板包也有了自己的版本生命周期破坏性变更可以按 semver 正常发布不用看核心包的脸色。拆仓库的价值不是文件变少了而是“问题能更快找到负责人”。2. 拆分之前先花两天把边界想清楚2.1 判断标准什么属于模板机制什么属于业务逻辑拆仓库最忌讳上来就搬文件。我在动手前花了两天确认模块的边界核心是三个判断问题。第一这个模块被多少业务方使用如果只有一个业务方说明它不是核心链路的一部分具备拆出去的前提。第二这个模块是否拥有完整的输入输出契约它对外是否提供清晰的配置格式、API 接口、错误信息有契约的模块才能独立演进。第三这个模块的核心逻辑是否依赖主项目的运行时状态如果它只依赖自己接收到的配置数据不依赖业务 store、不依赖全局单例那它就是一个可以脱离主仓库独立存在的模块。Teanary 的模板机制恰好三条都满足。它只依赖模板字符串和组件注册表完全不关心业务数据从哪来所以拆出去之后不会因为业务变动而被牵连。如果某个模块依赖业务 store那拆的时候就必须把依赖同时抽走或者改为外部注入成本会高很多。2.2 保留适配层核心代码里必须留一个薄薄的“接口壳”拆出去之后原有的调用代码不能直接断供。我在主仓库里保留了一个src/lib/template-adapter.ts它只做三件事引入新包、包装原有 API、保持对外签名不变。// 主仓库内的模板适配层保持对业务调用方的 API 稳定 import { compile, render, registerComponent, type TemplateRenderOptions, } from teanary/template; export function renderReportTemplate( template: string, data: Recordstring, unknown, options?: TemplateRenderOptions, ) { return render(compile(template), data, options); } export { registerComponent };这段代码让原有调用方几乎零修改地继续使用。很多人拆仓库失败就是因为直接把依赖换掉然后全局搜替换导致业务代码里到处散落新包的 API 调用。适配层的存在还带来一个额外好处未来模板包升级 API只需要在适配层做一次拦截处理业务代码完全不用跟着改。2.3 版本策略模板包按自己的 semver 走不和主仓库绑定模板包teanary/template独立发行版本主仓库的 package.json 里用^1.2.0声明依赖。模板包做破坏性变更时必须发 major 版本并且在仓库里提供 migration guide。主仓库不要求每次发版都同步升级模板包只有当模板 API 出现弃用提示时才在适配层做兼容处理。{ dependencies: { teanary/template: ^1.2.0 } }这里有个细节模板包版本更新不代表核心仓库立刻更新。用户在使用 Teanary 时可能像以前一样 npm install 到最新模板包也可能锁定在旧版本。版本策略的核心思想是“允许差异存在但要有明确的迁移路径”。3. 实操过程从核心代码里把模板机制搬进独立仓库3.1 仓库初始化与目录设计新仓库的名字直接叫teanary-template目录结构一开始就按职责分好避免以后再折腾。teanary-template/ ├── src/ │ ├── parser/ │ │ ├── tokenizer.ts │ │ └── ast.ts │ ├── renderer/ │ │ ├── render.tsx │ │ └── slots.ts │ ├── registry/ │ │ └── registry.ts │ └── index.ts ├── __tests__/ │ ├── parser.test.ts │ ├── render.test.tsx │ └── registry.test.ts ├── docs/ │ ├── syntax.md │ ├── architecture.md │ ├── extending.md │ └── migration.md ├── playground/ │ ├── index.html │ └── main.ts ├── package.json ├── tsup.config.ts └── README.md我把playground目录放在最前面是为了让贡献者拉下仓库后能立刻在浏览器里看到模板渲染效果而不是面对一堆源码发呆。这个目录虽然小但对降低贡献门槛的帮助非常明显。3.2 迁移策略从“移动文件”升级为“重写边界”这里我要强调一个经验不要把拆仓理解成git mv整个目录。原目录里多少都会混着业务耦合直接移动过去只会把耦合搬到新家。我实际的做法是四步走。第一步在src/template里挑出纯逻辑文件也就是 parser、registry、types 这类不依赖业务 state 的文件在删除之前先给它们补上类型声明和单测。第二步在新仓库初始化后把这些文件按新结构复制过去而不是移动。第三步在复制过程中重命名 API比如原来叫TemplateParser到了独立仓库就改成更朴素的parseTemplate顺手去掉对主仓库全局状态的依赖。第四步在新仓库里统一入口导出。搬的过程中我踩了一个坑原代码里有个函数偷偷引用了主仓库的store用于读取用户偏好设置。复制到新仓库后这个引用导致新包必须依赖整个业务层。后来我把这个依赖删掉改为渲染时从 options 里外部传入模板包才算真正独立。如果你在搬的过程中发现某个文件怎么都摘不干净那说明边界还没划对需要回到第 2 节重新梳理。3.3 构建与测试配置让新仓库能独立跑通构建工具我选了 tsup配置非常短// tsup.config.ts import { defineConfig } from tsup; export default defineConfig({ entry: [src/index.ts], format: [esm, cjs], dts: true, sourcemap: true, clean: true, target: es2020, external: [react, react-dom], });关键点在external。模板包本身是 React 组件渲染器但它不应该打包 React而是让宿主项目提供 React 运行时避免出现两个 React 实例导致 hooks 报错的经典问题。测试用 vitest 跑配置和日常写的单测差不多import { describe, it, expect } from vitest; import { renderReportTemplate } from ../src; describe(renderReportTemplate, () { it(基础变量可以被正确渲染, () { const output renderReportTemplate(p{{ title }}/p, { title: hello, }); expect(output.textContent).toContain(hello); }); });测试跑通是独立仓库可以发布的前提也是后续改解析器时最有效的安全网。3.4 主仓库替换一行依赖 一个适配层新仓库发布后回到主仓库做替换。删除src/template目录在 package.json 里加上teanary/template依赖然后把原来直接调用模板内部函数的地方改成调用适配层。这个过程看起来简单但有个细节容易被忽略原来调用方是import { parseTemplate } from /template/parser这种 import 散落在多个文件里。如果直接删目录会遇到几十个报错。我在替换时没有做全局重写而是只改真正使用模板机制的入口文件让它走适配层。其他文件对模板内部 API 的依赖在删除目录后自然暴露出来逐个清理。这样受影响的代码面最小也不会顺手把无关页面改出问题。3.5 顺带完成文档结构化拆仓库的重头戏其实是文档。代码搬走只需要一个下午文档能不能跟上才是决定这次拆分是否成功的关键。我给文档定了明确的分工README.md5 分钟上手覆盖安装、最小示例、常见用法。docs/syntax.md模板语法参考变量、条件、循环、插槽逐个讲。docs/architecture.md架构说明与扩展点适合想改解析器的人。docs/extending.md如何注册自定义组件、如何贡献一个新模板类型。docs/migration.md从旧内置模板迁移到新包的步骤和工具。文档必须和代码在同一个仓库里模板语法一旦改动文档要同步改否则就会变成“代码独立了文档还留在主仓库里腐烂”的尴尬状态。4. 独立仓库的文档与协作设计4.1 文档结构化的实战经验给三个层级的人提供服务我给这份文档定的目标是让三类人都能快速找到入口。第一类人只想抄作业他们需要一个模板示例复制粘贴改两行就能在项目里跑起来。README 的“最小示例”部分就是为他们准备的。第二类人想用透这个机制他们需要知道语法规则、插槽怎么写、组件怎么注册syntax.md 和 extending.md 就是他们的手册。第三类人想改进模板机制本身他们要看 architecture.md理解解析器、渲染器、注册表的分工并且知道改完哪里需要补测试。我还为模板配置本身设计了一份 JSON Schema 文档让模板配置可以结构化校验IDE 也能自动补全。模板配置的一个示例如下{ version: 1.0, blocks: [ { type: heading, props: { level: 2, text: 每周报告 } }, { type: table, props: { source: issues, columns: [title, status] } } ] }字段含义用表格列出来version是模板格式版本blocks是页面区块列表type对应注册表里的组件类型props传给对应组件的属性。这样一份结构化文档比几段长篇大论有效得多。4.2 贡献指南怎么做才能让人真的愿意来提 PR独立仓库最容易出现的情况是外面的人想参与却不知道门在哪。所以我写了一篇 CONTRIBUTING.md开头就写清楚环境准备克隆仓库、npm install、npm run dev打开 playground。里面还附了一个最小的“新增模板类型”的 diff 示例让贡献者照着抄就能完成一次有效 PR。再往前推一步issue 模板也很重要。模板相关的 bug 如果只写“渲染不对”维护者根本没法处理。我在仓库里配置了一个 bug 模板要求提交者必须附上模板字符串、期望输出、实际输出三样东西。这样一来问题定位的成本大大降低。4.3 文档与示例共同维护的约定模板仓库的贡献规范里写了一条硬性要求每个新增模板类型必须带一个对应示例并且放到 playground 里可以实际预览。没有示例的文档不能合入没有 playground 演示的模板类型也不能合入。这条规则实施后效果很明显。以前主仓库里模板文档经常滞后现在模板包每次发版文档和示例都是同步更新的贡献者在提 PR 时也会主动补全这部分的验证。5. 常见问题与排查技巧实录5.1 版本漂移主仓库升级后模板渲染行为变了拆成两个仓库后版本漂移是最常见的问题。比如主仓库发了 3.0模板包还停留在 1.x适配层看着一切正常但模板包 2.0 修复了一个插槽 bug 之后用户升级模板包渲染行为就会突然变化。问题不在于用户不该升级而是适配层完全没有感知。我的解决办法是在适配层做运行时版本检查从teanary/template的 package.json 读版本号如果发现大版本和适配层声明的不匹配就在控制台打印一条明确的警告信息。同时主仓库的 package.json 里用 peerDependencies 声明模板包的版本范围npm 安装时就会给出提示。这不能完全阻止版本漂移但能让问题在发生的第一时间被发现。5.2 依赖方向搞反模板包反过来依赖主仓库拆仓之后要守住一条铁律模板包可以依赖 React但绝对不能反向依赖主仓库。如果模板包为了复用日期格式化函数import 了主仓库的 utils那它就重新绑定了主仓库主仓库一重构模板包立刻被波及。这等于白拆。我处理这类问题的原则是公共工具要么下沉到共享基础包要么在模板仓库里复制一份极简实现。很多开发同学觉得复制代码很丢人但这类工具函数通常只有几行复制进来后能换来一个完全独立的模块非常划算。依赖方向必须是单向的这是拆仓后最重要的架构纪律。5.3 旧模板配置迁移不做迁移工具的拆分就是耍流氓模板包发布 major 版本时如果改了配置格式旧用户升级会直接报错。我不希望用户因为升级一个边缘功能而付出血的代价所以在新包里提供了一个migrate()方法输入旧格式配置输出新格式配置。playground 上也挂了一个“导入旧模板”的按钮用户上传旧配置就能立即看到迁移结果。这个迁移工具大大降低了升级阻力。哪怕格式变化很大用户也只需要跑一次迁移手工确认一遍渲染结果然后把新配置保存下来。5.4 贡献门禁怎么保证模板仓库的质量不滑坡独立仓库最怕贡献者一多质量失控。我在 CI 里加了三条门槛PR 必须附带 playground 预览截图如果是新增模板类型必须补对应示例如果是解析器改动必须跑过全量单测。这三条都是自动化检查push 代码后会自动提醒。实际跑下来模板仓库的 PR 通过率比主仓库还高因为贡献者看到门禁清晰反而更愿意把东西准备齐全。下面是这次拆仓过程中遇到的高频问题速查现象原因解决方案主仓库升级后模板渲染乱掉模板包版本与适配层声明不一致运行时版本检查 peerDependencies 声明新仓库编译报错提示找不到主仓库模块代码里残留对主仓库的内部 import逐一清理改为 props 注入或内置实现拆仓后核心包体积没下降模板包被错误打包进主 bundletsup 配置 external确认产物中是外部依赖旧配置在新版本中报错破坏性变更没有迁移工具提供migrate()方法并在 playground 放导入入口贡献者不知道测试怎么跑贡献文档没有环境说明CONTRIBUTING 里写清npm install和测试命令6. 拆完之后我对“模块边界”的一点真实体会6.1 仓库边界不是靠目录划出来的而是靠契约划出来的这次拆仓让我对“模块边界”有了新的理解。以前我以为模块边界是目录结构是文件放哪里。这次做完才明白真正的边界是契约对外提供什么 API接收什么格式的输入输出什么结构的结果。只要契约清晰模块放在独立仓库还是放在主仓库的文。 件夹里本质上没有区别。但把模块放进独立仓库能让契约显性化逼着你把文档写好、把版本管理做好。如果拆完之后连一份像样的 README 都写不出来那大概率不是拆仓的问题而是这个模块根本没到能拆的成熟度。6.2 给正在犹豫要不要拆仓库的你三个建议第一拆之前先把模块的契约写清楚否则只是换了一个地方继续乱。第二适配层一定要留它成本很低却能把风险隔离在接口之后未来升级才有余地。第三如果一个模块拆出去之后你连文档和示例都不想写那它就不是需要拆仓库而是需要被砍掉。我在这次拆分里最大的收获不是核心仓库变整洁了而是我终于理解了一个道理复杂的东西不需要被“隐藏”起来它需要一个合适自己的容器。模板机制有了自己的仓库、自己的文档、自己的版本号也有了自己的一批维护者和贡献者。它不再是主仓库里那个谁都不想碰的边角料而是一个可以独立呼吸的开源模块。如果下次再遇到“单独模块只被用一次但特别复杂”的情况我会毫不犹豫地按照这套流程拆下去。
最近在给 Teanary 做前端仓库治理有一件事我特别想拿出来聊聊我把一套只会被用到一次的复杂模板机制从核心代码里整个挪了出去单独开了一个仓库还配了一套完整文档。先说清楚这套模板机制是什么货色。Teanary 有个“自定义导出报告模板”的功能用户可以写一段模板配置运行时自动映射成组件渲染出报告。这个功能背后包含解析器、组件注册表、插槽系统、错误诊断代码量不小原理也相当绕。但它在整个核心仓库里只被一个页面用到——就是“报告模板”入口其余几十个页面完全碰不到它。刚接手的时候我也犹豫过既然它复杂拆出去会不会更麻烦后来我意识到真正麻烦的不是“复杂”本身而是“复杂和低频使用”叠在一起放在核心仓库里造成的那一堆问题。改核心代码要小心绕过它新同事看代码会困惑这一堆 template 文件跟主流程是什么关系发版节奏也被它拖住。与其继续在核心仓库里供着它不如拆出去让想用它、想改它、想贡献模板的人直接进对应仓库。这篇文章我就把整个拆分过程的思路、步骤、踩到的坑完整记录下来适合正在纠结“某个模块到底要不要从主仓库拆出去”的工程师参考。1. 为什么要拆复杂但低频的模板机制是核心仓库的“隐形负担”1.1 先还原现场这套模板机制到底复杂在哪我先把它在核心仓库里的样子描述一下。它不是简单的一段字符串替换而是有一套完整的执行链路模块职责复杂度来源parser把模板字符串解析成 AST语法规则、嵌套结构、错误定位registry维护“类型名 - 组件”的映射动态注册、命名冲突处理renderer递归渲染 AST 到组件树插槽、条件渲染、循环、props 转发validator配置校验与诊断信息要给出可读的错误提示而不是抛一个堆栈如果这是一个页面级的“一次性配置”那实现起来就是 if/else 拼组件非常简单。但作为“模板机制”它必须考虑通用性于是引入了解析、注册、渲染三层抽象。这类“机制级代码”和业务页面代码混在同一个仓库里认知负担一下子就上去了。新人打开目录看到src/template下十几个文件第一个反应往往是这是核心功能吗我改页面会不会碰到它答案可能是不用但光是解释这个“你不用管它”也需要花时间。1.2 留在核心代码里的三个真实痛点第一是体积和加载成本。核心 bundle 被迫带上了模板解析代码用户哪怕一辈子不用报告模板功能也得为这段逻辑买单。第二是认知负担。模板机制在主仓库里像一块“飞来石”跟业务逻辑没有强关联但它又真实存在导致每次梳理主流程的人都要先确认“这块和我有没有关系”。第三是发布节奏被绑架。模板机制的任何改动都会牵动核心包发版而这个功能实际上只有少数用户在使用。我印象最深的一次是模板的插槽规则想加一个逻辑核心包被迫跟着发了一个 patch。其他组看到 changelog 里莫名多了一条 template 相关记录问了半天才知道怎么回事。后来拆完模板仓库可以独立发版核心依赖方按自己的节奏升级再也不会因为一个边缘功能被动发版。1.3 拆出去能换来什么——不只是“干净”两个字拆完以后最直观的变化是主仓库的src/template目录整个消失调用点只剩一行 import。但更有价值的改变是模块的责任边界变得清晰了。模板机制的解析、渲染、注册、校验逻辑全部在独立仓库里自我闭环主仓库的业务代码只通过一个薄薄的适配层去调用它。模板贡献者不需要理解主项目的业务背景只需要看模板仓库的模板语法和扩展指南。模板相关的 issue 可以分流到独立仓库主仓库的 issue 列表不会再混入“模板渲染不对”这种其实跟核心无关的问题。模板包也有了自己的版本生命周期破坏性变更可以按 semver 正常发布不用看核心包的脸色。拆仓库的价值不是文件变少了而是“问题能更快找到负责人”。2. 拆分之前先花两天把边界想清楚2.1 判断标准什么属于模板机制什么属于业务逻辑拆仓库最忌讳上来就搬文件。我在动手前花了两天确认模块的边界核心是三个判断问题。第一这个模块被多少业务方使用如果只有一个业务方说明它不是核心链路的一部分具备拆出去的前提。第二这个模块是否拥有完整的输入输出契约它对外是否提供清晰的配置格式、API 接口、错误信息有契约的模块才能独立演进。第三这个模块的核心逻辑是否依赖主项目的运行时状态如果它只依赖自己接收到的配置数据不依赖业务 store、不依赖全局单例那它就是一个可以脱离主仓库独立存在的模块。Teanary 的模板机制恰好三条都满足。它只依赖模板字符串和组件注册表完全不关心业务数据从哪来所以拆出去之后不会因为业务变动而被牵连。如果某个模块依赖业务 store那拆的时候就必须把依赖同时抽走或者改为外部注入成本会高很多。2.2 保留适配层核心代码里必须留一个薄薄的“接口壳”拆出去之后原有的调用代码不能直接断供。我在主仓库里保留了一个src/lib/template-adapter.ts它只做三件事引入新包、包装原有 API、保持对外签名不变。// 主仓库内的模板适配层保持对业务调用方的 API 稳定 import { compile, render, registerComponent, type TemplateRenderOptions, } from teanary/template; export function renderReportTemplate( template: string, data: Recordstring, unknown, options?: TemplateRenderOptions, ) { return render(compile(template), data, options); } export { registerComponent };这段代码让原有调用方几乎零修改地继续使用。很多人拆仓库失败就是因为直接把依赖换掉然后全局搜替换导致业务代码里到处散落新包的 API 调用。适配层的存在还带来一个额外好处未来模板包升级 API只需要在适配层做一次拦截处理业务代码完全不用跟着改。2.3 版本策略模板包按自己的 semver 走不和主仓库绑定模板包teanary/template独立发行版本主仓库的 package.json 里用^1.2.0声明依赖。模板包做破坏性变更时必须发 major 版本并且在仓库里提供 migration guide。主仓库不要求每次发版都同步升级模板包只有当模板 API 出现弃用提示时才在适配层做兼容处理。{ dependencies: { teanary/template: ^1.2.0 } }这里有个细节模板包版本更新不代表核心仓库立刻更新。用户在使用 Teanary 时可能像以前一样 npm install 到最新模板包也可能锁定在旧版本。版本策略的核心思想是“允许差异存在但要有明确的迁移路径”。3. 实操过程从核心代码里把模板机制搬进独立仓库3.1 仓库初始化与目录设计新仓库的名字直接叫teanary-template目录结构一开始就按职责分好避免以后再折腾。teanary-template/ ├── src/ │ ├── parser/ │ │ ├── tokenizer.ts │ │ └── ast.ts │ ├── renderer/ │ │ ├── render.tsx │ │ └── slots.ts │ ├── registry/ │ │ └── registry.ts │ └── index.ts ├── __tests__/ │ ├── parser.test.ts │ ├── render.test.tsx │ └── registry.test.ts ├── docs/ │ ├── syntax.md │ ├── architecture.md │ ├── extending.md │ └── migration.md ├── playground/ │ ├── index.html │ └── main.ts ├── package.json ├── tsup.config.ts └── README.md我把playground目录放在最前面是为了让贡献者拉下仓库后能立刻在浏览器里看到模板渲染效果而不是面对一堆源码发呆。这个目录虽然小但对降低贡献门槛的帮助非常明显。3.2 迁移策略从“移动文件”升级为“重写边界”这里我要强调一个经验不要把拆仓理解成git mv整个目录。原目录里多少都会混着业务耦合直接移动过去只会把耦合搬到新家。我实际的做法是四步走。第一步在src/template里挑出纯逻辑文件也就是 parser、registry、types 这类不依赖业务 state 的文件在删除之前先给它们补上类型声明和单测。第二步在新仓库初始化后把这些文件按新结构复制过去而不是移动。第三步在复制过程中重命名 API比如原来叫TemplateParser到了独立仓库就改成更朴素的parseTemplate顺手去掉对主仓库全局状态的依赖。第四步在新仓库里统一入口导出。搬的过程中我踩了一个坑原代码里有个函数偷偷引用了主仓库的store用于读取用户偏好设置。复制到新仓库后这个引用导致新包必须依赖整个业务层。后来我把这个依赖删掉改为渲染时从 options 里外部传入模板包才算真正独立。如果你在搬的过程中发现某个文件怎么都摘不干净那说明边界还没划对需要回到第 2 节重新梳理。3.3 构建与测试配置让新仓库能独立跑通构建工具我选了 tsup配置非常短// tsup.config.ts import { defineConfig } from tsup; export default defineConfig({ entry: [src/index.ts], format: [esm, cjs], dts: true, sourcemap: true, clean: true, target: es2020, external: [react, react-dom], });关键点在external。模板包本身是 React 组件渲染器但它不应该打包 React而是让宿主项目提供 React 运行时避免出现两个 React 实例导致 hooks 报错的经典问题。测试用 vitest 跑配置和日常写的单测差不多import { describe, it, expect } from vitest; import { renderReportTemplate } from ../src; describe(renderReportTemplate, () { it(基础变量可以被正确渲染, () { const output renderReportTemplate(p{{ title }}/p, { title: hello, }); expect(output.textContent).toContain(hello); }); });测试跑通是独立仓库可以发布的前提也是后续改解析器时最有效的安全网。3.4 主仓库替换一行依赖 一个适配层新仓库发布后回到主仓库做替换。删除src/template目录在 package.json 里加上teanary/template依赖然后把原来直接调用模板内部函数的地方改成调用适配层。这个过程看起来简单但有个细节容易被忽略原来调用方是import { parseTemplate } from /template/parser这种 import 散落在多个文件里。如果直接删目录会遇到几十个报错。我在替换时没有做全局重写而是只改真正使用模板机制的入口文件让它走适配层。其他文件对模板内部 API 的依赖在删除目录后自然暴露出来逐个清理。这样受影响的代码面最小也不会顺手把无关页面改出问题。3.5 顺带完成文档结构化拆仓库的重头戏其实是文档。代码搬走只需要一个下午文档能不能跟上才是决定这次拆分是否成功的关键。我给文档定了明确的分工README.md5 分钟上手覆盖安装、最小示例、常见用法。docs/syntax.md模板语法参考变量、条件、循环、插槽逐个讲。docs/architecture.md架构说明与扩展点适合想改解析器的人。docs/extending.md如何注册自定义组件、如何贡献一个新模板类型。docs/migration.md从旧内置模板迁移到新包的步骤和工具。文档必须和代码在同一个仓库里模板语法一旦改动文档要同步改否则就会变成“代码独立了文档还留在主仓库里腐烂”的尴尬状态。4. 独立仓库的文档与协作设计4.1 文档结构化的实战经验给三个层级的人提供服务我给这份文档定的目标是让三类人都能快速找到入口。第一类人只想抄作业他们需要一个模板示例复制粘贴改两行就能在项目里跑起来。README 的“最小示例”部分就是为他们准备的。第二类人想用透这个机制他们需要知道语法规则、插槽怎么写、组件怎么注册syntax.md 和 extending.md 就是他们的手册。第三类人想改进模板机制本身他们要看 architecture.md理解解析器、渲染器、注册表的分工并且知道改完哪里需要补测试。我还为模板配置本身设计了一份 JSON Schema 文档让模板配置可以结构化校验IDE 也能自动补全。模板配置的一个示例如下{ version: 1.0, blocks: [ { type: heading, props: { level: 2, text: 每周报告 } }, { type: table, props: { source: issues, columns: [title, status] } } ] }字段含义用表格列出来version是模板格式版本blocks是页面区块列表type对应注册表里的组件类型props传给对应组件的属性。这样一份结构化文档比几段长篇大论有效得多。4.2 贡献指南怎么做才能让人真的愿意来提 PR独立仓库最容易出现的情况是外面的人想参与却不知道门在哪。所以我写了一篇 CONTRIBUTING.md开头就写清楚环境准备克隆仓库、npm install、npm run dev打开 playground。里面还附了一个最小的“新增模板类型”的 diff 示例让贡献者照着抄就能完成一次有效 PR。再往前推一步issue 模板也很重要。模板相关的 bug 如果只写“渲染不对”维护者根本没法处理。我在仓库里配置了一个 bug 模板要求提交者必须附上模板字符串、期望输出、实际输出三样东西。这样一来问题定位的成本大大降低。4.3 文档与示例共同维护的约定模板仓库的贡献规范里写了一条硬性要求每个新增模板类型必须带一个对应示例并且放到 playground 里可以实际预览。没有示例的文档不能合入没有 playground 演示的模板类型也不能合入。这条规则实施后效果很明显。以前主仓库里模板文档经常滞后现在模板包每次发版文档和示例都是同步更新的贡献者在提 PR 时也会主动补全这部分的验证。5. 常见问题与排查技巧实录5.1 版本漂移主仓库升级后模板渲染行为变了拆成两个仓库后版本漂移是最常见的问题。比如主仓库发了 3.0模板包还停留在 1.x适配层看着一切正常但模板包 2.0 修复了一个插槽 bug 之后用户升级模板包渲染行为就会突然变化。问题不在于用户不该升级而是适配层完全没有感知。我的解决办法是在适配层做运行时版本检查从teanary/template的 package.json 读版本号如果发现大版本和适配层声明的不匹配就在控制台打印一条明确的警告信息。同时主仓库的 package.json 里用 peerDependencies 声明模板包的版本范围npm 安装时就会给出提示。这不能完全阻止版本漂移但能让问题在发生的第一时间被发现。5.2 依赖方向搞反模板包反过来依赖主仓库拆仓之后要守住一条铁律模板包可以依赖 React但绝对不能反向依赖主仓库。如果模板包为了复用日期格式化函数import 了主仓库的 utils那它就重新绑定了主仓库主仓库一重构模板包立刻被波及。这等于白拆。我处理这类问题的原则是公共工具要么下沉到共享基础包要么在模板仓库里复制一份极简实现。很多开发同学觉得复制代码很丢人但这类工具函数通常只有几行复制进来后能换来一个完全独立的模块非常划算。依赖方向必须是单向的这是拆仓后最重要的架构纪律。5.3 旧模板配置迁移不做迁移工具的拆分就是耍流氓模板包发布 major 版本时如果改了配置格式旧用户升级会直接报错。我不希望用户因为升级一个边缘功能而付出血的代价所以在新包里提供了一个migrate()方法输入旧格式配置输出新格式配置。playground 上也挂了一个“导入旧模板”的按钮用户上传旧配置就能立即看到迁移结果。这个迁移工具大大降低了升级阻力。哪怕格式变化很大用户也只需要跑一次迁移手工确认一遍渲染结果然后把新配置保存下来。5.4 贡献门禁怎么保证模板仓库的质量不滑坡独立仓库最怕贡献者一多质量失控。我在 CI 里加了三条门槛PR 必须附带 playground 预览截图如果是新增模板类型必须补对应示例如果是解析器改动必须跑过全量单测。这三条都是自动化检查push 代码后会自动提醒。实际跑下来模板仓库的 PR 通过率比主仓库还高因为贡献者看到门禁清晰反而更愿意把东西准备齐全。下面是这次拆仓过程中遇到的高频问题速查现象原因解决方案主仓库升级后模板渲染乱掉模板包版本与适配层声明不一致运行时版本检查 peerDependencies 声明新仓库编译报错提示找不到主仓库模块代码里残留对主仓库的内部 import逐一清理改为 props 注入或内置实现拆仓后核心包体积没下降模板包被错误打包进主 bundletsup 配置 external确认产物中是外部依赖旧配置在新版本中报错破坏性变更没有迁移工具提供migrate()方法并在 playground 放导入入口贡献者不知道测试怎么跑贡献文档没有环境说明CONTRIBUTING 里写清npm install和测试命令6. 拆完之后我对“模块边界”的一点真实体会6.1 仓库边界不是靠目录划出来的而是靠契约划出来的这次拆仓让我对“模块边界”有了新的理解。以前我以为模块边界是目录结构是文件放哪里。这次做完才明白真正的边界是契约对外提供什么 API接收什么格式的输入输出什么结构的结果。只要契约清晰模块放在独立仓库还是放在主仓库的文。 件夹里本质上没有区别。但把模块放进独立仓库能让契约显性化逼着你把文档写好、把版本管理做好。如果拆完之后连一份像样的 README 都写不出来那大概率不是拆仓的问题而是这个模块根本没到能拆的成熟度。6.2 给正在犹豫要不要拆仓库的你三个建议第一拆之前先把模块的契约写清楚否则只是换了一个地方继续乱。第二适配层一定要留它成本很低却能把风险隔离在接口之后未来升级才有余地。第三如果一个模块拆出去之后你连文档和示例都不想写那它就不是需要拆仓库而是需要被砍掉。我在这次拆分里最大的收获不是核心仓库变整洁了而是我终于理解了一个道理复杂的东西不需要被“隐藏”起来它需要一个合适自己的容器。模板机制有了自己的仓库、自己的文档、自己的版本号也有了自己的一批维护者和贡献者。它不再是主仓库里那个谁都不想碰的边角料而是一个可以独立呼吸的开源模块。如果下次再遇到“单独模块只被用一次但特别复杂”的情况我会毫不犹豫地按照这套流程拆下去。
