每次聊到“共用代码”很多开发者的第一反应是“赶紧抽出来”。业务代码里反复出现几段相同的日期格式化、请求封装、列表分页逻辑时很难忍住不把它们整理成一个公共模块。开始几天确实很爽新增代码行数变少结构看起来也更清爽。但问题往往在几周之后浮出水面——你改了一个公共函数的默认行为结果三个线上系统一起变了你加了一个新参数却发现一部分调用方没有传直接落到旧逻辑。到了这一步多数人的第一反应是“公共代码害人不浅”。可真正的问题不是共用代码本身而是我们把共用代码当成了一个没有边界的公共杂物间。这篇文章想聊的是共用代码处理那点事本质上不是“怎么写”的问题而是“怎么管”的问题。1. 共用代码的真正成本不是抽取时而是后续每一次改动1.1 一改全改的连锁反应一个很常见的场景是两个业务系统都用到了同一个时间处理工具函数。起初它们的用法一致公共函数稳定运行了两个月。后来业务 A 提了一个需求要按某一种地区格式展示时间于是有人给公共函数加了一个region参数默认值为空。因为没有传region时走老逻辑业务 A 通知业务 B“不传就不影响”于是上线了。又过了一个月业务 C 也开始用这个函数但测试环境里没人看过默认格式问题直到线上灰度才暴露。类似故事每天都在不同团队发生。共用代码的麻烦在于写代码的人很难感知到“使用者”的范围。你面对的从语言层面看只是一个函数但在系统层面它可能连接着十几个入口。很多人觉得“复制粘贴”不好于是抽公共代码。但有一个反直觉的点需要记住复制粘贴虽然难看但它天然隔离了风险抽公共代码之后改动的影响范围会立刻被放大。这里并不是说应该回到复制粘贴而是说一旦选择共用代码就必须接受一个前提——它不再是“我自己的一段代码”而是“多方共享的契约”。契约一旦修改未通知到的调用方就会把风险带进生产环境。1.2 新生期、膨胀期、腐朽期公共模块的三个生命阶段我见过很多公共模块生命周期大致都经过三个阶段。新生期需求重叠度高抽象自然成立改一次往往能同时解决几个团队的痛点。这个阶段的公共代码是真正有价值的因为它把重复流程固化了下来提高了整体效率。膨胀期随着使用者变多每个团队开始带着自己的特殊诉求进来。有人要求增加配置项有人要求兼容旧数据有人希望不要影响自己的样式。最典型的信号是公共函数签名里的参数越来越多函数体里到处是if (options.xxx)分支。代码还没坏但每次改动都需要拉上一堆人确认。腐朽期公共模块内部逻辑已经复杂到没人敢动但业务方又被要求“尽量复用”结果大家开始绕开它在有公共模块的情况下另写了一份本地实现。这时仓库里会出现“假装在用公共代码”的现象模块还在引用还在但真正的业务逻辑已经各自为政。更麻烦的是没人敢删除旧模块。识别自己处于哪个阶段其实不需要复杂工具。看几个信号就够了是否有明确负责人、变更是否有测试保护、调用方是否清楚自己依赖什么版本、出现问题时多久能定位影响面。1.3 健康公共模块的几个简单信号可以用下面这个表格做一个快速体检维度健康信号危险信号负责人有明确的维护人或者小组属于“大家都能改但没人负责”使用范围调用方数量可列出来发布时可验证只记得被用了但没人说清哪些系统在用接口变更破坏性变更升主版本提前通知直接在公共函数上加参数、改默认值测试公共模块自带单元测试和关键场景回归靠调用方测试顺便覆盖文档有使用示例和变更记录只有源码注释甚至注释也过期这些信号不需要一次全部满足但至少要有两三项过关。如果一项都没有那么这个“共用代码”本质上是一个待爆的雷。注意健康的共用代码不是“永远不变”而是“每次变化都可追踪、可验证、可回退”。2. 抽共用代码的四个层级选错层级比不抽更危险2.1 第一次粘贴不算“共用”首先得厘清一个常见误区。很多人把“在不同仓库里复制同一段代码”也称为共用代码。严格来说这不是共用代码而是“共用了一次代码”。复制行为发生后的下一秒这两份代码就失去了共同演进的基础。后续任何一方的修复、优化、安全更新都不会自动同步到另一边。这种模式在短期应急时可以理解但它不应该被当成一种复用方案。如果团队已经处在这个状态第一步不是去建仓库、发包而是先统计这些重复代码出现在哪些位置评估它们之间的差异再决定是统一还是保留分叉。强行合并并不一定最优尤其当两份代码已经各自演化出不同行为时合并成本往往大于继续维护重复代码的成本。2.2 仓库内的公共目录适合小团队但门槛最低最常见的复用层级是仓库内的src/common、src/components、src/utils这类目录。好处是调用成本极低不需要发版本改完立刻生效非常适合单个仓库、小团队、业务耦合较高的场景。但它的弱点也很明显因为没有版本边界任何一次提交都相当于一次“隐式发布”你改了utils/time.js全仓库所有引用方立刻感受到变化。在单仓库模式下这种隐式发布可以通过代码评审和测试来缓解但前提是团队规模足够小、上下文足够一致。一旦仓库膨胀到几十个模块、上百个开发者公共目录就会慢慢变成“谁都不敢动的雷区”。这个时候很多人开始考虑把公共代码拆成独立包。2.3 独立成包工程化复用的起点把公共代码拆成独立工程再通过包管理器分发是目前最成熟的复用方式。前端会用 npm package后端可能是内部 Maven/Gradle 依赖或者一套自建私仓。独立成包的最大价值不是“代码更干净”而是引入了版本概念调用方可以锁定版本公共模块的维护者可以在发布新版本时保留兼容区间业务方再也不会因为别人git pull而被悄悄改掉行为。这一步看起来只是工程结构调整实际上设置了好几道隐性约束要有发布流程、变更记录、版本号、测试、包的访问权限管理。很多团队卡在这里不是不会写代码而是不愿意承担“维护一个包”的持续成本。如果你要抽的公共逻辑一年都改不了几次独立发包反而会增加负担。所以独立成包的判断不是“这段代码有多少处重复”而是“这个模块未来一年有没有独立的迭代节奏”。通常我会建议先给公共模块写一份README把使用方式、参数说明、变更记录写清楚。如果连这份文档都不愿意维护说明团队还没准备好独立发包。2.4 跨团队公共平台 / 微前端不是必须再往上一层是把公共代码升级成跨团队的基础设施比如统一组件库、公共业务中台、微前端容器。这个层级已经不是“抽代码”的问题而是“组织分工”的问题。它需要跨团队治理机制、清晰的 API 契约、稳定的发布节奏以及愿意为长期维护投入人力的经营团队。现实中很多失败案例不是技术选型错误而是组织上没有给公共模块“编制”业务团队各自有 KPI却要求他们合力维护一个公共平台最后通常变成“谁用谁改、谁改谁炸”。我的建议是不要因为看到大厂有统一组件库就觉得所有团队都必须上。小规模团队用仓库内公共目录中等规模用私有包大规模才需要认真规划公共平台。层级不是越高越好而是要匹配团队的协作半径。层级典型形式优点风险适合规模复制粘贴各仓库各放一份隔离风险实现最快修复不同步、差异蔓延紧急复制公共目录src/common、src/utils调用成本低、改完即生效无版本边界、隐式发布小团队单仓库独立包npm 包 / 内部构件库有版本、可升级、影响面可控需要发布和维护流程多仓库、多项目公共平台 / 微前端统一组件库、中台服务跨团队复用效率最高治理成本高、需要长期投入大型组织这个表格不是标准答案但可以帮助团队快速对齐认知你要解决的是“改起来太慢”还是“用起来太乱”还是“没人负责”的问题。不同问题对应的层级完全不同。3. 决定共用代码命运的是接口设计与变更管理3.1 先给调用方一个稳定的“契约”很多人抽公共代码时习惯把内部实现细节直接暴露给调用方。比如一个公共请求函数刚开始只有一个url参数后来有人需要自定义 header就再加一个header参数有人需要超时时间再加timeout有人需要重试于是再加retry。函数签名越来越长文档越来越难写调用方越来越困惑。更合理的做法是在接口设计阶段就把“容易变化的部分”收敛到一个配置对象里// 不推荐参数不断膨胀 request(url, data, header, timeout, retry) // 推荐只暴露必要的输入变化项放进 options request(url, data, options?: { headers?: Recordstring, string timeout?: number retry?: number })这样设计的目的不是让代码更“优雅”而是减少未来变更的破坏面。如果未来要支持signal中断请求你可以在options里新增一个可选字段调用方不传不会受到影响。相比新增一个位置参数这种变更的兼容性范围要大得多。接口稳定还有一个反向要求不要让调用方依赖你的内部实现细节。如果某个公共函数返回一个对象调用方开始直接读取对象的私有字段、深层结构那么之后你想调整内部逻辑就会非常痛苦。常见做法是返回结构尽量简单必要时提供稳定的访问方法减少外部对内部结构的直接依赖。3.2 语义化版本不是仪式在处理共用代码时版本号常常被当成一个流程负担。其实语义化版本是唯一能在“不打扰所有调用方”的前提下传递“这次改动会不会影响我”的通信机制。当一个公共包处于 1.0 之后的稳定阶段修复 bug、不改变对外行为发 patch 版本新增功能、保持向后兼容发 minor 版本破坏兼容性、改变现有行为发 major 版本。很多团队在实践时会把“破坏性变更”藏进 minor 版本里理由是“反正调用方都会升级”。这个理由在内部包场景里特别有迷惑性因为大家是同事不会有人严格按照版本约束。但这样做的代价是公共模块的信任体系崩溃。之后升级的人越来越少最后整个包被锁定在某个旧版本新的修复无法覆盖到所有调用方。更稳妥的做法是破坏性变更一定要发 major 版本并且在发布前写清CHANGELOG列出“影响、迁移方式、建议升级时间”。如果团队内部有公告渠道再发一条简短的同步不要只改代码。3.3 变更流程从“我改了”到“大家接受”公共模块的变更管理本质是“协作工程”不是纯粹的技术工程。修改一行代码之前先回答三个问题谁是当前使用方的负责人改动对他们意味着什么他们有没有时间在当前迭代内验证兼容性即使在一个很小的团队里也建议至少有一套轻量流程维护者在公共模块的CHANGELOG.md里更新变更说明PR 里明确列出“影响范围”和“自测结果”如果改动涉及默认行为最好提前在项目群里给一个“兼容性提示”完全移除某个废弃接口前给一个弃用周期。这套流程看起来麻烦但它能救回大量返工时间。一个常见的失败模式是有人修了一个公共函数的问题自测通过了但没想“还有哪个调用方依赖旧行为”。等上线后被其他系统发现双方争论一阵最后可能不得不回滚。这个来回消耗的时间往往远超当初写文档、发通知的时间。变更管理的核心不是“多开会”而是让每次修改都有清晰的“影响面”记录。哪怕只是在 PR 描述里写一句“已验证影响的系统A、B未验证C”都比沉默上线好得多。4. 共用代码治理先盘点再收敛最后退出4.1 三步框架盘点、收敛、消亡当公共模块多起来以后团队经常陷入两种极端要么把所有公共函数当成“历史遗留”放着不动要么找个时间大扫除把看起来没用的模块全删掉。两种都不太健康。与其凭感觉清理不如按三步走。第一步盘点。列出仓库或项目范围内所有公共模块/公共函数记录它们的位置、引用方数量、最近一次修改时间、是否有测试、是否有负责人。不需要做得很复杂一张表格就能开始。重点不是统计得有多全而是要把“未知影响”变成“已知影响”。第二步收敛。对相似功能的公共代码做归并。常见的情况是一个项目里有多个日期格式化函数分布在utils/time.ts、helpers/format.ts、common/date.ts中名字不同、行为相似。这类函数建议按业务域收敛到同一个模块并对外提供统一入口。收敛之后调用方不需要猜测“应该引哪个”新代码被错误复用的概率也会下降。第三步消亡。对已经确定无人使用、或已经被业务方绕开的公共模块要给一个退出路径。删除本身不是目的目的是减少维护者被噪音干扰。真正要谨慎的是不要因为“还有一两个调用方”就永远留着旧模块也不要因为“感觉没用”就直接删。正确的做法是先通过依赖分析或全局搜索确认没有引用再在版本里标记 deprecated给一段缓冲期最终移除。4.2 什么代码才值得抽出来共用判断是否要抽公共代码常见的说法是“出现三次以上再抽”。这个经验有一定道理但更关键的限制是你抽出来之后有没有能力持续维护它。如果没有哪怕重复出现了十次也未必值得抽。因为把十处复制粘贴换成一个公共模块只是把“看得见的重复”变成了“需要协作才能维护的依赖”。用三个条件来判断业务逻辑确实相同而不是仅仅“看起来相似”。有些代码因为用了同样的字段名显得相同但背后的业务语义完全不同强行合并会产生“假设统一”的风险。未来有明确的演化需求。如果两段代码目前相同但接下来半年各自的需求方向完全不同那么抽象公共代码反而会拖累两边。团队能指定一个维护人至少是兼职。公共模块不能“人人可改”至少要有人负责审查合并请求、回应 issue、决定版本迭代。满足这三个条件再考虑抽取。如果只是应付当前的一次需求直接在业务代码里写清楚不要急着抽。4.3 什么时候应该从公共代码中“拆出去”很多人只关心“怎么抽”很少想“怎么拆”。如果一个公共模块为了满足不同调用方已经叠加了大量if分支和配置项说明它已经从“公共资产”变成了“公共负债”。最务实的做法是把其中一小部分确实不同的逻辑拆回业务侧让公共模块只保留稳定的核心能力。举个例子一个公共组件为了兼容不同项目的 UI 风格内部积累了十多个开关主题配置从一个对象变成了一个类似配置语言的写法。这时候其实可以考虑让组件只提供基础布局和事件逻辑具体视觉表现通过 slot 或 render prop 交给调用方。这样公共部分变薄了变化的部分回归到业务侧反而更容易维护。拆开之后并不是失败。公共代码的价值不在于“什么都要共用”而在于把可以共用的部分做好把不能共用的部分尽早放开。一个健康的公共模块边界是清晰的它知道哪些能力是自己的哪些能力应该交给调用方。5. 真正落地时容易被低估的工程细节与排查链路5.1 调用方视角好公共代码应该让人“不看源码也能用对”写公共代码的人常犯一个低调的错误只关注自己的代码逻辑但没考虑使用者的体验。一个公共函数如果要在调用方那里正确使用需要满足几个基本条件函数/组件命名要能看出意图不要用过于泛化的单词。参数要有明确的类型定义。TypeScript 项目里给公共模块写类型不算额外负担它比任何文档都更直接。一个可直接运行的示例比一大段解释更有用。如果有不常用的配置项保持默认值合理避免让调用方做太多决策。比如一个下载文件的公共函数文档里如果只写“使用该方法可以下载文件”但没有说明它会如何感知文件名、是否自动处理鉴权、失败时抛什么异常调用方测试时就会靠猜。更合适的做法是给出一个“最小可用示例”和“常见异常说明”。这不是文案工作而是公共模块工程质量的一部分。5.2 维护方视角测试、日志、升级就绪度公共模块的维护者往往需要做“没有掌声”的事。写测试就是其中之一。一个公共函数如果调用方有 8 个系统每一次修改都应该跑过至少一份覆盖关键路径的测试。这不只是验证自己没改错更是给未来的维护者留一条安全绳。在发布前更建议准备一份“升级就绪度”清单是否更新了版本号是否更新了CHANGELOG是否在测试仓库或某个试点项目里验证过兼容性是否同步了类型定义或文档是否通知了主要调用方有些团队会做一次冒烟发布即先发布一个beta或next版本让少数调用方验证没问题后再正式发布。这个过程不复杂但它可以把“上线后才发现问题”的负反馈提前变成“发布前就发现”的正反馈。内部包尤其需要这种节奏因为内部包往往没有外部用户给你兜底。5.3 共用代码出问题时的排查顺序当线上出现一个疑似与公共模块相关的问题时很多人第一反应是“一定是公共模块最新版改坏了”。这个判断不一定错但直接下结论容易漏掉真正原因。按下面的顺序排查会更稳先看现象报错、白屏、数据异常、还是行为差异确定是否是公共模块范围内的输入输出问题。再看调用方版本通过锁文件package-lock.json / yarn.lock / pnpm-lock.yaml 等确认实际使用的公共模块版本不要凭 package.json 里的^1.2.3推断。再看变更记录对比版本之间的CHANGELOG找出可能与现象相关的改动。再看输入调用方传入的数据、上下文、权限、配置是否在更新后发生了变化。有时不是公共模块的问题而是调用方的数据不符合新逻辑的假设。再看环境不同 Node 版本、浏览器、操作系统、依赖组合都有可能放大公共模块的行为差异。最后做对照实验可以用上一个版本的锁文件回滚确认问题是否随之消失。如果回滚后仍然存在说明大概率不是公共模块版本导致的。这个链路看起来长但能避免很多“甩锅-争吵-回滚”的循环。关键是第一步不要先假设根因而是先确认事实。5.4 适合与不适合用共用代码的场景最后再回到全局用一张表总结共用代码的适用边界场景适合共用代码不适合共用代码三个以上系统需要相同的基础工具函数适合抽成独立包提供版本和测试不适合如果差异大于共同点两个业务团队共用一套复杂组件适合但要指定维护人不适合如果双方节奏和 UI 风格差距很大临时需求、一周内完成的小功能不适合抽公共代码反而拖慢进度适合直接用业务内函数团队处于快速原型验证阶段不适合过早抽象会增加认知负担适合先跑通再重构已经有重复代码但没人维护公共模块可以先盘点不要突然抽取适合但要先解决所有权问题这张表的核心判断依据不是代码技术而是“组织是否准备好承担后续的协作成本”。如果回答不了“谁来管”共用代码带来的长期成本很可能高于它的收益。所以再遇到共用代码不用急着开心也不要急着害怕。可以先问自己三个问题这个模块有明确负责人吗你能说清它的完整影响范围吗每次变更有没有至少一条测试或一份变更记录兜底如果答案模糊就别急着扩张它的边界。共用代码处理那点事说到底是一件把“方便”变成“秩序”的事。一个团队能安全地维护多少公共模块取决于他们愿意为秩序付出多少日常成本而不取决于一开始抽代码时省下的那几分钟。
共用代码治理：公共模块的版本管理与接口设计
每次聊到“共用代码”很多开发者的第一反应是“赶紧抽出来”。业务代码里反复出现几段相同的日期格式化、请求封装、列表分页逻辑时很难忍住不把它们整理成一个公共模块。开始几天确实很爽新增代码行数变少结构看起来也更清爽。但问题往往在几周之后浮出水面——你改了一个公共函数的默认行为结果三个线上系统一起变了你加了一个新参数却发现一部分调用方没有传直接落到旧逻辑。到了这一步多数人的第一反应是“公共代码害人不浅”。可真正的问题不是共用代码本身而是我们把共用代码当成了一个没有边界的公共杂物间。这篇文章想聊的是共用代码处理那点事本质上不是“怎么写”的问题而是“怎么管”的问题。1. 共用代码的真正成本不是抽取时而是后续每一次改动1.1 一改全改的连锁反应一个很常见的场景是两个业务系统都用到了同一个时间处理工具函数。起初它们的用法一致公共函数稳定运行了两个月。后来业务 A 提了一个需求要按某一种地区格式展示时间于是有人给公共函数加了一个region参数默认值为空。因为没有传region时走老逻辑业务 A 通知业务 B“不传就不影响”于是上线了。又过了一个月业务 C 也开始用这个函数但测试环境里没人看过默认格式问题直到线上灰度才暴露。类似故事每天都在不同团队发生。共用代码的麻烦在于写代码的人很难感知到“使用者”的范围。你面对的从语言层面看只是一个函数但在系统层面它可能连接着十几个入口。很多人觉得“复制粘贴”不好于是抽公共代码。但有一个反直觉的点需要记住复制粘贴虽然难看但它天然隔离了风险抽公共代码之后改动的影响范围会立刻被放大。这里并不是说应该回到复制粘贴而是说一旦选择共用代码就必须接受一个前提——它不再是“我自己的一段代码”而是“多方共享的契约”。契约一旦修改未通知到的调用方就会把风险带进生产环境。1.2 新生期、膨胀期、腐朽期公共模块的三个生命阶段我见过很多公共模块生命周期大致都经过三个阶段。新生期需求重叠度高抽象自然成立改一次往往能同时解决几个团队的痛点。这个阶段的公共代码是真正有价值的因为它把重复流程固化了下来提高了整体效率。膨胀期随着使用者变多每个团队开始带着自己的特殊诉求进来。有人要求增加配置项有人要求兼容旧数据有人希望不要影响自己的样式。最典型的信号是公共函数签名里的参数越来越多函数体里到处是if (options.xxx)分支。代码还没坏但每次改动都需要拉上一堆人确认。腐朽期公共模块内部逻辑已经复杂到没人敢动但业务方又被要求“尽量复用”结果大家开始绕开它在有公共模块的情况下另写了一份本地实现。这时仓库里会出现“假装在用公共代码”的现象模块还在引用还在但真正的业务逻辑已经各自为政。更麻烦的是没人敢删除旧模块。识别自己处于哪个阶段其实不需要复杂工具。看几个信号就够了是否有明确负责人、变更是否有测试保护、调用方是否清楚自己依赖什么版本、出现问题时多久能定位影响面。1.3 健康公共模块的几个简单信号可以用下面这个表格做一个快速体检维度健康信号危险信号负责人有明确的维护人或者小组属于“大家都能改但没人负责”使用范围调用方数量可列出来发布时可验证只记得被用了但没人说清哪些系统在用接口变更破坏性变更升主版本提前通知直接在公共函数上加参数、改默认值测试公共模块自带单元测试和关键场景回归靠调用方测试顺便覆盖文档有使用示例和变更记录只有源码注释甚至注释也过期这些信号不需要一次全部满足但至少要有两三项过关。如果一项都没有那么这个“共用代码”本质上是一个待爆的雷。注意健康的共用代码不是“永远不变”而是“每次变化都可追踪、可验证、可回退”。2. 抽共用代码的四个层级选错层级比不抽更危险2.1 第一次粘贴不算“共用”首先得厘清一个常见误区。很多人把“在不同仓库里复制同一段代码”也称为共用代码。严格来说这不是共用代码而是“共用了一次代码”。复制行为发生后的下一秒这两份代码就失去了共同演进的基础。后续任何一方的修复、优化、安全更新都不会自动同步到另一边。这种模式在短期应急时可以理解但它不应该被当成一种复用方案。如果团队已经处在这个状态第一步不是去建仓库、发包而是先统计这些重复代码出现在哪些位置评估它们之间的差异再决定是统一还是保留分叉。强行合并并不一定最优尤其当两份代码已经各自演化出不同行为时合并成本往往大于继续维护重复代码的成本。2.2 仓库内的公共目录适合小团队但门槛最低最常见的复用层级是仓库内的src/common、src/components、src/utils这类目录。好处是调用成本极低不需要发版本改完立刻生效非常适合单个仓库、小团队、业务耦合较高的场景。但它的弱点也很明显因为没有版本边界任何一次提交都相当于一次“隐式发布”你改了utils/time.js全仓库所有引用方立刻感受到变化。在单仓库模式下这种隐式发布可以通过代码评审和测试来缓解但前提是团队规模足够小、上下文足够一致。一旦仓库膨胀到几十个模块、上百个开发者公共目录就会慢慢变成“谁都不敢动的雷区”。这个时候很多人开始考虑把公共代码拆成独立包。2.3 独立成包工程化复用的起点把公共代码拆成独立工程再通过包管理器分发是目前最成熟的复用方式。前端会用 npm package后端可能是内部 Maven/Gradle 依赖或者一套自建私仓。独立成包的最大价值不是“代码更干净”而是引入了版本概念调用方可以锁定版本公共模块的维护者可以在发布新版本时保留兼容区间业务方再也不会因为别人git pull而被悄悄改掉行为。这一步看起来只是工程结构调整实际上设置了好几道隐性约束要有发布流程、变更记录、版本号、测试、包的访问权限管理。很多团队卡在这里不是不会写代码而是不愿意承担“维护一个包”的持续成本。如果你要抽的公共逻辑一年都改不了几次独立发包反而会增加负担。所以独立成包的判断不是“这段代码有多少处重复”而是“这个模块未来一年有没有独立的迭代节奏”。通常我会建议先给公共模块写一份README把使用方式、参数说明、变更记录写清楚。如果连这份文档都不愿意维护说明团队还没准备好独立发包。2.4 跨团队公共平台 / 微前端不是必须再往上一层是把公共代码升级成跨团队的基础设施比如统一组件库、公共业务中台、微前端容器。这个层级已经不是“抽代码”的问题而是“组织分工”的问题。它需要跨团队治理机制、清晰的 API 契约、稳定的发布节奏以及愿意为长期维护投入人力的经营团队。现实中很多失败案例不是技术选型错误而是组织上没有给公共模块“编制”业务团队各自有 KPI却要求他们合力维护一个公共平台最后通常变成“谁用谁改、谁改谁炸”。我的建议是不要因为看到大厂有统一组件库就觉得所有团队都必须上。小规模团队用仓库内公共目录中等规模用私有包大规模才需要认真规划公共平台。层级不是越高越好而是要匹配团队的协作半径。层级典型形式优点风险适合规模复制粘贴各仓库各放一份隔离风险实现最快修复不同步、差异蔓延紧急复制公共目录src/common、src/utils调用成本低、改完即生效无版本边界、隐式发布小团队单仓库独立包npm 包 / 内部构件库有版本、可升级、影响面可控需要发布和维护流程多仓库、多项目公共平台 / 微前端统一组件库、中台服务跨团队复用效率最高治理成本高、需要长期投入大型组织这个表格不是标准答案但可以帮助团队快速对齐认知你要解决的是“改起来太慢”还是“用起来太乱”还是“没人负责”的问题。不同问题对应的层级完全不同。3. 决定共用代码命运的是接口设计与变更管理3.1 先给调用方一个稳定的“契约”很多人抽公共代码时习惯把内部实现细节直接暴露给调用方。比如一个公共请求函数刚开始只有一个url参数后来有人需要自定义 header就再加一个header参数有人需要超时时间再加timeout有人需要重试于是再加retry。函数签名越来越长文档越来越难写调用方越来越困惑。更合理的做法是在接口设计阶段就把“容易变化的部分”收敛到一个配置对象里// 不推荐参数不断膨胀 request(url, data, header, timeout, retry) // 推荐只暴露必要的输入变化项放进 options request(url, data, options?: { headers?: Recordstring, string timeout?: number retry?: number })这样设计的目的不是让代码更“优雅”而是减少未来变更的破坏面。如果未来要支持signal中断请求你可以在options里新增一个可选字段调用方不传不会受到影响。相比新增一个位置参数这种变更的兼容性范围要大得多。接口稳定还有一个反向要求不要让调用方依赖你的内部实现细节。如果某个公共函数返回一个对象调用方开始直接读取对象的私有字段、深层结构那么之后你想调整内部逻辑就会非常痛苦。常见做法是返回结构尽量简单必要时提供稳定的访问方法减少外部对内部结构的直接依赖。3.2 语义化版本不是仪式在处理共用代码时版本号常常被当成一个流程负担。其实语义化版本是唯一能在“不打扰所有调用方”的前提下传递“这次改动会不会影响我”的通信机制。当一个公共包处于 1.0 之后的稳定阶段修复 bug、不改变对外行为发 patch 版本新增功能、保持向后兼容发 minor 版本破坏兼容性、改变现有行为发 major 版本。很多团队在实践时会把“破坏性变更”藏进 minor 版本里理由是“反正调用方都会升级”。这个理由在内部包场景里特别有迷惑性因为大家是同事不会有人严格按照版本约束。但这样做的代价是公共模块的信任体系崩溃。之后升级的人越来越少最后整个包被锁定在某个旧版本新的修复无法覆盖到所有调用方。更稳妥的做法是破坏性变更一定要发 major 版本并且在发布前写清CHANGELOG列出“影响、迁移方式、建议升级时间”。如果团队内部有公告渠道再发一条简短的同步不要只改代码。3.3 变更流程从“我改了”到“大家接受”公共模块的变更管理本质是“协作工程”不是纯粹的技术工程。修改一行代码之前先回答三个问题谁是当前使用方的负责人改动对他们意味着什么他们有没有时间在当前迭代内验证兼容性即使在一个很小的团队里也建议至少有一套轻量流程维护者在公共模块的CHANGELOG.md里更新变更说明PR 里明确列出“影响范围”和“自测结果”如果改动涉及默认行为最好提前在项目群里给一个“兼容性提示”完全移除某个废弃接口前给一个弃用周期。这套流程看起来麻烦但它能救回大量返工时间。一个常见的失败模式是有人修了一个公共函数的问题自测通过了但没想“还有哪个调用方依赖旧行为”。等上线后被其他系统发现双方争论一阵最后可能不得不回滚。这个来回消耗的时间往往远超当初写文档、发通知的时间。变更管理的核心不是“多开会”而是让每次修改都有清晰的“影响面”记录。哪怕只是在 PR 描述里写一句“已验证影响的系统A、B未验证C”都比沉默上线好得多。4. 共用代码治理先盘点再收敛最后退出4.1 三步框架盘点、收敛、消亡当公共模块多起来以后团队经常陷入两种极端要么把所有公共函数当成“历史遗留”放着不动要么找个时间大扫除把看起来没用的模块全删掉。两种都不太健康。与其凭感觉清理不如按三步走。第一步盘点。列出仓库或项目范围内所有公共模块/公共函数记录它们的位置、引用方数量、最近一次修改时间、是否有测试、是否有负责人。不需要做得很复杂一张表格就能开始。重点不是统计得有多全而是要把“未知影响”变成“已知影响”。第二步收敛。对相似功能的公共代码做归并。常见的情况是一个项目里有多个日期格式化函数分布在utils/time.ts、helpers/format.ts、common/date.ts中名字不同、行为相似。这类函数建议按业务域收敛到同一个模块并对外提供统一入口。收敛之后调用方不需要猜测“应该引哪个”新代码被错误复用的概率也会下降。第三步消亡。对已经确定无人使用、或已经被业务方绕开的公共模块要给一个退出路径。删除本身不是目的目的是减少维护者被噪音干扰。真正要谨慎的是不要因为“还有一两个调用方”就永远留着旧模块也不要因为“感觉没用”就直接删。正确的做法是先通过依赖分析或全局搜索确认没有引用再在版本里标记 deprecated给一段缓冲期最终移除。4.2 什么代码才值得抽出来共用判断是否要抽公共代码常见的说法是“出现三次以上再抽”。这个经验有一定道理但更关键的限制是你抽出来之后有没有能力持续维护它。如果没有哪怕重复出现了十次也未必值得抽。因为把十处复制粘贴换成一个公共模块只是把“看得见的重复”变成了“需要协作才能维护的依赖”。用三个条件来判断业务逻辑确实相同而不是仅仅“看起来相似”。有些代码因为用了同样的字段名显得相同但背后的业务语义完全不同强行合并会产生“假设统一”的风险。未来有明确的演化需求。如果两段代码目前相同但接下来半年各自的需求方向完全不同那么抽象公共代码反而会拖累两边。团队能指定一个维护人至少是兼职。公共模块不能“人人可改”至少要有人负责审查合并请求、回应 issue、决定版本迭代。满足这三个条件再考虑抽取。如果只是应付当前的一次需求直接在业务代码里写清楚不要急着抽。4.3 什么时候应该从公共代码中“拆出去”很多人只关心“怎么抽”很少想“怎么拆”。如果一个公共模块为了满足不同调用方已经叠加了大量if分支和配置项说明它已经从“公共资产”变成了“公共负债”。最务实的做法是把其中一小部分确实不同的逻辑拆回业务侧让公共模块只保留稳定的核心能力。举个例子一个公共组件为了兼容不同项目的 UI 风格内部积累了十多个开关主题配置从一个对象变成了一个类似配置语言的写法。这时候其实可以考虑让组件只提供基础布局和事件逻辑具体视觉表现通过 slot 或 render prop 交给调用方。这样公共部分变薄了变化的部分回归到业务侧反而更容易维护。拆开之后并不是失败。公共代码的价值不在于“什么都要共用”而在于把可以共用的部分做好把不能共用的部分尽早放开。一个健康的公共模块边界是清晰的它知道哪些能力是自己的哪些能力应该交给调用方。5. 真正落地时容易被低估的工程细节与排查链路5.1 调用方视角好公共代码应该让人“不看源码也能用对”写公共代码的人常犯一个低调的错误只关注自己的代码逻辑但没考虑使用者的体验。一个公共函数如果要在调用方那里正确使用需要满足几个基本条件函数/组件命名要能看出意图不要用过于泛化的单词。参数要有明确的类型定义。TypeScript 项目里给公共模块写类型不算额外负担它比任何文档都更直接。一个可直接运行的示例比一大段解释更有用。如果有不常用的配置项保持默认值合理避免让调用方做太多决策。比如一个下载文件的公共函数文档里如果只写“使用该方法可以下载文件”但没有说明它会如何感知文件名、是否自动处理鉴权、失败时抛什么异常调用方测试时就会靠猜。更合适的做法是给出一个“最小可用示例”和“常见异常说明”。这不是文案工作而是公共模块工程质量的一部分。5.2 维护方视角测试、日志、升级就绪度公共模块的维护者往往需要做“没有掌声”的事。写测试就是其中之一。一个公共函数如果调用方有 8 个系统每一次修改都应该跑过至少一份覆盖关键路径的测试。这不只是验证自己没改错更是给未来的维护者留一条安全绳。在发布前更建议准备一份“升级就绪度”清单是否更新了版本号是否更新了CHANGELOG是否在测试仓库或某个试点项目里验证过兼容性是否同步了类型定义或文档是否通知了主要调用方有些团队会做一次冒烟发布即先发布一个beta或next版本让少数调用方验证没问题后再正式发布。这个过程不复杂但它可以把“上线后才发现问题”的负反馈提前变成“发布前就发现”的正反馈。内部包尤其需要这种节奏因为内部包往往没有外部用户给你兜底。5.3 共用代码出问题时的排查顺序当线上出现一个疑似与公共模块相关的问题时很多人第一反应是“一定是公共模块最新版改坏了”。这个判断不一定错但直接下结论容易漏掉真正原因。按下面的顺序排查会更稳先看现象报错、白屏、数据异常、还是行为差异确定是否是公共模块范围内的输入输出问题。再看调用方版本通过锁文件package-lock.json / yarn.lock / pnpm-lock.yaml 等确认实际使用的公共模块版本不要凭 package.json 里的^1.2.3推断。再看变更记录对比版本之间的CHANGELOG找出可能与现象相关的改动。再看输入调用方传入的数据、上下文、权限、配置是否在更新后发生了变化。有时不是公共模块的问题而是调用方的数据不符合新逻辑的假设。再看环境不同 Node 版本、浏览器、操作系统、依赖组合都有可能放大公共模块的行为差异。最后做对照实验可以用上一个版本的锁文件回滚确认问题是否随之消失。如果回滚后仍然存在说明大概率不是公共模块版本导致的。这个链路看起来长但能避免很多“甩锅-争吵-回滚”的循环。关键是第一步不要先假设根因而是先确认事实。5.4 适合与不适合用共用代码的场景最后再回到全局用一张表总结共用代码的适用边界场景适合共用代码不适合共用代码三个以上系统需要相同的基础工具函数适合抽成独立包提供版本和测试不适合如果差异大于共同点两个业务团队共用一套复杂组件适合但要指定维护人不适合如果双方节奏和 UI 风格差距很大临时需求、一周内完成的小功能不适合抽公共代码反而拖慢进度适合直接用业务内函数团队处于快速原型验证阶段不适合过早抽象会增加认知负担适合先跑通再重构已经有重复代码但没人维护公共模块可以先盘点不要突然抽取适合但要先解决所有权问题这张表的核心判断依据不是代码技术而是“组织是否准备好承担后续的协作成本”。如果回答不了“谁来管”共用代码带来的长期成本很可能高于它的收益。所以再遇到共用代码不用急着开心也不要急着害怕。可以先问自己三个问题这个模块有明确负责人吗你能说清它的完整影响范围吗每次变更有没有至少一条测试或一份变更记录兜底如果答案模糊就别急着扩张它的边界。共用代码处理那点事说到底是一件把“方便”变成“秩序”的事。一个团队能安全地维护多少公共模块取决于他们愿意为秩序付出多少日常成本而不取决于一开始抽代码时省下的那几分钟。