FastAPI 进阶知识(三) 错误处理

作者：麦克煎蛋出处：https://www.cnblogs.com/mazhiyong/ 转载请保留这段声明，谢谢！

如果使用API时有错误发生，你需要通知给客户端(Web端或者API使用者)这个错误信息。

常见的错误信息为：

客户端没有权限进行相关的操作。
客户端找不到对应的路径操作。
客户端找不到对应的资源。
其他。

这些错误信息的HTTP状态码一般为400错误(400~499)。

`一、HTTPException`

我们用HTTPException模块返回带错误信息的Response。

HTTPException是一个普通的Python异常，同时带有与API访问有关的附加数据。

1、导入模块

from fastapi import HTTPException

2、抛出异常

在代码中抛出HTTPException。

raise HTTPException(status_code=404, detail="Item not found")

这里，参数detail除了可以传递字符串，还可以传递任何可以转换成JSON格式的数据，如dict、list等。

代码示例：

from fastapi import FastAPI, HTTPException

app = FastAPI()

items = {"foo": "The Foo Wrestlers"}


@app.get("/items/{item_id}")
async def read_item(item_id: str):
    if item_id not in items:
        raise HTTPException(status_code=404, detail="Item not found")
return {"item": items[item_id]}

`二、添加自定义头信息`

有时候针对HTTP错误，在一些场景下，我们需要添加自定义头信息。

from fastapi import FastAPI, HTTPException

app = FastAPI()

items = {"foo": "The Foo Wrestlers"}


@app.get("/items-header/{item_id}")
async def read_item_header(item_id: str):
    if item_id not in items:
        raise HTTPException(
            status_code=404,
            detail="Item not found",
            headers={"X-Error": "There goes my error"},
        )
    return {"item": items[item_id]}

`三、自定义异常处理器`

借助 the same exception utilities from Starlette，我们可以添加自定义异常处理器。

假设我们有个自定义异常 UnicornException，我们想在全局范围内处理这个异常。

借助 @app.exception_handler()，就可以实现我们的目标。

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


class UnicornException(Exception):
    def __init__(self, name: str):
        self.name = name


app = FastAPI()


@app.exception_handler(UnicornException)
async def unicorn_exception_handler(request: Request, exc: UnicornException):
    return JSONResponse(
        status_code=418,
        content={"message": f"Oops! {exc.name} did something. There goes a rainbow..."},
    )


@app.get("/unicorns/{name}")
async def read_unicorn(name: str):
    if name == "yolo":
        raise UnicornException(name=name)
    return {"unicorn_name": name}

这里如果我们请求 /unicorns/yolo，路径操作函数就会抛出异常 UnicornException，这个异常会被我们的异常处理器unicorn_exception_handler捕获到。

最后我们收到的HTTP错误码就是418，并且错误内容为：

{"message": "Oops! yolo did something. There goes a rainbow..."}

`四、重写缺省异常处理器`

FastAPI有一些缺省的异常处理器。当我们抛出HTTPException异常或者当请求有非法数据的时候，这些处理器负责返回默认的JSON结果。

我们可以重写这些异常处理器。

1、重写请求校验异常处理器

当一个请求包含非法数据的时候，FastAPI内部会抛出RequestValidationError异常，并且有默认的异常处理器来处理。

我们可以用 @app.exception_handler(RequestValidationError) 来重写这个异常处理器。

from fastapi import FastAPI, HTTPException
from fastapi.exceptions import RequestValidationError
from fastapi.responses import PlainTextResponse

app = FastAPI()

@app.exception_handler(RequestValidationError)
async def validation_exception_handler(request, exc):
    return PlainTextResponse(str(exc), status_code=400)


@app.get("/items/{item_id}")
async def read_item(item_id: int):
    if item_id == 3:
        raise HTTPException(status_code=418, detail="Nope! I don't like 3.")
    return {"item_id": item_id}

如果我们请求 /items/foo，那么返回结果就不是默认的：

{
    "detail": [
        {
            "loc": [
                "path",
                "item_id"
            ],
            "msg": "value is not a valid integer",
            "type": "type_error.integer"
        }
    ]
}

而是：

1 validation error
path -> item_id
  value is not a valid integer (type=type_error.integer)

同时RequestValidationError有个body字段，包含了请求内容的原文。

from fastapi import FastAPI, Request, status
from fastapi.encoders import jsonable_encoder
from fastapi.exceptions import RequestValidationError
from fastapi.responses import JSONResponse
from pydantic import BaseModel

app = FastAPI()


@app.exception_handler(RequestValidationError)
async def validation_exception_handler(request: Request, exc: RequestValidationError):
    return JSONResponse(
        status_code=status.HTTP_422_UNPROCESSABLE_ENTITY,
        content=jsonable_encoder({"detail": exc.errors(), "body": exc.body}),
    )


class Item(BaseModel):
    title: str
    size: int


@app.post("/items/")
async def create_item(item: Item):
    return item

如果我们传递了不合法的数据：

{
  "title": "towel",
  "size": "XL"
}

那么我们收到的返回结果如下：

{
  "detail": [
    {
      "loc": [
        "body",
        "item",
        "size"
      ],
      "msg": "value is not a valid integer",
      "type": "type_error.integer"
    }
  ],
  "body": {
    "title": "towel",
    "size": "XL"
  }
}

2、重写`HTTPException`异常处理器

同样的方法，我们可以重写HTTPException异常处理器。

例如，你可能想返回纯文本格式而不是JSON格式的错误信息。

from fastapi import FastAPI, HTTPException
from fastapi.responses import PlainTextResponse
from starlette.exceptions import HTTPException as StarletteHTTPException

app = FastAPI()


@app.exception_handler(StarletteHTTPException)
async def http_exception_handler(request, exc):
    return PlainTextResponse(str(exc.detail), status_code=exc.status_code)

@app.get("/items/{item_id}")
async def read_item(item_id: int):
    if item_id == 3:
        raise HTTPException(status_code=418, detail="Nope! I don't like 3.")
return {"item_id": item_id}

如果请求 /items/3，这时候返回的错误信息为：

Nope! I don't like 3.

如果没有自定义异常处理器http_exception_handler，返回的错误信息为：

{
    "detail": "Nope! I don't like 3."
}

`五、重用缺省异常处理器`

我们可以导入并且重用缺省的异常处理器。

我们从fastapi.exception_handlers导入缺省异常处理器。

from fastapi import FastAPI, HTTPException
from fastapi.exception_handlers import (
    http_exception_handler,
    request_validation_exception_handler,
)
from fastapi.exceptions import RequestValidationError
from starlette.exceptions import HTTPException as StarletteHTTPException

app = FastAPI()


@app.exception_handler(StarletteHTTPException)
async def custom_http_exception_handler(request, exc):
    print(f"OMG! An HTTP error!: {exc}")
    return await http_exception_handler(request, exc)


@app.exception_handler(RequestValidationError)
async def validation_exception_handler(request, exc):
    print(f"OMG! The client sent invalid data!: {exc}")
    return await request_validation_exception_handler(request, exc)


@app.get("/items/{item_id}")
async def read_item(item_id: int):
    if item_id == 3:
        raise HTTPException(status_code=418, detail="Nope! I don't like 3.")
    return {"item_id": item_id}

在示例中，我们在抛出异常之前添加了一条日志输出。我们可以根据业务需求灵活的重用缺省异常处理器。

`六、FastAPI HTTPException 对比 Starlette HTTPException`

FastAPI HTTPException 继承自 Starlette's HTTPException。

唯一的区别是，FastAPI HTTPException允许你在response添加头信息。主要在内部用于OAuth 2.0以及一些安全相关的功能。

因此，通常我们在代码中抛出FastAPI HTTPException异常。

但是，当我们注册异常处理器的时候，我们应该注册为Starlette HTTPException。

这样，当Starlette的内部代码或者Starlette扩展插件抛出Starlette HTTPException时，我们的处理器才能正常捕获和处理这个异常。

如果我们要在代码中同时使用这两个类，为了避免命名冲突，我们可以重命名其中一个类。

from fastapi import HTTPException
from starlette.exceptions import HTTPException as StarletteHTTPException

FastAPI 进阶知识(三) 错误处理

一、HTTPException

1、导入模块

2、抛出异常

二、添加自定义头信息

三、自定义异常处理器

四、重写缺省异常处理器

1、重写请求校验异常处理器

2、重写HTTPException异常处理器

五、重用缺省异常处理器

六、FastAPI HTTPException 对比 Starlette HTTPException