Infisical 前端组件生命周期管理指南V2/V3 组件迁移状态登记表COMPONENT_LIFECYCLE解读【免费下载链接】infisicalInfisical is the open-source platform for secrets, certificates, and privileged access management.项目地址: https://gitcode.com/GitHub_Trending/in/infisical导读Infisical 前端仓库frontend/维护着两代 UI 组件库以v2/为代表的旧组件族以及以v3/为方向的下一代组件族。本篇文章围绕 frontend/src/components/COMPONENT_LIFECYCLE.md 这份「共享组件生命周期登记表Shared component lifecycle ledger」完整梳理 V2 组件的五类生命周期状态Deprecated、Ready for focused deprecation、Blocked、Retained、Removal candidate与对应的迁移方向并结合仓库中的 barrel 导出、源码注解与 Storybook 元数据讲清楚每一类状态背后的判断依据、落地动作以及维护这张登记表本身的工程规范。读完本文你将能读懂 Infisical 组件库的迁移现状并知道如何在自己参与的组件迁移工作中遵循同样的登记、标注与分步节奏。一、登记表存在的意义源码与 Storybook 之外的生命周期事实组件源码能告诉你组件「现在长什么样」Storybook 能告诉你组件「怎么用」但两者都无法直观回答一个工程问题这个组件未来是要被替换、被冻结、被保留还是被删除生命周期登记表正是用来记录这些「从源码和 Storybook 看不出来的决策」的权威载体。登记表开头明确了三条使用规则使用V2 与 V3 的 barrel 导出即v2/index.tsx与v3/index.ts来获取当前的组件目录catalog使用V3 的 stories作为 API 与用法参考V3 组件普遍带stories.tsx并启用autodocs文档模式未列入登记表的组件意味着没有记录任何特殊生命周期决策其生命周期状态按「正常维护」理解即可。仓库证据对应如下V2 组件目录frontend/src/components/v2/index.tsx 以export * from ./Button形式导出了Accordion、Alert、Button、FilterableSelect、Modal等约 40 个组件V3 组件目录frontend/src/components/v3/index.ts 再聚合导出generic与platform两个子目录其中 v3/generic/index.ts 导出了AlertDialog、Calendar、Combobox、Dialog、Field、Loader、Sheet、Toast等新一代原语组件。这套「V2 老组件 V3 新组件并行」的结构正是登记表存在的大背景V3 组件在能力上逐步覆盖 V2但覆盖进度不一致因此需要对每个 V2 组件逐一判定状态。二、V2 组件状态全表五种状态与迁移方向登记表将 V2 组件划分为五类状态下面按原表完整展开并逐条补充含义说明。2.1 Deprecated已废弃组件状态迁移方向FilterableSelectDeprecated在其契约contract适配的情况下改用 V3ComboboxFilterableSelect是唯一一个在 V2 表中被直接标记为Deprecated的组件。这一点在源码中有双重证据V2 实现 frontend/src/components/v2/FilterableSelect/FilterableSelect.tsx 的 JSDoc 写明了deprecatedMigrate searchable single- and multi-select callsites to the v3Comboboxwhen its contract fits. Creatable, grouped, and advanced compatibility consumers remain supported.V3 的兼容包装 frontend/src/components/v3/generic/ReactSelect/FilterableSelect.tsx 同样带有deprecated注解且其 Storybook storiesv3/generic/ReactSelect/FilterableSelect.stories.tsx通过tags: [autodocs, deprecated]在文档站上把「已废弃」状态显式呈现出来。从源码看V2 与 V3 的FilterableSelect都基于react-select封装提供了groupBy、getGroupHeaderLabel、isMulti、closeMenuOnSelect等能力而 V3 的 Combobox 则基于base-ui/react/combobox重建契约与react-select并不完全等价例如它通过getOptionValue/getOptionLabel/getOptionKeywords显式声明选项解析方式通过multiple区分单选与多选。因此迁移方向中特别强调「where its contract fits契约适配时」——契约不匹配的调用点不能盲目迁移。2.2 Ready for focused deprecation可着手定向废弃组件状态迁移方向Button、Card、Checkbox、EmptyState、IconButton、Input、Pagination、Select、Switch、TextArea、TooltipReady for focused deprecation已有受支持的 V3 替代品在补充组件级指引前先检查有代表性的消费方representative consumers这组是「万事俱备、只欠东风」的状态V3 侧已经有对应的替代原语对照 v3/generic/index.ts 可见Button、Card、Checkbox、Input、Pagination、Switch、TextArea、Tooltip等均已有同名 V3 导出技术上具备废弃条件。但登记表要求在给每个组件写具体迁移指引之前先抽查代表性的消费方确认实际调用方式与 V3 契约的差异面避免指引与真实用法脱节。这意味着废弃工作不是「打一个deprecated标签」这么简单而是要先完成消费调研。2.3 Blocked受阻/暂缓这一状态是 V2 表中的主体原因是多样的。登记表将受阻组件进一步细分了阻塞原因组件状态阻塞原因方向说明Accordion、Alert、Blur、Breadcrumb、CopyButton、Dropdown、HoverCardv2、Skeleton、Spinner、Stepper、Table、TabsBlocked组合方式composition、交互interaction或状态state的等价性仍需验证ConfirmActionModal、DeleteActionModal、Menu、ModalBlocked在引导消费方迁移到 V3 overlays如Dialog、AlertDialog、Sheet前需先验证确认框、菜单项、嵌套浮层与关闭行为ContentLoader、Divider、FormControl、GenericFieldLabel、PageHeader、TagBlockedV3 替代品需要消费方特定的组合方式或可访问性accessibility改造DatePickerBlockedV3Calendar无法等价替代「输入框 弹层 日期值」的组合契约Editor、InfisicalSecretInput、SecretInput、SecretPathInput、PasswordGeneratorBlocked涉密或专业化行为需要工作流层面的等价性校验NoticeBannerV2Blocked需先验证 V3Alert能否覆盖现有布局与动作action需求LottieBlockedV3Loader是替代品但应用入口仍需 V2 兼容路径Popoverv2Blocked需先完成 V2DatePicker组合的迁移从这些细分原因可以提炼出 Infisical 团队判定「Blocked」的通用标准组合/契约等价性V3 替代品是否覆盖旧组件的复合用法如DatePicker的「输入框 popover 日期值」三段式契约交互与状态等价性浮层嵌套、关闭行为、选中状态等细节是否一致如Modal家族安全敏感性涉密输入类组件SecretInput、InfisicalSecretInput、SecretPathInput、PasswordGenerator、Editor需要工作流级验证不能只做视觉对照应用入口兼容如Lottie的加载动画仍被应用入口引用替换前需要保留 V2 兼容路径依赖顺序Popoverv2的迁移依赖DatePicker先完成体现了组件迁移之间的拓扑关系。2.4 Retained保留组件状态说明FontAwesomeSymbol、HighlightText、SliderRetained没有受支持的 V3 原语能替代其独特能力Retained 是「没有 V3 替代品、且短期内没有计划做替代品」的状态。FontAwesomeSymbolFontAwesome 图标渲染、HighlightText高亮文本与Slider滑块都属于能力独特、V3 组件族尚未覆盖的原语因此不做废弃处理继续以 V2 形态长期维护。2.5 Removal candidate移除候选组件状态说明CreatableSelect、Drawer、HeaderResizer、HoverCard、NoticeBanner、Popover、RadioGroupRemoval candidate先确认是否存在间接使用indirect use确认后再作为独立的清理工作处理移除注意一个容易混淆的细节这里列出的HoverCard、NoticeBanner、Popover是V2 命名不带 v2 后缀的旧版而登记表其他位置提到的HoverCardv2、NoticeBannerV2、Popoverv2是它们的 V2 升级版。也就是说 V2 组件族内部也存在新旧之分移除候选针对的是更老、已被 v2 后缀版本取代的形态。移除候选的前置动作是排查间接使用例如是否被其他组件在内部引用确认无引用后再把移除作为独立任务推进不与迁移混在一起。三、V3 组件状态ReactSelect 兼容层的两条记录V3 侧目前只登记了两条记录且都集中在ReactSelect兼容层组件状态迁移方向ReactSelect/FilterableSelectDeprecated改用Combobox消费方迁移期间保留兼容性ReactSelect/CreatableSelectBlockedCombobox不支持内联创建选项inline option creation这里的信息量值得展开V3 也保留了一个react-select兼容层v3/generic/ReactSelect/ 目录下同时存在FilterableSelect.tsx、CreatableSelect.tsx、components.tsx复用的 indicator/option 子组件与styles.ts统一样式。它们的存在是为了让尚未迁移的消费方在 V3 体系内仍能使用老契约。FilterableSelect在 V3 侧也是 Deprecated迁移终点统一是原生 V3 的Combobox基于base-ui/react/combobox见 Combobox.tsx但迁移期间兼容性必须保留——即不能直接删除兼容层而是等所有消费方迁走后再清理。CreatableSelect保持 Blocked 的根因是能力缺口从 v3/generic/ReactSelect/CreatableSelect.tsx 的源码看它直接基于react-select/creatable封装支持「输入新值并回车创建选项」的内联创建能力而 V3Combobox目前只提供从既有选项中筛选选择的能力不提供内联创建选项。在Combobox补齐 create-on-type 能力之前CreatableSelect不能被标记为 Deprecated。这两条记录说明V3 组件族自身的演进同样遵循「先有能力等价再标记废弃」的原则兼容层组件在完成历史使命前会一直保留并维护。四、如何更新这张登记表三条硬性工程规范文档末尾给出了维护登记表本身的规范共三条是团队协作时最容易产生分歧的地方值得逐条理解4.1 给导出的 API 加deprecated注解Adddeprecatedto the exported API with a supported replacement and any migration limits.位置组件导出文件不是登记表本身内容必须同时给出受支持的替代品与迁移限制仓库示例V2 FilterableSelect.tsx 与 V3 FilterableSelect.tsx 的 JSDoc 注释都同时包含了替代品Combobox和迁移限制creatable/grouped/advanced consumers remain supported正是这条规范的落地样板。4.2 给 Storybook 元数据加deprecated标签Add thedeprecatedtag to the components Storybook metadata when a story exists.当组件存在 story 时要在 Storybook 元数据中打上deprecated标签让组件库文档站直接呈现废弃状态。仓库证据FilterableSelect.stories.tsx 中的tags: [autodocs, deprecated]正是这条规范的真实应用。4.3 废弃、迁移与移除必须分步走Keep deprecation, consumer migration, and removal as separate changes unless the task explicitly combines them.这是最重要的一条协作约束废弃deprecation、消费方迁移consumer migration、移除removal三者必须作为独立的变更change提交除非任务明确要求合并。这解释了登记表里为什么会有「Ready for focused deprecation」废弃前先调研消费方与「Removal candidate」移除前先查间接使用这样细分的过渡状态——每个状态对应一个独立的工程步骤便于代码评审、回归测试与回滚。五、把登记表用起来阅读与参与迁移的实操建议结合登记表、barrel 导出与源码可以归纳出在 Infisical 前端仓库中参与组件迁移的标准动作序列定位组件目录通过 v2/index.tsx 与 v3/generic/index.ts 两份 barrel 导出快速确认目标组件属于哪一代、V3 有无对应替代品查询生命周期状态在 COMPONENT_LIFECYCLE.md 中查找该组件未登记 无特殊生命周期决策阅读 V3 替代品的契约以 V3 组件的stories.tsx启用autodocs作为 API 与用法参考对照旧组件 props 逐一比对契约差异如react-select契约 vsCombobox的getOptionValue/getOptionLabel契约按状态执行对应动作Deprecated新代码优先使用 V3 替代品老调用点按迁移方向逐步迁移Ready for focused deprecation先抽查代表性消费方再补充组件级迁移指引Blocked保持现状等待能力等价性验证完成或依赖组件先行迁移Retained继续正常使用与维护Removal candidate排查间接使用确认后作为独立清理任务移除登记状态变更时遵守三条规范导出 API 加deprecated含替代品与迁移限制、story 元数据加deprecated标签、废弃/迁移/移除分步提交。这套「登记表 barrel 目录 stories 契约 双份注解JSDoc 与 Storybook tag」的组合构成了 Infisical 前端组件库可持续演进的生命周期管理体系。对于维护大型 React 组件库的团队而言即使不直接使用 Infisical 的代码这份登记表的分类维度Deprecated / Ready / Blocked / Retained / Removal candidate与「先能力等价、再标记废弃、最后分步移除」的节奏也是可以直接借鉴的工程实践。【免费下载链接】infisicalInfisical is the open-source platform for secrets, certificates, and privileged access management.项目地址: https://gitcode.com/GitHub_Trending/in/infisical创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考