FastAPI教程 錯誤處理

某些情況下，需要向客戶端返回錯誤提示。

這里所謂的客戶端包括前端瀏覽器、其他應(yīng)用程序、物聯(lián)網(wǎng)設(shè)備等。

需要向客戶端返回錯誤提示的場景主要如下：

• 客戶端沒有執(zhí)行操作的權(quán)限
• 客戶端沒有訪問資源的權(quán)限
• 客戶端要訪問的項目不存在
• 等等 ...

遇到這些情況時，通常要返回 4XX（400 至 499）HTTP 狀態(tài)碼。

4XX 狀態(tài)碼與表示請求成功的 2XX（200 至 299） HTTP 狀態(tài)碼類似。

只不過，4XX 狀態(tài)碼表示客戶端發(fā)生的錯誤。

大家都知道「404 Not Found」錯誤，還有調(diào)侃這個錯誤的笑話吧？

使用 HTTPException

向客戶端返回 HTTP 錯誤響應(yīng)，可以使用 HTTPException。

導(dǎo)入 HTTPException

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]}

觸發(fā) HTTPException

HTTPException 是額外包含了和 API 有關(guān)數(shù)據(jù)的常規(guī) Python 異常。

因為是 Python 異常，所以不能 return，只能 raise。

如在調(diào)用路徑操作函數(shù)里的工具函數(shù)時，觸發(fā)了 HTTPException，F(xiàn)astAPI 就不再繼續(xù)執(zhí)行路徑操作函數(shù)中的后續(xù)代碼，而是立即終止請求，并把 HTTPException 的 HTTP 錯誤發(fā)送至客戶端。

在介紹依賴項與安全的章節(jié)中，您可以了解更多用 raise 異常代替 return 值的優(yōu)勢。

本例中，客戶端用 ID 請求的 item 不存在時，觸發(fā)狀態(tài)碼為 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]}

響應(yīng)結(jié)果

請求為 http://example.com/items/foo（item_id 為 「foo」）時，客戶端會接收到 HTTP 狀態(tài)碼 - 200 及如下 JSON 響應(yīng)結(jié)果：

 {
  "item": "The Foo Wrestlers"
}

但如果客戶端請求 http://example.com/items/bar（item_id 「bar」 不存在時），則會接收到 HTTP 狀態(tài)碼 - 404（「未找到」錯誤）及如下 JSON 響應(yīng)結(jié)果：

 {
  "detail": "Item not found"
}

提示

觸發(fā) HTTPException 時，可以用參數(shù) detail 傳遞任何能轉(zhuǎn)換為 JSON 的值，不僅限于 str。

還支持傳遞 dict、list 等數(shù)據(jù)結(jié)構(gòu)。

FastAPI 能自動處理這些數(shù)據(jù)，并將之轉(zhuǎn)換為 JSON。

添加自定義響應(yīng)頭

有些場景下要為 HTTP 錯誤添加自定義響應(yīng)頭。例如，出于某些方面的安全需要。

一般情況下可能不會需要在代碼中直接使用響應(yīng)頭。

但對于某些高級應(yīng)用場景，還是需要添加自定義響應(yīng)頭：

 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 的異常工具。

假設(shè)要觸發(fā)的自定義異常叫作 UnicornException。

且需要 FastAPI 實現(xiàn)全局處理該異常。

此時，可以用 @app.exception_handler() 添加自定義異?？刂破鳎?/p>

 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 時，路徑操作會觸發(fā) UnicornException。

但該異常將會被 unicorn_exception_handler 處理。

接收到的錯誤信息清晰明了，HTTP 狀態(tài)碼為 418，JSON 內(nèi)容如下：

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

技術(shù)細節(jié)

from starlette.requests import Request 和 from starlette.responses import JSONResponse 也可以用于導(dǎo)入 Request 和 JSONResponse。

FastAPI 提供了與 starlette.responses 相同的 fastapi.responses 作為快捷方式，但大部分響應(yīng)操作都可以直接從 Starlette 導(dǎo)入。同理，Request 也是如此。

覆蓋默認異常處理器

FastAPI 自帶了一些默認異常處理器。

觸發(fā) HTTPException 或請求無效數(shù)據(jù)時，這些處理器返回默認的 JSON 響應(yīng)結(jié)果。

不過，也可以使用自定義處理器覆蓋默認異常處理器。

覆蓋請求驗證異常

請求中包含無效數(shù)據(jù)時，F(xiàn)astAPI 內(nèi)部會觸發(fā) RequestValidationError。

該異常也內(nèi)置了默認異常處理器。

覆蓋默認異常處理器時需要導(dǎo)入 RequestValidationError，并用 @app.excption_handler(RequestValidationError) 裝飾異常處理器。

這樣，異常處理器就可以接收 Request 與異常。

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，可以看到以下內(nèi)容替換了默認 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

警告

如果您覺得現(xiàn)在還用不到以下技術(shù)細節(jié)，可以先跳過下面的內(nèi)容。

RequestValidationError 是 Pydantic 的 ValidationError 的子類。

FastAPI 調(diào)用的就是 RequestValidationError 類，因此，如果在 response_model 中使用 Pydantic 模型，且數(shù)據(jù)有錯誤時，在日志中就會看到這個錯誤。

但客戶端或用戶看不到這個錯誤。反之，客戶端接收到的是 HTTP 狀態(tài)碼為 500 的「內(nèi)部服務(wù)器錯誤」。

這是因為在響應(yīng)或代碼（不是在客戶端的請求里）中出現(xiàn)的 Pydantic ValidationError 是代碼的 bug。

修復(fù)錯誤時，客戶端或用戶不能訪問錯誤的內(nèi)部信息，否則會造成安全隱患。

覆蓋 HTTPException 錯誤處理器

同理，也可以覆蓋 HTTPException 處理器。

例如，只為錯誤返回純文本響應(yīng)，而不是返回 JSON 格式的內(nèi)容：

 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}

技術(shù)細節(jié)

還可以使用 from starlette.responses import PlainTextResponse。

FastAPI 提供了與 starlette.responses 相同的 fastapi.responses 作為快捷方式，但大部分響應(yīng)都可以直接從 Starlette 導(dǎo)入。

使用 RequestValidationError 的請求體

RequestValidationError 包含其接收到的無效數(shù)據(jù)請求的 body 。

開發(fā)時，可以用這個請求體生成日志、調(diào)試錯誤，并返回給用戶。

 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

現(xiàn)在試著發(fā)送一個無效的 item，例如：

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

收到的響應(yīng)包含 body 信息，并說明數(shù)據(jù)是無效的：

 {
  "detail": [
    {
      "loc": [
        "body",
        "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 錯誤類。

它們之間的唯一區(qū)別是，F(xiàn)astAPI 的 HTTPException 可以在響應(yīng)中添加響應(yīng)頭。

OAuth 2.0 等安全工具需要在內(nèi)部調(diào)用這些響應(yīng)頭。

因此你可以繼續(xù)像平常一樣在代碼中觸發(fā) FastAPI 的 HTTPException 。

但注冊異常處理器時，應(yīng)該注冊到來自 Starlette 的 HTTPException。

這樣做是為了，當(dāng) Starlette 的內(nèi)部代碼、擴展或插件觸發(fā) Starlette HTTPException 時，處理程序能夠捕獲、并處理此異常。

注意，本例代碼中同時使用了這兩個 HTTPException，此時，要把 Starlette 的 HTTPException 命名為 StarletteHTTPException：

from starlette.exceptions import HTTPException as StarletteHTTPException

復(fù)用 FastAPI 異常處理器

FastAPI 支持先對異常進行某些處理，然后再使用 FastAPI 中處理該異常的默認異常處理器。

從 fastapi.exception_handlers 中導(dǎo)入要復(fù)用的默認異常處理器：

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!: {repr(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}

雖然，本例只是輸出了夸大其詞的錯誤信息。

但也足以說明，可以在處理異常之后再復(fù)用默認的異常處理器。