vitepress-template

Appearance

bi-analysis 核心分析服务 ​

**本文引用的文件** - [[README.md]](../file/bi-analysis/readme.md) - [[go.mod]](../file/bi-analysis/go.mod) - [[cmd/bi-analysis/main.go]](../file/bi-analysis/cmd/bi-analysis/main.go) - [[internal/biz/query.go]](../file/bi-analysis/internal/biz/query.go) - [[internal/biz/sql_builder.go]](../file/bi-analysis/internal/biz/sql-builder.go) - [[internal/data/query.go]](../file/bi-analysis/internal/data/query.go) - [[internal/data/data.go]](../file/bi-analysis/internal/data/data.go) - [[internal/service/query.go]](../file/bi-analysis/internal/service/query.go) - [[internal/server/server.go]](../file/bi-analysis/internal/server/server.go) - [[internal/server/grpc.go]](../file/bi-analysis/internal/server/grpc.go) - [[internal/data/basic_client.go]](../file/bi-analysis/internal/data/basic-client.go) - [[internal/data/tenant_client.go]](../file/bi-analysis/internal/data/tenant-client.go) - [[internal/service/field_dict.go]](../file/bi-analysis/internal/service/field-dict.go) - [[internal/service/template_grpc.go]](../file/bi-analysis/internal/service/template-grpc.go) - [[api/anls/v1/query.proto]](../file/bi-analysis/api/anls/v1/query.proto) - [[internal/conf/conf.proto]](../file/bi-analysis/internal/conf/conf.proto) - [[configs/application-dev.yaml]](../file/bi-analysis/configs/application-dev.yaml) - [[internal/data/model/field.go]](../file/bi-analysis/internal/data/model/field.go) - [[internal/data/model/table.go]](../file/bi-analysis/internal/data/model/table.go) - [[docs/指标实现情况.md]](../file/bi-analysis/docs/.md)

更新摘要 ​

所做更改

  • 更新了依赖关系分析部分，反映移除了对 bi-proto 模块的依赖
  • 更新了服务适配与鉴权章节，反映 gRPC 客户端重构
  • 更新了架构图和组件关系图，体现新的依赖结构
  • 新增了服务间通信章节，说明与 bi-basic 和 bi-tenant 的集成

目录 ​

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

简介 ​

bi-analysis 是基于 Kratos 框架的 BI 分析服务，提供统一的查询 API、灵活的指标与维度组合、SQL 动态生成与执行、以及与 StarRocks 等数据库的集成能力。服务支持自定义指标、公式指标、衍生指标与订单/财务指标的联合分析，具备分页、排名、汇总等高级查询能力，并通过 OpenAPI 文档与 Apifox 同步，便于前后端协作。

项目结构 ​

  • 顶层采用 Kratos 微服务标准目录结构，包含 api、internal、third_party、configs、docs 等模块。
  • 内部采用分层架构：biz（业务用例）、data（数据访问）、service（gRPC/HTTP 服务）、server（网关与中间件）。
  • API 定义位于 api/anls/v1，使用 protobuf 并集成 OpenAPI 注解，自动生成文档。
  • 配置通过 Nacos 管理，支持 dev/test/prod 环境差异化配置。

图表来源

章节来源

核心组件 ​

  • 查询用例（QueryUsecase）：负责解析请求、加载字段/维度配置、解析公式依赖、拼接 SQL、执行查询并格式化结果。
  • SQL 生成器（SQLBuilder）：按字段类型与运行时配置生成复杂 CTE 查询，支持自定义指标、公式、衍生指标与订单/财务指标的联合分析。
  • 数据仓储（QueryRepo）：封装数据库与 Redis 访问，提供字段/维度查询、店铺信息获取、表存在性检查与缓存。
  • 服务适配（QueryService）：gRPC/HTTP 服务适配层，负责请求转换、鉴权中间件、响应封装。
  • 服务器（Server）：统一 gRPC/HTTP 服务器配置与远程鉴权中间件。
  • gRPC 客户端（BasicClient/TenantClient）：封装与 bi-basic 和 bi-tenant 服务的 gRPC 通信。

章节来源

架构总览 ​

服务采用"请求 → 服务适配 → 业务用例 → SQL 生成 → 数据访问 → 结果返回"的链路，结合 Nacos 配置中心、Kratos 服务发现与统一中间件，形成可扩展、可观测的微服务体系。

图表来源

详细组件分析 ​

查询 API 与请求/响应 ​

  • API 定义：提供 Preview 与 GetSQL 两个 RPC，分别用于数据预览与调试输出 SQL。
  • 请求参数：支持行维度、列维度、指标、字段运行时配置、分页、排序、排名、汇总等。
  • 响应格式：统一响应结构，包含配置、数据列表（Struct 动态字段）、总记录数与 SQL（调试）。

图表来源

章节来源

查询用例与 SQL 生成 ​

  • 用例职责：解析请求、加载字段/维度配置、解析公式依赖、兼容日期范围、按需获取店铺信息、构建 SQL、执行查询并格式化结果。
  • SQL 生成：按字段类型分类（基础/公式/衍生/自定义/订单），生成复杂 CTE 查询；支持时间维度序列、LEFT JOIN、维度聚合、排名与分页。
  • 公式解析：支持 JSON 格式公式表达式，递归解析依赖字段并合并加载。

图表来源

章节来源

数据访问与缓存 ​

  • 数据仓储：封装 gormx 与 redisx，提供字段/维度查询、店铺信息获取、表存在性检查与缓存。
  • 表存在性检查：先查缓存，未命中则查询 information_schema，并将结果写入 Redis 永久缓存。
  • 店铺过滤：调用 bi-basic 服务获取字典，过滤无效平台与不存在的订单表。

图表来源

章节来源

服务适配与鉴权 ​

  • 服务适配：将 gRPC 请求转换为业务请求，调用用例执行，再将结果转换为 Protobuf 响应。
  • 鉴权中间件：拦截请求，解析 Authorization，调用 bi-tenant 验证 Token，注入用户与租户信息。

图表来源

章节来源

服务间通信与 gRPC 客户端 ​

  • gRPC 客户端重构：BasicClient 和 TenantClient 独立管理与 bi-basic 和 bi-tenant 服务的连接。
  • 服务发现：通过 Nacos Registry 获取服务实例地址，支持 keepalive 参数配置。
  • 客户端生命周期：提供连接清理函数，确保资源正确释放。

图表来源

章节来源

指标实现概览 ​

  • 已实现：财务指标、退款指标（发生时间）、自定义公式、自定义指标、衍生指标、订单指标等。
  • 未实现：流量/广告/无界/地域/SKU/咨询/分摊等指标，需接入外部数据源或新增数据表。

章节来源

依赖关系分析 ​

更新 项目已移除对 bi-proto 模块的直接依赖，改为通过服务发现和本地接口定义进行通信。

  • 框架与组件：Kratos、bi-common（Nacos、gormx、redisx、kafkax、logger、apitypes 等）。
  • 生成工具：protoc-gen-openapiv2 用于 OpenAPI 文档生成与同步。
  • 配置来源：Nacos，支持多配置优先级与环境切换。
  • 服务依赖：通过 Kratos 服务发现机制调用 bi-basic 和 bi-tenant 服务。

图表来源

章节来源

性能考虑 ​

  • SQL 优化
    • 使用 CTE 分层构建，避免复杂嵌套子查询。
    • 对时间维度（日/周/月）生成序列并 LEFT JOIN，保证缺失日期也能返回 0。
    • 通过运行时配置控制聚合函数（SUM/AVG/MAX/MIN/AVG_CLEAN），减少重复计算。
    • 强制节点提示（FORCE_IMCI_NODES）提升执行计划稳定性。
  • 分页与排名
    • 使用 DENSE_RANK 实现稳定排名，配合 i_order_by 与 f_rank 实现跨维度排序与分页。
  • 缓存策略
    • 表存在性检查使用 Redis 永久缓存，降低 information_schema 查询压力。
    • 可在查询结果层面引入短期缓存（按租户+维度+时间范围键），减少重复查询。
  • 索引建议
    • 商品维度（c_product_id）、日期（t_date）、平台（c_platform）、店铺（i_shop_id）建立复合索引。
    • 订单/退款/试用表按支付时间/发生时间建立合适索引，加速退款/试用类指标。
  • 并发与资源
    • 使用 automaxprocs 自动设置 GOMAXPROCS，提升并发性能。
    • gRPC/HTTP 服务器配置合理超时与并发限制，避免雪崩。

故障排查指南 ​

  • 鉴权失败
    • 检查 Authorization 头是否携带 Bearer Token，确认 Token 在 bi-tenant 中有效。
    • 白名单路径需明确匹配，支持精确与前缀匹配。
  • 查询异常
    • 使用 GetSQL 接口获取生成 SQL，核对字段/维度/筛选条件是否正确。
    • 若提示"暂不支持基础指标"，需改用自定义/公式/衍生/订单指标组合。
  • 数据为空
    • 检查日期范围是否正确，确认时间维度与数据表匹配。
    • 核对店铺过滤条件，确认订单表存在且未被过滤。
  • 表不存在
    • 检查 Redis 缓存是否命中，必要时清理缓存后重试。
    • 确认租户/平台/店铺组合对应的订单表命名规则。
  • 服务发现失败
    • 检查 Nacos 配置是否正确，确认服务实例正常注册。
    • 验证 gRPC 客户端连接参数，特别是 keepalive 配置。

章节来源

结论 ​

bi-analysis 通过清晰的分层架构与强大的 SQL 生成能力，实现了灵活、可扩展的 BI 分析服务。当前已覆盖财务、退款、自定义公式、自定义指标、衍生指标与订单指标等核心领域，未来可通过接入外部数据源逐步完善流量、广告、SKU 等指标体系。配合 Nacos 配置中心、Kratos 中间件与 OpenAPI 文档，服务具备良好的可维护性与可扩展性。

附录 ​

查询 API 接口定义 ​

  • 预览查询（POST /api/v1/anls/query/preview）
    • 请求体：PreviewRequest（含 c_row、c_col、c_field、c_field_config、search、page、limit、c_order_by、c_order、b_rank、b_sum）
    • 响应体：PreviewReply（含 config、list、count、sql）
  • 获取 SQL（POST /api/v1/anls/query/sql）
    • 请求体：PreviewRequest
    • 响应体：GetSQLReply（含 sql）

章节来源

配置说明 ​

  • 环境配置文件：application-{env}.yaml（dev/test/prod）
  • Nacos 配置优先级：bi-common.yaml（通用）→ bi-analysis.yaml（项目）
  • 服务启动：./bin/bi-analysis -env

章节来源

数据模型 ​

  • 字段配置表（anls_field）：字段标识、表名、字段名、显示名、分组、类型、表达式、默认聚合函数等。
  • 数据表配置表（anls_table）：表展示名、维度、描述、排序等。

章节来源

服务间通信协议 ​

  • 指标字典服务：FieldDictService（供其他服务调用）
  • 模板服务：TemplateGRPCService（供其他服务调用）
  • 服务注册：通过 analysisv1 包注册到 gRPC 服务器

章节来源