项目背景

在实际使用 AI 服务进行开发时，经常会受到限流、异常断连、服务商兼容性限制等因素影响，导致调用链路不稳定，开发过程需要频繁切换不同的模型与平台。同时，各家厂商在接口协议、请求格式和流式响应方式上存在明显差异，使得客户端接入成本较高、维护复杂。

AI-Gateway 的目标是提供一个面向多协议、多提供商的统一接入层，通过协议适配、统一模型抽象、动态路由与故障转移机制，向外暴露稳定一致的 AI API 服务，减少客户端适配工作，并增强系统的可用性与扩展性。

项目名称

AI-Gateway — 多协议 AI API 统一网关

项目简介

基于 Spring Boot WebFlux 构建的高性能 AI API 网关，支持 OpenAI Chat / OpenAI Responses / Anthropic Messages / Gemini 四种协议的统一接入、协议互转、模型路由、故障转移与可视化管理。前端采用 Vue 3 + Element Plus 实现管理控制台，Maven 一体化构建。

技术栈

Java 21、Spring Boot 3.3、WebFlux（响应式）、MySQL + MyBatis + Flyway、Redis、JWT、AES-256-GCM、Vue 3 + TypeScript + Element Plus、Docker、Prometheus + Actuator

核心职责与成果

1. 多协议适配引擎（策略模式 + 统一模型）

• 设计 ProtocolAdapter 策略接口，实现 OpenAI Chat、OpenAI Responses、Anthropic Messages、Gemini 四种协议的请求解析与响应编码
• 定义 UnifiedRequest / UnifiedResponse / UnifiedStreamEvent 统一模型，核心编排层完全协议无关，新增厂商仅需实现 Provider + Adapter 两个类

2. 双层模型路由 + 运行时热更新

• 实现数据库优先、YAML 静态配置回退的双层路由机制
• 设计 RoutingSnapshotHolder 原子交换机制，管理后台修改路由规则后秒级生效，无需重启服务

3. 故障转移 + 熔断（响应式链路）

• 基于 Reactor switchIfEmpty 链式编排实现多候选 Provider 按优先级自动切换
• 按 provider + model 维度管理熔断状态，跳过已熔断节点，提高请求成功率
• 流式请求仅首 token 前允许故障转移，避免客户端收到重复/缺失内容

4. 流式 SSE 代理（全协议支持）

• 完整实现四种协议的 SSE 流式转发，包括 OpenAI 的 data: [DONE]、Anthropic 的命名事件流、Gemini 的 NDJSON
• 支持 StreamContext 上下文管理，处理 Anthropic 的 content_block_start/delta 分段等协议差异

5. 双层鉴权 + 安全存储

• Layer 1：API Key 鉴权，ak- 前缀密钥，SHA-256 哈希存储，校验状态/过期时间/用量限制
• Layer 2：JWT Admin 鉴权，HMAC-SHA 256 签发，管理后台独立认证
• Provider 上游 API Key 采用 AES-256-GCM 对称加密存储，运行时解密调用

6. 异步统计 + 可观测性

• 基于 Reactor Sinks 实现请求日志与聚合统计的异步批量刷写，不阻塞主请求链路
• 接入 Micrometer + Prometheus 端点，暴露请求量 / Token 消耗 / 成本 / RPM / TPM 等核心指标
• 管理后台仪表盘实时展示流量、成功率、延迟分布

7. 管理后台（Vue 3 全栈）

• 实现 Provider 渠道管理（CRUD + 拖拽优先级）、模型路由规则管理、API Key 生命周期管理、请求日志查询、运行时快照查看
• 前端通过 frontend-maven-plugin 集成到 Maven 构建，mvn clean package 一键输出含前端的可执行 JAR

项目亮点

• 策略模式 + 模板方法 + 责任链模式综合运用，架构扩展性强
• 响应式全链路（WebFlux + WebClient），非阻塞高并发
• 四种 AI 协议完整适配，流式/非流式双模式支持
• 智能路由、故障转移、错误熔断