Error Handling 错误处理与日志#

按项目规范实现错误处理与日志记录。适用于 API 异常、业务错误、日志打点，便于排查问题。

何时使用#

• 用户请求「加错误处理」「加日志」「异常处理」
• 实现 API 的异常返回
• 排查问题时需要定位错误来源

异常处理#

1. 业务异常#

python

from tkms.exception.api import ApiException

# 抛出业务异常，会返回给前端
raise ApiException(code=400, message="用户不存在")
raise ApiException(code=401, message="未登录")
raise ApiException(code=403, message="无权限")
raise ApiException(code=404, message="资源不存在")
raise ApiException(code=500, message="服务器内部错误")

• code：HTTP 状态码或业务错误码
• message：返回给前端的错误信息，避免暴露内部细节

2. 参数校验#

python

if not user_id:
    raise ApiException(code=400, message="用户ID不能为空")

if page < 1:
    raise ApiException(code=400, message="页码必须大于0")

3. 资源不存在#

python

user = await self.user_dao.get_by_id(user_id)
if not user:
    raise ApiException(code=404, message="用户不存在")

4. 捕获并转换#

python

try:
    result = await external_api.call()
except ConnectionError as e:
    raise ApiException(code=502, message="服务暂时不可用")
except Exception as e:
    # 记录详细日志，对外返回通用信息
    logger.exception("调用外部服务失败")
    raise ApiException(code=500, message="操作失败，请稍后重试")

日志规范#

1. 打点位置#

• 接口入口： logger.info("接口名 入参")
• 关键业务节点： logger.info("步骤 结果")
• 异常： logger.exception("异常描述") 或 logger.error("...")

2. 日志内容#

• 不输出密码、Token、完整卡号等敏感信息
• 包含关键上下文：user_id、request_id、操作类型
• 异常时记录堆栈便于排查

3. 示例#

python

import logging
logger = logging.getLogger(__name__)

# 入口
logger.info("get_user_list", extra={"user_id": user_id, "page": page})

# 业务节点
logger.info("查询完成", extra={"count": len(rows)})

# 异常
logger.exception("数据库查询失败", extra={"sql": sql_safe})

统一响应格式#

成功：

json

{"code": 0, "message": "success", "data": {...}}

失败（由 ApiException 触发）：

json

{"code": 400, "message": "用户不存在"}

前端错误处理#

• 根据 code 区分：401 跳登录、403 提示无权限、其他展示 message
• 网络错误：统一提示「网络异常，请稍后重试」