vitepress-template

Appearance

基础服务API ​

**本文档引用的文件** - [[[[[bi-basic/README.md]]]]](file/bi-basic/readme.md) - [[[[[bi-basic/go.mod]]]]](file/bi-basic/go.mod) - [[[[[bi-basic/api/order/v1/order.proto]]]]](file/bi-basic/api/order/v1/order.proto) - [[[[[bi-basic/api/goods/v1/goods.proto]]]]](file/bi-basic/api/goods/v1/goods.proto) - [[[[[bi-basic/api/shop/v1/shop.proto]]]]](file/bi-basic/api/shop/v1/shop.proto) - [[[[[bi-basic/api/after_sale_order/v1/after_sale_order.proto]]]]](file/bi-basic/api/after-sale-order/v1/after-sale-order.proto) - [[[[[bi-basic/cmd/server/main.go]]]]](file/bi-basic/cmd/server/main.go) - [[[[[bi-basic/internal/server/http.go]]]]](file/bi-basic/internal/server/http.go) - [[[[[bi-basic/internal/server/grpc.go]]]]](file/bi-basic/internal/server/grpc.go) - [[[[[bi-basic/configs/application-dev.yaml]]]]](file/bi-basic/configs/application-dev.yaml)

目录 ​

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

简介 ​

bi-basic 是 bi 项目的基础服务模块，提供核心业务实体的数据管理能力。该服务通过 gRPC 和 HTTP 双栈协议暴露以下核心业务实体的 API：

  • 订单管理（Order）
  • 商品管理（Goods）
  • 店铺管理（Shop）
  • 售后订单管理（AfterSaleOrder）

服务采用 Kratos 微服务框架构建，支持 Nacos 配置中心、JWT 认证、SSE 流式传输等特性。

项目结构 ​

bi-basic 项目遵循标准的 Go 模块结构，主要目录组织如下：

图表来源

章节来源

核心组件 ​

服务基于 Kratos 框架构建，包含以下核心组件：

服务器组件 ​

  • HTTP 服务器: 支持 RESTful API 和自定义路由
  • gRPC 服务器: 提供高性能 RPC 服务
  • Kafka 消费者: 异步事件处理

中间件层 ​

  • 认证中间件: 基于 bi-tenant 服务的远程 Token 验证
  • 日志中间件: 统一的日志记录
  • 恢复中间件: 异常恢复和错误处理
  • 验证中间件: 请求参数验证

服务层 ​

  • 业务服务: 核心业务逻辑实现
  • 数据适配器: 数据访问层
  • 异步服务: 异步任务处理

章节来源

架构概览 ​

服务采用微服务架构，通过 gRPC 和 HTTP 双栈提供服务，支持水平扩展和高可用部署。

图表来源

详细组件分析 ​

订单管理服务 (OrderService) ​

Protobuf 消息定义 ​

订单服务定义了完整的订单数据模型和业务操作接口：

图表来源

HTTP API 接口规范 ​

接口名称方法路径描述
获取订单详情POST/api/v1/basic/order/get根据订单编号获取订单详情
新增订单POST/api/v1/basic/order创建新的订单
修改订单POST/api/v1/basic/order/update修改订单信息
订单列表POST/api/v1/basic/orders/list获取订单列表
列表查询POST/api/v1/basic/orders/display获取订单展示列表数据
同步订单信息POST/api/v1/basic/order/sync-info根据订单编号同步订单信息
同步礼物单POST/api/v1/basic/order/sync-gift同步礼物单数据

gRPC API 接口规范 ​

接口名称方法描述
GetOrderRPC获取订单详情
CreateOrderRPC创建订单
UpdateOrderRPC更新订单
ListOrderRPC列出订单
ListOrderDisplayRPC列表查询
SyncOrderInfoRPC同步订单信息
SyncGiftOrderRPC同步礼物单

认证与授权 ​

  • 支持 Bearer Token 认证
  • 通过 bi-tenant 服务进行远程 Token 验证
  • 白名单机制支持特定接口免认证

章节来源

商品管理服务 (Goods) ​

Protobuf 消息定义 ​

商品服务提供了完整的产品生命周期管理能力：

图表来源

HTTP API 接口规范 ​

接口名称方法路径描述
商品列表POST/api/v1/basic/goods/list分页获取商品列表
创建商品POST/api/v1/basic/goods创建新的商品
删除商品POST/api/v1/basic/goods/delete删除指定商品
批量修改POST/api/v1/basic/goods/batch批量修改商品信息
标记虚拟商品POST/api/v1/basic/goods/set_virtual批量标记或取消虚拟商品
更新商品POST/api/v1/basic/goods/update更新商品信息
列表查询POST/api/v1/basic/goods/display获取商品展示列表
获取详情POST/api/v1/basic/goods/get获取商品详情
SKUPOST/api/v1/basic/goods/detail获取商品详情（含SKU列表）
导入商品货号POST/api/v1/basic/goods/import根据商品ID导入货号
按店铺批量更新POST/api/v1/basic/goods/batch-by-shop按店铺批量更新商品信息
同步SKU数据POST/api/v1/basic/goods/sync-sku-from-leke从乐客同步商品SKU数据
更新商品POST/api/v1/basic/goods/sync-from-platform从平台同步更新商品数据
创建链接分析模板POST/api/v1/basic/goods/link-template/create创建商品链接分析模板
更新模板排序POST/api/v1/basic/goods/link-template/sort批量更新链接分析模板排序
编辑链接分析模板POST/api/v1/basic/goods/link-template/update编辑商品链接分析模板
获取链接分析模板列表POST/api/v1/basic/goods/link-template/list获取商品链接分析模板列表

gRPC API 接口规范 ​

接口名称方法描述
ListGoodsRPC商品列表
CreateGoodsRPC创建商品
DeleteGoodsByNoRPC删除商品
BatchUpdateGoodsRPC批量修改商品
SetGoodsVirtualRPC标记虚拟商品
UpdateOneGoodsRPC更新商品
ListGoodsDisplayRPC列表查询
GetGoodsRPC获取详情
GetGoodsDetailRPCSKU详情
ImportGoodsRPC导入商品货号
BatchUpdateGoodsByShopRPC按店铺批量更新
SyncGoodsSkuFromLekeRPC同步SKU数据
SyncGoodsFromPlatformRPC更新商品
CreateGoodsLinkTemplateRPC创建链接分析模板
UpdateGoodsLinkTemplateSortRPC更新模板排序
UpdateGoodsLinkTemplateRPC编辑链接分析模板
ListGoodsLinkTemplateRPC获取链接分析模板列表

章节来源

店铺管理服务 (Shop) ​

Protobuf 消息定义 ​

店铺服务提供了完整的店铺生命周期管理：

图表来源

HTTP API 接口规范 ​

接口名称方法路径描述
新增店铺POST/api/v1/basic/shops创建新的店铺
获取店铺详情POST/api/v1/basic/shops/get根据ID获取店铺详情
修改店铺POST/api/v1/basic/shops/update修改店铺信息
店铺启用/禁用POST/api/v1/basic/shops/set_enabled设置店铺启用或禁用状态
删除店铺POST/api/v1/basic/shops/delete删除指定店铺
列表查询POST/api/v1/basic/shops/display获取店铺展示列表数据
日志查询POST/api/v1/basic/shops/logs店铺管理日志查询
下拉字典POST/api/v1/basic/shops/dict获取店铺下拉字典数据
新增店铺授权POST/api/v1/basic/shops/auth/create根据平台名称和token新增店铺授权
订单授权POST/api/v1/basic/shops/order_auth店铺订单授权
推广授权POST/api/v1/basic/shops/promotion_auth店铺推广授权
支付宝授权POST/api/v1/basic/shops/alipay_auth店铺支付宝授权
商品洞察开通POST/api/v1/basic/shops/product_insight_auth店铺商品洞察立即开通
商品洞察取消POST/api/v1/basic/shops/product_insight_cancel店铺商品洞察取消

gRPC API 接口规范 ​

接口名称方法描述
CreateShopRPC新增店铺
GetShopRPC获取店铺详情
UpdateShopRPC修改店铺
SetShopEnabledRPC店铺启用/禁用
DeleteShopRPC删除店铺
ListShopDisplayRPC列表查询
ListShopLogRPC日志查询
ListShopDictRPC下拉字典
CreateShopAuthByPlatformRPC新增店铺授权
OrderAuthRPC订单授权
PromotionAuthRPC推广授权
AlipayAuthRPC支付宝授权
ProductInsightAuthRPC商品洞察开通
ProductInsightCancelRPC商品洞察取消

章节来源

售后订单服务 (AfterSaleOrder) ​

Protobuf 消息定义 ​

售后订单服务专注于售后服务流程管理：

图表来源

HTTP API 接口规范 ​

接口名称方法路径描述
获取售后订单详情POST/api/v1/basic/after-sale-orders/get根据订单编号获取售后订单详情
新增售后订单POST/api/v1/basic/after-sale-orders创建新的售后订单
修改售后订单POST/api/v1/basic/after-sale-orders/update修改售后订单信息
售后订单列表POST/api/v1/basic/after-sale-orders/list获取售后订单列表
列表查询POST/api/v1/basic/after-sale-orders/display获取售后订单展示列表数据

gRPC API 接口规范 ​

接口名称方法描述
GetAfterSaleOrderRPC获取售后订单详情
CreateAfterSaleOrderRPC新增售后订单
UpdateAfterSaleOrderRPC修改售后订单
ListAfterSaleOrderRPC售后订单列表
ListAfterSaleOrderDisplayRPC列表查询

章节来源

依赖分析 ​

外部依赖关系 ​

图表来源

服务间通信 ​

图表来源

章节来源

性能考虑 ​

  • 连接池管理: 使用 Kratos 框架的连接池优化
  • 缓存策略: Redis 缓存热点数据
  • 异步处理: Kafka 异步事件处理
  • 负载均衡: 支持多实例部署
  • 监控指标: 内置性能监控和日志记录

故障排除指南 ​

常见问题及解决方案 ​

认证失败 ​

问题: Token 验证失败 解决方案:

  1. 检查 Token 格式是否正确（Bearer 前缀）
  2. 验证 bi-tenant 服务是否正常运行
  3. 确认 Token 未过期

数据库连接问题 ​

问题: 数据库连接超时或拒绝 解决方案:

  1. 检查数据库服务状态
  2. 验证连接参数配置
  3. 查看连接池使用情况

Kafka 消费异常 ​

问题: Kafka 消费消息失败 解决方案:

  1. 检查 Kafka 服务状态
  2. 验证主题和分区配置
  3. 查看消费者组状态

章节来源

结论 ​

bi-basic 基础服务提供了完整的电商核心业务数据管理能力，通过标准化的 gRPC 和 HTTP 接口，支持多种业务场景。服务架构清晰，具备良好的扩展性和可靠性，能够满足企业级应用的需求。

附录 ​

配置文件说明 ​

服务使用 Nacos 作为配置中心，支持多环境配置管理。

章节来源

认证流程 ​

服务采用远程认证机制，通过 bi-tenant 服务验证用户 Token，确保系统的安全性。

章节来源