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

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

### 项目名称
**[AI-Gateway](https://github.com/song782360037/AI-Gateway) — 多协议 AI API 统一网关**

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

![aacefd4a60e482c79c541dbb08f6907d.png](http://oss.songst.cn/img/bd46a5f7fe9b73cd7d11f60a834bbc97.aacefd4a60e482c79c541dbb08f6907d.png)

### 技术栈
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 协议完整适配，流式/非流式双模式支持
- 智能路由、故障转移、错误熔断

开源 AI 网关项目

### 用户级Claude.md
> 引用开源项目 https://github.com/multica-ai/andrej-karpathy-skills
```markdown
编码前先思考 不要假设。不要隐藏困惑。揭示权衡取舍。
在实现前： 明确陈述你的假设。如有疑问，请提出。 若存在多种解释，逐一呈现——不要默默选择。 若存在更简单的方法，请说明。在必要时提出异议。 如有任何不明确之处，请停止。指出困惑点并提出问题。

简洁优先 用最精简的代码解决问题。不做任何推测性添加。
不添加超出需求的功能。 不为一次性使用的代码创建抽象。 不添加未被要求的“灵活性”或“可配置性”。 不为不可能发生的场景编写错误处理。 如果你写了200行代码，而50行就能解决，请重写。 自问：“高级工程师会认为这过于复杂吗？”若是，则简化。

精准修改 只触及必须修改的部分。只清理自己造成的遗留问题。
编辑现有代码时： 不“改进”相邻代码、注释或格式。 不重构未损坏的部分。 保持现有代码风格，即使你有不同偏好。 若发现无关的遗留代码，可提及但不删除。 当你的修改产生废弃代码时： 删除因你的修改而变得无用的导入/变量/函数。 除非被要求，否则不删除原有的遗留代码。 检验标准：每一处修改都应直接追溯到用户需求。

目标导向执行 定义成功标准。循环验证直至完成。
将任务转化为可验证的目标： “添加验证” → “为无效输入编写测试，然后使其通过” “修复缺陷” → “编写可复现该问题的测试，然后使其通过” “重构X” → “确保测试在修改前后均通过” 对于多步骤任务，简要说明计划：

[步骤] → 验证：[检查项]
[步骤] → 验证：[检查项]
[步骤] → 验证：[检查项] 明确的成功标准可让你独立循环验证。模糊的标准（如“使其运行”）则需要不断澄清。
若以下情况出现，说明这些准则正在生效：代码差异中不必要的修改减少，因过度复杂导致的重写减少，且澄清性问题出现在实现之前而非错误发生之后。
```

### 用户级rule

#### user_rule.md
```markdown
当前为Windows 11系统环境，请使用PowerShell语法进行开发。在回复时，除必要的专业术语外，统一使用**中文**进行沟通。
在开发过程中，请严格遵循以下规范：
1. **API查询**：遇到不熟悉的API时，严禁猜测，必须使用**context7 MCP**工具查阅最新的官方文档。
2. **代码注释**：所有关键代码必须添加中文注释，重点说明代码的功能逻辑。
3. **网络搜索**：需联网查询时，若内置工具不可用，请使用**tavily-mcp**：联网搜索，用于查询实时信息
4. **数据库操作**：查看表结构或数据时，请根据目标库选择对应的mysql MCP工具（如查询aiops_paas库时使用**aiops_paas_mysql mcp**）。
5. **任务确认**：遇到不确定或有歧义的任务，请先向我询问直至完全理解；对于复杂任务，无论是否明确，均需先阐述开发规划，待我确认后再执行。
6. **代码审查**：任务完成后，必须使用**code-reviewer skills**进行审查，发现中高风险代码必须立即修复，低风险问题视情况处理。
```

### 项目级Claude.md
```markdown
# 该部分需要集合实践项目编写，最好可以包含项目架构、实现说明、项目规范等
```

> 规则生效说明：项目级Claude.md>用户级rule>用户级Claude.md。
> 但是他们之间并不是覆盖的关系，而是并存的。
> 他们也并不是作为 system 提示词注入的，而是塞到对话最前面作为 user message

- context7 MCP：用于查询最新文档说明、API使用示例等
- tavily-MCP：联网搜索，用于查询实时信息
- mysql MCP：用于获取数据库查询权限（无新增/修改/删除等权限）
- code-reviewer skills：用于对本次编写代码进行常规性审查

Claude Code个人规则

- 时间复杂度
- 空间复杂度
- 认知复杂度




### **1. 时间复杂度 (Time Complexity)**

#### **定义：**

* 时间复杂度表示**算法执行所需的时间**，随着输入规模的增大，算法执行时间的增长趋势。
* 用**大O符号**表示，例如 `O(n)`，`O(n^2)` 等。

#### **常见的时间复杂度：**

* **O(1)**：常数时间复杂度

  * 执行时间不随输入规模变化，时间是固定的。
  * 例：访问数组元素 `arr[i]`。

* **O(log n)**：对数时间复杂度

  * 执行时间随着输入规模的增大而增长，但增长速度较慢。
  * 例：二分查找。

* **O(n)**：线性时间复杂度

  * 执行时间与输入规模成正比。
  * 例：线性查找。

* **O(n log n)**：线性对数时间复杂度

  * 执行时间是输入规模的线性与对数的乘积，较常见于高效排序算法。
  * 例：归并排序、快速排序。

* **O(n^2)**：平方时间复杂度

  * 执行时间与输入规模的平方成正比。通常见于嵌套循环。
  * 例：冒泡排序、选择排序。

* **O(2^n)**：指数时间复杂度

  * 执行时间随着输入规模的增加以指数级别增长，通常见于暴力算法。
  * 例：汉诺塔问题、递归解法。

#### **总结：**

* 时间复杂度帮助我们评估算法的效率，通常期望它尽可能低，特别是对于大规模输入时。
* **最优情况**：最佳情况下的时间复杂度（例如数组已排序）。
* **最坏情况**：最坏情况下的时间复杂度（例如数组逆序）。
* **平均情况**：对于随机数据的时间复杂度。

---

### **2. 空间复杂度 (Space Complexity)**

#### **定义：**

* 空间复杂度表示**算法执行过程中所需的额外内存空间**，它衡量的是算法随着输入规模增大时，需要的存储空间如何变化。
* 同样使用**大O符号**来表示。

#### **常见的空间复杂度：**

* **O(1)**：常数空间复杂度

  * 算法使用的内存空间不随着输入规模的变化而变化。
  * 例：简单的交换操作，或是只用常数个变量。

* **O(n)**：线性空间复杂度

  * 算法需要的额外空间与输入数据规模成正比。
  * 例：归并排序（需要额外的数组来存储排序的元素）。

* **O(n^2)**：平方空间复杂度

  * 算法需要的空间是输入规模的平方，通常见于二维数组、矩阵等。
  * 例：矩阵乘法的动态规划实现。

#### **总结：**

* 空间复杂度衡量的是**算法的内存需求**，特别关注**额外的存储空间**，例如临时数据结构、数组等。
* 空间复杂度优化有时比时间复杂度更为重要，特别是在内存受限的环境下。

---

### **3. 认知复杂度 (Cognitive Complexity)**

#### **定义：**

* 认知复杂度是指**理解和维护代码的难度**，从程序员的角度评估代码的复杂度。
* 不像时间复杂度和空间复杂度有明确的数学公式，认知复杂度更加主观，依赖于代码的结构和可读性。

#### **影响因素：**

* **控制结构的嵌套深度**：如深层嵌套的循环、条件判断等使得代码理解起来更加困难。
* **逻辑的复杂性**：复杂的算法逻辑和边界条件判断增加了认知负担。
* **代码的清晰度和可读性**：难以理解的代码、冗长的函数、复杂的命名都增加认知复杂度。
* **函数/方法的职责不单一**：一个方法执行了过多任务，使得代码理解起来更为困难。

#### **总结：**

* 认知复杂度关注代码的可理解性和维护性。
* 影响代码质量的因素包括**结构清晰性**、**函数职责单一**以及**命名规范**。
* 对于我们开发人员来说，尽量保持代码简洁、清晰、结构化，避免过度嵌套和复杂逻辑，以提高认知舒适度。

---

### **总结对比：**

| 复杂度类型     | 描述                              | 关键因素           |
| --------- | ------------------------------- | -------------- |
| **时间复杂度** | 衡量算法执行所需时间，随着输入规模增大，执行时间如何变化    | 执行时间随输入规模的变化   |
| **空间复杂度** | 衡量算法执行所需的内存空间，随着输入规模增大，所需空间如何变化 | 使用的额外内存空间      |
| **认知复杂度** | 衡量理解和维护代码的难度，关注代码的可读性和可维护性      | 代码结构、逻辑复杂度、清晰度 |

---

### **扩展：**

* **时间复杂度与空间复杂度的权衡：** 有时为了优化时间复杂度，可能需要牺牲空间复杂度。例如，某些算法可能会使用更多内存来减少计算量（如缓存技术）。
* **认知复杂度与开发效率：** 代码的可读性与团队的开发效率密切相关，代码的认知复杂度过高可能导致更长的开发时间和更高的维护成本。

从时间、空间到认知：全面解析算法复杂度

### 设备说明
1. 个人 PC 电脑 (Windows 11)
2. 云服务一台（国内站点）
3. 家庭 `NAS` (` PVE `)
	- `OpenWRT` (网络中枢)
	- `FnOS`（`NAS` --主要折腾系统）
	- `CentOS 7`（用于部署测试组件、应用等）
	- `CentOS 7 PROD` (用于部署正式组件、应用等)
	- `Android`（虚拟化安卓系统）
	- `Ubuntu`（用于测试 Ubuntu 系统）
	- `deepin`（国产 Linux 系统）
4. 安卓手机
5. 其他需要联网设备

### 软件说明
1. PC 端
	- `SecureCRT`（用于连接 Linux 主机）
	- `Proxifier` (用于代理网络请求)
	- `Clash Party` (用于科学上网)
	- `Pritunl Client` (用于 `VPN` 连接公司网络)
	- `NPC`（用于内网穿透的客户端）
2. 云服务端
	- `NPS`（用于内网穿透服务端）
3. `NAS` 端（` OpenWRT `）
	- `NPC`（用于内网穿透的客户端）
	- `ShellCrash` / `OpenClash` (用于科学上网)
4. 手机端
	- `Postern` (用于代理网络请求)
	- `Clash Meta`（用于科学上网）

### 网络配置

#### 科学上网
1. 获取订阅地址后使用 `OpenWRT` 的 `OpenClash` 或者自己安装 `ShellCrash` 做旁路由（网关透明代理），其他需要科学上网的设备只需要将网关指向 `OpenWRT` 的主机即可
2. `Android` 可以通过 `Clash Meta` 配置订阅后实现科学上网，也可以在局域网下连接 `WiFi` 通过设置固定网关地址为 `OpenWRT` 的主机即可

#### 内网穿透
云服务器安装 `NPS` 服务端，`OpenWRT`、`PC` 上均安装 `NPC` 客户端，通过简单配置即可通过云服务器 IP + 端口访问到内网服务（也可通过域名解析到云服务器，通过 `nginx` 反代到 ` NPS ` 穿透的服务端口实现域名访问）

#### 网络代理
1. `NAS` 配置好内网穿透后，通过 `NPS` 配置一个 `socket` 代理（主要设置密码）
2. 个人 `PC` 上通过 `Proxifier` 配置 `NPS` 的 `socket` 代理信息，目标地址填写内网 IP 即可实现 `PC` 远程访问 `NAS` 设备和服务
3. `Android` 手机使用 `Postern` 配置 `NPS` 的 `socket` 代理信息，目标地址填写内网 IP 即可实现 `Android` 远程访问 `NAS` 设备和服务


家庭网络分享

### redis-rdb-cli安装
```shell
# 下载
wget https://github.com/leonchen83/redis-rdb-cli/releases/download/v0.9.3/redis-rdb-cli-release.zip
# 解压
unzip redis-rdb-cli-release.zip
cd ./redis-rdb-cli/bin
```
> 导出及导入主机均需安装 redis-rdb-cli

### rdb 转为 json
```shell
./rct -f json -s /data/work/redis/dump.rdb -o /data/work/redis/dump.json
```
> 实际使用替换真实路径

### 数据导出
```shell
./rdt -b redis://127.0.0.1:6378?authPassword=dvLcdfifpftfgv\!\)1223 -o /data/work/redis/dump.rdb -k v_.* v1_.* temp_.*
注意：密码为 dvLcdfifpftfgv!)1223，其中!以及)均需要转义；导出 v_以及 v 1_开头的数据
```
> 注意：密码为 Lciptv!)123，其中!以及)均需要转义,导出 v_以及 v1_、temp_开头的数据

### 数据导入
```shell
./rmt -s /data/work/redis/dump.rdb -m redis://127.0.0.1:6379?authPassword=Pccpvv%23.675 -r
注意：密码为Pccpvv#.675
```
> '#'需要进行urlencode