refactor(error): 统一异常处理和响应格式

这次提交重构了整个应用的异常处理机制，保证了处理方式的一致性，还能提供更详细的错误信息。主要改动包括： - 修改了 `ApiClient`，现在抛出的异常会同时包含状态码和消息。这样上游服务就能传递准确的 HTTP 错误响应啦。 - 更新了所有服务层（`gemini`、`openai`、`vertex`、`embedding`），现在会捕获这些结构化的异常，不再从字符串里解析错误消息了。 - 增强了路由级别的错误处理，特别是针对流式端点，能正确捕获初始化错误，并返回结构化的 JSON 错误响应，而不是格式错误的 SSE 事件。 - 在所有 API 路由中添加了 `allowed_token` 的日志记录，方便追踪和调试授权问题。 - 还有一些常规的代码清理，比如调整了 import 顺序和格式化代码，提高了可读性和可维护性。
2026-09-06 08:06:37 +08:00 · 2025-09-18 03:11:45 +08:00
parent e104a50cf4
commit 67dd1af583
12 changed files with 557 additions and 416 deletions
@@ -1,24 +1,31 @@
 # app/services/chat/api_client.py

-from typing import Dict, Any, AsyncGenerator, Optional
-import httpx
 import random
 from abc import ABC, abstractmethod
+from typing import Any, AsyncGenerator, Dict, Optional
+
+import httpx
+
 from app.config.config import settings
-from app.log.logger import get_api_client_logger
 from app.core.constants import DEFAULT_TIMEOUT
+from app.log.logger import get_api_client_logger

 logger = get_api_client_logger()

+
 class ApiClient(ABC):
    """API客户端基类"""

    @abstractmethod
-    async def generate_content(self, payload: Dict[str, Any], model: str, api_key: str) -> Dict[str, Any]:
+    async def generate_content(
+        self, payload: Dict[str, Any], model: str, api_key: str
+    ) -> Dict[str, Any]:
        pass

    @abstractmethod
-    async def stream_generate_content(self, payload: Dict[str, Any], model: str, api_key: str) -> AsyncGenerator[str, None]:
+    async def stream_generate_content(
+        self, payload: Dict[str, Any], model: str, api_key: str
+    ) -> AsyncGenerator[str, None]:
        pass


@@ -50,7 +57,7 @@ class GeminiApiClient(ApiClient):
    async def get_models(self, api_key: str) -> Optional[Dict[str, Any]]:
        """获取可用的 Gemini 模型列表"""
        timeout = httpx.Timeout(timeout=5)
-        
+
        proxy_to_use = None
        if settings.PROXIES:
            if settings.PROXIES_USE_CONSISTENCY_HASH_BY_API_KEY:
@@ -73,11 +80,13 @@ class GeminiApiClient(ApiClient):
            except httpx.RequestError as e:
                logger.error(f"请求模型列表失败: {e}")
                return None
-            
-    async def generate_content(self, payload: Dict[str, Any], model: str, api_key: str) -> Dict[str, Any]:
+
+    async def generate_content(
+        self, payload: Dict[str, Any], model: str, api_key: str
+    ) -> Dict[str, Any]:
        timeout = httpx.Timeout(self.timeout, read=self.timeout)
        model = self._get_real_model(model)
-        
+
        proxy_to_use = None
        if settings.PROXIES:
            if settings.PROXIES_USE_CONSISTENCY_HASH_BY_API_KEY:
@@ -85,42 +94,46 @@ class GeminiApiClient(ApiClient):
            else:
                proxy_to_use = random.choice(settings.PROXIES)
            logger.info(f"Using proxy for getting models: {proxy_to_use}")
-            
+
        headers = self._prepare_headers()
-        
+
        async with httpx.AsyncClient(timeout=timeout, proxy=proxy_to_use) as client:
            url = f"{self.base_url}/models/{model}:generateContent?key={api_key}"
-            
+
            try:
                response = await client.post(url, json=payload, headers=headers)
-                
+
                if response.status_code != 200:
                    error_content = response.text
-                    logger.error(f"API call failed - Status: {response.status_code}, Content: {error_content}")
-                    raise Exception(f"API call failed with status code {response.status_code}, {error_content}")
-                
+                    logger.error(
+                        f"API call failed - Status: {response.status_code}, Content: {error_content}"
+                    )
+                    raise Exception(response.status_code, error_content)
+
                response_data = response.json()
-                
+
                # 检查响应结构的基本信息
                if not response_data.get("candidates"):
                    logger.warning("No candidates found in API response")
-                
+
                return response_data
-                
+
            except httpx.TimeoutException as e:
                logger.error(f"Request timeout: {e}")
-                raise Exception(f"Request timeout: {e}")
+                raise Exception(500, f"Request timeout: {e}")
            except httpx.RequestError as e:
                logger.error(f"Request error: {e}")
-                raise Exception(f"Request error: {e}")
+                raise Exception(500, f"Request error: {e}")
            except Exception as e:
                logger.error(f"Unexpected error: {e}")
-                raise
+                raise Exception(500, f"Unexpected error: {e}")

-    async def stream_generate_content(self, payload: Dict[str, Any], model: str, api_key: str) -> AsyncGenerator[str, None]:
+    async def stream_generate_content(
+        self, payload: Dict[str, Any], model: str, api_key: str
+    ) -> AsyncGenerator[str, None]:
        timeout = httpx.Timeout(self.timeout, read=self.timeout)
        model = self._get_real_model(model)
-        
+
        proxy_to_use = None
        if settings.PROXIES:
            if settings.PROXIES_USE_CONSISTENCY_HASH_BY_API_KEY:
@@ -132,15 +145,19 @@ class GeminiApiClient(ApiClient):
        headers = self._prepare_headers()
        async with httpx.AsyncClient(timeout=timeout, proxy=proxy_to_use) as client:
            url = f"{self.base_url}/models/{model}:streamGenerateContent?alt=sse&key={api_key}"
-            async with client.stream(method="POST", url=url, json=payload, headers=headers) as response:
+            async with client.stream(
+                method="POST", url=url, json=payload, headers=headers
+            ) as response:
                if response.status_code != 200:
                    error_content = await response.aread()
                    error_msg = error_content.decode("utf-8")
-                    raise Exception(f"API call failed with status code {response.status_code}, {error_msg}")
+                    raise Exception(response.status_code, error_msg)
                async for line in response.aiter_lines():
                    yield line

-    async def count_tokens(self, payload: Dict[str, Any], model: str, api_key: str) -> Dict[str, Any]:
+    async def count_tokens(
+        self, payload: Dict[str, Any], model: str, api_key: str
+    ) -> Dict[str, Any]:
        timeout = httpx.Timeout(self.timeout, read=self.timeout)
        model = self._get_real_model(model)

@@ -158,14 +175,16 @@ class GeminiApiClient(ApiClient):
            response = await client.post(url, json=payload, headers=headers)
            if response.status_code != 200:
                error_content = response.text
-                raise Exception(f"API call failed with status code {response.status_code}, {error_content}")
+                raise Exception(response.status_code, error_content)
            return response.json()

-    async def embed_content(self, payload: Dict[str, Any], model: str, api_key: str) -> Dict[str, Any]:
+    async def embed_content(
+        self, payload: Dict[str, Any], model: str, api_key: str
+    ) -> Dict[str, Any]:
        """单一嵌入内容生成"""
        timeout = httpx.Timeout(self.timeout, read=self.timeout)
        model = self._get_real_model(model)
-        
+
        proxy_to_use = None
        if settings.PROXIES:
            if settings.PROXIES_USE_CONSISTENCY_HASH_BY_API_KEY:
@@ -177,32 +196,36 @@ class GeminiApiClient(ApiClient):
        headers = self._prepare_headers()
        async with httpx.AsyncClient(timeout=timeout, proxy=proxy_to_use) as client:
            url = f"{self.base_url}/models/{model}:embedContent?key={api_key}"
-            
+
            try:
                response = await client.post(url, json=payload, headers=headers)
-                
+
                if response.status_code != 200:
                    error_content = response.text
-                    logger.error(f"Embedding API call failed - Status: {response.status_code}, Content: {error_content}")
-                    raise Exception(f"API call failed with status code {response.status_code}, {error_content}")
-                
+                    logger.error(
+                        f"Embedding API call failed - Status: {response.status_code}, Content: {error_content}"
+                    )
+                    raise Exception(response.status_code, error_content)
+
                return response.json()
-                
+
            except httpx.TimeoutException as e:
                logger.error(f"Embedding request timeout: {e}")
-                raise Exception(f"Request timeout: {e}")
+                raise Exception(500, f"Request timeout: {e}")
            except httpx.RequestError as e:
                logger.error(f"Embedding request error: {e}")
-                raise Exception(f"Request error: {e}")
+                raise Exception(500, f"Request error: {e}")
            except Exception as e:
                logger.error(f"Unexpected embedding error: {e}")
-                raise
+                raise Exception(500, f"Unexpected embedding error: {e}")

-    async def batch_embed_contents(self, payload: Dict[str, Any], model: str, api_key: str) -> Dict[str, Any]:
+    async def batch_embed_contents(
+        self, payload: Dict[str, Any], model: str, api_key: str
+    ) -> Dict[str, Any]:
        """批量嵌入内容生成"""
        timeout = httpx.Timeout(self.timeout, read=self.timeout)
        model = self._get_real_model(model)
-        
+
        proxy_to_use = None
        if settings.PROXIES:
            if settings.PROXIES_USE_CONSISTENCY_HASH_BY_API_KEY:
@@ -214,26 +237,28 @@ class GeminiApiClient(ApiClient):
        headers = self._prepare_headers()
        async with httpx.AsyncClient(timeout=timeout, proxy=proxy_to_use) as client:
            url = f"{self.base_url}/models/{model}:batchEmbedContents?key={api_key}"
-            
+
            try:
                response = await client.post(url, json=payload, headers=headers)
-                
+
                if response.status_code != 200:
                    error_content = response.text
-                    logger.error(f"Batch embedding API call failed - Status: {response.status_code}, Content: {error_content}")
-                    raise Exception(f"API call failed with status code {response.status_code}, {error_content}")
-                
+                    logger.error(
+                        f"Batch embedding API call failed - Status: {response.status_code}, Content: {error_content}"
+                    )
+                    raise Exception(response.status_code, error_content)
+
                return response.json()
-                
+
            except httpx.TimeoutException as e:
                logger.error(f"Batch embedding request timeout: {e}")
-                raise Exception(f"Request timeout: {e}")
+                raise Exception(500, f"Request timeout: {e}")
            except httpx.RequestError as e:
                logger.error(f"Batch embedding request error: {e}")
-                raise Exception(f"Request error: {e}")
+                raise Exception(500, f"Request error: {e}")
            except Exception as e:
                logger.error(f"Unexpected batch embedding error: {e}")
-                raise
+                raise Exception(500, f"Unexpected batch embedding error: {e}")


 class OpenaiApiClient(ApiClient):
@@ -242,7 +267,7 @@ class OpenaiApiClient(ApiClient):
    def __init__(self, base_url: str, timeout: int = DEFAULT_TIMEOUT):
        self.base_url = base_url
        self.timeout = timeout
-        
+
    def _prepare_headers(self, api_key: str) -> Dict[str, str]:
        headers = {"Authorization": f"Bearer {api_key}"}
        if settings.CUSTOM_HEADERS:
@@ -267,12 +292,16 @@ class OpenaiApiClient(ApiClient):
            response = await client.get(url, headers=headers)
            if response.status_code != 200:
                error_content = response.text
-                raise Exception(f"API call failed with status code {response.status_code}, {error_content}")
+                raise Exception(response.status_code, error_content)
            return response.json()

-    async def generate_content(self, payload: Dict[str, Any], api_key: str) -> Dict[str, Any]:
+    async def generate_content(
+        self, payload: Dict[str, Any], api_key: str
+    ) -> Dict[str, Any]:
        timeout = httpx.Timeout(self.timeout, read=self.timeout)
-        logger.info(f"settings.PROXIES_USE_CONSISTENCY_HASH_BY_API_KEY: {settings.PROXIES_USE_CONSISTENCY_HASH_BY_API_KEY}")
+        logger.info(
+            f"settings.PROXIES_USE_CONSISTENCY_HASH_BY_API_KEY: {settings.PROXIES_USE_CONSISTENCY_HASH_BY_API_KEY}"
+        )
        proxy_to_use = None
        if settings.PROXIES:
            if settings.PROXIES_USE_CONSISTENCY_HASH_BY_API_KEY:
@@ -287,10 +316,12 @@ class OpenaiApiClient(ApiClient):
            response = await client.post(url, json=payload, headers=headers)
            if response.status_code != 200:
                error_content = response.text
-                raise Exception(f"API call failed with status code {response.status_code}, {error_content}")
+                raise Exception(response.status_code, error_content)
            return response.json()

-    async def stream_generate_content(self, payload: Dict[str, Any], api_key: str) -> AsyncGenerator[str, None]:
+    async def stream_generate_content(
+        self, payload: Dict[str, Any], api_key: str
+    ) -> AsyncGenerator[str, None]:
        timeout = httpx.Timeout(self.timeout, read=self.timeout)
        proxy_to_use = None
        if settings.PROXIES:
@@ -303,17 +334,21 @@ class OpenaiApiClient(ApiClient):
        headers = self._prepare_headers(api_key)
        async with httpx.AsyncClient(timeout=timeout, proxy=proxy_to_use) as client:
            url = f"{self.base_url}/openai/chat/completions"
-            async with client.stream(method="POST", url=url, json=payload, headers=headers) as response:
+            async with client.stream(
+                method="POST", url=url, json=payload, headers=headers
+            ) as response:
                if response.status_code != 200:
                    error_content = await response.aread()
                    error_msg = error_content.decode("utf-8")
-                    raise Exception(f"API call failed with status code {response.status_code}, {error_msg}")
+                    raise Exception(response.status_code, error_msg)
                async for line in response.aiter_lines():
                    yield line
-    
-    async def create_embeddings(self, input: str, model: str, api_key: str) -> Dict[str, Any]:
+
+    async def create_embeddings(
+        self, input: str, model: str, api_key: str
+    ) -> Dict[str, Any]:
        timeout = httpx.Timeout(self.timeout, read=self.timeout)
-        
+
        proxy_to_use = None
        if settings.PROXIES:
            if settings.PROXIES_USE_CONSISTENCY_HASH_BY_API_KEY:
@@ -332,10 +367,12 @@ class OpenaiApiClient(ApiClient):
            response = await client.post(url, json=payload, headers=headers)
            if response.status_code != 200:
                error_content = response.text
-                raise Exception(f"API call failed with status code {response.status_code}, {error_content}")
+                raise Exception(response.status_code, error_content)
            return response.json()
-                    
-    async def generate_images(self, payload: Dict[str, Any], api_key: str) -> Dict[str, Any]:
+
+    async def generate_images(
+        self, payload: Dict[str, Any], api_key: str
+    ) -> Dict[str, Any]:
        timeout = httpx.Timeout(self.timeout, read=self.timeout)

        proxy_to_use = None
@@ -352,5 +389,5 @@ class OpenaiApiClient(ApiClient):
            response = await client.post(url, json=payload, headers=headers)
            if response.status_code != 200:
                error_content = response.text
-                raise Exception(f"API call failed with status code {response.status_code}, {error_content}")
-            return response.json()
+                raise Exception(response.status_code, error_content)
+            return response.json()