Vault UI V2 表单系统完全指南：从 OpenAPI 驱动脚手架到 HDS 渲染的工程实践

Vault UI V2 表单系统完全指南从 OpenAPI 驱动脚手架到 HDS 渲染的工程实践【免费下载链接】vaultA tool for secrets management, encryption as a service, and privileged access management项目地址: https://gitcode.com/GitHub_Trending/va/vault导读本文讲解 Vault Web UIEmber 应用中新一代V2 表单系统的设计与使用。它以数据驱动方式在 HashiCorp Design SystemHDS之上构建表单一个FormConfig对象描述字段、分组section与提交逻辑V2Form类负责维护运行时状态payload 与校验错误Ember 组件负责渲染与提交流程。凡是新接入 Vault API 的表单都推荐使用本系统只要存在对应的 OpenAPI 操作就应优先运行pnpm generate:form-config生成带类型的脚手架而不是手写配置。读完本文你将掌握脚手架生成、配置覆盖override、手写配置、模板接入、多步向导wizard与校验体系的完整用法。架构总览V2 表单系统将「配置声明」与「运行时状态」解耦共分三层对应仓库中ui/app/forms/v2/与ui/app/components/form/v2/两个目录FormConfig (plain object) └── sections[] └── fields[] ← field name, type, label, validations, options… V2Form (class, tracked) ├── payload ← deep clone of FormConfig.payload ├── validationErrors ← MapfieldName, string[] ├── set(path, value) ← updates payload re-validates field ├── validateForm() ← validates all visible fields └── submit(api) ← validateForm() → config.submit(api, payload) Ember components ├── Form::V2 ← submit task, error state, yields Form submitTask ├── Form::V2::Renderer ← Hds::Form, iterates sections/fields ├── Form::V2::Section ← wraps fields in Form.Section with optional title ├── Form::V2::Field ← renders the correct HDS input component ├── Form::V2::ErrorAlert ← inline critical alert for submission errors ├── Form::V2::Wizard ← multi-step wizard orchestrator └── Form::V2::Apply ← final apply changes step with code snippet options各层职责如下FormConfig是一个纯对象类型定义位于 form-config.ts。它只描述表单长什么样、提交到哪、成功/失败后做什么不含任何运行时状态。V2Form类以tracked追踪payload与validationErrors具体实现见 v2-form.ts。构造时会对FormConfig.payload做一次深度克隆structuredClone保证表单运行期改动不会反向污染配置对象。Ember 组件负责把配置渲染成 HDS 表单并驱动提交任务全部组件位于 app/components/form/v2/按类型分文件field.ts、renderer.ts、section.ts、error-alert.ts、wizard.ts、apply.ts与入口index.ts。从源码结构看这套分层让「UI 定制」与「API 模型」分离配置可以手写、可以自动生成、也可以在生成结果之上叠加覆盖且相互之间互不侵入。前置条件使用 V2 表单系统及脚手架生成器前需要满足已执行过pnpm install会安装tsx及若干开发依赖已安装hashicorp/vault-client-typescript包——它提供openapi.json以及带类型的 SDK 方法。脚手架脚本在运行时直接读取node_modules/hashicorp/vault-client-typescript/openapi.json该路径由脚本内部解析得出见 generate-form-config.js。生成 Form Config把camelCase 形式的 API 方法名传给生成器它会从内置 OpenAPI 规范中读取字段定义写出一份全类型fully-typed脚手架。例如为POST /sys/mounts/{path}启用某个 secrets engine 的操作生成配置pnpm generate:form-config mountsEnableSecretsEngine该命令定义在 package.json 的scripts中实际调用scripts/generate-form-config.js。脚本入口会先校验必填参数methodName并给出友好的错误提示与用法示例。生成过程发生了什么对照 generate-form-config.js 的实现流程可归纳为加载并解析openapi.json打印发现的路径总数在 spec 中查找 dasherized 方法名如mounts-enable-secrets-engine对应的POST操作operationId提取路径参数与请求体属性跳过 deprecated已废弃字段依据 spec 中的x-vault-displayAttrs.group注解对字段分组没有该注解时回退到default分组由操作的 tag 与方法名推导 TypeScript 请求类型例如SystemApiMountsEnableSecretsEngineOperationRequest把.ts文件写入app/forms/v2/generated/并自动运行 Prettier 格式化。submit 中 API 类的自动判定submit中实际调用的 API 对象由 OpenAPI 的 tag 自动决定映射关系如下TagAPI classsystemapi.sysauthapi.authidentityapi.identitysecretsapi.secrets以mountsEnableSecretsEngine为例它属于systemtag生成的submit调用的是api.sys.mountsEnableSecretsEngineRaw(payload)。若操作缺少可识别的 tag脚本会直接报错退出并提示补写 tags。生成产物一个真实样例生成器把文件写入app/forms/v2/generated/文件名为 dasherized短横线风格app/forms/v2/generated/mounts-enable-secrets-engine-config.ts仓库中保留了这个真实生成文件见 mounts-enable-secrets-engine-config.ts。文件内容包含对类型化 SDK 请求类型的importSystemApiMountsEnableSecretsEngineOperationRequest一个FormConfigRequestType, unknown常量携带name、path、description、submit、payload、sections六个字段sections按 OpenAPI 规范分组params存放路径参数default存放请求体字段有x-vault-displayAttrs.group注解的会生成对应命名分组所有字段默认都以TextInput类型生成——审阅后需要自行修正type例如布尔开关应改成Toggle、枚举应改成Select。例如该文件的path为/sys/mounts/{path}description为Mount a new backend at a new path.payload 中路径参数path直接挂在一级请求体字段则统一放在MountsEnableSecretsEngineRequest嵌套对象下如config、description、external_entropy_access、local、options、plugin_name、plugin_version、seal_wrap、type这正好对应 Vault 的挂载请求结构。注意生成的文件不会自动注册需要按下一节手动接入。生成之后注册、覆盖、使用生成文件顶部带有⚠️ AUTO-GENERATED FILE - DO NOT EDIT标记不要直接编辑它。所有与 UI 相关的调整都应放在 override 中见下一节。接入表单需要三步1. 注册配置在app/forms/v2/generated/index.ts中加入导出import mountsEnableSecretsEngineConfig from ./mounts-enable-secrets-engine-config; const GENERATED_CONFIGS { mountsEnableSecretsEngine: mountsEnableSecretsEngineConfig, }; export default GENERATED_CONFIGS;2. 创建 override用于调整字段类型、标签、可见性或删除无关字段方法见下一节。3. 使用表单用注册表 key 或配置对象实例化V2Form方法见「在模板中使用表单」。覆盖Override生成的配置生成的配置忠实建模了 API 表面不应被直接修改。需要调整字段顺序、标签、可见性规则或增加非 API 字段时用configBuilder创建 override。Builder 的实现位于 override-field.ts它以深拷贝的方式复制生成配置的sections注意拷贝过程保留函数注释里特别强调避免 JSON 序列化因为它会剥离函数随后所有改动都作用于副本最终由build()与原始配置的非 section 属性合并返回新配置。在app/forms/v2/overrides/下新建文件// app/forms/v2/overrides/mounts-enable-secrets-engine-config.ts import generatedConfig from ../generated/mounts-enable-secrets-engine-config; import { configBuilder } from ./override-field; export default configBuilder(generatedConfig) .removeField(default, MountsEnableSecretsEngineRequest.seal_wrap) .updateField(params, path, { label: Mount path, helperText: The path to mount to. Example: aws/east, isRequired: true, }) .addSection({ name: engine_selection, title: Engine type, fields: [ { name: MountsEnableSecretsEngineRequest.type, type: Select, label: Type, options: [ { label: KV, value: kv }, { label: AWS, value: aws }, ], }, ], }, 0) // position 0 inserts before all other sections .build();在app/forms/v2/overrides/index.ts注册 overrideimport mountsEnableSecretsEngineConfig from ./mounts-enable-secrets-engine-config; const OVERRIDE_CONFIGS { mountsEnableSecretsEngine: mountsEnableSecretsEngineConfig, }; export default OVERRIDE_CONFIGS;getFormConfig()会先查 overrides 再查 generated configs因此 override 自动获得优先权。这一点在 get-form-config.ts 中实现得很直观先判断OVERRIDE_CONFIGS[configName]是否存在命中即返回否则回退到GENERATED_CONFIGS两者都未命中则抛出Form configuration not found for: …错误。可用的 builder 方法下表列出了configBuilder的全部方法源码签名与异常行为见 override-field.tsMethodDescriptionaddSection(section, position?)新增 section默认追加到末尾也可指定position插入removeSection(sectionName)按名称移除 sectionupdateSection(sectionName, updates)更新 section 的title、description或isVisibleaddField(sectionName, field)向既有 section 增加字段updateField(sectionName, fieldName, overrides)更新字段的任意属性name除外采用浅合并覆盖removeField(sectionName, fieldName)从 section 中移除字段moveField(fieldName, fromSection, toSection, position?)在 section 之间移动字段reorderFields(sectionName, fieldNames)重排 section 内的字段顺序build()返回最终的FormConfig需要留意的是当传入不存在的 section 或字段名时除removeField采用静默过滤外多数方法会抛出形如Section … not found、Field … not found in section …的异常便于尽早暴露配置错误。若只想批量调整一个 section 内若干字段的展示属性仓库还提供了一个更轻量的辅助函数overrideFieldsInSection(generatedConfig, sectionName, fieldOverrides)它内部逐个调用updateField后直接build()。手动编写配置对于没有对应 OpenAPI 操作的表单或生成的脚手架并不适用时可以直接手写配置。核心类型FormConfigRequest, Response与FormField、FormSection、WizardConfig等都定义在 form-config.ts下面的例子完整展示了其契约import type ApiService from vault/services/api; import type { FormConfig } from vault/forms/v2/form-config; interface MyPayload { name: string; ttl: number; enabled: boolean; } const myFormConfig: FormConfigMyPayload, unknown { name: myForm, path: /sys/example/{name}, title: Create example, payload: { name: , ttl: 0, enabled: false, }, submit: async (api: ApiService, payload: MyPayload) { return await api.sys.someMethodRaw(payload); }, onSuccess: (response) { // optional: redirect, show toast, etc. }, sections: [ { name: basic, title: Basic settings, fields: [ { name: name, type: TextInput, label: Name, isRequired: true, }, { name: ttl, type: TextInput, inputType: number, label: TTL, helperText: Time-to-live in seconds, }, { name: enabled, type: Toggle, label: Enable, }, ], }, ], };结合 form-config.ts 的类型定义补充几个字段语义要点name唯一标识表单通常与 API 方法名一致path用于生成 CURL 请求片段源码注释中明确说明此用途submit是提交处理器接收 API 服务与类型化 payload返回类型化的 API 响应onSuccess在提交成功后回调可做跳转、toast 等onError在提交失败时收到提取出的错误消息字段的name支持点路径dotted-path记法以表达嵌套属性如user.address.streetFieldValue的合法取值包括string | number | boolean | string[] | null | undefined。字段类型type到 HDS 渲染组件的映射如下typeHDS component renderedTextInputHds::Form::TextInput::FieldTextAreaHds::Form::Textarea::FieldSelectHds::Form::Select::FieldToggleHds::Form::Toggle::FieldCheckboxHds::Form::Checkbox::FieldRadioHds::Form::Radio::GroupRadioCardHds::Form::RadioCard::GroupMaskedInputHds::Form::MaskedInput::Field在 form-config.ts 中FormElement被建模为上述八个字符串的联合类型因此不认识的type在类型层面就会被编译器拒绝。若编译期已通过但运行期仍遇到未识别类型Form::V2::Field会回退到文本输入并在控制台打印[Form::V2::Field] Unsupported field type …警告。新字段类型的支持是按需as-needed添加的如果迁移到 V2 的表单需要上表之外的组件应当在Form::V2::Field中同步补充支持。TextInput还可以接受可选的inputType属性来指定 HTML input 类型合法值来自源码中的TextInputType联合类型包括text、email、password、url、search、date、time、datetime-local、month、week、tel严格取自 form-config.ts并非所有 HTML 类型都可用。Select、Radio、RadioCard必须提供options数组options: [ { label: Option A, value: a }, { label: Option B, value: b, description: Only for RadioCard }, ]其中FieldOption的value类型为string | number | booleandescription仅对 RadioCard 生效见 form-config.ts。条件可见性字段与 section 都接受isVisible属性类型为boolean | ((payload) boolean)即VisibilityRule// Static — always hidden { isVisible: false } // Dynamic — based on current payload { isVisible: (payload) payload.type advanced }隐藏字段的行为有两层保障对应 v2-form.ts 的实现校验排除validateForm()与字段级校验只作用于「可见字段集合」计算方式是先过滤可见 section、再拍平并过滤可见字段错误清理每次 payload 变化后调用#pruneHiddenFieldErrors()把不可见字段的错误从validationErrors中剔除避免残留报错。在模板中使用表单路由 / 组件中的初始化V2Form构造器支持两种入参FormConfigKey或配置对象这一点在 v2-form.ts 的注释中有详细说明// my-route.ts or my-component.ts import V2Form from vault/forms/v2/v2-form; // Option 1: registry key (config must be registered in generated/index.ts or overrides/index.ts) form new V2Form(mountsEnableSecretsEngine); // Option 2: direct config object form new V2Form(myFormConfig);按名称实例化适合单步表单从注册表中解析配置按配置对象实例化适合向导步骤等需要局部覆盖如动态 payload的场景类型上建议以new V2Formany, any(config)简化书写。构造时会自动执行#injectRequiredValidations()为所有isRequired: true的字段在validations最前面补入一条required规则消息为「{field.label} is required」除非该字段已有required规则。默认用法自动渲染字段 提交按钮Form::V2 form{{this.form}} onSuccess{{this.handleSuccess}} /Form::V2会管理提交任务submit task与错误状态并把Form与submitTask作为块参数block params向下传递。自定义提交按钮若需要自定义按钮区域可在块形式中拿到Form与submitTaskForm::V2 form{{this.form}} onSuccess{{this.handleSuccess}} as |Form submitTask| Form.Section Hds::ButtonSet Hds::Button textSave colorprimary typesubmit disabled{{or (not this.form.isValid) submitTask.isRunning}} {{on click (perform submitTask)}} / Hds::Button textCancel colorsecondary routevault.cluster.index / /Hds::ButtonSet /Form.Section /Form::V2disabled同时考察this.form.isValid对应validationErrors.size 0见 v2-form.ts与submitTask.isRunning防止无效或进行中的重复提交。隐藏自动渲染字段自定义布局传入hideFields{{true}}可抑制自动渲染的字段同时保留提交、错误处理以及Form上下文Form::V2 form{{this.form}} hideFields{{true}} as |Form submitTask| {{! render fields manually using Form.Section, Form.Field, etc. }} /Form::V2多步向导Multi-step Wizards当一个业务场景需要按顺序提交多张表单、且后续步骤依赖前序结果时用WizardConfigForm::V2::Wizard。WizardConfig与相关类型WizardStep、WizardStepState、WizardState同样定义在 form-config.ts。定义WizardConfigimport type { WizardConfig } from vault/forms/v2/form-config; import step1Config from vault/forms/v2/generated/step-one-config; import step2Config from vault/forms/v2/generated/step-two-config; const wizardConfig: WizardConfig { title: Enable secrets engine, applyChanges: true, // adds a final Apply changes step with code snippet options steps: [ { name: mountConfig, title: Mount configuration, heading: Configure the mount, formConfig: step1Config, }, { name: engineConfig, title: Engine settings, formConfig: { ...step2Config, // Dynamic payload: read the path entered in step 1 payload: (wizardState) ({ ...step2Config.payload, mount: wizardState.mountConfig?.payload?.path ?? , }), }, }, ], };在模板中挂载向导Form::V2::Wizard config{{this.wizardConfig}} onSuccess{{this.handleComplete}} onCancel{{this.handleCancel}} /跨步骤数据共享步骤的payload可以是函数(wizardState) payload。wizardState是一个以步骤name为 key 的映射每个已完成的步骤包含{ payload, response, error? }即WizardStepState见 form-config.ts。这样后一步可以基于前一步的提交结果如第一步输入的挂载路径预填字段。WizardState只存数据执行状态由 ember-concurrency 的任务属性推导源码注释明确说明了这一设计取舍。applyChanges 最终步骤当applyChanges: true时向导末尾会追加一个「Apply changes」步骤渲染Form::V2::Apply——它是一个 radio card 选择器让用户选择通过Terraform HCL、Vault CLI/API curl 命令或直接在 UI 中执行来应用变更。UI 组件 apply.ts 即为该步骤的实现载体。校验体系内置校验器任何字段都可以挂validations数组{ name: email, type: TextInput, label: Email, isRequired: true, // shorthand — auto-injects a required rule validations: [ { type: email, message: Please enter a valid email address }, { type: maxLength, message: Email must be under 255 characters, options: { maxLength: 255 } }, ], }内置校验器的行为对照 form-validators.ts 的实现typeValidatesrequired非空值拒绝null、undefined、、[]、{}emailEmail 格式urlURL 格式使用new URL()pattern正则——提供options.pattern字符串或RegExp可选options.flagsminLength最小字符串长度——提供options.minLengthmaxLength最大字符串长度——提供options.maxLengthmin最小数值——提供options.minmax最大数值——提供options.max几个值得注意的实现细节均可在 form-validators.ts 中验证required对字符串做trim().length 0判断纯空白字符串视为无效email、url、pattern、minLength、maxLength等对空值返回true视为通过因此强制必填需要配合required规则使用——这正是isRequired快捷方式存在的原因min对null、undefined、也直接放行pattern接受字符串或RegExp两种形态字符串时可通过flags指定修饰符。自定义校验器当内置规则不够用时可以传validator函数{ name: path, type: TextInput, label: Path, validations: [ { validator: (formData) !String(formData.path).includes( ), message: Path must not contain spaces, }, ], }自定义校验器收到的是整个表单 payloadformData因此天然支持跨字段联合校验。isRequired快捷方式对字段设置isRequired: true会自动在validations前部插入prepend一条required校验规则同时把isRequired传给 HDS 组件在标签上渲染星号。插入逻辑见 v2-form.ts只有当字段尚未包含type required的规则时才注入避免重复。校验时机字段变更即校验每次调用form.set()更新 payload 后立即对对应字段执行#validateField(propPath)同时触发#pruneHiddenFieldErrors()清理隐藏字段错误全部字段在提交前统一校验submit(api)先调用validateForm()仅校验可见字段校验失败则抛出Form validation failed不会调用config.submit隐藏字段自动豁免校验。常见问题排查Form configuration not found for: …—— 配置 key 未注册。请把它加入app/forms/v2/generated/index.ts或app/forms/v2/overrides/index.ts。对应异常抛出点在 get-form-config.ts。Operation … not found in openapi.json—— 方法名可能拼写错误或该操作属于 enterprise-only / 尚未纳入打包的 spec。请到node_modules/hashicorp/vault-client-typescript/openapi.json中核对确切的operationId。脚本内部用dasherize(methodName)把 camelCase 转成短横线形式再去匹配因此传入拼写不符的驼峰名会在此报错见 generate-form-config.js。Could not determine API class for …—— OpenAPI 操作缺少可识别的 tagsystem、auth、identity、secrets。可考虑改用手写配置。[Form::V2::Field] Unsupported field type …—— 配置中的type值不在受支持的FormElement联合类型中。对照上文的字段类型表修正即可。Section … not found—— 某个configBuilder方法使用了基配置中不存在的 section 名。可调用builder.getSections()检查现有 section 名。字段没有触发校验—— 确认字段上存在isRequired: true或validations数组。没有任何校验规则的字段永远被视为有效validateField对空规则集返回空错误列表。小结V2 表单系统为 Vault UI 提供了一条「OpenAPI 规范 → 类型化配置 → HDS 表单」的工业化通路脚手架生成器把 API 表面直接转成可编辑的配置骨架override 机制在不污染生成文件的前提下完成 UI 定制V2Form统一了状态、校验与提交流程而 wizard 则把多步骤、跨步骤共享数据的复杂交互收敛为一份声明式配置。对任何需要新增 Vault API 表单的开发者来说这套系统把「从零手写一个表单」降级为「生成、覆盖、接入」三个确定的步骤。若需要进一步深挖可以直接阅读 form-config.ts全部类型契约、v2-form.ts运行时状态机、override-field.tsbuilder 实现以及 generate-form-config.js脚手架主流程。【免费下载链接】vaultA tool for secrets management, encryption as a service, and privileged access management项目地址: https://gitcode.com/GitHub_Trending/va/vault创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考