做组件库也好做内部业务组件沉淀也好几乎每个团队都会走到同一个分岔口组件是抽出来了别人却不愿用或者用了之后每一次升级都鸡飞狗跳。我之前就遇到过这么一个需求一个后台管理系统同一张表格要在四个不同页面复用每个页面列定义、筛选项、操作按钮都不一样。刚接手时的第一反应是给Table组件堆props把所有差异都收进组件里结果三周下来props从30多个涨到80多个改一个页面的筛选逻辑另外三个页面一起报错。那之后我才彻底想明白一个事组件复用率低表面上看着是抽象不够实际上从API设计的第一天就埋下了隐患。标题里的“高可复用”在我看来不是形容词而是工程质量指标。它决定了组件库能不能被不同团队、不同业务快速接入也决定了后续维护时版本能否平稳演进。这篇文章想把API设计的方法、版本管理策略、文档自动化的技术链路完整串一遍给的是我在实际项目里验证过、能直接落地的做法而不是停留在“设计原则”层面上的车轱辘话。1. 为什么说可复用性是API设计问题而不是代码抽取问题1.1 组件库复用的本质是“接口契约”组件库的对外输出表面上是若干.vue或.tsx文件实际上是一份契约。调用方根据这份契约决定“我该传什么”“我能拿到什么”“出问题时是谁的锅”。你内部用递归重构还是闭包缓存调用方完全不关心也不应该关心。所以“可复用”并不是把公共代码抽到一个文件夹里那样简单。真正可复用的组件库要让不熟悉内部实现的前端同学也能在十分钟内接上自己的页面要让三个不同技术栈的项目接入时得到的行为是一致的要允许组件库自己发布新版本而不破坏既有调用方的功能。我习惯把它类比成养车你不需要知道发动机里每个螺丝怎么拧你只需要知道油门刹车方向盘怎么用车就能在路上跑。组件API就是那个油门刹车方向盘——设计得好各种路况都顺手设计得烂就算发动机底子再好别人也开不惯。1.2 API设计失败的典型症状判断一个组件库是不是在API层面就已经失败了不需要做复杂度量看几个现象就行。第一种props列表长得像需求文档。props超过一屏的时候调用方根本记不住哪个参数要配哪个参数互斥最后全靠复制粘贴历史代码这是配置式API无度膨胀的典型体现。你表面上提供了“一百种灵活性”实际上把选择成本全部甩给了使用的人。第二种调用方被逼着了解内部实现。组件内部名目繁多比如innerRef、contentSlotName、renderSuffix这些名字暴露了组件结构细节。一旦未来调整内部结构API就要断调用方为了用你的组件还得先读一遍源码这就彻底违背了复用的初衷。第三种升级等于跳崖。次版本更新或补丁版本更新结果行为不一致了、样式变了、事件触发的参数变了。调用方不敢升级最后组件库版本永远停在初始版本新加的bug修复和优化全都落不了地整个库慢慢变成僵尸库。第四种业务方始终觉得还是自己写一个更快。如果接组件比重新造轮子还要耗时那组件库的存在本身就是负资产。我看到很多强制设“组件复用率”KPI的团队最后使用率依然上不去原因就在这不是大家不想用是接口契约设计得让复用成本高于重建成本。等到这四种症状已经出现再去重构组件库内部已经来不及了因为调用方的代码是跟着旧API长出来的。所以组件库的API设计实际上是在项目启动的第一天就该被严肃对待的事而不是“等组件稳定后再来补”。2. 组件API设计的核心决策从props到分层2.1 组合优于配置少一点开关多一点接管很多人在设计组件库时脑子里默认的模型是“多功能一体机”把所有业务场景需要的功能都做成可选开关往组件里塞。结果就出现了一个能同时干十件事、但每件事都干得不太顺手的超级组件。更合理的思路是“组合优于配置”。我举个常见的例子按钮组件需求里有时候要带Tooltip有时候要带Icon有时候点击后要跳转。配置式API会写成Button tooltip删除 icontrash to/xxx /props越来越多。组合式API则拆成Tooltip content删除Button icon{TrashIcon /} onClick{() router.push(/xxx)} //Tooltip。基础组件各自独立通过调用方的组合把它拼成需要的形态。组合式设计的直接好处是每个组件都特别薄单个组件几乎不需要理解别人在做什么调用方对结构有完全的控制权未来组件库升级时这个组合调用方式通常不用改。坏处是代码确实多了几行但对于“复用”这件事多写两三行组合代码远比被组件作者的臆断约束住要好。那组件就不能有开关了吗也不是。在业务级封装层比如OrderTable、UserAvatar这类面向具体业务的组件可以用少量布尔或枚举参数去收敛常见差异。因为上一层封装的职责就是“让业务代码别写那么长”。但是越往上封装就越不应该进到通用组件库里——它应该留在业务项目里或者至少与通用组件分开存放。2.2 受控/非受控与“状态所有权”设计前端表单类和交互类组件最容易出的坑是“谁持有状态”说不清。最典型的例子是下拉框组件自己管理选中值还是由调用方控制这就是React社区反复讲的受控/非受控概念Vue里头也有对应的v-model与modelValue约定。我的设计习惯是能默认自管理就默认自管理但凡是会随业务变化的交互组件都必须支持受控模式和非受控模式的自由切换。具体落地时给一套双轨props比如interface SelectProps { defaultValue?: string; // 非受控组件自己管理初始值 value?: string; // 受控调用方传入当前值 onValueChange?: (value: string) void; // 受控模式下的变更回调 }调用方不做状态管理时不用传value组件内部自己维护选中项调用方需要对选中结果做逻辑判断时就传value和onValueChange把状态所有权拿回去。这里有几个细节要注意不要同时支持onChange和onValueChange给调用方制造选择困难受控与否的判定要以value ! undefined为准不要用defaultValue是否存在去猜用户意图切回非受控模式时历史状态不应该残留。2.3 用“分层API”兼容不同水平的调用方一个组件库只面对一类调用方几乎是不可能的。新来的前端希望拿一个封装好的组件直接跑通页面资深前端希望组件足够灵活能支持极端自定义。这两类诉求往往是冲突的。我采用的解法是“分层API”。跟网络协议栈类似越底层越原始越顶层越贴近业务但每一层都允许被接管层与层不互相覆盖。第一层是headless逻辑层只提供交互逻辑或状态管理不包含任何视觉结构比如useTable、useCombobox。想完全自绘界面的调用方这一层是他们的首选。第二层是视觉组件层带默认HTML结构和基础样式比如Table、Selectprops覆盖80%的常规场景。第三层是业务编排层把某个项目里的具体规则、接口数据格式、通用筛选逻辑集合进去直接对业务页面输出这部分建议放在业务项目里顶多用插件机制挂进组件库。这样设计之后调用组件库的团队各取所需不想动脑子的直接用第二层想高度自定义的去用第一层。而且当你发现某个组件撑不住需求时你不会被迫提一个“加个开关”的需求到组件库而是可以去用更底层的API重新组装。注意分层API的前提是每一层都有自己的类型定义和文档。只给一堆函数而不说是干嘛的等于让调用方去猜分层反而会变成新的理解障碍。3. 类型定义与默认值组件库可期待性的地基3.1 从类型定义开始设计而不是先写实现我见过的多数组件库是先写组件实现、再补类型声明。更合理的顺序是反过来先在源代码里定义好完整的props和暴露类型把类型当作对外契约来评审再写渲染逻辑。因为类型声明比实现更容易评审也更能体现“这个组件将来会被怎么用”。拿一个按钮的对外类型举例export type ButtonVariant primary | secondary | ghost | danger; export interface ButtonProps extends React.ButtonHTMLAttributesHTMLButtonElement { /** 按钮视觉形态默认 primary */ variant?: ButtonVariant; /** 当传入 href 时渲染为 a 标签 */ href?: string; /** 按钮尺寸默认 md */ size?: sm | md | lg; /** 是否处于加载状态为 true 时禁用点击 */ loading?: boolean; }这一份类型定义同时承担了好几个责任给编辑器提供自动补全给文档生成器提供字段表给调用方提供审查对象。字段名、可选性、联合类型范围全都一目了然。JSDoc里的注释也要认真写因为很多文档生成器会把这段注释直接渲染成文档说明注释写得好文档质量就成功了一半。一个容易忽视的点是props的命名一致性。比如表示“变更时触发”的回调整个库要么都用onXxxChange要么都用onXxx不能按钮写onClick、下拉框写onChange、日期选择又写onDateSelected。命名不统一每次接入新组件都要去翻文档文档再全也补救不了这个摩擦。3.2 默认值放在哪里组件库的默认值策略要同时满足两个矛盾的目标开箱即用又能在需要时精确覆盖。开箱即用意味着按钮默认就是primary表单控件默认就是某个常规尺寸表格默认不开启分页。这些默认值最好集中在默认配置对象里不要散落在渲染层各处。散落实现的后果是调用方想统一调整默认主题或默认排序规则时只能逐个覆盖无法通过配置中心一层改掉。// 默认值集中的组件类似 Ant Design 的 ConfigProvider 精神 LibraryProvider theme{{ primaryColor: #1668dc }} defaults{{ Button: { size: sm }, Select: { clearable: true } }} App / /LibraryProvider同时要警惕“默认值折叠”。比如某个组件内部把value的默认值设成[]调用方没传值也能正常工作但当他真的传了null之后组件内部可能因为空数组判断失效而崩掉因为[]和null在两个分支里的行为不一致。设计默认值的时候要把undefined和null单独区分开考虑这两个往往是调用方最容易踩的隐藏地雷。3.3 多态与as prop的取舍多态组件是很多组件库都会做的能力一个按钮既可以渲染成button也可以由调用方通过as让它渲染成a、RouterLink或div。它确实很灵活但也会给类型推导带来很大的复杂度。如果组件库以React为主我建议这样设计type ButtonPropsT extends React.ElementType button { as?: T; } OmitReact.ComponentPropsWithoutRefT, keyof CommonProps;不展开整段类型体操核心意图是当调用方传入asa时组件的类型提示能自动变成a标签支持的属性集合当as{RouterLink}时能识别RouterLink特有的to属性。这个能力一旦做出来调用体验会有明显提升。但所有组件都做多态并不是好主意。多态适合“结构单一、语义会变”的组件比如按钮、标签、标题不适合内部结构复杂的组件比如表格、日期选择器、树控件。复杂组件强行多态最后只能得到一堆难以理解的Omit和Extract类型徒增维护成本。设计时宁可先不支持也别为了炫技把类型面搞复杂。4. 版本演进中的API治理4.1 语义化版本不是发版口号组件库的版本号对调用方而言就是“这次升级我到底怕不怕”的信号源。语义化版本的基本盘是主版本号用于不兼容的API变更次版本号用于向后兼容的功能新增补丁号用于向后兼容的缺陷修复。组件库发版时最大的问题是“顺手塞私货”。明明是个patch修复样式顺手把某个event回调的触发时机改了这个改动没走主版本变更却直接破坏了线上调用方。所以组件库发版要加一道闸门凡是可能改变组件行为的修改即使在作者看来是“bug修复”也要审视有没有人可能依赖现有行为。一个老练的办法是用changesets之类的工具管理变更集发版时自动生成CHANGELOG并在变更区块里标明影响等级--- xx/design-system: minor --- 新增组件 DateRangePicker新增 Table 的 rowSelection 属性这套机制做得足够细之后“升级恐惧症”会明显缓解因为调用方可以精确知道某个行为变化落在哪个版本可以在自己项目里写升级测试用例来提前发现问题。4.2 弃用策略与平滑迁移API不会永远不变但删除API前的过渡期要比你想象的长。业内比较稳妥的做法是“三阶段弃用”。第一阶段新增替代API旧API继续正常工作但在JSDoc里标记deprecated同时在开发环境下通过console.warn提示调用方应该迁移。注意这个告警要带组件名和属性名方便检索。第二阶段经过一个主版本周期的缓冲旧API仍可使用但默认行为可能已经切到新API语义上告警频率提高文档里同步把旧API的示例全部替换成新API。第三阶段在下一个大版本里移除旧API。移除之前用codemod和搜索工具把内部仓库里的全部调用点迁移完防止老用户被迫停止升级。以按钮为例旧写法是Button isPrimary icondownload onSearch{handleSearch} /新写法可能是Button variantprimary icon{DownloadIcon /} onSearchChange{handleSearch} /旧API在不移除的前提下可以在内部做一层映射// 兼容层仅供旧调用方过渡 Button {...proxyRemovedProps(props)} /但兼容层不能长期存在否则它会让新老API长期共存代码阅读成本急剧上升最后谁都说不清组件到底支持哪些写法。4.3 用Codemod接管升级成本API迁移对调用方团队来说最怕的不是写代码而是“不知道哪里要改”。大型代码库里调用点可能有几十上百处靠自己搜索替换很容易漏而且替换时判断上下文也很麻烦。Codemod是解决这个问题的有效工具它本质上是用jscodeshift分析AST把旧API模式自动改写成新API模式。举一个简单脚本的思路遍历所有JSX/TSX节点找到Button元素把isPrimary属性替换成variantprimary如果同时存在isSecondary则改成variantsecondary两者同时出现就报错提示人工处理。这种脚本写起来不复杂但能把迁移成本从“一个迭代专门做”降到“半天顺手做完”调用方对升级的抵抗心理也会小很多。没有codemod能力的组件库至少要提供一份带grep命令的迁移指南让调用方能快速定位所有旧API调用点。把“升级成本”算进组件库的维护成本里而不是丢给下游团队这是很多内部组件库容易忽视的隐性责任。5. 文档自动化让文档成为组件的活体测试5.1 手动写文档为什么必然腐烂“文档和代码不一致”几乎是所有组件库的通病。原因很简单手动写文档等于维护两份信息而人的注意力天然偏向代码。组件改了props忘了同步文档三次下来文档就开始失真失真之后大家不再信任文档开始直接读源码文档就彻底死了。所以我在组件库里坚持一个原则文档不是单独写出来的是从组件定义里自动生成出来的。API描述、props列表、默认值、弃用状态都从TypeScript类型定义和JSDoc注释里提取示例代码同时又作为测试用例被跑通。逻辑上组件代码不更新文档就不会变组件代码更新了文档生成流程必须重新跑一遍任何API变更都会反映到文档里。这样文档才不会腐烂。5.2 从TS类型自动提取props表的方案具体怎么从源码自动提取多数组件库的做法是借助文档生成器再做一层渲染封装。不同框架的提取工具不太一样框架常用方案产物Reactreact-docgen / react-docgen-typescriptJSON / MarkdownVue 3vue-docgen-api / unplugin-vue-docgenJSON / MarkdownWeb Componentscustom-elements.jsonJSON以React组件为例我采用了类似这样的构建链路组件源码里写好TypeScript类型和JSDoc通过react-docgen-typescript生成一份props的JSON数据这份JSON会挂载到组件文档页里由文档站把它渲染成带类型说明、默认值、是否必填的表格。{ Button: { variant: { type: primary | secondary | ghost | danger, required: false, defaultValue: primary, description: 按钮视觉形态 } } }这里有一个体验上的关键点不要把生成出来的原始type字符串原样丢给调用方。\primary\ | \secondary\这种带引号的字符串在页面里非常丑需要把union类型里的引号去掉变成更易读的枚举列表。很多团队生成的文档看起来“很机器”就是这一步没做精细处理。5.3 示例代码与playground的自动化文档站只放一个props表格其实只能算“半文档”。对组件使用者来说能直接上手跑的示例信息量远高于静态表格。我的做法是每个组件维护一个或多个MDX示例文件文件既是文档站的展示源码也是组件的冒烟测试。文档站直接渲染这段MDX使用者能实时看到组件长什么样同时文档站会提供一个“查看代码”的面板把示例源码展示出来。import { Button } from xx/design-system; ### 基本用法 Button variantprimary onClick{handleClick}主操作/Button ### 危险确认 Button variantdanger onClick{handleDelete}删除/Button更进一步的方案是把playground做成交互式的调用方可以在这个例子上改props看组件实时变化。对于React可以使用react-live对于Vue可以使用repl或自定义的sandbox。这个能力虽然有成本但它是调用方理解组件API成本最低的路径——不需要建一个新工程不需要装依赖页面里就能试。5.4 发行说明和变更日志联动文档自动化不只是props表格自动化还包括版本变更记录自动化。changesets会在合并代码时让开发者描述“这个改动对使用方意味着什么”发版时自动汇总成CHANGELOG。如果组件库同时维护了文档站应该把CHANGELOG按版本聚合到文档站的一个固定页面让调用方在查组件API时顺手就能看到“最近版本改了什么、我要不要跟着升级”。这里我尤其推荐把deprecated标记与变更日志联动起来。一个API被标成deprecated就在CHANGELOG里对应一条next major migration提醒移除时再对应一条breaking change说明并附上codemod的用法。整个链路跑通之后组件库的版本演进、文档、迁移三个环节就能形成一个闭环。6. 实际项目中反复踩过的坑文档、评审与复用度6.1 文档自动化的几个反模式虽然文档自动化的方向对了但落地过程中还是有几个经常踩的坑。第一个过度依赖AST解析复杂类型。组件类型一旦用了泛型推导、交叉类型、条件类型文档生成器经常解析失败或者给出残缺结果。我的处理办法是把对外暴露的props定义写得朴素一些复杂类型先在独立类型里算好再把最终类型聚合到组件props上。宁可多写几个中间类型别名也别让文档生成器去猜。第二个只做了一堆自动生成的“死文档”。props表是自动了但没有示例没有说明使用场景文档里全是“类型为string默认值为undefined”这类废话。自动化的重点是“减少人工维护”但不是“消灭人类解释”。场景、注意事项、边界行为这种需要价值判断的内容还是值得人工写的人工写好之后机械性的类型表格再交给工具去对齐。第三个示例代码从源码里重复抽取但不同步。有些组件库会把示例代码既写在源码仓库又写在文档站两处拷贝。结果改了源码忘了文档站示例又对不上了。正确做法是文档站的示例和源码仓库里的example是同一个文件文档构建时通过import或读取引用把它拉进来从源头上杜绝双份维护。6.2 团队协作API评审与契约冻结组件库API设计不是一个人拍脑袋定出来的也不该在一个大版本里反复横跳。我在实际项目里比较管用的做法是新组件或新API进入开发前先做一次API评审。评审对象不是UI效果而是组件的第一版类型定义和示例调用代码。先把伪造的调用方代码写出来看读完这段代码后能不能理解这个组件怎么用不能理解趁早改类型因为改类型成本比改实现低得多。“评审用代码表达而不是口头描述”这个规则能让会议效率提升不少。对已经发布的组件API则要维护一份契约报告。用API Extractor之类的工具生成当前对外API的报告每次合入代码时diff这份报告让“公开API变了”这件事在代码评审阶段就被暴露出来而不是等发布后用户发现。这样每个合并请求里如果改了对外API评审人一定会看到并且可以追问“这个API变更的意图是什么、有没有走弃用流程”。6.3 “高可复用”最终的判断标准讲到这里我想回到“高可复用”本身的价值标准上。我不认为“复用率高”是指组件库里组件数量多、调用次数多更合理的判断是加一个新页面时开发者的工作量有多少花在了查文档、改组件、绕开坑上升级组件库一个主版本整个部门要投入多少人天去适配。另外一个容易被忽略的信号是“修改组件库代码的频率”。一个高可复用的组件在一个迭代周期里应该是稳定的需求变化不应该反过来频繁改动组件库的源码。如果组件库的代码天天被改大概率是API设计阶段没有封住变化点或者把不该进组件库的业务逻辑放进了通用组件里。这套从API设计、类型定义、版本治理到文档自动化全链路打通的方案在我们团队已经跑了两年多。刚开始做时我把大部分精力放在组件视觉统一和代码风格上后来才意识到调用方感知到的“组件库好不好用”最后都落在了API和文档这两个接触面上。每次回顾都觉得自己最有价值的投资是把API设计和文档自动化做成了一套可持续运转的机制而不是靠个人习惯去维持的自觉。在实际维护过程中我的经验是每加入一个新的组件前先强制自己用目标调用方的视角写三份调用示例一份是最简单场景一份是需要自定义的场景一份是未来可能需要迁移的场景再从这三份示例反推props长什么样。这个步骤看起来蠢却能提前暴露掉一大半设计缺陷。等到组件库逐渐庞大又会有新的问题冒出来比如跨组件主题变量如何收敛、复杂组件的无障碍API如何设计、多框架产物如何保持行为一致这些都是值得继续往下挖的方向。如果你正在做一个内部组件库希望你从API设计这一步就是对的后面系统才能长期走稳。