vitepress-template

Appearance

API集成与接口设计 ​

**本文引用的文件** - [[[[bi-common/api/auth/v1/auth.proto]]]](../ai/file/bi-common/api/auth/v1/auth.proto) - [[[[bi-common/auth/middleware.go]]]](../ai/file/bi-common/auth/middleware.go) - [[[[bi-sys/api/sys/v1/auth.proto]]]](../ai/file/bi-sys/api/sys/v1/auth.proto) - [[[[bi-tenant/api/tenant/v1/auth_http.pb.go]]]](../ai/file/bi-tenant/api/tenant/v1/auth-http.pb.go) - [[[[bi-analysis/api/anls/v1/common.proto]]]](../ai/file/bi-analysis/api/anls/v1/common.proto) - [[[[bi-analysis/api/anls/v1/query.proto]]]](../ai/file/bi-analysis/api/anls/v1/query.proto) - [[[[bi-chat/bi-chat-web/src/hooks/use-chat.ts]]]](../ai/file/bi-chat/bi-chat-web/src/hooks/use-chat.ts) - [[[[bi-chat/bi-chat-web/src/context/ChatContext.tsx]]]](../ai/file/bi-chat/bi-chat-web/src/context/chatcontext.tsx) - [[[[bi-chat/bi_chat/src/routes/chat.py]]]](../ai/file/bi-chat/bi-chat/src/routes/chat.py) - [[[[bi-chat/bi_chat/src/routes/sessions.py]]]](../ai/file/bi-chat/bi-chat/src/routes/sessions.py) - [[[[bi-chat/bi_chat/src/controllers/chat.py]]]](../ai/file/bi-chat/bi-chat/src/controllers/chat.py) - [[[[bi-chat/bi_chat/src/controllers/sessions.py]]]](../ai/file/bi-chat/bi-chat/src/controllers/sessions.py) - [[[[bi-chat/bi_chat/src/utils/websocket.py]]]](../ai/file/bi-chat/bi-chat/src/utils/websocket.py) - [[[[bi-api-jushuitan/internal/data/ratelimit/merchant_limiter.go]]]](../ai/file/bi-api-jushuitan/internal/data/ratelimit/merchant-limiter.go) - [[[[bi-api-jushuitan/internal/data/ratelimit/concurrency_limiter.go]]]](../ai/file/bi-api-jushuitan/internal/data/ratelimit/concurrency-limiter.go) - [[[[bi-api-jushuitan/internal/data/ratelimit/token_bucket.go]]]](../ai/file/bi-api-jushuitan/internal/data/ratelimit/token-bucket.go) - [[[[bi-intra/apisix/create-op-bi-sys.sh]]]](../ai/file/bi-intra/apisix/create-op-bi-sys.sh) - [[[[bi-common/fx/httpx/httpx.go]]]](../ai/file/bi-common/fx/httpx/httpx.go) - [[[[bi-api-leke/APITYPES_INTEGRATION.md]]]](../ai/file/bi-api-leke/apitypes-integration.md)

目录 ​

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

引言 ​

本文件面向BI分析平台的AI智能体系统API集成，系统化梳理RESTful API设计原则与实现规范，覆盖HTTP方法选择、URL路径设计、状态码使用；详述聊天接口（单智能体对话与多智能体协作）与会话管理API；介绍用户管理接口（认证、权限控制、个性化设置）；说明WebSocket实时通信（连接建立、消息传递、断线重连）；给出API版本管理策略与向后兼容性保障；并提供安全防护（身份验证、授权检查、速率限制）与完整使用示例及客户端集成指引。

项目结构 ​

本仓库采用多模块微服务架构，围绕“分析系统”“聊天系统”“认证与权限”“网关与限流”等维度划分。API层主要由gRPC/HTTP网关、OpenAPI注解、前端Web应用与Python后端聊天服务构成。

图表来源

章节来源

核心组件 ​

  • 认证与权限服务：统一的AuthService（JWT校验、权限查询、权限检查、Token刷新、失效），配合中间件实现JWT认证与RBAC授权。
  • 分析API：基于gRPC/HTTP网关的查询服务，提供数据预览与SQL生成能力。
  • 聊天与会话：前端Next.js应用通过HTTP与SSE消费后端聊天与会话接口；后端Python服务提供路由、控制器与WebSocket工具。
  • 网关与限流：APISIX路由脚本统一入口、限流与插件；业务侧实现令牌桶与并发控制器。
  • HTTP客户端：统一的HTTP客户端封装，支持重试与参数编码。

章节来源

架构总览 ​

下图展示API集成的关键交互：前端通过Next.js应用发起HTTP/SSE请求；后端Python服务处理聊天与会话；认证中间件进行JWT与RBAC校验；分析服务提供查询能力；APISIX作为统一入口与限流网关。

图表来源

详细组件分析 ​

RESTful API 设计原则与实现规范 ​

  • HTTP方法选择
    • GET：幂等查询（如获取用户信息、菜单、会话列表）
    • POST：创建资源或提交动作（如新建会话、提交聊天消息）
    • PUT/PATCH：更新资源（如更新会话元数据）
    • DELETE：删除资源（如删除会话）
  • URL路径设计
    • 采用分层命名：/api/{version}/{domain}/
    • 示例：/api/v1/tenant/auth/info、/api/v1/anls/query/preview
  • 状态码使用
    • 200：成功（含统一错误响应时也返回200，内部携带code/message）
    • 400：参数错误/校验失败
    • 401：未认证
    • 403：权限不足
    • 404：资源不存在
    • 429：请求过于频繁（限流）
    • 500：服务器内部错误
  • OpenAPI注解
    • 使用google.api.http与openapiv2注解，自动生成Swagger文档

章节来源

聊天接口设计（单智能体与多智能体协作） ​

  • 单智能体对话
    • 端点：POST /api/v1/chat/messages（消息提交）
    • 流程：前端发送消息 → 后端路由接收 → 控制器处理 → 调用模型/工具 → SSE流式返回
  • 多智能体协作
    • 端点：POST /api/v1/chat/workflows（工作流启动）
    • 流程：前端提交任务/意图 → 后端调度多Agent → 通过事件/状态轮询或SSE推送进度
  • 实时通信
    • WebSocket：建立连接 → 订阅会话/任务事件 → 推送增量结果
    • 前端示例：Next.js应用通过SSE解析“data: ”行，累积对象并渲染

图表来源

章节来源

会话管理API ​

  • 会话创建
    • 端点：POST /api/v1/sessions
    • 返回：会话ID与初始状态
  • 会话查询
    • 端点：GET /api/v1/sessions/
    • 返回：会话元数据与最近消息摘要
  • 会话更新
    • 端点：PUT /api/v1/sessions/
    • 场景：重命名、标记收藏、更新偏好
  • 会话删除
    • 端点：DELETE /api/v1/sessions/
  • 历史消息加载
    • 端点：GET /api/v1/sessions/{id}/messages
    • 前端示例：Next.js应用在切换会话时拉取历史消息

图表来源

章节来源

用户管理接口 ​

  • 认证
    • 登录：POST /api/v1/auth/login（用户名/密码，可选验证码）
    • 刷新：POST /api/v1/auth/refresh（刷新令牌）
    • 注销：POST /api/v1/auth/logout
  • 权限
    • 获取用户信息：GET /api/v1/auth/userinfo
    • 获取用户菜单：GET /api/v1/auth/menus
    • 初始化BI：GET /api/v1/tenant/auth/init
  • 管理端路径区分
    • 客户端API：不带“-m”
    • 管理端API：路径包含“-m”，通过bi-sys RPC校验

图表来源

章节来源

WebSocket 实时通信接口 ​

  • 连接建立
    • 前端通过WebSocket工具建立持久连接
  • 消息传递
    • 服务端推送事件（如任务进度、增量结果）
  • 断线重连机制
    • 前端监听连接状态，指数退避重连
  • 前端SSE解析
    • Next.js应用按“data: ”行解析，累积对象并渲染

图表来源

章节来源

API版本管理与向后兼容 ​

  • 版本策略
    • URL中显式版本：/api/v1、/api/v2
    • 前端通过上下文保存版本，便于切换
  • 向后兼容
    • Protobuf定义保持不变，gRPC服务不受影响
    • HTTP响应格式统一为{code,message,data}，兼容旧客户端

章节来源

API安全防护 ​

  • 身份验证
    • JWT中间件：拦截未认证请求
    • 白名单：无需认证的公开端点
    • 黑名单：Token失效管理
  • 授权检查
    • RBAC中间件：基于权限提供者进行细粒度授权
    • 客户端/管理端路径区分：-m路径走管理端权限提供者
  • 速率限制
    • APISIX：全局限流插件（限速、突发、拒绝码）
    • 业务侧：令牌桶限流（Redis分布式）、并发控制器（按商户维度）

图表来源

章节来源

依赖关系分析 ​

  • 组件耦合
    • 前端对后端API的依赖通过HTTP/SSE/WS抽象；后端路由/控制器依赖中间件与分析服务
    • 认证中间件与权限提供者解耦于具体业务
  • 外部依赖
    • APISIX网关提供统一入口与限流
    • Redis支撑分布式令牌桶限流
  • 循环依赖
    • 当前结构清晰，未见循环导入

图表来源

章节来源

性能考量 ​

  • HTTP客户端重试
    • 统一HTTP客户端支持重试与指数退避，提升稳定性
  • 限流策略
    • APISIX全局限流：防止雪崩
    • 业务侧令牌桶：平滑突发，避免瞬时峰值
    • 并发控制器：按商户维度控制并发，避免下游过载
  • 缓存与分页
    • 查询接口支持分页与缓存开关，降低数据库压力

章节来源

故障排查指南 ​

  • 常见错误与处理
    • 401/403：检查JWT是否过期、是否在白名单、权限提供者是否可用
    • 429：查看APISIX限流配置与业务侧限流策略
    • 500：检查后端日志与Redis可用性
  • 客户端重试
    • HTTP客户端内置重试逻辑，建议结合指数退避
  • 前端SSE解析
    • 注意过滤“[DONE]”标记，捕获解析异常并记录

章节来源

结论 ​

本方案以gRPC/HTTP网关与OpenAPI注解为核心，结合APISIX网关与业务侧限流，构建了高可用、可扩展的API体系。前端通过Next.js与SSE/WS实现流畅的实时交互；后端通过中间件与权限提供者确保安全可控。版本化设计与统一响应格式保障了向后兼容与客户端演进空间。

附录 ​

  • 客户端集成要点
    • 保存API版本（v1/v2），在路由与请求头中体现
    • 使用统一HTTP客户端，启用重试与超时
    • WebSocket连接需实现断线重连与事件去重
  • 示例端点清单
    • 聊天：POST /api/v1/chat/messages
    • 会话：GET/POST/PUT/DELETE /api/v1/sessions/
    • 认证：POST /api/v1/auth/login、POST /api/v1/auth/refresh、POST /api/v1/auth/logout
    • 分析：POST /api/v1/anls/query/preview、POST /api/v1/anls/query/sql