跳到主要内容

数据分析链路

引用文件

本文引用的文件

目录​

  1. 简介
  2. 项目结构
  3. 核心组件
  4. 架构总览
  5. 详细组件分析
  6. 依赖关系分析
  7. 性能考量
  8. 故障排查指南
  9. 结论
  10. 附录

简介​

本技术文档围绕“数据分析链路”展开，覆盖从数据采集到分析输出的完整流程，重点包括：

  • 数据源配置与多数据源路由
  • SQL 查询执行与结果集处理
  • 数据格式转换与统一响应模型
  • TDengine 时序数据库的集成实现（JDBC 连接、动态数据源切换、SQL 查询优化、元数据解析）
  • 多数据源查询机制（数据源标识、连接池管理、事务控制、异常处理）
  • 数据查询 API 接口文档（请求参数、响应格式、错误码说明）
  • 性能优化建议与最佳实践

项目结构​

数据分析能力主要集中在 report 模块的控制器、服务层、工具类与 SQL 资源中，并通过动态数据源切换实现对 MySQL、TDengine、ES、Redis 等多种数据源的统一访问。

Mermaid Diagram Code:

graph TB
subgraph "报告模块"
C["GoViewDataController<br/>REST 控制器"]
Svc["GoViewDataService 接口"]
MysqlSvc["GoViewMysqlDataServiceImpl<br/>MySQL 实现"]
TDEngSvc["GoViewTDEngineDataServiceImpl<br/>TDengine 实现"]
Util["SqlParamUtil<br/>SQL 参数与时间参数处理"]
Const["DataSourceConstants<br/>数据源常量"]
end
subgraph "配置与资源"
Yaml["datasource.yaml<br/>生产环境数据源配置"]
SQLApp["app_activity.sql<br/>TDengine 应用活跃表结构"]
SQLDev["device_runtime.sql<br/>TDengine 设备运行表结构"]
SQLMon["monitor.sql<br/>TDengine 监控表结构"]
end
C --> Svc
Svc --> MysqlSvc
Svc --> TDEngSvc
C --> Util
C --> Const
MysqlSvc --> Yaml
TDEngSvc --> Yaml
MysqlSvc --> SQLApp
MysqlSvc --> SQLDev
MysqlSvc --> SQLMon

图表来源

章节来源

核心组件​

  • 控制器层：统一入口，负责请求参数校验、SQL 加密/解密、参数注入、多 SQL 批量执行、SQL 与 HTTP 示例接口。
  • 服务层：抽象接口与多实现，分别针对 MySQL 与 TDengine 提供统一的 SQL 查询能力。
  • 工具层：SQL 参数与时间参数解析，支持动态参数与日期参数的嵌套替换。
  • 配置层：数据源常量与生产环境 YAML 配置，支撑动态数据源切换与 JDBC 连接。

章节来源

架构总览​

整体采用“控制器-服务-数据源”的分层架构，通过动态数据源上下文在运行时切换目标数据源，实现对 MySQL 与 TDengine 的统一查询入口。

Mermaid Diagram Code:

sequenceDiagram
participant Client as "客户端"
participant Ctrl as "GoViewDataController"
participant Svc as "GoViewDataService"
participant DS as "动态数据源上下文"
participant JDBC as "JdbcTemplate/驱动"
Client->>Ctrl : "POST /report/go-view/data/get-by-sql"
Ctrl->>Ctrl : "参数校验/SQL 加密/注入参数"
Ctrl->>Svc : "根据 dataSource 选择具体实现"
Svc->>DS : "push(dataSource)"
Svc->>JDBC : "queryForRowSet(sql)"
JDBC-->>Svc : "SqlRowSet 结果集"
Svc->>Svc : "解析元数据/构建响应"
Svc-->>Ctrl : "GoViewDataRespVO"
Ctrl-->>Client : "JSON 响应"
Svc->>DS : "clear() 清理上下文"

图表来源

详细组件分析​

控制器层：GoViewDataController​

  • 职责
    • 统一入口，支持单 SQL、批量 SQL、HTTP 示例接口。
    • 对 SQL 进行加密/解密与参数注入，确保安全与灵活性。
    • 根据 dataSource 路由到不同数据源实现。
  • 关键流程
    • 请求参数校验与 SQL 加密。
    • 通过工厂方法选择具体服务实现。
    • 将 Map 形式的明细数据转换为表格形式（可选）。
  • 错误处理
    • 当 dataSource 不支持时抛出业务异常。

章节来源

服务层接口与实现​

接口：GoViewDataService​

  • 方法：getDataBySQL(reqVO) 返回 GoViewDataRespVO。
  • 设计意图：屏蔽底层数据源差异，统一对外查询能力。

章节来源

实现：GoViewMysqlDataServiceImpl​

  • 功能
    • 使用 JdbcTemplate 执行 SQL，解析 SqlRowSet 元数据与明细。
    • 通过动态数据源上下文切换至指定数据源。
    • 返回统一响应对象。
  • 优化点
    • 使用 LinkedList 存储明细，避免扩容复制成本。
    • 使用有序 Map 保持列顺序一致性。

章节来源

实现：GoViewTDEngineDataServiceImpl​

  • 功能
    • 面向 TDengine 的查询实现，同样通过动态数据源上下文切换。
    • 使用 JDBC RowSet 解析列名与数据，构建统一响应。
  • 特殊点
    • 在非默认数据源时手动切换数据源上下文。
    • 通过注释保留了基于注解的自动切换方式（可选启用）。

章节来源

MyBatis 映射：TDEngineBaseMapper​

  • 功能
    • 通过注解绑定到 TDengine 数据源常量，便于 MyBatis 层面的 TDengine 访问。
  • 适用场景
    • 需要使用 MyBatis 的实体映射与通用 Mapper 能力时。

章节来源

实体：JmTdEntity​

  • 作用
    • 作为 TDengine 相关实体的占位类，配合 MyBatis Mapper 使用。

章节来源

工具层：SqlParamUtil​

  • 功能
    • 动态参数替换：支持嵌套参数，最多递归 20 次，防止循环引用。
    • 日期参数替换：支持多种偏移类型（年/月/日/时/分/秒/周/季度）与输出格式。
    • 时间戳输出：支持毫秒级时间戳输出。
  • 使用场景
    • 报表设计时在 SQL 中使用占位符，运行时由参数注入替换。

章节来源

数据源常量：DataSourceConstants​

  • 功能
    • 统一管理数据源标识，包括默认、MySQL、TDengine、ES、Redis。
  • 价值
    • 保证各模块间常量一致，避免魔法字符串。

章节来源

TDengine 数据库脚本​

  • 应用活跃明细：按日/月/年划分数据库与超级表结构，支持活跃时长、IP、国家等字段扩展。
  • 设备运行时长：提供按日/月/年划分的统计表结构。
  • 监控指标：按分钟粒度统计接口访问次数与成功率等。

章节来源

TDengine 标签与查询示例​

  • 单测中展示了对 TDengine 表的标签与分区查询示例，便于理解数据组织方式与查询策略。

章节来源

依赖关系分析​

  • 控制器依赖服务接口与工具类，通过工厂方法选择具体实现。
  • 服务实现依赖动态数据源上下文与 JDBC 模板。
  • 生产环境 YAML 提供 TDengine JDBC URL、用户名、密码等配置。
  • MyBatis Mapper 通过注解绑定 TDengine 数据源常量。

Mermaid Diagram Code:

graph LR
Ctrl["GoViewDataController"] --> IFace["GoViewDataService"]
IFace --> ImplM["GoViewMysqlDataServiceImpl"]
IFace --> ImplT["GoViewTDEngineDataServiceImpl"]
ImplM --> DSConst["DataSourceConstants"]
ImplT --> DSConst
ImplM --> Yaml["datasource.yaml"]
ImplT --> Yaml
ImplM --> Util["SqlParamUtil"]
ImplT --> Util
ImplT --> Mapper["TDEngineBaseMapper"]

图表来源

章节来源

性能考量​

  • 结果集处理
    • 使用 SqlRowSet 逐行读取，避免一次性加载全部数据到内存。
    • 使用 LinkedList 存储明细，减少扩容复制成本。
  • 参数处理
    • 动态参数与日期参数支持嵌套与递归替换，注意最大递归深度，防止循环引用导致栈溢出。
  • 数据源切换
    • 在非默认数据源时手动切换上下文，结束后及时清理，避免上下文泄漏。
  • JDBC 连接
    • 生产环境使用 RestfulDriver 连接 TDengine，建议结合连接池配置与超时设置，确保高并发下的稳定性。
  • SQL 优化
    • 针对 TDengine 的时间序列特性，合理利用超级表与标签过滤，减少扫描范围。
    • 在报表查询中尽量使用聚合与分区裁剪，避免全表扫描。

故障排查指南​

  • 数据源不可用
    • 现象：连接失败或查询异常。
    • 排查：检查 datasource.yaml 中的 JDBC URL、用户名、密码是否正确；确认 TDengine 服务可达。
  • SQL 注入与参数问题
    • 现象：参数未生效或报错。
    • 排查：确认 SQL 中占位符格式与参数键名一致；检查 SqlParamUtil 的替换逻辑与递归深度限制。
  • 数据源切换异常
    • 现象：切换后仍访问默认数据源。
    • 排查：确认 dataSource 值与 DataSourceConstants 常量一致；确保在 finally 中调用清理方法。
  • 响应格式不符合预期
    • 现象：表格形式与明细形式混用导致前端解析困难。
    • 排查：区分 /get-by-sql 与 /get-by-sql/2/table 的返回结构；确保前端按接口约定消费。

章节来源

结论​

该数据分析链路通过统一的控制器与服务接口，结合动态数据源切换与 JDBC 查询能力，实现了对 MySQL 与 TDengine 的灵活访问。配合 SQL 参数与时间参数工具，满足报表设计与运行时参数注入的需求。建议在生产环境中进一步完善连接池配置、SQL 优化与异常监控，持续提升查询性能与稳定性。

附录​

数据查询 API 接口文档​

  • 接口：使用 SQL 查询数据（单条）

    • 方法：POST
    • 路径：/report/go-view/data/get-by-sql
    • 权限：report:go-view-data:get-by-sql
    • 请求体：GoViewDataGetBySqlReqVO
      • sql：必填，密文字符串（后端解密）
      • dataSource：可选，数据源标识（默认 master；支持 mysql、tdengine、es、redis 等）
      • tableName：可选，ES 等非标准 SQL 的索引名
      • standardSql：可选，是否为标准 SQL（默认 true）
    • 响应：GoViewDataRespVO
      • dimensions：列名数组
      • source：明细数据列表（每项为列名到值的映射）

  • 接口：使用 SQL 查询数据（表格形式）

    • 方法：POST
    • 路径：/report/go-view/data/get-by-sql/2/table
    • 权限：report:go-view-data:get-by-sql
    • 请求体：同上
    • 响应：二维数组（按列顺序排列的行数据）

  • 接口：使用 SQL 查询数据（多条，保持顺序）

    • 方法：POST
    • 路径：/report/go-view/data/get-by-sqls
    • 权限：report:go-view-data:get-by-sql
    • 请求体：GoViewDataGetBySqlReqVO 列表
    • 响应：GoViewDataRespVO 列表（按提交顺序返回）

  • 接口：SQL 加密/解密（调试辅助）

    • 方法：POST
    • 路径：/report/go-view/data/djfn37dfhf73hcs723nf（加密）
    • 路径：/report/go-view/data/dmhd62hdfgikas2asbjsd72sd（解密）
    • 权限：report:go-view-data:get-by-sql
    • 请求参数：sql（明文或密文）
    • 响应：处理后的字符串

  • 请求参数说明

    • dataSource：支持前缀匹配（如 mysql 开头即走 MySQL 实现），若为默认或以 tdengine 开头则走 TDengine 实现。
    • params：查询参数，用于 SqlParamUtil 注入 SQL 占位符。

  • 响应格式说明

    • GoViewDataRespVO：包含 dimensions 与 source 两部分，source 为有序映射列表，保证列顺序稳定。
    • 表格形式：将 source 中的每行映射按列顺序转为对象列表，便于前端展示。

  • 错误码说明

    • 不支持的数据源：当 dataSource 无法匹配任何实现时抛出业务异常（由控制器内部处理）。

章节来源

用户文档
AI 助手
Agent 列表
请选择一个 Agent 开始对话
AI 问答