API设计规范
**本文引用的文件** - [[main.go]](../file/bi-analysis/cmd/bi-analysis/main.go) - [[error.go]](../file/bi-common/apitypes/error.go) - [[response.go]](../file/bi-common/apitypes/response.go) - [[request.go]](../file/bi-common/apitypes/request.go) - [[page.go]](../file/bi-common/apitypes/page.go) - [[cors.go]](../file/bi-common/apitypes/middleware/cors.go) - [[middleware.go]](../file/bi-common/auth/middleware.go) - [[rbac.go]](../file/bi-common/auth/rbac.go) - [[context.go]](../file/bi-common/auth/context.go) - [[merchant_limiter.go]](../file/bi-api-jushuitan/internal/data/ratelimit/merchant-limiter.go) - [[token_bucket.go]](../file/bi-api-jushuitan/internal/data/ratelimit/token-bucket.go) - [[Makefile（聚水潭）]](../file/bi-api-jushuitan/makefile) - [[Makefile（分析）]](../file/bi-analysis/makefile) - [[Makefile（模板）]](../file/bi-template/makefile) - [[Makefile（淘析）]](../file/bi-plan-taoxi/makefile)
目录
引言
本规范面向BI分析平台的API设计，覆盖gRPC与HTTP双协议的统一设计原则与实现规范，明确Protobuf消息与服务接口设计模式、请求/响应格式约定、错误码体系与错误处理机制、版本管理与向后兼容策略、鉴权认证与中间件使用规范、跨域处理方案、API文档生成与维护流程、性能优化与限流策略、API测试与Mock数据生成、以及与前端框架的集成最佳实践。目标是确保API设计的一致性、可扩展性与可维护性。
项目结构
- 服务入口与启动：各子系统均通过Kratos应用启动，统一承载gRPC与HTTP服务，并接入Nacos配置与注册中心。
- 通用能力：bi-common提供统一的错误码、响应体、分页、鉴权中间件、CORS中间件等基础能力。
- 协议与文档：通过Protobuf定义服务契约，结合OpenAPI生成工具链输出Swagger文档，统一HTTP响应包装。
- 限流与性能：基于Redis的分布式令牌桶实现，支持按租户/商家粒度限流。
图示来源
- [main.go]
- [error.go]
- [response.go]
- [request.go]
- [page.go]
- [cors.go]
- [middleware.go]
- [rbac.go]
- [context.go]
- [merchant_limiter.go]
- [token_bucket.go]
- [Makefile（分析）]
- [Makefile（聚水潭）]
- [Makefile（模板）]
- [Makefile（淘析）]
章节来源
核心组件
- 统一错误码与响应体
- 业务错误通过统一错误封装，携带业务错误码与消息；HTTP响应体采用统一包装，便于前端一致处理。
- 错误码映射HTTP状态码，实际对外统一返回200，由中间件负责编码。
- 通用请求模型
- ID/IDs、时间范围、排序、分页等通用模型，约束边界并提供默认值与校验。
- 鉴权与权限控制
- JWT认证中间件与Header透传鉴权；RBAC权限中间件支持管理端与客户端路径差异化校验，支持缓存与通配权限。
- CORS跨域
- 提供CORS中间件、Handler与Filter三种形式，支持预检缓存与灵活配置。
- 文档生成
- 通过Makefile调用Python脚本对OpenAPI JSON进行二次加工，统一HTTP响应包装Schema。
章节来源
- [error.go]
- [response.go]
- [request.go]
- [page.go]
- [middleware.go]
- [rbac.go]
- [context.go]
- [cors.go]
- [Makefile（分析）]
架构总览
下图展示API层的关键交互：HTTP与gRPC共存，统一经由中间件栈（CORS、鉴权、权限、日志、指标），错误与响应体统一收敛，文档自动生成。
图示来源
详细组件分析
统一错误码与响应体
- 设计要点
- 业务错误码采用XXYYZZZ格式，XX部分映射HTTP状态码；消息体包含code/message/data三段式。
- 中间件统一将Kratos错误转换为业务错误码，HTTP始终返回200，由前端根据code判断成功与否。
- 关键流程
图示来源
章节来源
通用请求模型与分页
- 设计要点
- ID/IDs、时间范围、排序、分页等模型统一约束与默认值，减少重复校验逻辑。
- 分页参数自动校验并计算offset/limit，避免越界与过大请求。
- 关键流程
图示来源
章节来源
鉴权与权限控制
- 设计要点
- JWT认证中间件支持白名单、黑名单与过期处理；Header透传鉴权用于网关已鉴权场景。
- RBAC中间件按路径区分管理端/客户端，支持缓存、通配权限与路径到权限映射。
- 关键流程
图示来源
章节来源
CORS跨域处理
- 设计要点
- 支持中间件、Handler、Filter三种形式；默认允许所有源与常用方法/头；可配置暴露头、凭证与预检缓存。
- 关键流程
图示来源
章节来源
gRPC与HTTP双协议设计
- 设计要点
- 服务通过Kratos同时暴露gRPC与HTTP，HTTP侧统一响应包装，便于前端一致消费。
- Protobuf定义服务契约，结合OpenAPI生成工具链输出Swagger文档。
- 关键流程
图示来源
章节来源
API文档生成与维护
- 设计要点
- 通过Makefile中的Python脚本对OpenAPI JSON进行二次加工，统一将响应schema包装为包含code/message/data的结构，便于前端统一处理。
- 关键流程
图示来源
章节来源
依赖关系分析
- 组件耦合
- 业务服务依赖通用错误与响应体；鉴权中间件依赖JWT与RBAC；CORS独立于业务逻辑。
- 外部依赖
- 服务注册与配置来自Nacos；限流依赖Redis；文档生成依赖OpenAPI与Python脚本。
- 循环依赖
- 通过接口抽象（PermissionProvider、PermissionCache）避免循环依赖。
图示来源
章节来源
性能与限流
- 令牌桶算法
- 基于Redis Lua脚本实现，支持桶容量与生成速率配置，key按租户/商家哈希，过期时间可控。
- 商家级限流
- 以商家维度隔离，保守策略（80%限额）避免第三方限流触发；支持等待与超时等待。
- 性能建议
- 合理设置桶容量与速率，避免突发超限；对热点资源增加本地缓存；开启预检缓存降低OPTIONS开销。
图示来源
章节来源
故障排查指南
- 常见问题定位
- 未登录/Token无效：检查Authorization头、Bearer前缀、Token黑名单与过期。
- 无权限访问：确认路径是否命中管理端规则、用户角色与所需权限标识。
- 跨域失败：检查AllowOrigins/AllowMethods/AllowHeaders配置与预检缓存。
- 限流触发：核对商家限流阈值与Redis键空间，观察Wait/WaitWithTimeout行为。
- 建议手段
- 打开中间件日志与指标埋点；使用统一错误码快速定位业务错误类型；对热点接口增加缓存与降级策略。
章节来源
结论
本规范以bi-common为核心，统一了错误码、响应体、鉴权与跨域等关键能力，结合gRPC与HTTP双协议与OpenAPI文档生成，形成可扩展、可维护、前后端一致的API设计体系。配合令牌桶限流与性能优化建议，可在高并发场景下保持稳定与可预期的用户体验。
附录
- 版本管理与兼容
- 采用语义化版本与命名空间隔离（如anls/v1、anls-m/v1），变更遵循向后兼容或提供迁移指引。
- 测试与Mock
- 建议在各模块内提供单元测试与集成测试，结合Mock数据生成工具，确保接口稳定性。
- 前端集成
- 前端统一处理HTTP 200 + code=0的成功路径，错误路径统一提示与重试策略；跨域配置与CORS中间件保持一致。