memory-bank/systemPatterns.md

系统模式 (systemPatterns.md)

系统架构

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

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 返回给客户端。