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 环境差异化配置。

图表来源

• [[[[cmd/bi-analysis/main.go]]]]
• [[[[internal/service/query.go]]]]
• [[[[internal/biz/query.go]]]]
• [[[[internal/biz/sql_builder.go]]]]
• [[[[internal/data/query.go]]]]
• [[[[internal/data/data.go]]]]
• [[[[internal/server/grpc.go]]]]
• [[[[internal/data/basic_client.go]]]]
• [[[[internal/data/tenant_client.go]]]]
• [[[[api/anls/v1/query.proto]]]]

章节来源

• [[[[README.md]]]]
• [[[[go.mod]]]]

核心组件

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

章节来源

• [[[[internal/biz/query.go]]]]
• [[[[internal/biz/sql_builder.go]]]]
• [[[[internal/data/query.go]]]]
• [[[[internal/service/query.go]]]]
• [[[[internal/server/server.go]]]]
• [[[[internal/data/basic_client.go]]]]
• [[[[internal/data/tenant_client.go]]]]

架构总览

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

图表来源

• [[[[internal/service/query.go]]]]
• [[[[internal/biz/query.go]]]]
• [[[[internal/biz/sql_builder.go]]]]
• [[[[internal/data/query.go]]]]

详细组件分析

查询 API 与请求/响应

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

图表来源

• [[[[api/anls/v1/query.proto]]]]
• [[[[api/anls/v1/query.proto]]]]

章节来源

• [[[[api/anls/v1/query.proto]]]]
• [[[[api/anls/v1/query.proto]]]]
• [[[[api/anls/v1/query.proto]]]]

查询用例与 SQL 生成

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

图表来源

• [[[[internal/biz/query.go]]]]
• [[[[internal/biz/sql_builder.go]]]]

章节来源

• [[[[internal/biz/query.go]]]]
• [[[[internal/biz/sql_builder.go]]]]

数据访问与缓存

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

图表来源

• [[[[internal/data/query.go]]]]

章节来源

• [[[[internal/data/query.go]]]]
• [[[[internal/data/query.go]]]]

服务适配与鉴权

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

图表来源

• [[[[internal/server/server.go]]]]

章节来源

• [[[[internal/server/server.go]]]]
• [[[[internal/service/query.go]]]]

服务间通信与 gRPC 客户端

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

图表来源

• [[[[internal/data/basic_client.go]]]]
• [[[[internal/data/tenant_client.go]]]]

章节来源

• [[[[internal/data/basic_client.go]]]]
• [[[[internal/data/tenant_client.go]]]]

指标实现概览

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

章节来源

• [[[[docs/指标实现情况.md]]]]

依赖关系分析

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

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

图表来源

• [[[[go.mod]]]]
• [[[[go.mod]]]]
• [[[[configs/application-dev.yaml]]]]

章节来源

• [[[[go.mod]]]]
• [[[[configs/application-dev.yaml]]]]

性能考虑

• 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 配置。

章节来源

• [[[[internal/server/server.go]]]]
• [[[[internal/biz/query.go]]]]
• [[[[internal/data/query.go]]]]
• [[[[internal/data/basic_client.go]]]]
• [[[[internal/data/tenant_client.go]]]]

结论

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）

章节来源

• [[[[api/anls/v1/query.proto]]]]
• [[[[api/anls/v1/query.proto]]]]
• [[[[api/anls/v1/query.proto]]]]

配置说明

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

章节来源

• [[[[README.md]]]]
• [[[[configs/application-dev.yaml]]]]
• [[[[cmd/bi-analysis/main.go]]]]

数据模型

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

章节来源

• [[[[internal/data/model/field.go]]]]
• [[[[internal/data/model/table.go]]]]

服务间通信协议

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

章节来源

• [[[[internal/service/field_dict.go]]]]
• [[[[internal/service/template_grpc.go]]]]
• [[[[internal/server/grpc.go]]]]