FastAPI教程 路徑參數(shù)和數(shù)值校驗(yàn)

與使用 Query 為查詢參數(shù)聲明更多的校驗(yàn)和元數(shù)據(jù)的方式相同，你也可以使用 Path 為路徑參數(shù)聲明相同類型的校驗(yàn)和元數(shù)據(jù)。

導(dǎo)入 Path

首先，從 fastapi 導(dǎo)入 Path：

from typing import Optional

from fastapi import FastAPI, Path, Query

app = FastAPI()


@app.get("/items/{item_id}")
async def read_items(
    item_id: int = Path(..., title="The ID of the item to get"),
    q: Optional[str] = Query(None, alias="item-query"),
):
    results = {"item_id": item_id}
    if q:
        results.update({"q": q})
    return results

聲明元數(shù)據(jù)

你可以聲明與 Query 相同的所有參數(shù)。

例如，要聲明路徑參數(shù) item_id的 title 元數(shù)據(jù)值，你可以輸入：

from typing import Optional

from fastapi import FastAPI, Path, Query

app = FastAPI()


@app.get("/items/{item_id}")
async def read_items(
    item_id: int = Path(..., title="The ID of the item to get"),
    q: Optional[str] = Query(None, alias="item-query"),
):
    results = {"item_id": item_id}
    if q:
        results.update({"q": q})
    return results

Note

路徑參數(shù)總是必需的，因?yàn)樗仨毷锹窂降囊徊糠帧?/p>

所以，你應(yīng)該在聲明時(shí)使用 ... 將其標(biāo)記為必需參數(shù)。

然而，即使你使用 None 聲明路徑參數(shù)或設(shè)置一個(gè)其他默認(rèn)值也不會(huì)有任何影響，它依然會(huì)是必需參數(shù)。

按需對(duì)參數(shù)排序

假設(shè)你想要聲明一個(gè)必需的 str 類型查詢參數(shù) q。

而且你不需要為該參數(shù)聲明任何其他內(nèi)容，所以實(shí)際上你并不需要使用 Query。

但是你仍然需要使用 Path 來聲明路徑參數(shù) item_id。

如果你將帶有「默認(rèn)值」的參數(shù)放在沒有「默認(rèn)值」的參數(shù)之前，Python 將會(huì)報(bào)錯(cuò)。

但是你可以對(duì)其重新排序，并將不帶默認(rèn)值的值（查詢參數(shù) q）放到最前面。

對(duì) FastAPI 來說這無關(guān)緊要。它將通過參數(shù)的名稱、類型和默認(rèn)值聲明（Query、Path 等）來檢測參數(shù)，而不在乎參數(shù)的順序。

因此，你可以將函數(shù)聲明為：

from fastapi import FastAPI, Path

app = FastAPI()


@app.get("/items/{item_id}")
async def read_items(
    q: str, item_id: int = Path(..., title="The ID of the item to get")
):
    results = {"item_id": item_id}
    if q:
        results.update({"q": q})
    return results

按需對(duì)參數(shù)排序的技巧

如果你想不使用 Query 聲明沒有默認(rèn)值的查詢參數(shù) q，同時(shí)使用 Path 聲明路徑參數(shù) item_id，并使它們的順序與上面不同，Python 對(duì)此有一些特殊的語法。

傳遞 * 作為函數(shù)的第一個(gè)參數(shù)。

Python 不會(huì)對(duì)該 * 做任何事情，但是它將知道之后的所有參數(shù)都應(yīng)作為關(guān)鍵字參數(shù)（鍵值對(duì)），也被稱為 kwargs，來調(diào)用。即使它們沒有默認(rèn)值。

from fastapi import FastAPI, Path

app = FastAPI()


@app.get("/items/{item_id}")
async def read_items(
    *, item_id: int = Path(..., title="The ID of the item to get"), q: str
):
    results = {"item_id": item_id}
    if q:
        results.update({"q": q})
    return results

數(shù)值校驗(yàn)：大于等于

使用 Query 和 Path（以及你將在后面看到的其他類）可以聲明字符串約束，但也可以聲明數(shù)值約束。

像下面這樣，添加 ge=1 后，item_id 將必須是一個(gè)大于（greater than）或等于（equal）1 的整數(shù)。

from fastapi import FastAPI, Path

app = FastAPI()


@app.get("/items/{item_id}")
async def read_items(
    *, item_id: int = Path(..., title="The ID of the item to get", ge=1), q: str
):
    results = {"item_id": item_id}
    if q:
        results.update({"q": q})
    return results

數(shù)值校驗(yàn)：大于和小于等于

同樣的規(guī)則適用于：

• gt：大于（greater than）
• le：小于等于（less than or equal）

from fastapi import FastAPI, Path

app = FastAPI()


@app.get("/items/{item_id}")
async def read_items(
    *,
    item_id: int = Path(..., title="The ID of the item to get", gt=0, le=1000),
    q: str,
):
    results = {"item_id": item_id}
    if q:
        results.update({"q": q})
    return results

數(shù)值校驗(yàn)：浮點(diǎn)數(shù)、大于和小于

數(shù)值校驗(yàn)同樣適用于 float 值。

能夠聲明 gt 而不僅僅是 ge 在這個(gè)前提下變得重要起來。例如，你可以要求一個(gè)值必須大于 0，即使它小于 1。

因此，0.5 將是有效值。但是 0.0或 0 不是。

對(duì)于 lt 也是一樣的。

from fastapi import FastAPI, Path, Query

app = FastAPI()


@app.get("/items/{item_id}")
async def read_items(
    *,
    item_id: int = Path(..., title="The ID of the item to get", ge=0, le=1000),
    q: str,
    size: float = Query(..., gt=0, lt=10.5)
):
    results = {"item_id": item_id}
    if q:
        results.update({"q": q})
    return results

總結(jié)

你能夠以與 查詢參數(shù)和字符串校驗(yàn) 相同的方式使用 Query、Path（以及其他你還沒見過的類）聲明元數(shù)據(jù)和字符串校驗(yàn)。

而且你還可以聲明數(shù)值校驗(yàn)：

• gt：大于（greater than）
• ge：大于等于（greater than or equal）
• lt：小于（less than）
• le：小于等于（less than or equal）

Info

Query、Path 以及你后面會(huì)看到的其他類繼承自一個(gè)共同的 Param 類（不需要直接使用它）。

而且它們都共享相同的所有你已看到并用于添加額外校驗(yàn)和元數(shù)據(jù)的參數(shù)。

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

當(dāng)你從 fastapi 導(dǎo)入 Query、Path 和其他同類對(duì)象時(shí)，它們實(shí)際上是函數(shù)。

當(dāng)被調(diào)用時(shí)，它們返回同名類的實(shí)例。

如此，你導(dǎo)入 Query 這個(gè)函數(shù)。當(dāng)你調(diào)用它時(shí)，它將返回一個(gè)同樣命名為 Query 的類的實(shí)例。

因?yàn)槭褂昧诉@些函數(shù)（而不是直接使用類），所以你的編輯器不會(huì)標(biāo)記有關(guān)其類型的錯(cuò)誤。

這樣，你可以使用常規(guī)的編輯器和編碼工具，而不必添加自定義配置來忽略這些錯(cuò)誤。