Simon
144 lines
5.2 KiB
Python
144 lines
5.2 KiB
Python
# =============================================================================
|
||
# 企微IT智能服务台 — 统一响应格式工具
|
||
# =============================================================================
|
||
# 说明：定义所有 API 的统一响应格式和异常处理
|
||
# 格式：{code: 0, data: {}, message: "success"}
|
||
# code=0 表示成功，非0表示错误（1000+通用/2000+企微/3000+业务）
|
||
# =============================================================================
|
||
|
||
from typing import Any, Dict, Optional
|
||
|
||
from fastapi import Request
|
||
from fastapi.responses import JSONResponse
|
||
|
||
|
||
# --------------------------------------------------------------------------
|
||
# 统一响应函数
|
||
# --------------------------------------------------------------------------
|
||
def success_response(data: Any = None, message: str = "success") -> Dict[str, Any]:
|
||
"""构建成功响应。
|
||
|
||
所有 API 成功时都应使用此函数返回统一格式。
|
||
|
||
Args:
|
||
data: 业务数据（可以是字典、列表、None等）
|
||
message: 成功消息（默认 "success"）
|
||
|
||
Returns:
|
||
Dict[str, Any]: 统一格式的响应字典
|
||
示例: {"code": 0, "data": {...}, "message": "success"}
|
||
"""
|
||
return {
|
||
"code": 0,
|
||
"data": data,
|
||
"message": message,
|
||
}
|
||
|
||
|
||
def error_response(code: int, message: str, data: Any = None) -> Dict[str, Any]:
|
||
"""构建错误响应。
|
||
|
||
所有 API 错误时都应使用此函数返回统一格式。
|
||
|
||
Args:
|
||
code: 错误码（1000+通用/2000+企微/3000+业务）
|
||
message: 错误消息
|
||
data: 附加数据（可选，如验证错误详情）
|
||
|
||
Returns:
|
||
Dict[str, Any]: 统一格式的错误响应字典
|
||
示例: {"code": 1001, "data": null, "message": "参数错误"}
|
||
"""
|
||
return {
|
||
"code": code,
|
||
"data": data,
|
||
"message": message,
|
||
}
|
||
|
||
|
||
# --------------------------------------------------------------------------
|
||
# 业务异常类
|
||
# --------------------------------------------------------------------------
|
||
class AppException(Exception):
|
||
"""业务异常基类。
|
||
|
||
在业务逻辑中抛出此异常，全局异常处理器会自动转换为统一响应格式。
|
||
避免在每个路由函数中重复写 try/except 和响应构造代码。
|
||
|
||
Attributes:
|
||
code: 错误码
|
||
message: 错误消息
|
||
data: 附加数据
|
||
"""
|
||
|
||
def __init__(self, code: int, message: str, data: Any = None):
|
||
"""初始化业务异常。
|
||
|
||
Args:
|
||
code: 错误码
|
||
message: 错误消息
|
||
data: 附加数据
|
||
"""
|
||
self.code = code
|
||
self.message = message
|
||
self.data = data
|
||
super().__init__(self.message)
|
||
|
||
|
||
# --------------------------------------------------------------------------
|
||
# 预定义错误常量
|
||
# --------------------------------------------------------------------------
|
||
# 错误码规范:
|
||
# 0 = 成功
|
||
# 1000+ = 通用错误（参数错误、未授权等）
|
||
# 2000+ = 企微 API 错误
|
||
# 3000+ = 业务逻辑错误
|
||
|
||
# --- 通用错误 (1000+) ---
|
||
ERR_PARAMS = AppException(1001, "参数错误")
|
||
ERR_UNAUTHORIZED = AppException(1002, "未授权")
|
||
ERR_NOT_FOUND = AppException(1003, "资源不存在")
|
||
ERR_FORBIDDEN = AppException(1004, "无权限访问")
|
||
ERR_INTERNAL = AppException(1005, "服务器内部错误")
|
||
|
||
# --- 企微 API 错误 (2000+) ---
|
||
ERR_WECOM_TOKEN = AppException(2001, "企微 access_token 获取失败")
|
||
ERR_WECOM_SEND = AppException(2002, "企微消息发送失败")
|
||
ERR_WECOM_DECRYPT = AppException(2003, "企微消息解密失败")
|
||
ERR_WECOM_ENCRYPT = AppException(2004, "企微消息加密失败")
|
||
ERR_WECOM_VERIFY = AppException(2005, "企微回调签名验证失败")
|
||
ERR_WECOM_USER_INFO = AppException(2006, "企微用户信息获取失败")
|
||
|
||
# --- 业务逻辑错误 (3000+) ---
|
||
ERR_AGENT_OFFLINE = AppException(3001, "坐席不在线")
|
||
ERR_CONVERSATION_RESOLVED = AppException(3002, "会话已结单")
|
||
ERR_CONVERSATION_NOT_FOUND = AppException(3003, "会话不存在")
|
||
ERR_AGENT_NOT_FOUND = AppException(3004, "坐席不存在")
|
||
ERR_AGENT_BUSY = AppException(3005, "坐席已满负荷，无法接单")
|
||
ERR_DUPLICATE_ASSIGN = AppException(3006, "会话已分配坐席")
|
||
ERR_GRAB_NO_AGENT = AppException(3011, "该会话尚未分配坐席，请使用接单功能")
|
||
ERR_GRAB_SELF = AppException(3012, "不能接手自己的会话")
|
||
ERR_GRAB_NOT_SERVING = AppException(3013, "只能接手服务中的会话")
|
||
|
||
|
||
# --------------------------------------------------------------------------
|
||
# 全局异常处理器
|
||
# --------------------------------------------------------------------------
|
||
async def app_exception_handler(request: Request, exc: AppException) -> JSONResponse:
|
||
"""AppException 全局异常处理器。
|
||
|
||
当业务逻辑抛出 AppException 时，FastAPI 自动调用此处理器，
|
||
将异常转换为统一响应格式返回给前端。
|
||
|
||
Args:
|
||
request: 请求对象（FastAPI 自动传入）
|
||
exc: 业务异常对象（FastAPI 自动传入）
|
||
|
||
Returns:
|
||
JSONResponse: 统一格式的错误响应
|
||
"""
|
||
return JSONResponse(
|
||
status_code=200, # 业务错误仍返回 HTTP 200，通过 code 区分
|
||
content=error_response(exc.code, exc.message, exc.data),
|
||
)
|