Unleash 前端表单架构实践基于 ADR 的 Hook 无逻辑表单组件 Create/Edit 组合模式【免费下载链接】unleashOpen-source feature management platform项目地址: https://gitcode.com/GitHub_Trending/un/unleash本篇技术指南基于 preferred-form-architecture.md 这份前端架构决策记录ADR系统讲解 Unleash 前端团队如何在DRY避免重复与关注点分离这对天然矛盾之间做出取舍并沉淀为可复用的三件套表单架构逻辑 Hook 无逻辑表单组件 独立的 Create/Edit 组合组件。读完本文你将掌握这套架构的每一层职责、数据流方向、源码级实现形态并能直接将其复用到你自己的 React 表单开发中。背景表单为什么棘手Unleash 前端React TypeScript是典型的中后台管理界面充斥着大量新建 / 编辑型表单创建 API Token、新建/编辑用户组、添加用户、配置策略等。处理这些表单时开发者总是希望组件足够 DRY——公共的表单布局、输入控件、校验逻辑只写一遍同时又希望各组件职责清晰、互不耦合。ADR 明确指出这是表单场景的根本矛盾You cant both have it DRY and completely separated.一个表单如果既想完全 DRY又想彻底分离关注点往往难以两全。Unleash 的选择是不追求极端而是明确划分每一层的职责边界让 DRY 与关注点分离各得其所。这正是这份 ADR 的价值——它为团队定下了一个统一的思考基线避免每个开发者凭个人偏好写出风格迥异的表单。决策三层架构各司其职ADR 的决策部分给出了完整的架构蓝图共三个层次逻辑 Hook包含表单的全部逻辑返回一个表单对象内含所有表单状态与更新状态所需的函数。可复用表单组件只负责渲染与交互布局不含任何业务逻辑。独立的 Create 与 Edit 组件分别组合表单组件与表单 Hook各自实现自己的提交逻辑。用 ADR 的原话总结这套设计的收益In this way, we keep as much of the form as possible DRY, but we avoid passing state internally in the form so the form doesnt need to know whether it is in create or edit mode.也就是说表单组件自己不持有内部状态因此它完全不需要关心当前处于 Create 还是 Edit 模式——这两种模式的状态管理和提交差异全部上移到外层组合组件。开发者每次只需面对单一状态不必为同一组件存在双份状态而烦恼。源码级拆解三件套在 Unleash 中的真实形态这套架构并非停留在纸面而是被 frontend/src/component 下的大量模块实际落地。下文以两个最具代表性的案例做源码级拆解。案例一API Token 表单API Token 的创建表单是该架构的教科书级实现对应目录为 frontend/src/component/admin/apiToken。第一层useApiTokenFormHook逻辑层useApiTokenForm.ts 集中了全部表单状态与操作状态tokenName、typeToken 类型、projects关联项目、environment环境、errors校验错误副作用通过useEffect在 Token 类型或初始环境变化时自动同步environment字段联动逻辑setTokenType中处理了 ADMIN 类型与普通类型切换时的项目记忆恢复memorizedProjects提交数据getApiTokenPayload()将状态组装为符合后端接口IApiTokenCreate的请求负载校验逻辑isValid()集中校验Token 名称必填至少选择一个项目并把错误写入errors权限联动借助useHasRootAccess判断当前用户是否具备创建各类 Token 的权限进而决定下拉选项的可用性。注意一个细节Hook 的返回值tokenName、setTokenName、errors、clearErrors……恰好是状态 更新函数的组合——这与 ADR 描述的return a form object that contains all the form state and functions to update the state完全对应。第二层ApiTokenForm组件纯展示层ApiTokenForm.tsx 只接收 propshandleSubmit、handleCancel、mode: Create | Edit、actions与children。组件内部渲染统一的StyledForm骨架根据 UI 配置useUiConfig条件渲染 Cloud 环境的提示 Alert把children各个字段子组件与底部操作按钮区组合起来。整个组件没有任何 useState也不发起任何 API 调用——它纯粹是一个表单外壳。字段子组件如 TokenInfo.tsx、TokenTypeSelector.tsx、ProjectSelector.tsx、EnvironmentSelector.tsx 同样遵循受控组件模式状态从 Hook 流入用户输入通过回调函数流回 Hook。第三层CreateApiToken组件业务编排层CreateApiToken.tsx 将前两层组合起来并承担创建场景独有的职责调用useApiTokenForm()取得表单对象调用useApiTokensApi()、useToast()、useTracking()等 hooks 处理提交、错误提示与埋点handleSubmit中先isValid()校验再组装 payload 调用createToken成功后展示ConfirmToken确认弹窗并refetch刷新列表通过FormTemplate生成可直接复制的curl示例代码formatApiCode校验limitReachedToken 配额上限来禁用提交按钮。注意ApiTokenForm收到的modeCreate只是展示文案层面的标识表单壳本身并不依赖它做任何状态分支——这正是form doesnt need to know whether it is in create or edit mode的体现。案例二用户组表单Create/Edit 成对出现如果说 API Token 只实现了 Create 场景那么用户组模块则完整展示了Create 与 Edit 成对复用同一套 Hook 表单组件的形态位于 frontend/src/component/admin/groups逻辑层hooks/useGroupForm.ts它接收name、description、mappingsSSO、users、rootRole等初始值作为参数——Edit 场景传入既有数据完成回填展示层GroupForm/GroupForm.tsx配合 GroupFormUsersSelect、GroupFormUsersTable 等子组件编排层CreateGroup/CreateGroup.tsx 与 EditGroup/EditGroup.tsx 各自调用useGroupForm后者传入group的现有字段、组装提交 payload。以 EditGroup.tsx 为例可以清楚看到 Edit 模式的差异全部收敛在编排层通过useGroup(groupId)获取既有分组数据作为useGroupForm的初始值handleSubmit调用updateGroup(groupId, payload)后refetchGroup()、refetchGroups()并导航返回提交按钮的disabled{!isValid}由编排层自行计算名称非空 名称唯一mode{EDIT}仅用于告知表单组件当前处于编辑上下文。数据流单向、显式、可预测综合上述实现这套架构的数据流是严格的单向受控流状态与操作 useXxxForm Hook唯一状态源 │ 通过 Hook 返回值state setters向下传递 ▼ 字段子组件 ── 用户输入/选择事件 ──► 回调 setter ▲ │ 通过 props 接收 value onChange/onXxx │ ApiXxxForm无状态表单壳组合字段子组件 actions ▲ │ handleSubmit / handleCancel CreateXxx / EditXxx编排层校验、提交、toast、埋点、导航校验逻辑在 Hook 层如isValid/clearErrors见useApiTokenForm与编排层如 EditGroup 的名称唯一性校验都可能出现但共同点是校验结果始终回流到 Hook 的errors状态再以受控方式展示在字段组件上。这种设计让每个字段的错误展示、清错时机clearErrors完全可预期。为什么值得坚持收益与取舍从 ADR 原文与源码实现可以提炼出这套架构的核心收益最大程度 DRY表单外壳、字段子组件、校验与提交 payload 组装逻辑全部只写一次Create/Edit 共享同一套 UI 与逻辑基线单一状态心智表单壳不持有内部状态不存在Create 分支 vs Edit 分支双状态并存的复杂度开发者只需面对 Hook 暴露的一个表单对象职责边界清晰逻辑在 Hook、渲染在外壳组件、场景差异在编排层任何一个新人接手都能快速定位改逻辑去哪、改 UI 去哪、改提交去哪可测试性提升Hook 与编排层是纯 TypeScript 逻辑便于单测表单壳是纯 props 驱动便于组件测试例如 CreateApiToken.test.tsx 即围绕编排层的提交行为做断言。同时也要看到它的有意为之的取舍由于状态不放表单组件内部所有字段必须通过 props 显式传入编排层的 JSX 会略显冗长参见CreateApiToken中每个字段组件都要绑定 value setter。这正是 ADR 开篇所承认的——DRY 与完全分离不可兼得团队选择了以显式传参换取单一状态心智。与相邻 ADR 的配合这套表单架构不是孤立约定它与前端目录下的其他 ADR 共同构成完整的开发规范建议配套阅读preferred-data-fetching-method.md 与 preferred-data-mutation-method.md规定表单所需数据的获取方式hooks 层与提交变更的方式编排层preferred-component-props-usage.md约束表单壳与字段组件的 props 设计preferred-folder-structure.md对应CreateXxx/、EditXxx/、XxxForm/、hooks/的目录划分上述案例目录结构即为其落地component-naming.md 与 preferred-export.md规范表单相关组件的命名与导出方式。实践建议如果你正在 Unleash 仓库中新增或重构表单或想把这套模式引入自己的 React 项目可以按以下步骤落地先写 Hook用useXxxForm(initialValues?)收敛全部表单状态、联动副作用、校验与 payload 组装初始值参数留好便于 Edit 场景回填再写表单壳XxxForm组件只接收handleSubmit、handleCancel、mode、actions与children内部用受控子组件拼装 UI自身不持有状态最后写编排层分别实现CreateXxx与EditXxx各自调用 Hook、绑定数据源、实现提交/错误处理/成功后刷新与导航校验分层通用字段校验放 Hook需要请求外部数据如名称唯一性的校验放编排层结果统一回写errors状态。遵循这套架构你的表单代码将同时获得 DRY 的复用性、清晰的职责边界与可预期的单一数据流——这正是这份 ADR 为 Unleash 前端代码库长期维护性所做的关键设计决策。【免费下载链接】unleashOpen-source feature management platform项目地址: https://gitcode.com/GitHub_Trending/un/unleash创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考
Unleash 前端表单架构实践基于 ADR 的 Hook 无逻辑表单组件 Create/Edit 组合模式【免费下载链接】unleashOpen-source feature management platform项目地址: https://gitcode.com/GitHub_Trending/un/unleash本篇技术指南基于 preferred-form-architecture.md 这份前端架构决策记录ADR系统讲解 Unleash 前端团队如何在DRY避免重复与关注点分离这对天然矛盾之间做出取舍并沉淀为可复用的三件套表单架构逻辑 Hook 无逻辑表单组件 独立的 Create/Edit 组合组件。读完本文你将掌握这套架构的每一层职责、数据流方向、源码级实现形态并能直接将其复用到你自己的 React 表单开发中。背景表单为什么棘手Unleash 前端React TypeScript是典型的中后台管理界面充斥着大量新建 / 编辑型表单创建 API Token、新建/编辑用户组、添加用户、配置策略等。处理这些表单时开发者总是希望组件足够 DRY——公共的表单布局、输入控件、校验逻辑只写一遍同时又希望各组件职责清晰、互不耦合。ADR 明确指出这是表单场景的根本矛盾You cant both have it DRY and completely separated.一个表单如果既想完全 DRY又想彻底分离关注点往往难以两全。Unleash 的选择是不追求极端而是明确划分每一层的职责边界让 DRY 与关注点分离各得其所。这正是这份 ADR 的价值——它为团队定下了一个统一的思考基线避免每个开发者凭个人偏好写出风格迥异的表单。决策三层架构各司其职ADR 的决策部分给出了完整的架构蓝图共三个层次逻辑 Hook包含表单的全部逻辑返回一个表单对象内含所有表单状态与更新状态所需的函数。可复用表单组件只负责渲染与交互布局不含任何业务逻辑。独立的 Create 与 Edit 组件分别组合表单组件与表单 Hook各自实现自己的提交逻辑。用 ADR 的原话总结这套设计的收益In this way, we keep as much of the form as possible DRY, but we avoid passing state internally in the form so the form doesnt need to know whether it is in create or edit mode.也就是说表单组件自己不持有内部状态因此它完全不需要关心当前处于 Create 还是 Edit 模式——这两种模式的状态管理和提交差异全部上移到外层组合组件。开发者每次只需面对单一状态不必为同一组件存在双份状态而烦恼。源码级拆解三件套在 Unleash 中的真实形态这套架构并非停留在纸面而是被 frontend/src/component 下的大量模块实际落地。下文以两个最具代表性的案例做源码级拆解。案例一API Token 表单API Token 的创建表单是该架构的教科书级实现对应目录为 frontend/src/component/admin/apiToken。第一层useApiTokenFormHook逻辑层useApiTokenForm.ts 集中了全部表单状态与操作状态tokenName、typeToken 类型、projects关联项目、environment环境、errors校验错误副作用通过useEffect在 Token 类型或初始环境变化时自动同步environment字段联动逻辑setTokenType中处理了 ADMIN 类型与普通类型切换时的项目记忆恢复memorizedProjects提交数据getApiTokenPayload()将状态组装为符合后端接口IApiTokenCreate的请求负载校验逻辑isValid()集中校验Token 名称必填至少选择一个项目并把错误写入errors权限联动借助useHasRootAccess判断当前用户是否具备创建各类 Token 的权限进而决定下拉选项的可用性。注意一个细节Hook 的返回值tokenName、setTokenName、errors、clearErrors……恰好是状态 更新函数的组合——这与 ADR 描述的return a form object that contains all the form state and functions to update the state完全对应。第二层ApiTokenForm组件纯展示层ApiTokenForm.tsx 只接收 propshandleSubmit、handleCancel、mode: Create | Edit、actions与children。组件内部渲染统一的StyledForm骨架根据 UI 配置useUiConfig条件渲染 Cloud 环境的提示 Alert把children各个字段子组件与底部操作按钮区组合起来。整个组件没有任何 useState也不发起任何 API 调用——它纯粹是一个表单外壳。字段子组件如 TokenInfo.tsx、TokenTypeSelector.tsx、ProjectSelector.tsx、EnvironmentSelector.tsx 同样遵循受控组件模式状态从 Hook 流入用户输入通过回调函数流回 Hook。第三层CreateApiToken组件业务编排层CreateApiToken.tsx 将前两层组合起来并承担创建场景独有的职责调用useApiTokenForm()取得表单对象调用useApiTokensApi()、useToast()、useTracking()等 hooks 处理提交、错误提示与埋点handleSubmit中先isValid()校验再组装 payload 调用createToken成功后展示ConfirmToken确认弹窗并refetch刷新列表通过FormTemplate生成可直接复制的curl示例代码formatApiCode校验limitReachedToken 配额上限来禁用提交按钮。注意ApiTokenForm收到的modeCreate只是展示文案层面的标识表单壳本身并不依赖它做任何状态分支——这正是form doesnt need to know whether it is in create or edit mode的体现。案例二用户组表单Create/Edit 成对出现如果说 API Token 只实现了 Create 场景那么用户组模块则完整展示了Create 与 Edit 成对复用同一套 Hook 表单组件的形态位于 frontend/src/component/admin/groups逻辑层hooks/useGroupForm.ts它接收name、description、mappingsSSO、users、rootRole等初始值作为参数——Edit 场景传入既有数据完成回填展示层GroupForm/GroupForm.tsx配合 GroupFormUsersSelect、GroupFormUsersTable 等子组件编排层CreateGroup/CreateGroup.tsx 与 EditGroup/EditGroup.tsx 各自调用useGroupForm后者传入group的现有字段、组装提交 payload。以 EditGroup.tsx 为例可以清楚看到 Edit 模式的差异全部收敛在编排层通过useGroup(groupId)获取既有分组数据作为useGroupForm的初始值handleSubmit调用updateGroup(groupId, payload)后refetchGroup()、refetchGroups()并导航返回提交按钮的disabled{!isValid}由编排层自行计算名称非空 名称唯一mode{EDIT}仅用于告知表单组件当前处于编辑上下文。数据流单向、显式、可预测综合上述实现这套架构的数据流是严格的单向受控流状态与操作 useXxxForm Hook唯一状态源 │ 通过 Hook 返回值state setters向下传递 ▼ 字段子组件 ── 用户输入/选择事件 ──► 回调 setter ▲ │ 通过 props 接收 value onChange/onXxx │ ApiXxxForm无状态表单壳组合字段子组件 actions ▲ │ handleSubmit / handleCancel CreateXxx / EditXxx编排层校验、提交、toast、埋点、导航校验逻辑在 Hook 层如isValid/clearErrors见useApiTokenForm与编排层如 EditGroup 的名称唯一性校验都可能出现但共同点是校验结果始终回流到 Hook 的errors状态再以受控方式展示在字段组件上。这种设计让每个字段的错误展示、清错时机clearErrors完全可预期。为什么值得坚持收益与取舍从 ADR 原文与源码实现可以提炼出这套架构的核心收益最大程度 DRY表单外壳、字段子组件、校验与提交 payload 组装逻辑全部只写一次Create/Edit 共享同一套 UI 与逻辑基线单一状态心智表单壳不持有内部状态不存在Create 分支 vs Edit 分支双状态并存的复杂度开发者只需面对 Hook 暴露的一个表单对象职责边界清晰逻辑在 Hook、渲染在外壳组件、场景差异在编排层任何一个新人接手都能快速定位改逻辑去哪、改 UI 去哪、改提交去哪可测试性提升Hook 与编排层是纯 TypeScript 逻辑便于单测表单壳是纯 props 驱动便于组件测试例如 CreateApiToken.test.tsx 即围绕编排层的提交行为做断言。同时也要看到它的有意为之的取舍由于状态不放表单组件内部所有字段必须通过 props 显式传入编排层的 JSX 会略显冗长参见CreateApiToken中每个字段组件都要绑定 value setter。这正是 ADR 开篇所承认的——DRY 与完全分离不可兼得团队选择了以显式传参换取单一状态心智。与相邻 ADR 的配合这套表单架构不是孤立约定它与前端目录下的其他 ADR 共同构成完整的开发规范建议配套阅读preferred-data-fetching-method.md 与 preferred-data-mutation-method.md规定表单所需数据的获取方式hooks 层与提交变更的方式编排层preferred-component-props-usage.md约束表单壳与字段组件的 props 设计preferred-folder-structure.md对应CreateXxx/、EditXxx/、XxxForm/、hooks/的目录划分上述案例目录结构即为其落地component-naming.md 与 preferred-export.md规范表单相关组件的命名与导出方式。实践建议如果你正在 Unleash 仓库中新增或重构表单或想把这套模式引入自己的 React 项目可以按以下步骤落地先写 Hook用useXxxForm(initialValues?)收敛全部表单状态、联动副作用、校验与 payload 组装初始值参数留好便于 Edit 场景回填再写表单壳XxxForm组件只接收handleSubmit、handleCancel、mode、actions与children内部用受控子组件拼装 UI自身不持有状态最后写编排层分别实现CreateXxx与EditXxx各自调用 Hook、绑定数据源、实现提交/错误处理/成功后刷新与导航校验分层通用字段校验放 Hook需要请求外部数据如名称唯一性的校验放编排层结果统一回写errors状态。遵循这套架构你的表单代码将同时获得 DRY 的复用性、清晰的职责边界与可预期的单一数据流——这正是这份 ADR 为 Unleash 前端代码库长期维护性所做的关键设计决策。【免费下载链接】unleashOpen-source feature management platform项目地址: https://gitcode.com/GitHub_Trending/un/unleash创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考
