Hasura Console 前端开发指南：基于 Nx 的 GraphQL Engine 管理控制台工程实践-平芜编程栈

Hasura Console 前端开发指南：基于 Nx 的 GraphQL Engine 管理控制台工程实践

【免费下载链接】graphql-engineBlazing fast, instant realtime GraphQL APIs on all your data with fine grained access control, also trigger webhooks on database events.项目地址: https://gitcode.com/gh_mirrors/gr/graphql-engine

本指南以 graphql-engine 仓库的 frontend/README.md 为骨架，系统讲解 Hasura Console（GraphQL Engine 的 Web 管理控制台）前端工程的架构、开发环境搭建、开发服务器启动、构建、测试与代码规范。读完本文，你将掌握在一个 Nx 单仓库（monorepo）中搭建并调试 Hasura Console（含 CE / EE 多应用形态）的完整工作流，并理解server与cli两种运行模式及其环境变量体系。

一、工程定位：Hasura Console 是什么

Hasura Console 是用于管理已连接数据库、并在浏览器中直接试用 GraphQL API 的管理员仪表盘。根据 frontend/README.md 与 frontend/docs/generic-info.md 的描述：

它是一个React 应用，使用Webpack打包；
应用状态主要由 Redux 管理（仓库 frontend/package.json 中可见redux@4.1.0、react-redux@7.2.4、redux-thunk@2.3.0、reselect等依赖）；
它运行在 GraphQL Engine 的/console端点（服务端启用--enable-console标志时），或由 Hasura CLI 的hasura console命令托管。

Console 的典型职责包括：管理表结构（schema）、配置权限（permissions）、编写并执行 GraphQL 查询与变更、管理 actions、事件触发器（event triggers）、定时触发器（scheduled triggers）、远程 schema（remote schemas）等。这些能力在 frontend/apps/console-ce-e2e/src/e2e 的端到端测试目录中都能找到对应的覆盖场景（actions、cron-triggers、event-triggers、remote-schemas、table-permission-input-validation等）。

整个frontend目录本身是一个Nx 工作区（monorepo）：README 开篇即说明"This project was generated using Nx"，其中容纳了 Hasura Console 的所有形态——社区版（CE）、企业版（EE）以及对应的端到端测试应用。

二、仓库结构：apps 与 libs 的划分

Nx 工作区遵循"应用（apps）+ 库（libs）"的组织方式。frontend/docs/from-previous-console.md 给出了一个关键的心智模型：应用是"容器"，负责链接、打包并编译库中实现的功能以便部署；因此约80% 的业务逻辑应放在libs/目录，而apps/只保留约 20% 的装配代码。这些库不需要单独构建，而是直接被应用引用并随应用一起构建，因此从纯部署角度而言没有任何差异。

2.1 apps 目录

从 frontend/apps 的实际结构看，工作区包含以下应用：

应用	作用
`console-ce`	社区版 Console 应用（一个较"空"的壳，承载 CE Console 的全局样式与入口，见`apps/console-ce/src/index.html`、`main.tsx`）
`console-ce-e2e`	CE Console 的 Cypress 端到端测试应用
`console-ee`	企业版 Console 应用（结构与`console-ce`平行）
`console-ee-e2e`	EE Console 的 Cypress 端到端测试应用
`nx`	Nx 内部插件自身的端到端测试（`internal-plugin-e2e`）

其中console-ce与console-ee是"空壳"这一点，在迁移文档中有明确说明：现阶段二者主要包含全局 CSS 与入口，真正的业务代码放在libs/中。

2.2 libs 目录

frontend/libs/console 下目前有两个库：

legacy-ce：CE Console 的主库。旧/console代码库中/console/src下的所有内容，1:1 迁移到了 frontend/libs/console/legacy-ce/src/lib 目录；index.ts是库的入口。
legacy-ee：EE Console 的主库，对应旧/pro/console代码库，1:1 迁移到其src/lib。

从 frontend/libs/console/legacy-ce/src/lib 的目录清单可以看到这套库内部的组织方式：components/、features/、metadata/、store/、hooks/、helpers/、utils/、telemetry/、theme/、dataSources/、docs/等，是一个典型的大型 React + Redux 前端库结构。

2.3 推荐使用 Nx Console 插件

README 强烈建议安装 Nx Console 编辑器插件（支持 VSCode、IntelliJ 与 Neovim）。它可以让你在 IDE 中以 UI 方式使用全部 Nx 命令、在编辑器内直接查看 Nx 依赖图（Nx graph），并辅助执行项目相关的任务。

三、环境准备与依赖安装

3.1 前置要求

Node.js v16（代号 'Gallium'）：frontend/docs/generic-info.md 明确指定 v16；frontend/package.json 的engines字段也声明了"node": ">=16"、"npm": ">=8"的下限。
nvm（Linux/macOS）或 nvm-windows（Windows）：用于切换 Node 版本；文档特别建议启用 nvm 的"deeper shell integration"，这样在项目目录执行nvm use时能自动应用.nvmrc指定的版本。
Hasura GraphQL Engine与Hasura CLI：前者是 Console 后端，后者用于迁移（migrations）工作流。

3.2 安装依赖

在frontend目录下执行：

npm install

或者按照仓库中packageManager: "yarn@4.17.1"的约定使用 yarn。安装完成后，frontend根目录的package.json提供了若干常用脚本（start:ce、build:ce、server-build:ce、lint、test:unit、test:e2e、storybook等），实际开发中也可直接使用这些 npm script 代替裸的nx命令。

四、两种运行模式：server 模式与 cli 模式

这是理解 Console 开发的核心概念。Console 可以以两种模式被托管（详见 frontend/docs/generic-info.md）：

4.1 server 模式（GraphQL Engine 托管）

Console 由 GraphQL Engine 在/console端点提供（服务端需启用--enable-console标志）。此模式下迁移（migration）功能被禁用，控制台中对应的迁移功能入口会被隐藏，Console 上的操作不会自动生成 migration yaml 文件。大多数用户使用的就是这种模式。

4.2 cli 模式（Hasura CLI 托管）

Console 由hasura console命令提供，此时迁移功能启用。所有对 schema / metadata 的更改都会被追踪，并以 migration yaml 文件 + metadata yaml 文件的形式输出到文件系统，从而方便对 schema 与 metadata 进行版本控制。

两种模式都要求有一个正在运行的 GraphQL Engine 实例作为后端。

4.3 运行模式如何驱动 Console 行为

从源码层面看，NX_CONSOLE_MODE这个环境变量决定了 Console 与哪个后端通信：frontend/apps/console-ce/src/index.html 中有一段模板脚本，它先定义serverEnvVars与cliEnvVars两套变量集合，然后通过

const envVars = getEnv('%NX_CONSOLE_MODE%') === 'cli' ? cliEnvVars : serverEnvVars; window.__env = envVars;

决定把哪一套配置注入window.__env。也就是说，运行时环境变量由服务端/CLI 在返回 HTML 时替换模板占位符（%NX_XXX%形式）注入；开发环境下则由 dotenv 从.env文件读取（getEnv函数还做了保护：若变量未被替换、仍以%NX开头，则按undefined处理）。

五、配置`.env`文件

开发时使用 dotenv 从.env文件读取环境变量；生产环境下，这些变量由服务端或 CLI 模板化注入。.env文件既可以放在frontend目录根，也可以按应用单独放置（如apps/console-ce/.env、apps/console-ee/.env）。需要注意：端到端测试应用（如console-ce-e2e）也需要独立的.env文件，因为它们在启动 Cypress 之前会先内部启动前端应用的 web server。

5.1 server 模式的环境变量

变量	说明
`NODE_ENV`	Console 构建环境（`development`/`production`）
`NX_CDN_ASSETS`	静态资源是否从 CDN 加载（`true`/`false`）
`NX_ASSETS_PATH`	Console 静态资源路径
`NX_ASSETS_VERSION`	所服务的 Console 静态资源版本
`NX_ENABLE_TELEMETRY`	是否启用遥测（`true`/`false`）
`NX_URL_PREFIX`	Console 运行的路径前缀
`NX_DATA_API_URL`	Hasura GraphQL Engine 地址（Heroku 上形如`https://<app-name>.herokuapp.com`，本地形如`http://localhost:<port>`）
`NX_SERVER_VERSION`	GraphQL Engine 服务端版本
`NX_CONSOLE_MODE`	server 模式下应为`server`
`NX_IS_ADMIN_SECRET_SET`	GraphQL Engine 是否配置了 admin secret（`true`/`false`）
`NX_HASURA_CONSOLE_TYPE`	Console 运行环境：`oss`、`pro`或`cloud`

server 模式的示例.env：

NODE_ENV=development NX_CDN_ASSETS=true NX_ASSETS_PATH=https://graphql-engine-cdn.hasura.io/console/assets NX_ASSETS_VERSION=channel/stable/v1.0 NX_ENABLE_TELEMETRY=true NX_URL_PREFIX=/ NX_DATA_API_URL=http://localhost:8080 NX_SERVER_VERSION=v1.0.0 NX_CONSOLE_MODE=server NX_HASURA_CONSOLE_TYPE=oss NX_IS_ADMIN_SECRET_SET=true

5.2 cli 模式的环境变量

变量	说明
`NODE_ENV`	Console 构建环境（`development`/`production`）
`NX_API_HOST`	Hasura CLI 主机，CLI 默认运行在`http://localhost`
`NX_API_PORT`	Hasura CLI 端口，CLI 默认在`9693`暴露 API
`NX_CDN_ASSETS`	静态资源是否从 CDN 加载（`true`/`false`）
`NX_ASSETS_PATH`	Console 静态资源路径
`NX_ASSETS_VERSION`	所服务的 Console 静态资源版本
`NX_ENABLE_TELEMETRY`	是否启用遥测（`true`/`false`）
`NX_URL_PREFIX`	Console 运行的路径前缀
`NX_DATA_API_URL`	Hasura GraphQL Engine 地址
`NX_SERVER_VERSION`	GraphQL Engine 服务端版本
`NX_CONSOLE_MODE`	cli 模式下应为`cli`
`NX_ADMIN_SECRET`	通过 CLI 传入的 admin secret
`NX_HASURA_CLOUD_ROOT_DOMAIN`	云根域名，用于以 PAT 模式模拟/测试 Hasura Pro CLI（例如本地 lux 环境的`lux-dev.hasura.me`）

cli 模式的示例.env：

NODE_ENV=development PORT=3000 NX_API_HOST=http://localhost NX_API_PORT=9693 NX_CDN_ASSETS=true NX_ASSETS_PATH=https://graphql-engine-cdn.hasura.io/console/assets NX_ASSETS_VERSION=channel/stable/v1.0 NX_ENABLE_TELEMETRY=true NX_URL_PREFIX=/ NX_DATA_API_URL=http://localhost:8080 NX_SERVER_VERSION=v1.0.0 NX_CONSOLE_MODE=cli NX_ADMIN_SECRET=my-admin-secret

5.3 关于生产环境的`consolePath`

文档特别提示：生产环境中，服务端还会把consolePath模板化进window.__env，它是当前页面的相对路径（形如/console/data/schema/public）。Console 在生产环境据此推导DATA_API_URL；开发阶段不必关心，因为你在.env中硬编码了NX_DATA_API_URL。这一机制同样能在 frontend/apps/console-ce/src/index.html 的serverEnvVars.consolePath定义中看到对应项。

六、启动开发服务器

6.1 切换 Node 版本

nvm install nvm use

6.2 启动 CE Console 开发服务器

nx serve console-ce

（等价于 npm script：npm run start:ce，即nx run console-ce:serve。）

该命令需要一个.env文件（见上文配置说明）。启动后访问http://localhost:4200/，修改任意源码文件时应用会自动热重载。console-ce应用的servetarget 在 frontend/apps/console-ce/project.json 中定义，基于@nrwl/webpack:dev-server，开发配置默认开启hmr: true。

6.3 cli 模式下的配套启动

cli 模式开发需要先有一个 Hasura CLI console 服务在运行，且其 endpoint 要与.env中配置的NX_DATA_API_URL一致：

hasura console --endpoint <DATA_API_URL> --admin-secret <your-admin-secret> (可选)

然后再启动前端开发服务器：

npx nx run console-ce:serve

如需启动 Storybook：

npx nx run console-legacy-ce:storybook

6.4 验证与调试

访问 http://localhost:4200 确认环境就绪；
改动代码后 Console 自动重载，持续迭代；
新增功能时建议同步补充相应测试；
开发模式下可借助Redux DevTools Extension检查与调试 Redux store——启动开发模式时它会自动连接到 Redux store。

6.5 查看依赖图

nx graph

该命令会在浏览器中展示项目间的依赖关系图，帮助你理解应用与库的依赖拓扑（README 将其作为理解工作区的重要手段）。

七、构建生产产物

7.1 构建 CE Console

nx build console-ce

（等价于npm run build:ce。）构建产物输出到dist/目录，具体为dist/apps/console-ce。从 frontend/apps/console-ce/project.json 可以看到构建细节：

使用@nrwl/webpack:webpackexecutor，compiler为babel；
入口为apps/console-ce/src/main.tsx，HTML 模板为apps/console-ce/src/index.html；
样式入口为apps/console-ce/src/css/tailwind.css（Tailwind CSS）；
生产配置（production）会做文件替换（environment.ts→environment.prod.ts）、开启optimization、outputHashing: "bundles"等。

7.2 服务端资源构建

仓库中还提供将 Console 产物打包为 GraphQL Engine 可直接内嵌服务资源的 target：

nx run console-ce:build-server-assets

（npm script：npm run server-build:ce。）从project.json看，该 target 由内部插件@hasura/internal-plugin:build-server-assets执行，输出到dist/apps/server-assets-console-ce，并依赖validate-javascript-bundle-output与buildtarget。这对应了"Console 由 GraphQL Engine 在/console端点提供"的生产形态——前端资源被打包进服务端资源目录，随 GraphQL Engine 一起发布。完整的源码级构建流程可参考仓库根目录的 Makefile 与 server/CONTRIBUTING.md。

八、运行测试

8.1 单元测试（Jest）

nx test console-ce

执行console-ce的单元测试（基于 Jest）。若要执行受改动影响的测试：

nx affected:test

Nx 会基于 git 状态与nx.json中的affected.defaultBase（main）自动推断受影响的工程并只运行对应测试。nx.json中的targetDefaults还定义了各 target 的输入（inputs）与缓存策略——例如test依赖jest.preset.js，build依赖^build（先构建依赖库）等，这些配置保证了增量构建与缓存的正确性。

8.2 端到端测试（Cypress）

打开 Cypress UI 交互式调试：

nx e2e console-ce-e2e --watch

无头执行端到端测试：

nx e2e console-ce-e2e

执行受改动影响的端到端测试：

nx affected:e2e

以上 e2e 命令均需要.env文件。从 frontend/apps/console-ce-e2e 的结构看，测试用例覆盖了 actions 转换、cron 触发器、事件触发器、一次性定时触发器、远程 schema 及远程 schema 关系、表权限输入校验、OpenTelemetry 配置、API GraphiQL 追踪等核心控制台功能，cypress.config.ts定义了 Cypress 配置。更多测试规范可参考 frontend/apps/console-ce-e2e/README.md。

8.3 测试脚本速查

根目录 frontend/package.json 提供了聚合脚本：

npm run test:unit # nx run-many --target=test npm run test:e2e # nx run-many --target=e2e

九、代码质量：Lint 与格式化

对所有文件运行 lint：

nx run-many --target=lint

（或npm run lint。）对所有文件执行格式化：

npx nx format:write

（package.json中还提供format:write（基于origin/main的增量格式化）与format:write:all两个脚本。）工作区的 lint 通过 ESLint 执行（@nrwl/linter:eslintexecutor），nx.json的targetDefaults.lint表明其输入包括.eslintrc.json与tools/eslint-rules下的自定义规则。

十、从旧代码库迁移的工程师须知

如果你来自旧的/console与/pro/console代码库，frontend/docs/from-previous-console.md 是必读的迁移指南，要点如下：

10.1 代码去哪里了

旧/console/src下的全部内容现在位于libs/console/legacy-ce/src/lib/（1:1 映射）；旧/console/exports对应libs/console/legacy-ce/src/exports/。旧/pro/console的内容则在libs/console/legacy-ee/src/lib/。

10.2 环境变量名称变化

最大的变化是：所有本地开发环境变量必须以NX_为前缀（例如NX_CDN_ASSETS、NX_DATA_API_URL、NX_CONSOLE_MODE），否则无法被注入。这一约定不影响生产配置（生产环境仍由服务端/CLI 模板化注入）。如果要新增变量，需要同时修改对应应用的index.html（frontend/apps/console-ce/src/index.html 或frontend/apps/console-ee/src/index.html）中的window.__env模板，取决于你要改的是哪个 Console。

十一、提交变更与贡献

开发工作在自己的 fork 中进行，仓库根目录的 CONTRIBUTING.md 对提交信息（commit message）有明确规范，提交前请对照检查；
完成改动后创建 Pull Request；仓库 CI 会自动运行测试套件，通过后还会生成一个可预览的 Heroku 应用，供维护者与贡献者审阅源码和预览效果。

总结

Hasura Console 前端工程是一个典型的 Nx 单仓库实践：apps负责装配与部署形态（CE / EE / e2e），libs承载 80% 的业务逻辑；开发时通过.env+NX_前缀环境变量区分server（GraphQL Engine 托管、无迁移）与cli（Hasura CLI 托管、启用迁移）两种运行模式；构建产物既可输出到dist/，也可通过build-server-assets打包进 GraphQL Engine 服务端资源；测试体系则由 Jest（单元）+ Cypress（端到端）构成。掌握这套工作流，你就能够在本地完整搭建、调试并扩展 Hasura Console 的任意功能模块。

创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考