CloudBeaver 开发指南：从项目地图到模块化规范的完整解读-育师

后端
数据库客户端
前端

【免费下载链接】cloudbeaver

Cloud Database Manager

项目地址：https://gitcode.com/gh_mirrors/cl/cloudbeaver

CloudBeaver 是一个开源、基于 Web 的数据库管理应用（Cloud Database Manager），其模块化前端承载了数据库导航器、SQL 编辑器、数据编辑器、管理后台等全部功能，并通过 GraphQL 与 CloudBeaver 服务端通信。本文以仓库根目录的 AGENTS.md 为主线，系统梳理该仓库面向开发者的工程约定：前端项目的目录地图与依赖方向、开发环境的搭建与常用命令、模块化工作规范，以及后端 GraphQL API 的命名与兼容性要求。读完本文，你将能在一个大型 Yarn PnP + TypeScript + React 工作区中快速定位模块、遵守依赖边界、正确运行构建与校验命令，并理解前后端协作时的代码生成链路。

一、CloudBeaver 是什么

CloudBeaver 的定位是"数据库管理应用"，其产品形态以 Web 方式交付，用户通过浏览器即可完成对多种数据库的连接、浏览、SQL 执行与数据编辑等日常运维工作。从仓库结构看，项目由两大块构成：

前端：位于 webapp/ 目录，是模块化的单页应用，包含数据库导航树、SQL 编辑器、数据网格、管理控制台等所有交互界面；
后端：位于 server/ 目录，是一组基于 OSGi/Tycho 的 Java 插件（bundle），通过 GraphQL 向客户端暴露数据操作与业务能力。

两者通过 GraphQL 协议衔接：前端以.gql文件声明操作，后端在server/bundles/*/schema/中维护*.graphqls模式定义，前端再据此生成类型安全的客户端代码。这也解释了为什么 AGENTS.md 会强调"后端 GraphQL schema 是前端代码生成的输入"。

需要特别指出的是，CloudBeaver 后端是headless（无界面）的：它不使用 SWT 或 Eclipse RCP，全部能力都以 GraphQL API 形式对外提供，这与经典 Eclipse 桌面插件体系有本质区别。后端至少要支持 PostgreSQL、MySQL、Oracle、SQL Server 四类数据库，对其它数据库的支持是可选的。

二、前端工程地图：webapp 目录结构

AGENTS.md 给出了明确的项目地图，下面结合仓库实际内容逐项展开。

工作区根与脚本入口

webapp/package.json是整个前端工作区的根，它声明了 Yarn Plug'n'Play（PnP）workspaces（./common-react与packages/*），并集中存放了仓库级脚本：

脚本	作用
`yarn test`	调用`dbeaver-test`（即`@cloudbeaver/tests-runner`提供的测试运行器）执行全仓测试
`yarn lint`	运行 ESLint 完成仓库级静态检查
`yarn validate-dependencies`	通过`core-cli-validate-dependencies`校验包间依赖方向与依赖图无环
`yarn check-license`	用`core-cli-check-license`检查源码文件的许可证头
`yarn add-plugin`	通过`core-cli-add-plugin`脚手架生成新插件包

工作区根同时锁定了工具链版本：packageManager: "yarn@4.14.1"，React/ReactDOM 为^19，TypeScript 为^5.8，ESLint 为^9，Vitest 为^4，并通过resolutions对 lodash、immutable、axios 等传递依赖做了统一版本约束。AGENTS.md 因此要求：以package.json、.yarnrc.yml和前端 CI 工作流为工具与运行时版本的唯一事实来源，不要在文档中重复维护版本号。

核心包与插件包的分层

按 AGENTS.md 的分层约定，webapp/packages/下有三类包：

core-*（共享应用基石）：如core-di（DI/模块注册）、core-utils（工具函数）、core-blocks（UI 原语）、core-events、core-settings、core-connections、core-navigation-tree等。它们提供应用基础服务、状态管理与通用 UI，是其它包的地基。
plugin-*（功能模块）：如plugin-sql-editor、plugin-data-viewer、plugin-connections、plugin-navigation-tree等。每个插件通常通过src/module.ts注册服务与启动逻辑，并通过src/index.ts暴露公共 API。
product-*（产品组装）：product-default是可运行/可打包的 CE 前端入口（Vite 构建目标），product-default-impl负责选定 CE 的插件集合；另有product-base提供公共产品底座。

以plugin-sql-editor为例，其 src/module.ts 调用ModuleRegistry.add({ name, configure })，在configure中通过serviceCollection.addSingleton(Bootstrap, ...)注册 LocaleService、MenuBootstrap、SqlEditorView 等引导与视图服务，通过addTransient(SqlEditorModel)注册每次新建编辑器时瞬态创建的数据模型。而 src/index.ts 的第一行就是import './module.js'，随后把SqlEditorService、SQLEditorLoader、ACTION_SQL_EDITOR_EXECUTE等公共符号统一 re-export——这就是 AGENTS.md 所说"模块注册与公共 API 分离"的标准形态。

GraphQL 代码生成

webapp/packages/core-sdk承担 GraphQL 操作的收集与客户端类型生成：

新增或修改 GraphQL 操作应写成core-sdk下的.gql文件；
通过yarn workspace @cloudbeaver/core-sdk gql:gen重新生成代码；
生成产物src/sdk.ts属于被忽略（gitignore）的自动生成文件，严禁手工编辑。

core-sdk/package.json里可以看到完整的代码生成工具链：graphql-codegen、@graphql-codegen/typescript、@graphql-codegen/typescript-operations、@graphql-codegen/near-operation-file-preset等，以及gql:gen:dev的--watch监听模式，配合product-default的dev脚本可在开发时保持客户端类型与后端 schema 同步。

共享工具与 React 组件

工作区还包含两级共享库：

webapp/common-typescript/@dbeaver/*：纯 TypeScript 工具，如js-helpers、jdbc-uri-parser、result-set-api；
webapp/common-react/@dbeaver/*：React 组件库，如ui-kit、react-data-grid、react-translate。

这些库通过@dbeaver/*命名空间导出，供工作区内各包引用。

三、技术栈一览

AGENTS.md 用一句话概括了前端技术栈，可拆解如下：

语言与模块：TypeScript ES Modules；
UI 层：React（仓库当前为 React 19）；
状态管理：MobX（配合mobx-react-lite在组件层响应式消费）；
依赖注入与模块注册：项目自研的 DI/模块注册体系（@cloudbeaver/core-di的ModuleRegistry、serviceCollection）；
GraphQL 客户端：GraphQL Code Generator +graphql-request/axios；
构建与包管理：Vite（product-default的bundle脚本用vite build --mode production）、Yarn workspaces with PnP；
测试：Vitest + Testing Library（含happy-dom、msw）；
代码质量：ESLint、Prettier；
样式：CSS Modules + 基于 Tailwind 的主题体系（仓库根还引入了 Tailwind 4，见product-default的tailwindcss: 4.0.7）。

测试约定是"与源码同目录共置"：*.test.ts/*.test.tsx紧挨被测文件；样式通常也是共置的 CSS Modules。

四、环境搭建与常用命令

AGENTS.md 给出的开发环境初始化命令如下（前端命令默认在webapp/下执行，Node 版本以前端 CI 配置为准，Yarn 版本以webapp/package.json中packageManager为准）：

corepack enable cd webapp yarn install --immutable

由于工作区采用 Yarn PnP，--immutable安装保证锁文件.yarn.lock（仓库根另有webapp/yarn.lock）不被改动，适合 CI 与严格复现的场景。若需要同步tsconfig.json的项目引用，则要执行一次非 immutable安装，让配置好的ts-project-linker自动完成引用同步；自动链接失败时才手工编辑 references，之后运行yarn validate-dependencies校验。

日常开发与校验命令

# 启动前端开发服务器；需要单独运行一个兼容的 CloudBeaver API 服务 (cd packages/product-default && yarn dev) # 仓库级检查（在 webapp/ 下执行） yarn lint yarn test yarn validate-dependencies # 生产构建 (cd packages/product-default && yarn bundle)

yarn dev实际执行yarn build && concurrently ... "vite {@}"，即先做一次构建与gql:gen，再用concurrently并行跑 Vite 开发服务器和core-sdk的gql:gen:dev --watch，保证后端 schema 变化能实时反映到客户端类型；
yarn bundle是yarn build && vite build --mode production，产出可部署的生产包；
若只想聚焦某个包，使用该包package.json中已存在的脚本，例如yarn workspace @cloudbeaver/core-utils test或yarn workspace @cloudbeaver/plugin-sql-editor lint。AGENTS.md 明确提醒：不要发明包中不存在的脚本。

许可证头模板

/* * CloudBeaver - Cloud Database Manager * Copyright (C) 2020-<CURRENT_YEAR> DBeaver Corp and others * * Licensed under the Apache License, Version 2.0. * you may not use this file except in compliance with the License. */

修改已有源文件时，应保留原有起始年份，只把结束年份更新为当前四位数年份，并通过仓库自带的 ESLint/Prettier 配置约束格式，而不是手工排版。仓库根的lefthook.yml与webapp/package.json中的sync-pre-commit-hooks脚本也体现了对 pre-commit 校验的自动化管理。

五、前端工作约定：依赖方向与模块边界

AGENTS.md 把协作规范讲得很细，这些约定直接决定了大型工作区能否长期健康演进：

改动放进最小的归属包：优先复用现有core-*抽象与 UI 原语，而不是新增跨包辅助工具。
依赖方向固定为 plugin → core：core-*包绝不import 或依赖plugin-*包；插件可以使用 core 包的公共 API，也可以使用其它插件的公共 API（但要遵守管理边界与无环规则）。
管理功能独立成包：仅管理后台使用的行为放入以-administration结尾的独立包；普通（非管理）插件不得依赖管理包。仓库中plugin-authentication-administration、plugin-connection-administration、plugin-product-information-administration等即是这类包的实例。
依赖图必须无环：禁止引入直接或间接的循环依赖。
只通过公共导出导入：工作区包一律通过@cloudbeaver/*或@dbeaver/*公共导出引用，禁止深入其它包的src/目录。
新增依赖走 Yarn：通过 Yarn 修改目标包的package.json，改完跑yarn validate-dependencies。
注册走 module.ts：服务与引导逻辑通过包的src/module.ts注册；只有启用/停用 CE 产品的插件时才改动产品组装（product-default-impl）。
文案走本地化：用户可见文本放入包的本地化文件，并遵循相邻的LocaleService模式，不要在组件里硬编码 UI 文案。每个包的src/LocaleService.ts+locales/目录就是该约定的落地形态。
GraphQL 操作走 core-sdk：以.gql文件新增/修改，用yarn workspace @cloudbeaver/core-sdk gql:gen重新生成，永不手工编辑生成产物。
不提交生成/安装产物：node_modules/、.pnp.*、lib/、dist/、coverage/、allure-results/一律不编辑、不提交。
行为变更补测试：交付前对受影响的包运行 lint 与测试；跨切面或产品组装变更还要跑仓库级检查与product-default打包。

六、后端与 GraphQL API 规范

后端工作开始前，需阅读并遵循../dbeaver/AGENTS.md中继承的 Java 与 Tycho 约定（该文件属于上游 DBeaver 仓库，不在当前仓库内）。此外注意三点：

headless 无 UI：不用 SWT / Eclipse RCP；
配置生成链路：服务端配置文件由 apps/config-generator 生成，修改时更新 config/template/cloudbeaver-base.conf，或针对特定产品参数使用补丁（patches）；
数据库支持下限：必须支持 PostgreSQL、MySQL、Oracle、SQL Server，其余数据库可选（仓库 server/drivers/ 下可见 mysql、postgresql、oracle、sqlserver 等驱动 bundle 与之对应）。

GraphQL 命名与版本兼容

ID 类型：ID 必须使用 GraphQL 类型ID；ID 类参数与输入字段必须以Id结尾，例如projectId。
顶层方法命名：遵循{pluginId}{methodName}模式，例如authLogin、rmListProjects、navNodeChildren；新增公共 API 需标记@since。
保持已发布 API 兼容：对已发布 API 采用弃用（deprecate）而非重命名/删除，标注弃用版本，且只有超过一年之后才能移除；EA 专属 API 可以在公开发布前变更。
新参数必须可选：给已发布 API 新增的参数与输入字段必须是可选的。

这些约束在server/bundles/*/schema/*.graphqls的 schema 定义与server/bundles/*/src/的解析器实现中落地，前端core-sdk的代码生成正是以它们为输入。

七、结语：把 AGENTS.md 当作协作契约

AGENTS.md 本质上是 CloudBeaver 仓库的"工程师协作契约"：它把目录职责、依赖方向、命令入口、代码生成链路和 API 兼容策略固化成了可执行规则。对初次接触仓库的开发者而言，建议按以下顺序上手：

先读 AGENTS.md 与webapp/package.json，建立工作区分层认知；
从webapp/packages/plugin-sql-editor/src/module.ts这类"最小插件"入手，理解ModuleRegistry注册与服务引导的写法；
按第四节命令完成安装、yarn lint/yarn test/yarn validate-dependencies全绿后再动代码；
改动涉及 GraphQL 时，遵守"改.gql→gql:gen→ 不碰sdk.ts"的闭环。