FastAPI 错误处理与自定义错误消息完全指南：构建健壮的 API 应用 ️-牛翰网

title: FastAPI 错误处理与自定义错误消息完全指南：构建健壮的 API 应用 ️
date: 2025/3/12
updated: 2025/3/12
author: cmdragon

excerpt:
我们将涵盖常见的错误类型、如何捕获和处理这些错误、以及如何返回自定义的错误消息。通过实例和最佳实践，您将能够有效地应对常见错误，提高 API 的鲁棒性和可维护性。此外，文章中包含课后测验和常见错误解决方案，帮助您巩固所学知识。

categories:

后端开发
FastAPI

tags:

FastAPI
错误处理
自定义错误消息
API设计
Web开发
数据校验
开发最佳实践

图片[1]-FastAPI 错误处理与自定义错误消息完全指南：构建健壮的 API 应用 ️-牛翰网

扫描二维码关注或者微信搜一搜：编程智域前端至全栈交流与成长

探索数千个预构建的 AI 应用，开启你的下一个伟大创意

第一章：FastAPI 中的错误处理基础

1.1 什么是错误处理？

错误处理是指在应用程序运行过程中，捕获和处理可能发生的错误，确保程序能够优雅地处理异常情况并给出适当的反馈。

1.2 FastAPI 的默认错误响应

FastAPI 提供了内置的错误处理机制，能够自动返回 HTTP 状态码和错误信息。例如，当请求的资源不存在时，会返回 404 错误。

from fastapi import FastAPI, HTTPException

app = FastAPI()


@app.get("/items/{item_id}")
async def read_item(item_id: int):
    if item_id != 1:
        raise HTTPException(status_code=404, detail="Item not found")
    return {"item_id": item_id}

1.3 常见的 HTTP 错误状态码

400 Bad Request：请求参数无效或缺失。
404 Not Found：请求的资源未找到。
422 Unprocessable Entity：请求格式正确，但内容有误。
500 Internal Server Error：服务器内部错误。

第二章：自定义错误消息

2.1 自定义错误响应

您可以通过自定义错误响应来改善用户体验，提供更清晰的错误信息。

from fastapi import Request, FastAPI, HTTPException
from fastapi.responses import JSONResponse

app = FastAPI()


@app.exception_handler(HTTPException)
async def http_exception_handler(request: Request, exc: HTTPException):
    return JSONResponse(
        status_code=exc.status_code,
        content={"detail": exc.detail, "error": "Custom error message"},
    )

2.2 示例：使用自定义错误消息

在前面的例子中，如果请求的资源未找到，将返回自定义的错误消息。

@app.get("/items/{item_id}")
async def read_item(item_id: int):
    if item_id != 1:
        raise HTTPException(status_code=404, detail="Item not found")
    return {"item_id": item_id}

示例请求：

curl "http://localhost:8000/items/2"

{
  "detail": "Item not found",
  "error": "Custom error message"
}

2.3 处理其他异常

除了 HTTPException，您还可以处理其他类型的异常，例如数据库连接错误。

@app.exception_handler(Exception)
async def generic_exception_handler(request: Request, exc: Exception):
    return JSONResponse(
        status_code=500,
        content={"detail": "An unexpected error occurred", "error": str(exc)},
    )

第三章：最佳实践

3.1 记录错误

在生产环境中，记录错误信息是非常重要的，可以帮助您排查问题。

import logging

logging.basicConfig(level=logging.INFO)


@app.exception_handler(Exception)
async def generic_exception_handler(request: Request, exc: Exception):
    logging.error(f"Unexpected error: {exc}")
    return JSONResponse(
        status_code=500,
        content={"detail": "An unexpected error occurred"},
    )