Chaos Mesh UI 前后端代码同步方案：@ui/openapi 包如何将 OpenAPI 与 kubebuilder 标记自动生成 TypeScript API 客户端和 Formik 表单

云原生运维测试可观测性【免费下载链接】chaos-meshA Chaos Engineering Platform for Kubernetes.项目地址https://gitcode.com/gh_mirrors/ch/chaos-mesh点击查看免费下载Chaos Mesh 是一个面向 Kubernetes 的混沌工程平台其 Dashboard 前端ui/app需要为十余种 Chaos 类型AWSChaos、PodChaos、NetworkChaos 等渲染创建/编辑表单并调用大量后端 API。本文围绕仓库中 ui/packages/openapi/README.md 讲解ui/openapi这个代码生成包它如何利用 OpenAPI V2 规范一次性解决前后端代码同步与重复类型定义两大痛点把swagger.yaml自动翻译成可直接使用的 TypeScript API 客户端与 Formik 表单元数据。读完本文你将掌握该包的两个核心命令client与formik的执行链路、产物结构、表单字段映射规则以及ui:form:*标记如何从 Go 类型注释一路传递到前端表单的完整机制。动机为什么需要一个代码生成包前后端类型不同步的痛点在引入ui/openapi之前Chaos Mesh Dashboard 前端面临两类典型问题代码同步后端 API 与 Swagger 文档、前端调用代码需要手工保持一致任何字段变更都要跨仓库/跨目录同步极易遗漏重复类型定义同一个 Chaos 类型例如V1alpha1AWSChaosSpec既要在 Go 侧定义又要在 TypeScript 侧以接口形式重复书写形成双份维护负担。ui/openapi的思路是用代码生成代替手工同步——以 pkg/dashboard/swaggerdocs/swagger.yaml 为单一事实来源通过codegen命令自动产出前端所需的全部代码从根源上消除手写差异。TL;DR一句话概括本包通过codegen命令把后端 Swagger 描述自动转换成两样东西TypeScript 风格的 API 客户端供前端发请求使用Formik 表单元数据供前端动态渲染各类 Chaos 的配置表单。codegen 命令总览ui/openapi是一个 pnpm workspace 下的私有包见 ui/packages/openapi/package.jsonname: ui/openapiprivate: true入口脚本为 codegen.js使用yargs解析子命令。运行以下命令查看用法pnpm -F ui/openapi codegen -h输出如下codegen.js [command] Commands: codegen.js client generate API client by openapitools/openapi-generator-cli codegen.js formik convert the definitions generated by openapitools/openapi-generator-cli to Formik form data也就是说codegen暴露了三个子命令见 codegen.js 的yargs注册与switch分发逻辑子命令作用对应函数client由 orval 基于swagger.yaml生成 API 客户端runClient()formik基于生成的 TypeScript 类型定义生成 Formik 表单数据runFormik()all依次执行上面两步先生成客户端再生成表单runClient()runFormik()说明README 中描述client命令调用的是openapitools/openapi-generator-cli而当前仓库的 codegen.js 实际已改用orvalimport { generate as orval } from orval并在 orval.config.ts 中通过defineConfig配置生成行为。这与 README 存在版本演进差异本文以当前源码为准。client从 OpenAPI 到 TypeScript API 客户端执行流程client子命令的完整链路如下对应 codegen.js 中的runClient()拷贝 Swagger 文件将pkg/dashboard/swaggerdocs/swagger.yaml复制到包目录下的./swagger.yaml清洗模块前缀读取该文件用正则github_com_chaos-mesh_chaos-mesh.*_去掉 Go 包路径前缀这类前缀会污染生成的标识符再写回./swagger.yaml调用 orval 生成执行orval(./orval.config.ts)依据 orval.config.ts 的配置产出代码清理临时文件生成结束后用rimraf删除临时./swagger.yaml——这正是 README 中At the end of the generation, this file will be deleted的行为。orval 生成配置解读orval.config.ts 中值得关注的配置项input./swagger.yaml即上一步清洗后的 OpenAPI 文件output.modesplit按模块拆分输出文件output.clientreact-query生成基于 TanStack React Query 的 hooks而不是 README 时代的typescript-axiosoutput.httpClientaxios底层 HTTP 库output.target../../app/src/openapi/index.ts输出入口mutator指向../../app/src/api/http.ts的customInstance即前端自定义的 axios 实例鉴权、拦截器等逻辑集中于此query配置retry: 1、retryDelay: 3000的查询重试策略mock开启 mock 支持mock: truedelay: 0required: true。生成产物输出目录为 ui/app/src/openapi当前包含三个文件index.tsAPI 客户端入口由 orval 生成包含各模块方法与 react-query hooksindex.schemas.tsOpenAPI 定义对应的 TypeScript 接口/类型是下一步formik命令的输入index.msw.ts基于 MSWMock Service Worker的接口 mock。前端业务代码直接 import 这些产物发起请求后端接口的任何变更只需重新运行codegen client即可同步到前端。formik从 TypeScript 类型到 Formik 表单元数据formik子命令的核心是 index.js 中的genForms(source)函数输入为ui/app/src/openapi/index.schemas.ts见 codegen.js 的runFormik()。生成哪些文件对以下 12 种 Chaos 类型每种生成一个表单数据文件输出到 ui/app/src/formikAWSChaos、DNSChaos、GCPChaos、HTTPChaos、IOChaos、JVMChaos、 KernelChaos、NetworkChaos、PhysicalMachineChaos、PodChaos、 StressChaos、TimeChaos对应产物为AWSChaos.ts、PodChaos.ts等 12 个文件外加一个汇总所有 action 的actions.ts。查找 Spec 的方式genForms用 TypeScript Compiler API 建立程序ts.createProgram([source], ...)然后过滤出所有InterfaceDeclarationindex.schemas.ts中的接口按约定命名V1alpha1${child}Spec查找对应 Spec 接口例如V1alpha1PodChaosSpec见 index.js遍历该接口的属性签名跳过ignores列表selector、mode、value、duration、uid定义于 constants.js若属性是action则从注释中提取所有可选动作否则调用nodeToField生成表单字段对象。生成的表单数据示例以 AWSChaos 为例ui/app/src/formik/AWSChaos.ts 生成内容形如/** * This file was auto-generated by ui/openapi. * Do not make direct changes to the file. */ export const actions [ec2-stop, ec2-restart, detach-volume], data [ { field: text, label: awsRegion, value: , helperText: AWSRegion defines the region of aws., }, { field: text, label: deviceName, value: , helperText: Optional. DeviceName indicates the name of the device. Needed in detach-volume., when: actiondetach-volume, }, { field: text, label: ec2Instance, value: , helperText: Ec2Instance indicates the ID of the ec2 instance., }, { field: text, label: secretName, value: , helperText: Optional. SecretName defines the name of kubernetes secret., }, { field: text, label: volumeID, value: , helperText: Optional. EbsVolume indicates the ID of the EBS volume. Needed in detach-volume., when: actiondetach-volume, }, ]每个字段对象包含属性含义field渲染控件类型text/number/select/label/numbers/text-text/text-label/reflabel字段名对应 Spec 的属性名value初始值由类型推导见下文helperText来自 Go 侧 jsdoc 注释的帮助文案items下拉选项枚举或布尔值的true/falsewhen条件表达式例如actiondetach-volume用于按 action 动态显示字段childrenref类型的嵌套子字段对应 Go 中的嵌套结构体actions与data两个导出值共同驱动前端表单渲染README 原话We will use theactionsanddatafields to render the form in the interface。再看一个实际产物 ui/app/src/formik/PodChaos.tsexport const actions [pod-kill, pod-failure, container-kill], data [ { field: label, label: containerNames, value: [], helperText: Optional. ContainerNames indicates list of the name of affected container. If not set, the first container will be injected, }, { field: number, label: gracePeriod, value: 0, helperText: Optional. GracePeriod is used in pod-kill action. It represents the duration in seconds before the pod should be deleted. Value must be non-negative integer. The default value is zero that indicates delete immediately., }, { field: text, label: remoteCluster, value: , helperText: Optional. RemoteCluster represents the remote cluster where the chaos will be deployed, }, ]TypeScript 类型到表单字段的映射规则映射规则集中在 factory.js 的typeTextToFieldType与typeTextToInitialValue两个函数中并被 factory.test.js 的单元测试逐条验证TypeScript 类型field初始值valuestringtextnumbernumber0booleanselectfalseitems为[true, false]string[]label[]number[]numbers[]string[][]text-label{}{ [key: string]: string }text-text{}{ [key: string]: string[] }text-label{}V1alpha1XXX[]label[]枚举类型selectitems为枚举值列表结构体引用ref递归生成children子字段对于结构体引用TypeReferencetypeReferenceToObjectLiteralExpressionfactory.js会递归展开其成员若成员类型本身又是类型引用则继续嵌套V1alpha1Frame[]这类非原始类型数组会被标记为multiple: true的ref字段用于渲染可增删的重复子结构。注释标记的解析规则生成器会读取 Go 侧 jsdoc 注释中的ui:form:*系列标记解析逻辑位于 utils.js并被 utils.test.js 覆盖标记正则作用ui:form:enuma;b;c\ui:form:enum(.)\s提取 action 枚举值用;分隔kubebuilder:validation:Enuma;b;c\kubebuilder:validation:Enum(.)\s?兼容 kubebuilder 枚举标记同样可提取枚举ui:form:whenactiondetach-volume\ui:form:when(.)\s生成字段的when条件表达式换行会被替换为空格ui:form:ignore\ui:form:ignore\s跳过该字段不生成表单项getUIFormEnum会优先匹配ui:form:enum其次回退到kubebuilder:validation:EnumcleanMarkers则负责把ui:form:when、kubebuilder...等标记从注释中剥离并把optional改写成 Optional. 前缀对应测试cleanMarkers(DeviceName ... ui:form:when... optional)输出为Optional. DeviceName indicates the name of the device.。这些标记的真实来源是 API 类型定义例如 api/v1alpha1/awschaos_types.go 中// ui:form:ignore ... // ui:form:whenactiondetach-volume // DeviceName indicates the name of the device. Needed in detach-volume. // optional DeviceName string json:deviceName,omitempty类似的标记还出现在 gcpchaos_types.go、iochaos_types.go、physical_machine_chaos_types.go 等多个类型文件中——可以说表单的智能哪些字段随 action 动态出现、哪些字段被隐藏、下拉选项是什么完全由 Go 类型注释驱动前端无需再维护一份规则。生成的表单数据如何被前端消费生成的formik/*.ts文件并非静态死代码而是被 Dashboard 的表单组件动态加载。以 ui/app/src/components/AutoForm/index.tsx 为例const { data }: { data: AtomFormData[] } await import(../../formik/${kind}.ts) const form action ? data.filter((d) { if (kind NetworkChaos d.label target) { return false // 某些 selector 暂不支持忽略 target } if (d.when) { const parsed parse(d.when) return expEval(parsed, { action }) // 根据当前 action 求值 when 表达式 } return true }) : data setInitialValues((oldValues) _.merge({}, oldValues, formikProps.initialValues || formToRecords(form))) setForm(form)关键点通过import(\../../formik/${kind}.ts)按 Chaos 类型动态加载对应的表单元数据当用户选择了某个action后组件用表达式求值器对d.when如actiondetach-volume求值只保留当前动作相关的字段formToRecords会把data数组转换为 Formik 的initialValues对象ref类型递归展开multiple字段转成数组渲染阶段同文件 index.tsx 的renderForm根据field值分发到不同控件text/number渲染TextFieldselect渲染SelectFieldlabel渲染多选AutocompleteFieldtext-text/text-label渲染TextTextFieldref渲染带Chip删除能力的嵌套区块。另外ui/app/src/components/NewWorkflowNext/Elements/Kubernetes.tsx 与 PhysicalNodes.tsx 会直接import _actions from /formik/actions用actions.ts中汇总的各类 Chaos 动作列表来渲染工作流编排页面的节点选项。端到端数据流小结把整条链路串起来api/v1alpha1/*.go含 ui:form:* 注释 │ controller-gen 生成 CRD 与 OpenAPI 描述 ▼ pkg/dashboard/swaggerdocs/swagger.yaml │ codegen client拷贝 → 清洗模块前缀 → orval ▼ ui/app/src/openapi/index.schemas.tsTypeScript 类型 index.tsAPI 客户端 │ codegen formikTS Compiler API 解析 字段映射 ▼ ui/app/src/formik/{AWSChaos,...}.ts表单元数据 actions.ts │ AutoForm/index.tsx 动态 import when 表达式求值 ▼ Dashboard 上的 Chaos 创建/编辑表单这条流水线的收益是改 Go 类型注释 → 重新生成 → 前端表单与 API 客户端自动更新任何一次codegen都能同时刷新 ui/app/src/openapi 与 ui/app/src/formik 两套产物从机制上消灭手写类型不一致。如何参与贡献通过 Pull Request 提交改动或在 Issue 中描述问题推荐的 PR/Issue 标题格式xxx(ui/openapi): xxx便于在 changelog 与评审流中快速识别该包的变更与 ui/packages/openapi/package.json 的包名对应若修改了 factory.js 或 utils.js 等生成逻辑请同步运行pnpm -F ui/openapi testjest验证 factory.test.js 与 utils.test.js 中的映射规则与标记解析行为。License与 Chaos Mesh 主体一致遵循 Apache License 2.0源码文件头均含 Copyright 与 License 声明。赞分享云原生运维测试可观测性【免费下载链接】chaos-meshA Chaos Engineering Platform for Kubernetes.项目地址https://gitcode.com/gh_mirrors/ch/chaos-mesh点击查看免费下载相关推荐FastEndpoints客户端生成终极指南如何自动生成TypeScript和C客户端代码FastEndpoints客户端生成终极指南如何自动生成TypeScript和C 客户端代码 想要快速为你的ASP.NET Core API项目生成类型后端Web框架API设计OpenAPI Generator 终极指南如何快速生成API客户端与服务端代码OpenAPI Generator 终极指南如何快速生成API客户端与服务端代码 OpenAPI Generator 是一款强大的开源工具能够根据OpenA开发工具代码生成API设计CLI如何快速上手OpenAPI Generator自动生成API客户端与服务端代码的完整指南如何快速上手OpenAPI Generator自动生成API客户端与服务端代码的完整指南 OpenAPI Generator是一个强大的开源工具能够根据Op开发工具代码生成API设计CLI上一篇LKMPG认证讲师成为内核培训师的路径下一篇MEV-template-rs错误处理与监控构建稳定运行的MEV机器人系统创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考