QDATA 前后端架构报告¶

生成日期：2026-08-27 | 基于源码深度分析

一、后端架构（Java / Spring Boot）¶

1.1 项目概况¶

qData 是一个企业级**数据中台**（Data Governance Platform），由江苏千统科技有限公司开发，版本 1.6.1，采用 Apache License 2.0 授权。后端基于 Java 8 + Spring Boot 2.5.15 构建，Maven 多模块单体架构，共 16 个业务模块 + 12 个框架子模块 + 2 个独立微服务。

维度	数量
Controller 总数	146
REST 端点总数	1,242
Service 接口	~130
ServiceImpl 实现类	~125
DO（实体）类	118
VO 类	403
DTO 类	223
MyBatis Mapper 接口	143
Mapper XML 文件	109
数据库表（latest）	2,095

1.2 分层架构¶

┌─────────────────────────────────────────────────────────────┐
│                     qdata-server（入口）                      │
│                  QDataApplication.java :8080                 │
├─────────────────────────────────────────────────────────────┤
│                 qdata-framework（框架层，12 个子模块）          │
│  auth │ common │ config │ file │ generator │ mybatis         │
│  neo4j│ pay    │ quartz │ redis│ security  │ websocket       │
├─────────────────────────────────────────────────────────────┤
│               业务模块层（10 个模块，api + biz 拆分）           │
│  system │ att │ da │ dg │ dm │ dp │ dpp │ ds │ mc │ ai      │
├─────────────────────────────────────────────────────────────┤
│            qdata-api-ds（DolphinScheduler 集成接口）           │
├─────────────────────────────────────────────────────────────┤
│          独立微服务：service-ai :8087 │ service-quality :8083  │
└─────────────────────────────────────────────────────────────┘

1.3 模块清单与职责¶

模块	Controller	端点	职责
`qdata-module-system`	31	209	用户、角色、菜单、部门、字典、日志、消息、CA 证书
`qdata-module-da`	23	237	数据资产编目、数据源管理、数据发现、资产审计、GIS/视频资产
`qdata-module-att`	20	196	分类管理（10 类）、项目管理、标签、规则、客户端
`qdata-module-dpp`	16	158	ETL 数据集成、数据开发、任务调度、质量任务
`qdata-module-mc`	13	113	元数据采集、变更检测、版本管理、方言适配
`qdata-module-dg`	11	87	数据分类分级、脱敏规则、敏感数据管理
`qdata-module-dp`	9	85	数据标准、数据元、码表映射、逻辑模型、文档管理
`qdata-module-dm`	6	50	数据域、数据层、主题域、业务分类
`qdata-module-ds`	4	27	数据服务 API 发布、客户端认证、调用日志
`qdata-module-ai`	3	21	AI 对话、模型管理（内嵌模式）
`qdata-framework`	4	33	文件上传、代码生成器、Quartz 任务管理
`qdata-service-ai`	3	15	独立 AI 服务（JDK 17，Text2SQL）
`qdata-service-quality`	2	10	独立数据质量服务（MongoDB）
`qdata-server`	1	1	默认入口

1.4 路由设计¶

所有业务 Controller 使用统一的 RESTful 前缀约定：

模块前缀	示例路径	说明
`/system/`	`/system/user/list`, `/system/role`	系统管理
`/da/`	`/da/asset/list`, `/da/datasource`	数据资产
`/att/`	`/att/project/list`, `/att/tag`	分类管理
`/dpp/`	`/dpp/etl/task/list`, `/dpp/quality/task`	数据开发
`/mc/`	`/mc/task/list`, `/mc/db`	元数据采集
`/dg/`	`/dg/dataCategory/list`, `/dg/desensitize/rule`	数据治理
`/dp/`	`/dp/model/list`, `/dp/dataElem`	数据标准
`/dm/`	`/dm/dataDomain/list`, `/dm/dataLayer`	数据建模
`/ds/`	`/ds/api/list`, `/ds/apiLog`	数据服务
`/ai/`	`/ai/chatConversation`, `/ai/model`	AI 模块
`/services/v1.0.0/`	动态注册的 API 端点	数据服务运行时

1.5 Service 层¶

每个业务模块遵循 api + biz 拆分模式： - *-api —— 接口定义、DTO、枚举、领域对象 - *-biz —— 业务逻辑、Controller、ServiceImpl、MyBatis Mapper

关键 Service 职责：

Service	模块	核心职责
`IDppEtlTaskService`	dpp	ETL 任务 CRUD、发布/下线、调度器集成
`McTaskServiceImpl`	mc	元数据采集执行、增量/全量、变更检测
`DaAssetServiceImpl`	da	资产编目、血缘追踪（Neo4j）、发现任务
`DsApiServiceImpl`	ds	API 发布/注销、SQL 解析、在线测试
`QualityTaskExecutorServiceImpl`	quality	质量规则执行、错误数据存储（MongoDB）
`DpModelServiceImpl`	dp	逻辑模型管理、数据元关联、物化视图
`TokenService`	security	JWT 签发/验证/刷新、Redis 存储

1.6 数据模型¶

共 748 个模型类（118 DO + 403 VO + 223 DTO + 4 Entity），按模块分布：

模块	DO	说明
`da`	25	`DaAssetDO`, `DaDatasourceDO`, `DaDiscoveryTaskDO` 等
`att`	20	`AttProjectDO`, `AttTagDO`, `AttClientDO` 等
`dpp`	18	`DppEtlTaskDO`, `DppEtlNodeDO`, `DppEtlSchedulerDO` 等
`mc`	12	`McDbDO`, `McTableDO`, `McColumnDO`, `McTaskDO` 等
`dg`	11	`DgDataCategoryDO`, `DgDesensitizeRuleDO` 等
`dp`	9	`DpModelDO`, `DpModelColumnDO`, `DpDataElemDO` 等
`quality`	7	`QualityRuleEntity`, `CheckErrorData` 等
`dm`	6	`DmDataDomainDO`, `DmDataLayerDO` 等
`system`	5	`SysConfig`, `SysNotice`, `SysOperLog` 等
`ai`	3	`AiModelDO`, `AiChatConversationDO`, `AiChatMessageDO`
`ds`	2	`DsApiDO`, `DsApiLogDO`

1.7 认证机制¶

主认证：Spring Security 5.7.12 + JWT（HS512）

┌──────────┐    POST /login     ┌──────────────┐
│  Client  │ ──────────────────► │ AuthController│
└──────────┘                     └──────┬───────┘
                                        │
                                        ▼
                              ┌──────────────────┐
                              │  SysLoginService   │
                              │  · BCrypt 密码校验  │
                              │  · 验证码校验       │
                              │  · IP 黑名单检查    │
                              └────────┬─────────┘
                                       │
                                       ▼
                              ┌──────────────────┐
                              │   TokenService     │
                              │  · HS512 签发 JWT  │
                              │  · Redis 存储      │
                              │  · 自动续期（20min）│
                              └──────────────────┘

Token 通过 Authorization: Bearer {token} 传递
Redis Key：login_tokens:{uuid}，默认 TTL 600 分钟（10 小时）
Token 在剩余 **20 分钟**时自动续期
密码加密：BCrypt
CSRF 已禁用（无状态策略）

OAuth2 支持：基于 SA-Token 框架，支持全部 4 种授权模式（Authorization Code、Implicit、Password、Client Credentials），路径 /oauth2/**。

数据服务客户端认证：独立的 DsCheckClientToken 注解 + ApiJwtUtil，7 天 Token + 30 天 Refresh Token。

1.8 配置管理¶

配置项	值
服务端口	8080
Tomcat 最大线程	800
Tomcat 最小空闲线程	100
文件上传上限	3,000 MB
XSS 过滤路径	`/system/`, `/monitor/`, `/tool/*`
i18n 资源包	13 个（跨模块）
分页插件	PageHelper（MySQL 方言）
ID 策略	自增 + 雪花 ID

数据源支持：MySQL（主）、DM8、KingbaseES、Oracle、PostgreSQL、SQL Server，通过 application-dev.yml 切换。连接池使用 Alibaba Druid 1.2.23（初始 5，最大 20）。

二、前端架构（Vue 3 / TypeScript）¶

2.1 技术栈¶

类别	技术	版本
框架	Vue 3	^3.5.21
UI 库	Element Plus	2.7.6
构建工具	Vite	5.3.2
状态管理	Pinia	2.1.7
路由	Vue Router	4.4.0
国际化	vue-i18n	^11.4.5
HTTP 客户端	Axios	0.28.1
图表	ECharts	5.5.1
流程图	AntV X6	^2.18.1
代码编辑器	Monaco Editor	^0.52.2
富文本	Vue Quill	1.2.0
Markdown	markdown-it	^14.1.0
网络图	vis-network	^9.1.13
表单设计器	@form-create/designer	^3.2.11
文档预览	@vue-office/docx/excel/pdf	^1.6.3 / ^1.7.14 / ^2.0.10
模糊搜索	Fuse.js	6.6.2
拖拽	vuedraggable	^4.1.0
加密	crypto-js + jsencrypt	^4.2.0 / 3.3.2

2.2 目录结构¶

qdata-ui/src/
├── api/            # 14 个模块目录，151 个 API 文件
├── assets/         # 静态资源（197 个 SVG 图标）
├── components/     # 38 个组件目录，83 个文件
├── composables/    # 5 个组合式函数
├── directive/      # 4 个自定义指令（copyText, hasPermi, hasRole）
├── layout/         # 12 个布局组件
├── locales/        # 3 语言 × 18 命名空间 = 54 个翻译文件
├── plugins/        # 8 个插件（auth, cache, download, modal, tab, i18n）
├── router/         # 27 个路由文件
├── store/          # 8 个 Pinia Store
├── utils/          # 30 个工具文件
└── views/          # 13 个模块目录，322 个页面组件

2.3 路由设计¶

共 91 个路由声明，分为两层：

constantRoutes（公开路由）：来自 18 个路由模块文件，无需权限
dynamicRoutes（动态路由）：来自 4 个模块文件，由后端菜单接口动态注入

路由组件解析使用 import.meta.glob('./../../views/**/*.vue') 实现懒加载。beforeEach 守卫在路由切换时取消未完成的 HTTP 请求。

路由 Top 5：

路由文件	路由数
`system/public/index.js`	19
`system/dynamic/index.js`	10
`dp/document/index.js`	10
`da/quality/index.js`	8
`meta/dynamic/index.js`	8

2.4 状态管理¶

8 个 Pinia Store：

Store	职责
`app`	侧边栏状态、设备类型、UI 尺寸
`user`	认证信息（Token、用户、角色、权限）
`dict`	字典缓存（内存 KV）
`permission`	动态路由管理、菜单树解析
`settings`	布局配置（主题色、顶栏、标签页等）
`tags-view`	标签页导航管理
`locale`	国际化语言切换
`project`	项目上下文、资产/模型分类树

2.5 组件体系¶

19 个全局注册组件：

组件	说明
`SvgIcon`	SVG 图标渲染器（197 个图标）
`Pagination`	分页封装
`ImageUpload`	图片上传预览
`FileUpload`	文件上传
`FileUploadbtn`	文件上传按钮
`Editor`	富文本编辑器（Quill）
`DictTag`	字典值标签
`DetailInfo`	通用详情页头
`DescriptionsInfo`	描述信息封装
`RightToolbar`	表格工具栏（列切换、搜索、刷新）
`TreeSelect`	树形下拉选择
`QtTable` / `QtSearchBar` / `QtFormItem` / `QtTabPane` / `QtTagGroup` / `QtWrap`	qData 定制组件
`ImagePreview`	图片预览灯箱
`GuideTip`	引导提示

专用组件（非全局）：

组件	说明
`SqlEditor`	SQL 编辑器（Monaco/CodeMirror，支持 FlinkSQL）
`ShellEditor`	Shell 脚本编辑器
`ProTable`	专业表格组件
`Crontab`	Cron 表达式编辑器（8 个子组件）
`MarkdownView`	Markdown 渲染器
`DeptTree`	部门树选择器
`HeaderSearch`	头部搜索（Fuse.js 模糊匹配）

2.6 国际化¶

语言	命名空间	翻译键值对	行数
zh-CN（主）	18	~6,320	7,420
en-US	18	~6,200	7,130
ja-JP	18	~6,200	7,175

最大的命名空间：dpp（数据开发）1,636 行，sys（系统管理）1,017 行，da（数据资产）810 行。

2.7 构建配置¶

开发服务器：端口 81，4 个代理规则：

代理路径	目标	说明
`/dev-api`	`http://localhost:8080`	主后端
`/dev-ai`	`http://localhost:8087`	AI 服务
`/jmreport`	`http://localhost:8080`	报表服务
`/v3/api-docs`	`http://localhost:8080`	Swagger 文档

构建优化： - 手动 chunk 拆分（每个 node_modules 包独立分包） - Gzip/Brotli 压缩（通过 VITE_BUILD_COMPRESS 环境变量控制） - SVG 图标精灵（vite-plugin-svg-icons，197 个图标） - 自动导入（unplugin-auto-import + unplugin-vue-components）

2.8 文件统计¶

类别	数量
Vue 文件总数	405
JS 文件总数	310
TS 文件总数	8
源文件总数	730
views/ 下 Vue 文件	322
components/ 下 Vue 文件	71
API 文件	151
路由文件	27
Store 文件	8
翻译文件	54
SVG 图标	197

三、前后端交互模型¶

3.1 通信架构¶

┌────────────────────────────────────────────────────────────────┐
│                        qdata-ui (Vue 3)                         │
│  ┌──────────┐  ┌──────────┐  ┌──────────┐  ┌───────────────┐  │
│  │  views/   │  │  store/  │  │  router/  │  │   api/        │  │
│  │  322 页面 │  │  8 Store │  │  91 路由  │  │  151 API 文件 │  │
│  └────┬─────┘  └────┬─────┘  └────┬─────┘  └──────┬────────┘  │
│       │              │              │               │           │
│       └──────────────┴──────────────┴───────┬───────┘           │
│                                             │ Axios             │
└─────────────────────────────────────────────┼───────────────────┘
                                              │
                    ┌─────────────────────────┼────────────────────┐
                    │   Nginx :80（生产）      │                    │
                    │   /prod-api → :8080      │                    │
                    │   /prod-ai  → :8087      │                    │
                    └─────────────────────────┼────────────────────┘
                                              │
              ┌───────────────────────────────┼────────────────────────┐
              │                               │                        │
              ▼                               ▼                        ▼
    ┌──────────────────┐          ┌──────────────────┐      ┌──────────────────┐
    │   qdata-api       │          │  qdata-service-ai │      │  qdata-service-   │
    │   :8080           │          │  :8087            │      │  quality :8083    │
    │   146 Controller  │          │  3 Controller     │      │  2 Controller     │
    │   1,242 端点       │          │  15 端点           │      │  10 端点           │
    └────────┬─────────┘          └──────────────────┘      └──────────────────┘
             │
    ┌────────┼────────┬──────────┬──────────┐
    ▼        ▼        ▼          ▼          ▼
  MySQL    Redis   RabbitMQ    Neo4j    MongoDB
  /DM8     :6379   :5672      :7687    :27017

3.2 认证流程¶

前端调用 POST /login（用户名 + 密码 + 验证码）
后端 AuthController → SysLoginService 校验（BCrypt + 验证码 + IP 黑名单）
TokenService 签发 JWT（HS512），存入 Redis（login_tokens:{uuid}，TTL 600min）
前端存储 Token 到 Cookie，后续请求通过 Authorization: Bearer {token} 携带
JwtAuthenticationTokenFilter 拦截请求，从 Redis 验证 Token 有效性
Token 剩余 20 分钟时自动续期

3.3 动态菜单与路由¶

前端登录后调用 getRouters() 获取后端菜单树
permission Store 将菜单树转换为 Vue Router 路由配置
组件字符串通过 import.meta.glob 解析为懒加载组件
addRoutes() 动态注入路由，router.addRoute() 添加 404 兜底
侧边栏、顶栏、面包屑均从路由元数据（meta.title, meta.icon）渲染

3.4 API 文档¶

SpringDoc OpenAPI 3 + Knife4j 增强 UI
分组：system、example、ai、dm
Swagger UI 路径：/swagger-ui.html
API 文档路径：/v3/api-docs
i18n 支持：SwaggerI18nCustomizer 运行时翻译 @Tag 和 @Operation
Knife4j 基础认证：test / 12313

四、文件统计汇总¶

维度	数量
后端 Controller	146
后端 REST 端点	1,242
后端 Service 接口	~130
后端 DO 类	118
后端 Mapper 接口	143
后端 Mapper XML	109
数据库表	2,095
前端 Vue 文件	405
前端 JS/TS 文件	318
前端 API 文件	151
前端路由	91
前端 Pinia Store	8
前端组件	83
前端翻译键值对	~6,320
SVG 图标	197
Docker 服务	22