用户指南 - 处理错误 - 《fastapi》

使用HTTPException
添加自定义头
安装自定义异常处理
复写默认的异常处理

在许多情况下，您需要将错误通知给正在使用API的客户端。
该客户端可以是带有前端的浏览器，其他人的代码，IoT设备等。
你需要告知客户端:

客户端没有足够的权限进行该操作。
客户端无权访问该资源。
客户端尝试访问的项目不存在。

在这些情况下，您通常会返回400（从400到499）范围内的HTTP状态代码。
这类似于200的HTTP状态代码（从200到299）。这些“200”状态代码意味着请求中某种程度上存在“成功”。
400范围内的状态代码表示客户端出现错误。
还记得所有那些“ 404 Not Found”错误（和笑话）吗？

使用HTTPException

返回有错误的http响应给客户端使用HTTPException.

导入`HTTPException`

from fastapi import FastAPI, HTTPException

在你的代码中抛出`HTTPException`

HTTPException是普通的Python异常，其中包含与API相关的其他数据。
因为它是Python异常，所以您不返回它，而是raise它。
这也意味着，如果您在要在路径操作函数内部调用的实用程序函数内部，并且从该实用程序函数内部抛出HTTPException，它将不会运行路径操作函数中的其余代码，它将立即终止该请求，并将HTTP错误从HTTPException发送到客户端。
在有关依赖关系和安全性的部分中，抛出异常而不是返回值的好处将更加明显。
在此示例中，当客户端通过不存在的ID请求商品时，引发状态代码为404的异常：

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://example.com/items/foo](http://example.com/items/foo)（item_id为“bar”），则他将收到HTTP状态代码200和JSON响应：

{
  "item": "The Foo Wrestlers"
}

但是，如果客户端请求[http://example.com/items/bar](http://example.com/items/bar)（不存在的item_id“ bar”），则他将收到HTTP状态码404（“找不到”错误）和JSON响应：

{
  "detail": "Item not found"
}

提示引发HTTPException时，您可以传递任何可以转换为JSON的值作为参数详细信息，而不仅限于str。您可以传递字典，列表等。它们由FastAPI自动处理并转换为JSON。

添加自定义头

在某些情况下，能够将自定义标头添加到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]}

安装自定义异常处理

您可以使用Starlette中的相同异常实用程序添加自定义异常处理程序。
假设您有一个自定义异常UnicornException，您（或您使用的库）可能会引发该异常。
您想使用FastAPI全局处理此异常。您可以使用@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，JSON内容为：

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

详细教学您还可以使用from starlette.requests import Request和from starlette.responses import JSONResponse。 FastAPI提供与starlette.responses相同的fastapi.responses，只是为开发人员提供了便利。但是大多数可用的响应直接来自Starlette。与请求相同。

复写默认的异常处理

FastAPI有一些默认的异常处理。
这些处理程序负责在引发HTTPException以及请求包含无效数据时返回默认的JSON响应。
你可以自己复写这些异常处理。

覆盖请求验证异常

当请求包含无效数据时，FastAPI在内部引发RequestValidationError。
它还包括一个默认的异常处理程序。
要覆盖它，请导入RequestValidationError并将其与@app.exception_handler(RequestValidationError)配合使用以装饰异常处理程序。
异常处理程序将接收请求和异常。

from fastapi import FastAPI, HTTPException
from fastapi.exceptions import RequestValidationError
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.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，而不是使用以下命令获取默认的JSON错误：

{
    "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 vs ValidationError

警告这些技术细节如果现在对您不重要，则可以跳过。

RequestValidationError是 Pydantic’s 中ValidationError的一个子类。
FastAPI使用它的目的是，如果您在response_model中使用Pydantic模型，并且您的数据有错误，您将在日志中看到该错误。
但是客户端/用户将看不到它。而是，客户端将收到带有HTTP状态代码500的“内部服务器错误”。
之所以应该这样，是因为如果您的响应中或代码中的任何地方（而不是客户的请求中）都存在Pydantic ValidationError，则实际上是代码中的错误。
而且，在修复该错误时，您的客户/用户不应访问有关该错误的内部信息，因为这可能会暴露一个安全漏洞。

复写`HTTPException`错误处理

同样的方式，你可以复写HTTPException处理。
例如，对于这些错误，您可能希望返回纯文本响应而不是JSON：

from fastapi import FastAPI, HTTPException
from fastapi.exceptions import RequestValidationError
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.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}

详细说明你也可以使用from starlette.responses import PlainTextResponse FastAPI提供与starlette.responses相同的fastapi.responses，只是为开发人员提供了便利。但是大多数可用的响应直接来自Starlette。

使用`RequestValidationError`体

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

现在尝试发送无效的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"
  }
}

FastAPI的`HTTPException` vs Starlette的`HTTPException`

FastAPI有自己的HTTPException。
FastAPI的HTTPException错误类继承自Starlette的HTTPException错误类。
唯一的区别是，FastAPI的HTTPException允许您添加要包含在响应中的标头。
OAuth 2.0和某些安全实用程序在内部需要/使用此功能。
因此，您可以像平常一样在代码中继续提高FastAPI的HTTPException。
但是，当您注册异常处理程序时，应该为Starlette的HTTPException注册它。
这样，如果Starlette内部代码的任何部分或Starlette扩展或插件引发了Starlette的HTTPException，则您的处理程序将能够捕获并处理它。
在此示例中，为了能够将两个HTTPExceptions包含在同一代码中，Starlette的异常被重命名为StarletteHTTPException：

from starlette.exceptions import HTTPException as StarletteHTTPException

重新使用FastAPI的异常处理

您也可能只想以某种方式使用该异常，然后使用FastAPI中相同的默认异常处理程序。
您可以从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}

在此示例中，您仅使用非常具有表现力的消息来print错误。
但是您知道了，可以使用异常，然后重新使用默认的异常处理程序。

处理错误