开源通用组件如何沉淀？

本文目录导读：

1. 第一阶段：识别与发现（不要为了“沉淀”而“沉淀”）
2. 第二阶段：抽象与剥离（从“能用”到“可复用”）
3. 第三阶段：工程化与规范（从“散养”到“标准化”）
4. 第四阶段：推广与反馈（让更多人“用”）
5. 第五阶段：治理与共生（从“开源”到“生态”）
6. 一个反直觉的真相

这是一个非常具有工程价值的问题,很多团队在早期都热衷于造轮子（因为业务快速迭代），但到了后期却发现组件库混乱、维护成本高、复用性差。

“沉淀”开源通用组件，本质上是一个 从“项目私有”到“通用抽象”，再到“社区共治” 的演进过程，以下是一套经过验证的、可落地的沉淀路线和方法论：

第一阶段：识别与发现（不要为了“沉淀”而“沉淀”）

核心理念： 通用组件不是“规划”出来的，而是“长”出来的，至少被3个不同的业务场景（或页面）重复使用，才值得沉淀。

需要识别什么样的组件值得沉淀：

1. 业务无关性： 组件内部不包含具体业务逻辑（如“去结算”按钮、“用户头像”），如有业务逻辑，必须通过 Props 或 Slot 注入。
2. 高复用性： 常见的弹窗、表单、表格、选择器、图表容器、布局组件等。
3. 独立性： 组件不依赖特定后端接口返回的字段名（如 userName 而非 name）。

具体动作：

• 建立 重复代码监控机制（如 CodeQL 或简单的 grep 脚本）。
• 在 Code Review 中，设立一条红线：“同一段逻辑或UI出现2次，可以容忍；出现3次，必须提取”。

第二阶段：抽象与剥离（从“能用”到“可复用”）

这一阶段是将组件从具体业务项目中“抽骨头”，这是最难也最关键的一步。

核心原则：

1. 单一职责（SRP）： 一个组件只做一件事，如果一个组件既要做筛选又要做数据导出，拆开。
2. 控制反转（IoC）： 组件只负责 UI 渲染和状态管理，具体行为（点击后干嘛、请求哪个API）由父组件通过事件或回调注入。
3. 配置化驱动： 通过 Props（配置对象）而非硬编码来驱动组件表现。
   • 不好的：<Table columns="name,age,email" />
   • 好的：<Table :columns=[{key:'name', title:'姓名', width:100}, ...] />

具体动作：

• 语义化 API 设计： Props 命名要清晰（visible vs show，建议统一成 visible）。
• 状态映射： 组件内部只维护 UI 状态（loading, empty, error, success），数据获取、格式化交给外部。
• 写出测试用例： 这是倒逼组件解耦的最佳手段，Mock 数据很困难，说明组件耦合了过多外部依赖。

第三阶段：工程化与规范（从“散养”到“标准化”）

当组件被提取出来后,需要一套工具和规范来管理它们，使其达到“开源”标准（即便只在公司内部开源）。

1. 独立仓库 + Monorepo：

   • 使用 pnpm workspace 或 TurboRepo 创建独立仓库。
   • 每个组件一个子包,有独立的 package.json、README、CHANGELOG。

2. 多包管理（Monorepo）标准结构：

   packages/
     components/  (核心组件包)
     hooks/       (与组件配套的逻辑钩子)
     utils/       (工具函数)
     theme/       (主题变量)

3. 文档与演示（几乎等同于代码质量）：

   • 必选： 使用 Storybook 或 Histoire 搭建交互式文档。
   • 每个组件必须有：使用场景介绍、API 文档、Props 表格、Event 表格、至少3个不同状态的 Demo（正常、加载、空状态、错误）。
   • 记录 设计决策（为什么这样设计 API？为什么没有用某个其他方案？）。

4. 版本号规范（SemVer）：

   • 遵循 major.minor.patch。
   • 不兼容的 API 改动（Breaking Change）必须发大版本。
   • Breaking Change 一定要在 CHANGELOG.md 中用 ### BREAKING CHANGES 醒目标记。

第四阶段：推广与反馈（让更多人“用”）

如果没人用,组件就沉淀不了。

1. 降低接入成本（0配置）：

   • 提供 CDN 引入方式 + <script>
   • 提供 ES Module 和 CommonJS 两种打包产物。
   • 必须导出 TypeScript 类型定义（.d.ts）。

2. 内部推广策略：

   • 提供即开即用的脚手架工具（如 npm create my-company-ui）。
   • 在官方文档中,直接嵌入“复制代码”按钮。
   • 创建 组件需求池（类似 GitHub Issues）：开发者可以提需求，但必须附带业务场景描述（“我的场景是xxx，需要组件支持xxx”）。

3. 负面反馈处理机制：

   • 设立“组件急救”标签（P0 Bug 必须24小时内响应）。
   • 不要害怕“重写”或“废弃”，如果一个组件因为早期设计不合理，导致大家都在绕开它，可以考虑标记为 @deprecated 并给出迁移路径。