vitepress-template

Appearance

API参考文档 ​

**本文档引用的文件** - [[[[bi-common/api/auth/v1/auth.proto]]]](../api/file/bi-common/api/auth/v1/auth.proto) - [[[[bi-basic/api/goods/v1/goods.proto]]]](../api/file/bi-basic/api/goods/v1/goods.proto) - [[[[bi-analysis/api/anls/v1/common.proto]]]](../api/file/bi-analysis/api/anls/v1/common.proto) - [[[[bi-common/apitypes/error.go]]]](../api/file/bi-common/apitypes/error.go) - [[[[bi-common/apitypes/response.go]]]](../api/file/bi-common/apitypes/response.go) - [[[[bi-common/apitypes/request.go]]]](../api/file/bi-common/apitypes/request.go) - [[[[bi-common/auth/middleware.go]]]](../api/file/bi-common/auth/middleware.go) - [[[[bi-common/auth/jwt.go]]]](../api/file/bi-common/auth/jwt.go) - [[[[bi-common/auth/context.go]]]](../api/file/bi-common/auth/context.go) - [[[[bi-basic/internal/server/http.go]]]](../api/file/bi-basic/internal/server/http.go) - [[[[bi-notify/internal/server/http.go]]]](../api/file/bi-notify/internal/server/http.go) - [[[[bi-basic/api/shop_auth/v1/shop_auth_http.pb.go]]]](../api/file/bi-basic/api/shop-auth/v1/shop-auth-http.pb.go) - [[[[bi-common/fx/httpx/httpx.go]]]](../api/file/bi-common/fx/httpx/httpx.go) - [[[[bi-api-leke/APITYPES_INTEGRATION.md]]]](../api/file/bi-api-leke/apitypes-integration.md)

目录 ​

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

简介 ​

本文件为BI分析平台的API参考文档，覆盖gRPC服务与HTTP API的完整规范，包括：

  • 公共接口定义与调用方式
  • 请求/响应格式与参数说明
  • 错误码体系与错误处理
  • Protobuf消息格式与数据类型
  • API版本管理策略与向后兼容性
  • 认证授权机制与安全考虑
  • 实际调用示例与SDK使用指南
  • 性能特征与使用限制
  • 客户端集成最佳实践

项目结构 ​

BI分析平台采用多模块微服务架构，API层主要分布在以下模块：

  • bi-common：统一鉴权、错误码、HTTP响应格式、JWT工具
  • bi-basic：基础业务API（商品、订单、店铺等）
  • bi-analysis：分析系统API（客户端聚合查询）
  • 各服务通过gRPC提供RPC能力，并通过HTTP网关暴露REST风格接口

图表来源

章节来源

核心组件 ​

  • 鉴权服务AuthService：提供Token验证、权限查询、权限校验、Token刷新与失效等RPC接口
  • 统一错误码与响应：定义业务错误码映射HTTP状态码的规则，以及统一的HTTP响应结构
  • JWT工具：生成访问令牌与刷新令牌对，支持过期时间与签名配置
  • HTTP网关：基于OpenAPI注解，将gRPC方法映射为REST风格的HTTP端点
  • 通用请求模型：ID、批量ID、时间范围、排序、分页+排序等通用结构

章节来源

架构总览 ​

下图展示了API的端到端调用流程：客户端通过HTTP访问，经由HTTP网关映射到gRPC服务，服务内部进行鉴权与业务处理，最终返回统一格式的响应。

图表来源

详细组件分析 ​

鉴权服务（AuthService） ​

  • 服务接口
    • VerifyToken：验证JWT并返回用户声明
    • GetUserPermissions：获取用户权限列表
    • CheckPermission：检查用户是否具备某权限
    • RefreshToken：刷新访问令牌
    • InvalidateToken：使令牌失效（登出）
  • 关键消息
    • UserClaims：包含用户ID、用户名、租户ID、角色ID列表、部门/组织ID、管理员标识、过期时间等
  • 调用示例
    • 客户端在HTTP请求头中携带Authorization: Bearer <token>
    • 服务端中间件解析并校验Token，必要时调用AuthService进行权限校验

图表来源

章节来源

商品管理API（HTTP REST） ​

  • 服务：Goods（商品管理）
  • OpenAPI文档元信息：标题、版本、标签
  • 主要端点
    • 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：获取商品详情
    • POST /api/v1/basic/goods/detail：获取商品详情（含SKU）
    • POST /api/v1/basic/goods/import：根据商品ID导入货号
    • POST /api/v1/basic/goods/batch-by-shop：按店铺批量更新商品人员与类目
    • 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：获取链接分析模板列表
  • 请求/响应格式
    • 请求体：JSON，遵循对应消息定义
    • 响应体：统一JSON结构，包含code、message、data
  • HTTP注册与路由
    • 服务启动时通过RegisterGoodsHTTPServer注册各端点
    • HTTP中间件链路包含链路追踪、元数据、请求ID、日志、恢复、鉴权等

图表来源

章节来源

统一错误码与响应 ​

  • 错误码映射HTTP状态码规则
    • 20XX：成功类
    • 400：参数错误
    • 401：认证失败
    • 403：权限不足
    • 404：资源不存在
    • 405：方法不允许
    • 408：请求超时
    • 409：资源冲突
    • 410：资源已失效
    • 429：请求过于频繁 422：业务规则限制
    • 500：服务端错误
    • 503：服务不可用
    • 504：网关超时
    • 502：第三方API错误
  • 统一响应结构
    • code：业务错误码（0表示成功）
    • message：响应消息
    • data：响应数据（成功时返回）

图表来源

章节来源

通用请求模型 ​

  • IDRequest：单个ID请求，必填且>0
  • IDsRequest：批量ID请求，必填且长度1~100
  • TimeRangeRequest：时间范围请求，需满足开始时间早于结束时间
  • SortRequest：排序请求，支持asc/desc，默认降序
  • PageSortRequest：分页+排序请求

章节来源

HTTP客户端工具 ​

  • 支持GET/POST重试机制，指数退避
  • 统一封装请求构造、参数编码、响应解析
  • 适用于SDK封装与集成测试

章节来源

依赖关系分析 ​

  • 服务间依赖
    • 业务服务依赖AuthService进行鉴权与权限校验
    • HTTP网关依赖OpenAPI注解将gRPC映射为REST
  • 组件耦合
    • 鉴权中间件与JWT工具解耦，便于替换与扩展
    • 统一响应与错误码独立于具体业务，提升复用性

图表来源

章节来源

性能考量 ​

  • HTTP响应统一为200，业务错误码承载具体语义，减少HTTP状态码污染
  • 重试机制建议在SDK侧实现，避免对上游造成压力
  • 建议客户端对高频接口进行缓存与限流控制
  • gRPC与HTTP网关的连接池与超时配置需结合业务QPS调优

章节来源

故障排查指南 ​

  • 认证失败
    • 检查Authorization头是否正确（Bearer <token>）
    • 确认Token未过期且未在黑名单中
  • 权限不足
    • 确认用户角色与目标资源权限匹配
    • 检查AuthService返回的权限列表
  • 请求异常
    • 查看统一响应中的code与message
    • 根据错误码映射定位问题类型
  • SDK集成
    • 使用HTTP客户端工具进行重试与超时控制
    • 在测试环境使用HeaderAuthMiddleware模拟用户上下文

章节来源

结论 ​

本参考文档提供了BI分析平台的API全貌，涵盖gRPC与HTTP接口、鉴权机制、错误码与响应格式、版本策略与兼容性、性能与安全建议。建议客户端在生产环境中严格遵循统一响应格式与错误码规范，配合SDK工具实现稳定可靠的集成。

附录 ​

API版本管理与向后兼容 ​

  • Protobuf定义保持不变，gRPC服务不受影响
  • HTTP响应格式统一为{code,message,data}，不影响gRPC
  • 建议通过OpenAPI文档与语义化版本管理接口变更

章节来源

认证与授权最佳实践 ​

  • 使用JWT进行无状态认证，支持刷新与失效
  • 在HTTP中间件中启用鉴权与RBAC检查
  • 对敏感接口区分管理端与客户端路径模式

章节来源

SDK使用指南 ​

  • 使用HTTP客户端工具封装请求与重试
  • 统一处理响应与错误码
  • 在测试环境使用HeaderAuthMiddleware快速验证

章节来源