跳到主要内容

数据分析链路

目录

  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 问答