memory-bank/systemPatterns.md

# 系统模式 (systemPatterns.md)

## 系统架构
本项目采用简单的客户端-代理-目标 API 的三层架构。

```mermaid
graph LR
    Client[客户端 (e.g., Postman, curl)] --> Proxy[FastAPI 代理 (SuperProxy)]
    Proxy --> TargetAPI[目标 API (e.g., Google Gemini API)]
```

## 关键技术决策
*   **FastAPI**：选择 FastAPI 作为 Web 框架，因为它提供了高性能、易于使用的异步 API 开发能力，非常适合构建轻量级代理服务。
*   **httpx**：选择 `httpx` 作为 HTTP 客户端库，因为它支持异步请求，与 FastAPI 的异步特性完美结合，避免了阻塞。
*   **环境变量配置**：使用 `python-dotenv` 管理敏感信息（如 API 密钥）和可配置参数（如目标 API 基 URL），增强了安全性和灵活性。
*   **通用路由**：采用 `/{path:path}` 通用路由来捕获所有传入请求，实现灵活的转发，无需为每个目标 API 端点单独定义路由。

## 设计模式
*   **代理模式 (Proxy Pattern)**：本项目是代理模式的经典应用，FastAPI 应用程序充当客户端和目标 API 之间的代理，控制对目标 API 的访问并进行请求/响应转换。
*   **配置即代码 (Configuration as Code)**：通过 `.env` 文件管理配置，使得部署和环境切换更加便捷和可控。

## 组件关系
*   **FastAPI 应用 (`app.py`)**：核心组件，负责路由、请求解析、请求转发和响应处理。
*   **httpx 客户端**：在 FastAPI 应用内部使用，负责向目标 API 发送实际的 HTTP 请求。
*   **python-dotenv**：在应用启动时加载 `.env` 文件中的环境变量，供 FastAPI 应用使用。
*   **客户端**：可以是任何 HTTP 客户端（浏览器、Postman、`curl`、自定义应用），向 FastAPI 代理发送请求。
*   **目标 API**：本项目中特指 Google Gemini API（OpenAI 兼容接口），是代理请求的最终目的地。

## 关键实现路径
1.  **请求接收**：FastAPI 的 `@app.api_route("/{path:path}")` 装饰器捕获所有传入请求。
2.  **请求解析**：`Request` 对象用于获取请求方法、头部、查询参数和请求体。
3.  **头部处理**：移除 `Host` 头，添加 `Authorization: Bearer` 头，并强制设置 `User-Agent`。
4.  **URL 构建**：根据 `GEMINI_BASE_URL` 和传入的 `path` 构建目标 API 的完整 URL。
5.  **请求转发**：使用 `httpx.AsyncClient().request()` 异步发送请求到目标 API。
6.  **响应处理**：将目标 API 的 `content`、`status_code` 和 `headers` 封装成 `FastAPI.Response` 返回给客户端。
7.  **错误处理**：捕获 `httpx.RequestError` 和 `httpx.HTTPStatusError`，并转换为 `HTTPException` 返回给客户端。