Unleash 前端开发指南从本地联调到 OpenAPI 客户端生成与 E2E 测试【免费下载链接】unleashOpen-source feature management platform项目地址: https://gitcode.com/GitHub_Trending/un/unleashUnleash 是开源的功能开关feature flag管理平台其仓库中的frontend/目录承载着全部管理员界面Admin UI前端应用。本文以 frontend/README.md 为主线系统梳理该前端的本地运行方式、远程 API 沙箱联调、端到端测试的启动与调试以及基于 OpenAPI 规范生成类型化客户端的方法并结合仓库源码与配置文件补充背后的实现细节帮助你快速上手 Unleash 前端的日常开发与验证流程。目录结构与技术栈概览在深入运行方式之前先了解frontend/目录的整体构成。从仓库结构看该目录包含src/前端源码其中component/下约 2000 个组件文件以.tsx/.ts为主hooks/、utils/、interfaces/等目录分别承载数据获取、工具函数与类型定义src/openapi/由后端 OpenAPI 规范生成的类型定义models/以及统一的fetcher.ts与index.tscypress/端到端测试按oss/开源版与enterprise/企业版拆分覆盖 feature、segments、groups、projects 等核心页面vite.config.mtsVite 构建与开发服务器配置同时内嵌 Vitest 测试配置orval.config.tsOpenAPI 客户端生成器的配置package.json全部脚本与依赖声明前端包名unleash-frontend-local要求 Node 22使用 pnpm 管理依赖。从 frontend/package.json 的依赖可以确认技术选型React 19 TypeScript Vite 8 作为构建基础MUIMaterial UI提供组件体系SWR 负责数据请求Cypress 承担 E2E 测试Vitest Testing Library 负责单元测试。这些细节在后续各章节中会逐一体现。本地开发环境与 unleash-api 同时运行前置准备按照 contributing/CONTRIBUTING.md 的 How to run the project 一节本地运行需要Node.js22 及以上仓库engines字段同样声明node 22pnpm推荐使用仓库锁定packageManager: pnpm11.15.1Docker用于启动 Postgres 数据库PostgreSQL 14。启动流程在仓库根目录执行pnpm install pnpm dev这一组合命令会同时启动两个开发服务器前端开发服务器端口3000由 vite.config.mts 中server.port: 3000定义后端开发服务器端口4242Unleash API 的默认端口。前端通过 Vite 的server.proxy将/api、/auth、/logout、/health、/invite、/edge等路径代理到后端目标地址默认目标即http://localhost:4242const UNLEASH_API process.env.UNLEASH_API || http://localhost:4242; // ... server: { open: true, host: true, port: 3000, proxy: { [${UNLEASH_BASE_PATH}api]: { target: UNLEASH_API, changeOrigin: true }, [${UNLEASH_BASE_PATH}auth]: { target: UNLEASH_API, changeOrigin: true }, // ... }, },这意味着浏览器只访问localhost:3000涉及鉴权与业务数据的请求会被 Vite 透明转发给后端从而避免跨域问题。UNLEASH_BASE_PATH默认是/且必须以/开头和结尾否则启动时会直接报错退出。登录凭据后端默认创建一个管理员账号登录localhost:3000时使用用户名admin密码unleash4allCypress 配置frontend/cypress.config.ts中的AUTH_USERadmin, AUTH_PASSWORDunleash4all与之一致说明这组凭据同样被 E2E 测试使用。使用远程沙箱实例联调前端如果不想在本地跑起整个 unleash-api包括数据库与后端进程可以改用远程沙箱 API。进入前端目录执行cd ./frontend pnpm install pnpm run start:sandboxstart:sandbox脚本定义在 frontend/package.jsonstart:sandbox: UNLEASH_APIhttps://sandbox.getunleash.io/ VITE_TEST_REDIRECTtrue UNLEASH_BASE_PATH/pro/ pnpm run start它通过环境变量把前端的 API 目标指向远程实例同时指定了基础路径/pro/。Vite 启动后UNLEASH_API会作为代理目标UNLEASH_BASE_PATH会成为应用挂载的基础路径对应vite.config.mts中base: UNLEASH_BASE_PATH。仓库还提供了其他沙箱变体可按需选用脚本环境变量用途start:sandboxUNLEASH_APIhttps://sandbox.getunleash.io/UNLEASH_BASE_PATH/pro/对接开源沙箱VITE_TEST_REDIRECTtruestart:sandbox:enterprise同沙箱地址UNLEASH_BASE_PATH/enterprise/对接企业版沙箱start:demoUNLEASH_APIhttps://app.unleash-hosted.com/UNLEASH_BASE_PATH/demo/对接托管演示实例start:demo2UNLEASH_APIhttps://sandbox.getunleash.io/UNLEASH_BASE_PATH/demo2/对接演示环境这种“后端在别处、前端在本地”的开发模式非常适合前端开发者在不需要修改后端逻辑时快速验证 UI 效果。针对 localhost 的端到端测试标准流程E2E 测试使用 Cypress全部 spec 文件位于 frontend/cypress 目录按oss/开源版与enterprise/企业版分类。测试在仓库根目录执行以下命令pnpm build:frontend pnpm dev:start这两个命令分别完成前端构建与后端构建产物的一体化启动。随后运行测试pnpm run e2ee2e脚本实际执行e2e:osse2e: pnpm run e2e:oss, e2e:oss: pnpm run cypress:run --config baseUrlhttp://localhost:4242 --spec \cypress/oss/**/*.spec.ts\注意baseUrl指向4242后端端口且e2e:oss只运行cypress/oss/下的 spece2e:enterprise则不加--spec限制运行全部测试包括cypress/enterprise/。企业版测试如果你开发的功能涉及企业版enterprise能力需要启动企业版后端并运行对应测试套件pnpm run start:enterprise pnpm run e2e:enterprise调试 E2E 测试在开发过程中调试单个测试时建议使用开发构建而不是生产构建。仓库 README 特别提醒对开发版前端跑 E2E 会明显变慢可能慢 5 倍以上因此最佳实践是打开 Cypress 交互界面只挑选当前正在开发的测试用例运行。调试步骤如下在仓库根目录以开发模式同时启动前后端例如pnpm dev前端 3000、后端 4242在前端目录执行pnpm e2e:dev:open该脚本对应e2e:dev:open: pnpm run cypress:open --config baseUrlhttp://localhost:3000它把baseUrl指向前端开发服务器3000 端口并打开 Cypress 图形界面cypress open便于逐条运行与断点式调试。相比之下e2e:open则针对生产/后端地址4242。Cypress 的整体行为由 frontend/cypress.config.ts 控制其中值得留意的默认值包括viewportWidth: 1920、viewportHeight: 1080、runMode下失败重试 1 次、测试失败自动截图并录制视频以及通过cypress-vite预处理器让 Cypress 直接复用vite.config.mts编译测试代码。E2E 支持层frontend/cypress/support 目录提供了API.ts、UI.ts、commands.ts、e2e.ts、index.ts等支持文件用于封装 API 调用与 UI 交互的通用命令cypress/oss/demo/demo.spec.ts、cypress/oss/feature/feature.spec.ts、cypress/oss/segments/segments.spec.ts分别是演示、功能开关与分段segments的测试入口。若测试需要指向其他端口如迁移验证场景可用e2e:migrations脚本它通过EXPOSED_PORT环境变量默认 4242决定baseUrl。生成 OpenAPI 客户端为什么需要生成Unleash 前端与后端通过 REST API 通信前端使用由后端 OpenAPI 规范生成的类型化客户端保证前后端数据结构一致、接口变更可被编译器及时捕获。当前仓库的策略是只使用生成的类型src/openapi/models定义请求/响应数据结构方法层src/openapi/apis暂未启用未来新特性会逐步迁移使用。这一点在 orval.config.ts 的注释与 frontend/README.md 中均有明确说明。生成命令每当后端 API 发生变更都需要重新生成客户端pnpm gen:api rm -rf src/openapi/apis然后清理src/openapi/index.ts的导入只保留第一行export * from ./models;仓库还提供了封装好的脚本gen:api:clean一步完成上述三件事gen:api:clean: pnpm run gen:api rm -rf src/openapi/apis sed -i.bak 1q src/openapi/index.ts rm src/openapi/index.ts.bak当前仓库的 src/openapi/index.ts 实际内容为export * from ./models/index;与文档描述的清理后状态一致。配置与数据源生成器基于 Orval配置见 orval.config.ts输入process.env.UNLEASH_OPENAPI_URL || http://localhost:4242/docs/openapi.json即默认从本地 4242 端口的运行时 OpenAPI 文档生成输出src/openapi工作区模式为tags类型输出到models/方法输出到apis/客户端swr与前端的数据请求方案一致自定义请求器./fetcher.ts中的fetcher属性排序Alphabetical收尾钩子afterAllFilesWrite执行 scripts/clean_orval_generated.sh该脚本会删除生成的apis目录、将index.ts重置为仅导出 models、并运行 lint 与 Biome 格式化。该脚本假定你有一个运行在http://localhost:4242的实例文档说明可以是企业版后端因为企业版暴露了更完整的 OpenAPI 规范生成结果来自该实例的运行时 schema。如需更换来源设置环境变量即可UNLEASH_OPENAPI_URLhttps://your-instance/docs/openapi.json pnpm run gen:api仓库同样预置了针对托管与沙箱实例的变体gen:api:demohttps://app.unleash-hosted.com/demo/docs/openapi.json与gen:api:sandboxhttps://sandbox.getunleash.io/demo2/docs/openapi.json。分析打包体积当需要排查前端产物体积时在frontend/目录下运行npx vite-bundle-visualizer该工具会基于 Vite 构建产物生成依赖与 chunk 的可视化分析帮助定位体积异常的模块。构建相关的关键配置位于 vite.config.mts产物输出到build/静态资源放到static/开发模式下开启 sourcemap此外还有针对mui/icons-material深路径导入的 ESM 重定向插件以及开发模式下注入的 Emotion Babel 插件用于组件样式标签命名。前端质量门禁与常用脚本frontend/package.json 中定义了一套完整的质量保障脚本贯穿本地开发与 CI命令作用pnpm dev/pnpm start启动 Vite 开发服务器端口 3000pnpm build先执行lint:material:icons校验 MUI 图标导入规范见 check-imports.rc再执行vite buildpnpm lint使用 Biome 检查代码biome check . --error-on-warningspnpm lint:fixBiome 自动修复pnpm ts:checkTypeScript 类型检查tscpnpm testVitest 单元测试vitest runtest:watch为监听模式pnpm ciCI 一体化流程lint 修复 类型检查 构建 测试单元测试配置同样内嵌于 vite.config.mts 的vitestConfig使用jsdom环境、全局模式、setupFiles: src/setupTests.ts、超时 30 秒并排除cypress目录。小结与最佳实践综合 frontend/README.md 与仓库源码Unleash 前端开发的推荐工作流可以归纳为日常 UI 开发根目录pnpm install pnpm dev前后端分别在 3000/4242 端口联动登录admin / unleash4all仅改前端进入frontend/执行pnpm run start:sandbox对接远程 API 避免本地起后端验证功能根目录构建并启动后运行pnpm run e2e开源版或pnpm run e2e:enterprise企业版单测调试用pnpm e2e:dev:open打开 Cypress UI注意开发模式下测试速度会明显下降后端 API 变更后在本地 4242 运行实例的前提下执行pnpm gen:api或一键脚本gen:api:clean同步更新src/openapi/models类型提交前依次通过pnpm lint、pnpm ts:check、pnpm test、pnpm build的质量门禁。理解这些脚本背后对应的 Vite 代理配置、Orval 生成规则与 Cypress 运行参数能让你在遇到端口、鉴权、类型不同步等问题时快速定位根因更高效地参与 Unleash 前端的开发与维护。【免费下载链接】unleashOpen-source feature management platform项目地址: https://gitcode.com/GitHub_Trending/un/unleash创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考 Unleash 前端开发指南：从本地联调到 OpenAPI 客户端生成与 E2E 测试
Unleash 前端开发指南从本地联调到 OpenAPI 客户端生成与 E2E 测试【免费下载链接】unleashOpen-source feature management platform项目地址: https://gitcode.com/GitHub_Trending/un/unleashUnleash 是开源的功能开关feature flag管理平台其仓库中的frontend/目录承载着全部管理员界面Admin UI前端应用。本文以 frontend/README.md 为主线系统梳理该前端的本地运行方式、远程 API 沙箱联调、端到端测试的启动与调试以及基于 OpenAPI 规范生成类型化客户端的方法并结合仓库源码与配置文件补充背后的实现细节帮助你快速上手 Unleash 前端的日常开发与验证流程。目录结构与技术栈概览在深入运行方式之前先了解frontend/目录的整体构成。从仓库结构看该目录包含src/前端源码其中component/下约 2000 个组件文件以.tsx/.ts为主hooks/、utils/、interfaces/等目录分别承载数据获取、工具函数与类型定义src/openapi/由后端 OpenAPI 规范生成的类型定义models/以及统一的fetcher.ts与index.tscypress/端到端测试按oss/开源版与enterprise/企业版拆分覆盖 feature、segments、groups、projects 等核心页面vite.config.mtsVite 构建与开发服务器配置同时内嵌 Vitest 测试配置orval.config.tsOpenAPI 客户端生成器的配置package.json全部脚本与依赖声明前端包名unleash-frontend-local要求 Node 22使用 pnpm 管理依赖。从 frontend/package.json 的依赖可以确认技术选型React 19 TypeScript Vite 8 作为构建基础MUIMaterial UI提供组件体系SWR 负责数据请求Cypress 承担 E2E 测试Vitest Testing Library 负责单元测试。这些细节在后续各章节中会逐一体现。本地开发环境与 unleash-api 同时运行前置准备按照 contributing/CONTRIBUTING.md 的 How to run the project 一节本地运行需要Node.js22 及以上仓库engines字段同样声明node 22pnpm推荐使用仓库锁定packageManager: pnpm11.15.1Docker用于启动 Postgres 数据库PostgreSQL 14。启动流程在仓库根目录执行pnpm install pnpm dev这一组合命令会同时启动两个开发服务器前端开发服务器端口3000由 vite.config.mts 中server.port: 3000定义后端开发服务器端口4242Unleash API 的默认端口。前端通过 Vite 的server.proxy将/api、/auth、/logout、/health、/invite、/edge等路径代理到后端目标地址默认目标即http://localhost:4242const UNLEASH_API process.env.UNLEASH_API || http://localhost:4242; // ... server: { open: true, host: true, port: 3000, proxy: { [${UNLEASH_BASE_PATH}api]: { target: UNLEASH_API, changeOrigin: true }, [${UNLEASH_BASE_PATH}auth]: { target: UNLEASH_API, changeOrigin: true }, // ... }, },这意味着浏览器只访问localhost:3000涉及鉴权与业务数据的请求会被 Vite 透明转发给后端从而避免跨域问题。UNLEASH_BASE_PATH默认是/且必须以/开头和结尾否则启动时会直接报错退出。登录凭据后端默认创建一个管理员账号登录localhost:3000时使用用户名admin密码unleash4allCypress 配置frontend/cypress.config.ts中的AUTH_USERadmin, AUTH_PASSWORDunleash4all与之一致说明这组凭据同样被 E2E 测试使用。使用远程沙箱实例联调前端如果不想在本地跑起整个 unleash-api包括数据库与后端进程可以改用远程沙箱 API。进入前端目录执行cd ./frontend pnpm install pnpm run start:sandboxstart:sandbox脚本定义在 frontend/package.jsonstart:sandbox: UNLEASH_APIhttps://sandbox.getunleash.io/ VITE_TEST_REDIRECTtrue UNLEASH_BASE_PATH/pro/ pnpm run start它通过环境变量把前端的 API 目标指向远程实例同时指定了基础路径/pro/。Vite 启动后UNLEASH_API会作为代理目标UNLEASH_BASE_PATH会成为应用挂载的基础路径对应vite.config.mts中base: UNLEASH_BASE_PATH。仓库还提供了其他沙箱变体可按需选用脚本环境变量用途start:sandboxUNLEASH_APIhttps://sandbox.getunleash.io/UNLEASH_BASE_PATH/pro/对接开源沙箱VITE_TEST_REDIRECTtruestart:sandbox:enterprise同沙箱地址UNLEASH_BASE_PATH/enterprise/对接企业版沙箱start:demoUNLEASH_APIhttps://app.unleash-hosted.com/UNLEASH_BASE_PATH/demo/对接托管演示实例start:demo2UNLEASH_APIhttps://sandbox.getunleash.io/UNLEASH_BASE_PATH/demo2/对接演示环境这种“后端在别处、前端在本地”的开发模式非常适合前端开发者在不需要修改后端逻辑时快速验证 UI 效果。针对 localhost 的端到端测试标准流程E2E 测试使用 Cypress全部 spec 文件位于 frontend/cypress 目录按oss/开源版与enterprise/企业版分类。测试在仓库根目录执行以下命令pnpm build:frontend pnpm dev:start这两个命令分别完成前端构建与后端构建产物的一体化启动。随后运行测试pnpm run e2ee2e脚本实际执行e2e:osse2e: pnpm run e2e:oss, e2e:oss: pnpm run cypress:run --config baseUrlhttp://localhost:4242 --spec \cypress/oss/**/*.spec.ts\注意baseUrl指向4242后端端口且e2e:oss只运行cypress/oss/下的 spece2e:enterprise则不加--spec限制运行全部测试包括cypress/enterprise/。企业版测试如果你开发的功能涉及企业版enterprise能力需要启动企业版后端并运行对应测试套件pnpm run start:enterprise pnpm run e2e:enterprise调试 E2E 测试在开发过程中调试单个测试时建议使用开发构建而不是生产构建。仓库 README 特别提醒对开发版前端跑 E2E 会明显变慢可能慢 5 倍以上因此最佳实践是打开 Cypress 交互界面只挑选当前正在开发的测试用例运行。调试步骤如下在仓库根目录以开发模式同时启动前后端例如pnpm dev前端 3000、后端 4242在前端目录执行pnpm e2e:dev:open该脚本对应e2e:dev:open: pnpm run cypress:open --config baseUrlhttp://localhost:3000它把baseUrl指向前端开发服务器3000 端口并打开 Cypress 图形界面cypress open便于逐条运行与断点式调试。相比之下e2e:open则针对生产/后端地址4242。Cypress 的整体行为由 frontend/cypress.config.ts 控制其中值得留意的默认值包括viewportWidth: 1920、viewportHeight: 1080、runMode下失败重试 1 次、测试失败自动截图并录制视频以及通过cypress-vite预处理器让 Cypress 直接复用vite.config.mts编译测试代码。E2E 支持层frontend/cypress/support 目录提供了API.ts、UI.ts、commands.ts、e2e.ts、index.ts等支持文件用于封装 API 调用与 UI 交互的通用命令cypress/oss/demo/demo.spec.ts、cypress/oss/feature/feature.spec.ts、cypress/oss/segments/segments.spec.ts分别是演示、功能开关与分段segments的测试入口。若测试需要指向其他端口如迁移验证场景可用e2e:migrations脚本它通过EXPOSED_PORT环境变量默认 4242决定baseUrl。生成 OpenAPI 客户端为什么需要生成Unleash 前端与后端通过 REST API 通信前端使用由后端 OpenAPI 规范生成的类型化客户端保证前后端数据结构一致、接口变更可被编译器及时捕获。当前仓库的策略是只使用生成的类型src/openapi/models定义请求/响应数据结构方法层src/openapi/apis暂未启用未来新特性会逐步迁移使用。这一点在 orval.config.ts 的注释与 frontend/README.md 中均有明确说明。生成命令每当后端 API 发生变更都需要重新生成客户端pnpm gen:api rm -rf src/openapi/apis然后清理src/openapi/index.ts的导入只保留第一行export * from ./models;仓库还提供了封装好的脚本gen:api:clean一步完成上述三件事gen:api:clean: pnpm run gen:api rm -rf src/openapi/apis sed -i.bak 1q src/openapi/index.ts rm src/openapi/index.ts.bak当前仓库的 src/openapi/index.ts 实际内容为export * from ./models/index;与文档描述的清理后状态一致。配置与数据源生成器基于 Orval配置见 orval.config.ts输入process.env.UNLEASH_OPENAPI_URL || http://localhost:4242/docs/openapi.json即默认从本地 4242 端口的运行时 OpenAPI 文档生成输出src/openapi工作区模式为tags类型输出到models/方法输出到apis/客户端swr与前端的数据请求方案一致自定义请求器./fetcher.ts中的fetcher属性排序Alphabetical收尾钩子afterAllFilesWrite执行 scripts/clean_orval_generated.sh该脚本会删除生成的apis目录、将index.ts重置为仅导出 models、并运行 lint 与 Biome 格式化。该脚本假定你有一个运行在http://localhost:4242的实例文档说明可以是企业版后端因为企业版暴露了更完整的 OpenAPI 规范生成结果来自该实例的运行时 schema。如需更换来源设置环境变量即可UNLEASH_OPENAPI_URLhttps://your-instance/docs/openapi.json pnpm run gen:api仓库同样预置了针对托管与沙箱实例的变体gen:api:demohttps://app.unleash-hosted.com/demo/docs/openapi.json与gen:api:sandboxhttps://sandbox.getunleash.io/demo2/docs/openapi.json。分析打包体积当需要排查前端产物体积时在frontend/目录下运行npx vite-bundle-visualizer该工具会基于 Vite 构建产物生成依赖与 chunk 的可视化分析帮助定位体积异常的模块。构建相关的关键配置位于 vite.config.mts产物输出到build/静态资源放到static/开发模式下开启 sourcemap此外还有针对mui/icons-material深路径导入的 ESM 重定向插件以及开发模式下注入的 Emotion Babel 插件用于组件样式标签命名。前端质量门禁与常用脚本frontend/package.json 中定义了一套完整的质量保障脚本贯穿本地开发与 CI命令作用pnpm dev/pnpm start启动 Vite 开发服务器端口 3000pnpm build先执行lint:material:icons校验 MUI 图标导入规范见 check-imports.rc再执行vite buildpnpm lint使用 Biome 检查代码biome check . --error-on-warningspnpm lint:fixBiome 自动修复pnpm ts:checkTypeScript 类型检查tscpnpm testVitest 单元测试vitest runtest:watch为监听模式pnpm ciCI 一体化流程lint 修复 类型检查 构建 测试单元测试配置同样内嵌于 vite.config.mts 的vitestConfig使用jsdom环境、全局模式、setupFiles: src/setupTests.ts、超时 30 秒并排除cypress目录。小结与最佳实践综合 frontend/README.md 与仓库源码Unleash 前端开发的推荐工作流可以归纳为日常 UI 开发根目录pnpm install pnpm dev前后端分别在 3000/4242 端口联动登录admin / unleash4all仅改前端进入frontend/执行pnpm run start:sandbox对接远程 API 避免本地起后端验证功能根目录构建并启动后运行pnpm run e2e开源版或pnpm run e2e:enterprise企业版单测调试用pnpm e2e:dev:open打开 Cypress UI注意开发模式下测试速度会明显下降后端 API 变更后在本地 4242 运行实例的前提下执行pnpm gen:api或一键脚本gen:api:clean同步更新src/openapi/models类型提交前依次通过pnpm lint、pnpm ts:check、pnpm test、pnpm build的质量门禁。理解这些脚本背后对应的 Vite 代理配置、Orval 生成规则与 Cypress 运行参数能让你在遇到端口、鉴权、类型不同步等问题时快速定位根因更高效地参与 Unleash 前端的开发与维护。【免费下载链接】unleashOpen-source feature management platform项目地址: https://gitcode.com/GitHub_Trending/un/unleash创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考