带你看源码

千桐科技2026/8/13大约 13 分钟源码结构核心优势源码结构二开

qData 源码结构说明

谁适合看这份指南？

初次接触 qData 源码，希望快速了解项目结构的开发者
准备基于 qData 进行二次开发的开发人员
需要根据页面、接口或数据库表快速定位代码的开发人员

模块清单、版本和依赖关系以当前分支的 pom.xml 与实际代码为准。

1、顶层目录介绍

qData/
├── pom.xml                    # 主 Maven 聚合工程与统一版本管理
├── qdata-server/              # 主服务启动模块
├── qdata-framework/           # 安全、数据访问、缓存、文件、调度等公共能力
├── qdata-module-system/       # 用户、角色、菜单、字典和日志等系统管理
├── qdata-module-att/          # 项目、类目、标签、主题和规则等基础配置
├── qdata-module-da/           # 数据源、数据资产、资产发现与资产操作
├── qdata-module-dm/           # 数据域、业务分类、数仓分层与主题域
├── qdata-module-dp/           # 数据元、码值映射、逻辑模型与标准文档
├── qdata-module-dpp/          # 数据集成、数据开发、调度实例和质量任务编排
├── qdata-module-ds/           # API 数据服务、鉴权与调用日志
├── qdata-module-mc/           # 元数据采集任务、实例和元数据版本
├── qdata-module-dg/           # 数据分类分级、敏感识别与脱敏治理
├── qdata-module-ai/           # AI 模型、会话和消息的业务模数据与管理接口
├── qdata-api-ds/              # DolphinScheduler 接口契约与适配实现
├── qdata-executor-etl/        # Spark / DataX 数据处理程序
├── qdata-service-quality/     # 独立的数据质量执行服务
├── qdata-service-ai/          # 独立的智能问数 Maven 工程
├── qdata-ui/                  # Vue 3 前端工程
├── sql/                       # MySQL、达梦和 DolphinScheduler SQL 脚本
├── docker/                    # Compose、Nginx、中间件和服务部署配置
├── docs/                      # 随仓库维护的多语言文档
└── images/                    # README 与文档图片

架构优势

前后端分离：qdata-ui 独立构建，通过接口访问后端服务，页面开发与服务开发互不干扰。
业务模块化：系统、资产、标准、研发、数据服务、元数据和治理等能力按业务模拆分，便于定位和扩展。
管理与执行解耦：主服务负责管理，ETL、质量和 AI 由独立执行单元承担，可分别配置资源和排查日志。
公共能力复用：安全、数据访问、缓存、文件和调度等能力集中在 qdata-framework，减少重复实现。
部署边界清晰：源码、数据库脚本和 Docker 配置分区明确，便于本地开发与容器化部署。

2、运行类说明

运行单元	入口文件	默认端口	主要职责	构建位置
主服务	`QDataApplication.java`	8080	登录鉴权、系统管理及业务模业务 API	根 Maven 工程
质量执行服务	`QualityApplication.java`	8083	生成并执行质量检查 SQL	根 Maven 工程
ETL 程序	`EtlApplication.java`	无	数据读取、转换和写出	根 Maven 工程，产物由调度器调用
智能问数服务	`QDataAiApplication.java`	8087	模型调用、对话和 Text2SQL	`qdata-service-ai` 独立工程
前端应用	`qdata-ui/src/main.js`	开发环境默认 81	初始化 Vue、路由、Pinia 和国际化	`qdata-ui` 工程

3、前端工程结构介绍

3.1、前端根目录

qdata-ui/
├── .env.development          # 开发环境变量
├── .env.production           # 生产环境变量
├── .env.staging              # 测试环境变量
├── .eslintignore             # ESLint 忽略配置
├── eslint.config.js          # ESLint 规则
├── index.html                # Vite 页面入口
├── package.json              # 依赖、版本与 npm 命令
├── yarn.lock                 # Yarn 依赖锁定文件
├── vite.config.js            # Vite、代理和构建配置
├── run-dev.sh                # 开发环境启动脚本
├── bin/                      # Windows 构建与启动脚本
│   ├── build.bat
│   ├── package.bat
│   └── run-web.bat
├── html/
│   └── ie.html               # 浏览器兼容提示页面
├── public/                   # 不参与编译的公共静态资源
│   ├── excel/                # Excel 导入模板
│   ├── favicon.ico
│   └── qData-simlogo.png
├── vite/
│   └── plugins/              # Vite 插件配置
│       ├── auto-import.js
│       ├── compression.js
│       ├── setup-extend.js
│       ├── svg-icon.js
│       └── index.js
└── src/                      # 前端业务源码

前端根目录优势

配置集中：环境变量、依赖和构建规则统一维护。
使用便捷：提供多平台启动与构建脚本。
边界清晰：静态资源、构建配置和业务源码各自独立。

3.2、src 源码目录

qdata-ui/src/
├── App.vue                   # Vue 根组件
├── main.js                   # 应用初始化入口
├── permission.js             # 登录校验与全局路由守卫
├── settings.js               # 页面标题、主题和布局设置
├── api/                      # HTTP 请求函数
├── views/                    # 页面与页面级组件
├── router/                   # 路由定义
├── store/                    # Pinia 状态管理
├── layout/                   # 主页面布局
├── components/               # 跨页面通用组件
├── composables/              # Vue 组合式函数
├── directive/                # 自定义指令
├── plugins/                  # 全局插件
├── utils/                    # 通用工具
├── assets/                   # 编译期静态资源
└── locales/                  # 页面和菜单多语言文案

src 源码结构优势

定位快捷：views 与 api 按业务域对应，便于追踪请求。
职责清晰：页面、路由、状态和公共能力分目录管理。
易于扩展：公共组件和多语言资源集中复用。

3.3、路由机制

前端路由有两个来源：

登录、详情、编辑等固定或隐藏路由在 src/router 中维护。
菜单路由由主后端 /getRouters 返回，src/store/system/permission.js 使用 import.meta.glob 将组件路径转换为 src/views 中的 Vue 组件并动态注册。

3.4、如何找到前端对应的后端模块

前端按业务目录组织页面与请求，后端按相同业务边界拆分模块，常见对应关系如下：

业务功能	前端模块	后端模块
数据资产	`src/views/da`、`src/api/da`	`qdata-module-da`
元数据采集	`src/views/mc`、`src/api/mc`	`qdata-module-mc`
数据集成与开发	`src/views/dpp`、`src/api/dpp`	`qdata-module-dpp`
数据服务	`src/views/ds`、`src/api/ds`	`qdata-module-ds`
系统管理	`src/views/system`、`src/api/system`	`qdata-module-system`

前后端使用相同的业务缩写和模块边界，例如 da 表示数据资产，mc 表示元数据采集。

前后端模块对应优势

结构直观：看到前端目录即可判断对应的后端业务模块。
职责统一：同一业务的页面、请求和后端实现集中在相同领域内，减少模块交叉。
协作高效：前后端开发人员可以围绕同一业务模块并行开发和沟通。
维护方便：修改或排查某项业务时，能够快速确定相关代码范围。
扩展清晰：新增业务功能时可沿用相同的目录与模块规则，保持工程结构一致。

3.5、如何定位前端页面源码

进行二次开发时，可以通过以下方式找到浏览器页面对应的 .vue 文件：

记录页面信息：打开目标页面，记下浏览器地址、菜单名称和页面中有辨识度的文字。
查找固定页面：在 src/router 中搜索地址里的路由路径，路由配置中的 component 会指向对应的 src/views 文件。
通过菜单管理查找：进入 系统管理 → 菜单管理，按菜单名称找到目标菜单，查看其 组件路径，再到 src/views 中定位对应的页面文件。
按业务目录查找：根据地址中的业务缩写在 src/views 下查找同名目录，例如 da/asset 通常对应 src/views/da/asset。
通过页面文字查找：如果无法从路径定位，可在 src/views 中搜索页面标题、按钮名称或提示文字。

新增 .vue 文件后，还需要由路由或其他组件引用，页面才能被访问。

4、后端工程模块介绍

后端代码主要由业务模块、公共框架和独立执行程序组成。主服务通过 Maven 依赖各业务的 biz 子模块，将业务能力装配到同一运行进程中；ETL、质量和 AI 则根据运行特点独立执行。

4.1、`qdata-framework`

公共框架聚合模块，包含以下子模块：

子模块	提供的能力
`qdata-common`	统一返回对象、异常、基础对象、枚举、注解、工具类、Excel、加密脱敏和数据库适配
`qdata-config`	Spring、线程池、国际化、过滤器、验证码、RabbitMQ、OpenAPI 和服务器监控配置
`qdata-mybatis`	MyBatis-Plus、分页、基础 Mapper、动态数据源、数据权限查询和类型处理
`qdata-security`	登录认证、令牌校验、接口权限、数据权限、限流、操作日志和全局异常处理
`qdata-auth`	Sa-Token、OAuth2 及授权模式相关配置
`qdata-redis`	Redis 序列化、缓存配置和通用缓存服务
`qdata-websocket`	WebSocket 配置、在线会话管理和消息推送
`qdata-quartz`	Quartz 任务管理、执行策略、运行日志和统一调度适配
`qdata-file`	文件上传、存储配置和文件处理工具
`qdata-generator`	数据库表解析，以及前端、后端、SQL 和多语言代码模板生成
`qdata-neo4j`	Neo4j 节点、关系、Repository 和数据血缘访问
`qdata-pay`	支付宝、微信支付、退款、回调通知和签名验证

模块优势

公共能力集中复用：安全、数据库、缓存、文件、调度和图数据访问等基础能力统一维护，让业务模块专注业务模逻辑并保持一致的技术实现。

4.2、`api` 与 `biz` 的拆分

多数业务模块采用以下结构：

qdata-module-xxx/
├── pom.xml
├── qdata-module-xxx-api/
│   └── src/main/java/.../api/
│       ├── dto/               # 跨模块传递的数据对象
│       ├── service/           # 暴露给其他模块的服务接口
│       └── enums/             # 共享枚举，部分模块存在
└── qdata-module-xxx-biz/
    └── src/main/
        ├── java/.../module/xxx/
        │   ├── controller/    # HTTP 接口与请求、响应 VO
        │   ├── service/       # 业务接口与实现
        │   ├── dal/
        │   │   ├── dataobject/# 数据库实体 DO
        │   │   └── mapper/    # MyBatis Mapper 接口
        │   ├── convert/       # DTO、VO、DO 对象转换
        │   └── utils/         # 业务模内部工具
        └── resources/
            ├── mapper/        # MyBatis XML
            ├── i18n/          # 模块国际化文案
            └── application-*.yml

模块优势

跨模块边界明确：*-api 只暴露接口、DTO 和共享枚举，*-biz 保留 Controller、Service、Mapper 和业务模实现，避免其他模块直接依赖内部实现。

*-api 是跨模块调用的契约层。其他业务模需要复用能力时，应优先依赖这里的接口和 DTO。
*-biz 是完整实现层，包含 Controller、Service、Mapper 和资源文件，由 qdata-server 统一装配。

4.3、ETL 模块

qdata-executor-etl 负责执行数据读取、清洗转换和写出，不对外提供 Web 接口。

qdata-executor-etl/src/main/
├── java/tech/qiantong/qdata/
│   ├── spark/etl/
│   │   ├── EtlApplication.java     # Spark ETL 主入口
│   │   ├── reader/                 # 数据读取组件
│   │   ├── transition/             # 清洗与转换组件
│   │   ├── writer/                 # 数据写出组件
│   │   └── utils/                  # 日志、RabbitMQ、Redis 和数据库工具
│   └── datax/
│       ├── DataXExecutor.java       # DataX 执行器
│       ├── DataXJsonBuilder.java    # DataX Job JSON 构建
│       ├── DataXProperties.java     # DataX 配置
│       └── DataXResult.java         # DataX 执行结果
└── resources/
    ├── i18n/                       # ETL 国际化文案
    └── json/                       # 任务配置示例

模块优势

管理与执行解耦：DPP 负责任务配置和调度，qdata-executor-etl 专注 Spark / DataX 计算；Reader、Transition、Writer 按职责拆分，便于独立扩展输入、转换和输出能力。

组件	职责
`ReaderFactory`	根据组件类型选择数据库、CSV 或 Excel Reader
`TransitionFactory`	选择字段、常量、去重、派生、排序和值映射等转换
`WriterFactory`	根据组件类型选择数据写出实现
`RabbitmqUtils`	回传流程实例、节点实例和日志
`RedisUtils`	保存增量读取等执行状态
`DataXJsonBuilder`	根据输入、处理和输出节点生成 DataX Job JSON
`DataXExecutor`	调用 DataX 并采集执行结果

Spark ETL 调用链：

qdata-module-dpp
  → qdata-api-ds
  → DolphinScheduler
  → EtlApplication
  → ReaderFactory → TransitionFactory → WriterFactory
  → RabbitMQ
  → qdata-module-dpp/listener 更新状态和日志

状态监听器位于：

qdata-module-dpp/qdata-module-dpp-biz/src/main/java/
└── tech/qiantong/qdata/module/dpp/listener/
    ├── ProcessListener.java
    ├── TaskListener.java
    └── TaskLogListener.java

使用前需准备 qData 主服务、DolphinScheduler、Spark、RabbitMQ、Redis，以及任务需要访问的源端和目标端数据源。后端配置应指向正确的 Spark Master、ETL JAR 和入口类：

ds:
  spark:
    master_url: spark://spark:7077
    main_jar: file:/dolphinscheduler/default/resources/spark-jar/qdata-executor-etl.jar
    main_class: tech.qiantong.qdata.spark.etl.EtlApplication

构建并将 JAR 上传到 ds.spark.main_jar 对应的 DolphinScheduler 资源目录：

mvn clean package -pl qdata-executor-etl -am -DskipTests

然后在 qData 的 ETL 页面完成以下操作：

配置并测试源端、目标端数据源。
新建数据集成任务，添加一个读取节点、零个或多个转换节点和一个写入节点。
保存并发布任务，由 DolphinScheduler 提交到 Spark 执行。
在任务实例和节点日志页面查看状态与错误信息。

4.4、AI 模块

独立 qdata-service-ai 工程负责模型调用、对话编排和 Text2SQL。

模块	定位	主要职责
`qdata-ai-core`	独立 AI 工程的核心模块	Prompt、模型适配、对话编排和 Text2SQL
`qdata-ai-server`	独立 AI 工程的启动模块	HTTP 接口、安全认证、异常处理和运行配置

独立 qdata-service-ai 结构：

qdata-service-ai/
├── pom.xml
├── qdata-ai-core/
│   └── src/main/java/.../ai/core/
│       ├── enums/                    # 平台、消息和回复类型
│       ├── prompt/                   # Prompt 构建
│       ├── service/                  # 会话、消息和模型服务
│       ├── service/impl/             # 智能问数核心实现
│       ├── utils/                    # LLM 工具
│       └── vo/                       # 请求与响应对象
└── qdata-ai-server/
    └── src/main/
        ├── java/.../ai/
        │   ├── server/               # 启动、安全和异常处理
        │   └── controller/admin/     # 模型、会话和消息接口
        └── resources/                # AI 服务配置

AI 请求关系：

智能问数页面
  → requestAi.js → /prod-ai/chat/message
  → qdata-ai-server → qdata-ai-core → 大模型服务

模块优势

独立部署：qdata-service-ai 独立承担模型调用与 Text2SQL，可根据 AI 负载单独部署、升级和扩容。

qdata-service-ai 必须使用 JDK 17，主工程仍使用 JDK 8。原因是 AI 工程基于 Spring Boot 3.5.8、Spring AI 1.1.0 和 Jakarta 生态，这些依赖要求 Java 17，无法直接使用主工程的 JDK 8 运行。

AI 服务是独立 Maven 工程，需要单独构建和启动：

cd qdata-service-ai
mvn clean package -DskipTests
java -jar qdata-ai-server/target/qdata-ai-server.jar --spring.profiles.active=dev

也可以在 IDE 中为 qdata-service-ai 配置 JDK 17，运行：

qdata-service-ai/qdata-ai-server/src/main/java/
└── tech/qiantong/qdata/ai/server/QDataAiApplication.java

服务默认端口为 8087，前端通过 /prod-ai 访问。启动前应确认 AI 服务使用的数据库、Redis、Neo4j 和模型接口配置可用。修改共享 DTO、API 或依赖后，需要分别验证 Java 8 主工程和 Java 17 AI 工程。

5、配置、数据库与部署文件说明

5.1、项目配置

配置类型	主要位置	说明
主服务公共配置	`qdata-server/src/main/resources/application.yml`	端口、Profile、MyBatis、接口文档和通用 Spring 配置
主服务环境配置	`qdata-server/src/main/resources/application-dev.yml`、`application-prod.yml`	数据库、Redis、RabbitMQ、DolphinScheduler 和质量服务地址等
质量服务配置	`qdata-service-quality/src/main/resources/application*.yml`	质量执行数据库、MongoDB、文件和消息组件配置
AI 服务配置	`qdata-service-ai/qdata-ai-server/src/main/resources/application*.yml`	AI 服务数据源、Redis、模型和业务模配置
文件配置片段	`qdata-framework/qdata-file/src/main/resources/application-file-*.yml`	文件存储配置
系统配置片段	`qdata-module-system/qdata-module-system-biz/src/main/resources/application-system-*.yml`	系统模块配置
元数据配置片段	`qdata-module-mc/qdata-module-mc-biz/src/main/resources/application-mc-*.yml`	元数据采集配置
前端环境配置	`qdata-ui/.env.*`、`qdata-ui/vite.config.js`	接口前缀、认证模式、开发代理和构建配置

5.2、数据库脚本

sql/
├── mysql/
│   ├── initialization/       # 各版本完整初始化脚本
│   └── upgrade/              # 相邻版本升级脚本
├── dm/
│   ├── initialization/       # 达梦完整初始化脚本
│   └── upgrade/              # 达梦升级脚本
└── dolphinscheduler/
    └── upgrade/              # DolphinScheduler 相关升级脚本

5.3、Docker

文件或目录	作用
`docker/docker-compose.yml`	完整环境的 Compose 编排入口
`docker/docker-compose-base*.yml`	数据库、Redis、RabbitMQ 等基础组件
`docker/docker-compose-qdata*.yml`	qData 服务相关编排
`docker/docker-compose-dolphinscheduler.yml`	DolphinScheduler 编排
`docker/docker-compose-spark.yml`	Spark 编排
`docker/docker-compose-hadoop.yml`	Hadoop 相关组件编排
`docker/nginx/sites/qdata.conf`	前端静态资源及 `/prod-api`、`/prod-ai` 反向代理
`docker/qdata-server`	主服务镜像构建文件
`docker/qdata-service-quality`	质量服务镜像构建文件
`docker/qdata-service-ai`	AI 服务镜像构建文件
`docker/dolphinscheduler`	DolphinScheduler 配置、SQL、资源和依赖文件