vitepress-template

Appearance

通用API类型 ​

**本文引用的文件** - [[[[[bi-common/apitypes/error.go]]]]](file/bi-common/apitypes/error.go) - [[[[[bi-common/apitypes/page.go]]]]](file/bi-common/apitypes/page.go) - [[[[[bi-common/apitypes/request.go]]]]](file/bi-common/apitypes/request.go) - [[[[[bi-common/apitypes/response.go]]]]](file/bi-common/apitypes/response.go) - [[[[[bi-common/apitypes/result.go]]]]](file/bi-common/apitypes/result.go) - [[[[[bi-common/auth/jwt.go]]]]](file/bi-common/auth/jwt.go) - [[[[[bi-common/auth/rbac.go]]]]](file/bi-common/auth/rbac.go) - [[[[[bi-common/auth/context.go]]]]](file/bi-common/auth/context.go) - [[[[[bi-common/conf/common.proto]]]]](file/bi-common/conf/common.proto) - [[[[[bi-analysis/api/anls/v1/common.proto]]]]](file/bi-analysis/api/anls/v1/common.proto)

目录 ​

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

简介 ​

本文件为通用API类型与数据结构的权威参考，覆盖以下主题：

  • 统一的错误码规范与通用消息格式
  • Protobuf消息定义、枚举与OpenAPI注解
  • 分页参数、排序规则与过滤条件的标准化接口
  • 认证令牌、权限标识与租户上下文的通用规范
  • API版本管理与向后兼容策略
  • SDK使用示例与客户端集成指南

目标是帮助跨服务开发者快速理解并正确使用通用API类型，确保一致性与可维护性。

项目结构 ​

围绕“通用API类型”这一主题，核心代码位于 bi-common 模块，涵盖：

  • apitypes：统一响应、错误、分页、请求体与结果封装
  • auth：JWT工具、RBAC中间件、上下文与元数据传递
  • conf：通用配置的Protobuf定义（服务、数据、Kafka、日志、鉴权等）
  • 各业务模块的API目录下包含Protobuf定义与OpenAPI注解

图表来源

章节来源

核心组件 ​

  • 统一响应与错误
    • 统一响应结构、成功/错误便捷构造器
    • 业务错误封装与HTTP状态映射、元数据携带业务错误码
  • 分页与排序
    • 分页请求/响应、偏移与限制计算
    • 排序请求与默认排序方向
  • 通用请求体
    • ID/IDs请求、时间范围请求与校验
  • 泛型结果封装
    • 分页/树形/列表/选项/ID/空结果等
  • 认证与授权
    • JWT签发/解析、令牌对、过期与刷新阈值
    • RBAC中间件、路径到权限映射、白名单与缓存
    • 租户上下文与跨服务元数据传递
  • 配置与API定义
    • 通用配置Protobuf（服务、数据、Kafka、日志、鉴权）
    • 业务API通用枚举与OpenAPI注解

章节来源

架构总览 ​

通用API类型在服务端的典型流转如下：

图表来源

详细组件分析 ​

统一响应与错误 ​

  • 统一响应结构包含业务码、消息与数据字段；提供成功/错误便捷构造器
  • 业务错误封装：
    • 业务错误码采用XXYYZZZ格式，XX部分映射HTTP状态
    • 错误对象携带业务码元数据，便于下游识别与处理
    • 提供从错误对象提取业务码与消息的工具函数

图表来源

章节来源

分页与排序 ​

  • 分页请求参数：页码、每页大小；提供参数校验、偏移与限制计算
  • 分页响应：总条数、列表、当前页与每页大小
  • 排序请求：排序字段与方向，默认降序
  • 分页+排序组合：继承分页与排序请求

图表来源

章节来源

通用请求体与结果封装 ​

  • ID/IDs请求：单个与批量ID，约束与上限
  • 时间范围请求：起止时间校验
  • 泛型结果封装：分页/树形/列表/选项/ID/空结果
  • 选项结果：标签与值对

图表来源

章节来源

认证与租户上下文 ​

  • JWT工具：生成访问/刷新令牌对、解析令牌、过期判断与刷新阈值
  • 认证中间件：从Header解析Authorization，白名单与黑名单校验，注入用户上下文与Kratos元数据
  • Header认证中间件：下游服务从Header信任网关传递的用户信息
  • 租户上下文：用户ID、租户ID、用户名、角色/部门/组织、是否超级/租户管理员
  • 跨服务元数据：统一键名用于传递用户身份信息

图表来源

章节来源

RBAC权限控制 ​

  • 中间件根据路径是否包含“-m”区分管理端与客户端API
  • 管理端：仅系统用户可访问，超级管理员跳过检查；否则通过Provider/RPC校验
  • 客户端：超级管理员/租户管理员跳过检查；否则校验本地或RPC权限
  • 权限标识默认规则：模块:资源 或 模块:资源:动作
  • 支持白名单、缓存与自定义路径到权限映射函数

图表来源

章节来源

Protobuf消息定义与OpenAPI注解 ​

  • 通用配置Protobuf：服务(HTTP/GRPC)、数据源(GORM/StarRocks)、Redis、Kafka、日志、Snowflake、鉴权(JWT/白名单)
  • 业务API通用定义：通用枚举（如状态）、OpenAPI全局信息与标签

图表来源

章节来源

依赖关系分析 ​

  • 统一响应/错误被各服务广泛使用，保证错误语义一致
  • 分页/排序/请求体作为通用输入模型，降低重复实现
  • JWT/RBAC/上下文形成认证授权闭环，贯穿所有HTTP中间件
  • Protobuf配置与业务API定义为跨语言/跨服务契约

图表来源

章节来源

性能考量 ​

  • 分页参数校验与默认值设置，避免过大页大小导致内存压力
  • 排序默认降序减少不必要的升序扫描
  • RBAC中间件支持缓存，建议结合LRU/Redis缓存提升权限查询性能
  • JWT刷新阈值与过期时间合理配置，平衡安全与性能
  • 跨服务元数据传递使用轻量键名，避免冗余字段

故障排查指南 ​

  • 未登录/Token无效/过期
    • 检查中间件白名单配置与Authorization头
    • 核对JWT密钥、签发者与过期时间
  • 无权限访问
    • 确认用户角色与权限标识
    • 检查路径到权限映射规则与缓存一致性
  • 错误码不一致
    • 统一使用业务错误封装与提取工具
    • 核对业务码XX部分与HTTP状态映射
  • 分页异常
    • 校验页码与每页大小边界
    • 确认偏移与限制计算逻辑

章节来源

结论 ​

通用API类型通过统一响应、错误、分页、排序与认证授权机制，为多服务协作提供了稳定契约。配合Protobuf配置与业务API定义，实现了跨语言、跨服务的一致性与可维护性。建议在新服务中直接复用这些通用类型，并遵循本文档的版本管理与兼容策略。

附录 ​

API版本管理与向后兼容 ​

  • 版本命名：按服务目录下的 vX 子目录区分版本（如 anls/v1、tenant/v1）
  • 向后兼容原则：
    • 新增字段保持可选，避免破坏旧客户端
    • 不删除/重命名已有字段
    • 枚举新增值需确保旧客户端可忽略或安全降级
    • 通过OpenAPI注解维护文档与变更追踪

章节来源

SDK使用示例与客户端集成 ​

  • HTTP客户端集成要点
    • 统一响应：解析响应中的业务码与消息
    • 错误处理：根据业务码进行分支处理
    • 分页：传入页码与每页大小，使用偏移与限制计算
    • 排序：指定排序字段与方向
  • gRPC客户端集成要点
    • 使用Protobuf定义的消息类型
    • 在Metadata中携带用户上下文键（如 x-user-id、x-tenant-id），便于服务端透传
  • 认证流程
    • 登录获取访问/刷新令牌对
    • 请求时在Authorization头添加Bearer前缀
    • 令牌即将过期时使用刷新令牌换取新令牌

章节来源