vitepress-template

Appearance

分析服务API ​

**本文档引用的文件** - [[[[[bi-analysis/README.md]]]]](file/bi-analysis/readme.md) - [[[[[bi-analysis/cmd/bi-analysis/main.go]]]]](file/bi-analysis/cmd/bi-analysis/main.go) - [[[[[bi-analysis/go.mod]]]]](file/bi-analysis/go.mod) - [[[[[bi-analysis/api/anls/v1/query.proto]]]]](file/bi-analysis/api/anls/v1/query.proto) - [[[[[bi-analysis/api/anls/v1/table.proto]]]]](file/bi-analysis/api/anls/v1/table.proto) - [[[[[bi-analysis/api/anls/v1/template.proto]]]]](file/bi-analysis/api/anls/v1/template.proto) - [[[[[bi-analysis/api/anls/v1/field.proto]]]]](file/bi-analysis/api/anls/v1/field.proto) - [[[[[bi-analysis/api/anls-m/v1/dimension.proto]]]]](file/bi-analysis/api/anls-m/v1/dimension.proto) - [[[[[bi-analysis/internal/biz/query.go]]]]](file/bi-analysis/internal/biz/query.go) - [[[[[bi-analysis/internal/biz/table.go]]]]](file/bi-analysis/internal/biz/table.go) - [[[[[bi-analysis/internal/biz/template.go]]]]](file/bi-analysis/internal/biz/template.go) - [[[[[bi-analysis/internal/biz/field.go]]]]](file/bi-analysis/internal/biz/field.go) - [[[[[bi-analysis/internal/biz/dimension.go]]]]](file/bi-analysis/internal/biz/dimension.go)

目录 ​

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

简介 ​

本文件为 bi-analysis 分析服务的全面 API 文档，覆盖指标查询、数据表操作、模板管理、维度管理等分析相关能力。文档基于项目实际代码与协议定义，说明查询引擎的 API 设计、SQL 构建接口与结果集处理流程，并提供性能优化建议、查询限制说明、实际查询示例与响应格式说明，以及分析服务与数据存储的交互方式与缓存策略。

项目结构 ​

bi-analysis 采用 Kratos 微服务框架，结合 bi-common 公共组件，提供统一响应格式与 OpenAPI 文档生成能力。项目通过 proto 定义 API，经 gateway 生成 HTTP 接口，内部通过 biz 层编排业务逻辑，data 层对接数据存储。

图表来源

章节来源

核心组件 ​

  • 查询服务（QueryService）：提供数据预览查询与 SQL 获取接口，支持行维度、列维度、指标、筛选条件、排序、分页与汇总/排名控制。
  • 数据表服务（TableService）：提供自定义数据表配置、批量/单条自定义数据写入、自定义数据查询与分页。
  • 模板服务（TemplateService）：提供分析模板的保存、查询、列表、删除与排序批量更新。
  • 指标字段服务（FieldService）：提供自定义指标字段、订单指标字段、公式字段与衍生指标字段的保存、删除与管理端维护。
  • 维度服务（DimensionService）：提供维度的列表、创建、更新、状态变更、删除与批量删除。

章节来源

架构总览 ​

分析服务基于 Kratos 框架，通过 Nacos 配置中心加载运行配置，统一响应格式，支持 OpenAPI 文档生成与同步。HTTP 请求经 gateway 映射到 gRPC 服务，biz 层负责业务编排与 SQL 构建，data 层对接底层存储。

图表来源

详细组件分析 ​

查询服务 API ​

  • 服务：QueryService
  • 功能：数据预览查询、获取 SQL（调试）
  • 关键点：
    • 支持行维度、列维度、指标、筛选条件、排序、分页、排名与汇总控制
    • 自动解析字段配置与公式依赖，按租户维度构建 SQL
    • 订单指标场景下自动解析可用店铺集合，确保表名正确拼接
    • 返回统一响应结构，包含配置、列表、总数与 SQL

图表来源

章节来源

查询请求参数 ​

  • 行维度（c_row）：逗号分隔的维度标识
  • 列维度（c_col）：通常为 field
  • 指标（c_field）：逗号分隔的指标标识
  • 字段配置（c_field_config）：运行时配置 JSON
  • 展示样式（c_style）、排序（c_order_by、c_order）、分页（page、limit）
  • 排名/汇总（b_rank、b_sum）
  • 筛选条件（SearchCondition）：日期范围、店铺、商品、负责人、分类、平台、状态、收藏夹等

章节来源

查询响应结构 ​

  • config：包含 row、col、field
  • list：动态字段列表
  • count：总记录数（字符串）
  • sql：生成的 SQL（调试）

章节来源

SQL 构建与结果处理 ​

  • 用例层负责解析参数、加载字段与维度配置、解析公式依赖、处理日期范围、按租户与店铺信息拼接表名
  • 使用 SQLBuilder 生成最终 SQL，执行后对结果进行格式化与总数统计

章节来源

数据表配置 API ​

  • 服务：TableService
  • 功能：数据表配置列表、创建、批量/单条自定义数据写入、自定义数据查询与分页
  • 关键点：
    • 创建时校验维度 key 有效性与维度组合唯一性（忽略顺序）
    • 自动生成物理表名 diy_{租户ID}_
    • 批量/单条写入按维度组合判断新增或更新
    • 默认分页上限与安全校验

图表来源

章节来源

自定义数据写入 ​

  • 批量写入：按行维度与指标字段进行 upsert，返回每行处理结果与新增/更新标记
  • 单条写入：按维度与数值字段 upsert，返回字段与新增/更新标记
  • 查询分页：支持按字段条件进行单值精确或双值范围查询

章节来源

模板配置 API ​

  • 服务：TemplateService
  • 功能：保存模板、获取模板详情、模板列表、删除模板、批量设置模板排序
  • 关键点：
    • 保存时检查名称唯一性，设置默认图标、颜色与列维度
    • 删除模板时级联删除关联的字段可见性配置
    • 排序批量更新按租户维度执行

图表来源

章节来源

指标字段配置 API ​

  • 服务：FieldService
  • 功能：保存自定义指标字段、删除自定义指标字段；保存订单指标字段、删除订单指标字段；保存公式字段、删除公式字段；保存衍生指标字段、删除衍生指标字段
  • 关键点：
    • 保存自定义指标字段时，若表名未设置则从表ID获取，校验显示名称唯一性
    • DDL 操作（添加/删除列）不在事务中执行，失败时回滚记录
    • 订单指标字段保存时进行表字段与过滤条件校验
    • 公式与衍生指标保存时进行唯一性与依赖字段校验

图表来源

章节来源

维度管理 API ​

  • 服务：DimensionService
  • 功能：维度列表、创建、更新、变更状态、删除、批量删除
  • 关键点：
    • 创建与更新时检查维度标识唯一性
    • 批量删除支持 1-100 个 ID
    • 提供全量维度列表与分页查询

图表来源

章节来源

依赖关系分析 ​

  • 服务依赖：各服务均依赖对应的用例层，用例层依赖仓储接口，仓储接口对接底层数据存储
  • 外部依赖：Kratos 框架、Nacos 配置中心、OpenAPI 文档生成、bi-common 组件库

图表来源

章节来源

性能考虑 ​

  • SQL 构建与执行
    • 通过 SQLBuilder 在用例层集中构建 SQL，避免分散逻辑导致的重复扫描与拼接错误
    • 对订单指标场景，按租户与可用店铺集合动态选择表名，减少无关表扫描
  • 结果集处理
    • 统一格式化输出，避免空值与时间字段格式化差异带来的前端处理开销
    • 仅在需要时计算总数（i_count），避免不必要的聚合
  • 分页与限制
    • 自定义数据查询默认分页参数与上限保护，防止大页查询造成内存压力
  • 缓存策略
    • 查询请求支持缓存开关（cache 字段），可在网关或上游进行缓存控制，降低重复查询压力
  • 并发与资源
    • 使用 Kratos 的并发控制与资源管理，结合 automaxprocs 优化 CPU 利用率

[本节为通用指导，无需列出具体文件来源]

故障排查指南 ​

  • 字段依赖解析失败
    • 现象：公式字段依赖无法解析或缺失
    • 排查：确认字段表达式中的引用字段存在且可解析，检查 loadFormulaDependencies 递归加载逻辑
  • 店铺信息缺失
    • 现象：订单指标查询时报错“未找到可用的店铺信息”
    • 排查：确认租户下是否存在可用店铺，或筛选条件中的店铺 ID 是否有效
  • 自定义表创建失败
    • 现象：创建自定义表配置时 DDL 失败
    • 排查：检查维度 key 是否有效、维度组合是否重复、物理表创建权限与命名规则
  • 字段列操作异常
    • 现象：新增/更新/删除字段列失败
    • 排查：DDL 操作不在事务中执行，需检查表结构变更权限与字段注释设置
  • 模板删除级联问题
    • 现象：删除模板后字段可见性配置未清理
    • 排查：确认模板删除流程中是否调用字段可见性仓储的删除接口

章节来源

结论 ​

本 API 文档基于 bi-analysis 项目的实际实现，系统性地梳理了查询、表配置、模板与字段配置、维度管理等核心能力。通过统一响应格式、OpenAPI 文档与清晰的业务分层，服务具备良好的扩展性与可维护性。建议在生产环境中结合缓存策略与查询限制，持续监控 SQL 执行计划与资源占用，确保查询性能与稳定性。

[本节为总结性内容，无需列出具体文件来源]

附录 ​

API 规范与统一响应 ​

  • 统一响应结构
    • 成功：包含 code、message、data
    • 分页列表：data 包含 total 与 list
    • 单条数据：data 为对象
  • 错误码与消息：由 apitypes 中间件统一处理

章节来源

查询示例与响应格式 ​

  • 示例请求
    • 行维度：多个维度以逗号分隔
    • 指标：多个指标以逗号分隔
    • 筛选条件：日期范围、店铺 ID、商品 ID、平台、状态等
    • 排序与分页：支持按字段升/降序与页码/条数控制
  • 示例响应
    • config：包含 row、col、field
    • list：动态字段列表
    • count：总记录数（字符串）
    • sql：生成的 SQL（调试）

章节来源

查询限制与最佳实践 ​

  • 自定义数据查询默认分页上限与安全校验
  • 字段表达式解析支持 JSON 与简单表达式两种形式
  • 订单指标场景下必须存在可用店铺集合
  • 模板保存时自动设置默认图标、颜色与列维度

章节来源