一、问题背景

在开发基于 FastAPI 的应用程序时，异常处理是一个非常重要的环节。然而，FastAPI 自带的异常处理机制存在一个让人头疼的问题：它会吞掉原始堆栈信息。这就好比你在找东西，线索突然没了，排查生产环境里的错误就像瞎猜一样，特别难搞。不过，我们可以通过自定义 ExceptionHandler 来保留上下文信息，并且输出结构化的日志，这样排查问题就容易多啦。

二、FastAPI 异常处理的问题

2.1 原始堆栈信息丢失

FastAPI 默认的异常处理机制，在处理异常时会把原始的堆栈信息给吞掉。比如说下面这个简单的 FastAPI 应用：

# 技术栈名称：Python + FastAPI
from fastapi import FastAPI

app = FastAPI()

@app.get("/")
def read_root():
    # 故意制造一个错误
    result = 1 / 0  
    return {"Hello": "World"}

当我们运行这个应用，调用 / 接口时，会触发 ZeroDivisionError 异常。FastAPI 进行异常处理后，输出的错误日志里很难看到完整的错误上下文，只知道出错了，却不知道具体错在哪里。

2.2 排查生产错误困难

在生产环境中，没有原始堆栈信息，排查错误就像大海捞针。因为不知道错误发生的具体位置和调用链，我们只能通过不断猜测和尝试来定位问题，这不仅浪费时间，还可能导致问题解决不及时，影响系统的稳定性和可用性。

三、自定义 ExceptionHandler 来解决问题

3.1 自定义 ExceptionHandler 的原理

自定义 ExceptionHandler 就是我们自己写一个函数来处理异常，这个函数可以捕获异常，保留原始的堆栈信息，并且按照我们想要的格式输出日志。这样，当异常发生时，我们就能从日志里获取到足够的信息来排查问题。

3.2 实现自定义 ExceptionHandler

# 技术栈名称：Python + FastAPI
import logging
import traceback
from fastapi import FastAPI, Request
from fastapi.responses import JSONResponse

app = FastAPI()

# 配置日志
logger = logging.getLogger(__name__)
logging.basicConfig(level=logging.ERROR)

# 自定义异常处理函数
async def custom_exception_handler(request: Request, exc: Exception):
    # 获取异常的堆栈信息
    stack_trace = traceback.format_exc()
    # 构建结构化日志
    log_data = {
        "message": str(exc),
        "stack_trace": stack_trace,
        "request_url": str(request.url)
    }
    # 输出结构化日志
    logger.error(log_data)
    # 返回 JSON 响应
    return JSONResponse(
        status_code=500,
        content={"error": "Internal Server Error", "details": log_data}
    )

# 注册自定义异常处理函数
app.add_exception_handler(Exception, custom_exception_handler)

@app.get("/")
def read_root():
    # 故意制造一个错误
    result = 1 / 0  
    return {"Hello": "World"}

在这个例子中，我们定义了一个 custom_exception_handler 函数，它接受 request 和 exc 两个参数。request 是请求对象，exc 是捕获到的异常。在函数内部，我们使用 traceback.format_exc() 获取异常的堆栈信息，然后构建一个包含错误信息、堆栈信息和请求 URL 的结构化日志，最后将日志输出到控制台，并返回一个包含错误信息的 JSON 响应。

3.3 测试自定义 ExceptionHandler

启动上面的 FastAPI 应用，访问 / 接口，就会触发 ZeroDivisionError 异常。这时，你会看到控制台输出的日志包含了完整的堆栈信息和请求 URL，就像这样：

ERROR:__main__:{'message': 'division by zero', 'stack_trace': 'Traceback (most recent call last):\n  File "/path/to/your/app.py", line XX, in read_root\n    result = 1 / 0  \nZeroDivisionError: division by zero\n', 'request_url': 'http://localhost:8000/'}

有了这样的日志，排查问题就容易多啦，我们可以清楚地知道错误发生在哪个文件的哪一行。

四、应用场景

4.1 复杂业务逻辑的应用

在一些复杂的业务逻辑应用中，函数调用关系复杂，一个错误可能会在多个函数间传递。如果没有原始堆栈信息，很难确定错误最初发生的位置。通过自定义 ExceptionHandler 保留上下文信息，就能轻松定位错误。比如说，一个电商系统里，订单处理涉及到商品库存检查、价格计算、用户信息验证等多个步骤，任何一个步骤出错，都可以通过结构化日志快速找到问题所在。

4.2 微服务架构的应用

在微服务架构中，服务之间相互调用，一个服务的错误可能会影响到其他服务。当出现错误时，想要快速定位是哪个服务出了问题，就需要完整的堆栈信息。自定义 ExceptionHandler 可以在每个服务中实现，将错误信息详细记录下来，方便排查跨服务的错误。

4.3 生产环境的故障排查

生产环境对稳定性要求很高，一旦出现错误，必须尽快解决。自定义 ExceptionHandler 输出的结构化日志，能够为运维人员提供足够的信息，快速定位和解决问题，减少系统的停机时间。

五、技术优缺点

5.1 优点

  • 保留上下文信息：自定义 ExceptionHandler 可以保留完整的原始堆栈信息和请求上下文，让排查错误变得容易。就像给你一张地图，让你清楚地知道错误发生的位置和路径。
  • 输出结构化日志：将错误信息以结构化的方式输出，方便日志分析和监控。可以根据日志里的不同字段进行筛选和排序，快速找到关键信息。
  • 提高开发效率：减少了排查错误的时间，让开发人员和运维人员能够更快地解决问题，提高了整个团队的开发效率。

5.2 缺点

  • 增加开发成本：需要额外编写异常处理函数和配置日志，增加了开发的工作量。不过，从长远来看，这是值得的，因为可以减少后续的排查错误成本。
  • 性能影响：记录详细的堆栈信息和输出结构化日志会占用一定的系统资源，可能会对应用的性能产生一些影响。但是，在大多数情况下，这种影响是可以忽略不计的。

六、注意事项

6.1 日志安全

在输出结构化日志时，要注意不要包含敏感信息，比如用户的密码、信用卡号等。可以对日志进行过滤和脱敏处理，避免信息泄露。

6.2 日志存储和管理

结构化日志会产生大量的数据，需要合理规划日志的存储和管理。可以使用日志管理工具，如 Elasticsearch、Logstash 和 Kibana（ELK 堆栈），将日志集中存储和分析，方便后续的查询和监控。

6.3 异常处理的优先级

在注册自定义 ExceptionHandler 时，要注意异常处理的优先级。如果先注册了更具体的异常处理函数，再注册通用的异常处理函数，那么具体的异常处理函数会先被执行。

七、文章总结

FastAPI 自带的异常处理机制存在吞掉原始堆栈信息的问题，这给生产环境的错误排查带来了很大的困难。通过自定义 ExceptionHandler，我们可以保留上下文信息，输出结构化日志，从而提高错误排查的效率。自定义 ExceptionHandler 在复杂业务逻辑应用、微服务架构应用和生产环境故障排查中有广泛的应用场景。虽然它有一些缺点，如增加开发成本和性能影响，但从整体来看，优点远远大于缺点。在使用自定义 ExceptionHandler 时，要注意日志安全、日志存储和管理以及异常处理的优先级等问题。