閱讀(3.9k) 書簽贊(1) 我要糾錯

FastAPI教程查詢參數(shù)和字符串校驗

2021-11-02 14:58 更新

FastAPI 允許你為參數(shù)聲明額外的信息和校驗。

讓我們以下面的應(yīng)用程序為例：

from typing import Optional

from fastapi import FastAPI

app = FastAPI()


@app.get("/items/")
async def read_items(q: Optional[str] = None):
    results = {"items": [{"item_id": "Foo"}, {"item_id": "Bar"}]}
    if q:
        results.update({"q": q})
    return results

查詢參數(shù) q 的類型為 str，默認(rèn)值為 None，因此它是可選的。

額外的校驗

我們打算添加約束條件：即使 q 是可選的，但只要提供了該參數(shù)，則該參數(shù)值不能超過50個字符的長度。

導(dǎo)入 Query

為此，首先從 fastapi 導(dǎo)入 Query：

from typing import Optional

from fastapi import FastAPI, Query

app = FastAPI()


@app.get("/items/")
async def read_items(q: Optional[str] = Query(None, max_length=50)):
    results = {"items": [{"item_id": "Foo"}, {"item_id": "Bar"}]}
    if q:
        results.update({"q": q})
    return results

使用 Query 作為默認(rèn)值

現(xiàn)在，將 Query 用作查詢參數(shù)的默認(rèn)值，并將它的 max_length 參數(shù)設(shè)置為 50：

from typing import Optional

from fastapi import FastAPI, Query

app = FastAPI()


@app.get("/items/")
async def read_items(q: Optional[str] = Query(None, max_length=50)):
    results = {"items": [{"item_id": "Foo"}, {"item_id": "Bar"}]}
    if q:
        results.update({"q": q})
    return results

由于我們必須用 Query(None) 替換默認(rèn)值 None，Query 的第一個參數(shù)同樣也是用于定義默認(rèn)值。

所以：

q: str = Query(None)

...使得參數(shù)可選，等同于：

q: str = None

但是 Query 顯式地將其聲明為查詢參數(shù)。

然后，我們可以將更多的參數(shù)傳遞給 Query。在本例中，適用于字符串的 max_length 參數(shù)：

q: str = Query(None, max_length=50)

將會校驗數(shù)據(jù)，在數(shù)據(jù)無效時展示清晰的錯誤信息，并在 OpenAPI 模式的路徑操作中記錄該參??數(shù)。

添加更多校驗

你還可以添加 min_length 參數(shù)：

from typing import Optional

from fastapi import FastAPI, Query

app = FastAPI()


@app.get("/items/")
async def read_items(q: Optional[str] = Query(None, min_length=3, max_length=50)):
    results = {"items": [{"item_id": "Foo"}, {"item_id": "Bar"}]}
    if q:
        results.update({"q": q})
    return results

添加正則表達(dá)式

你可以定義一個參數(shù)值必須匹配的正則表達(dá)式：

from typing import Optional

from fastapi import FastAPI, Query

app = FastAPI()


@app.get("/items/")
async def read_items(
    q: Optional[str] = Query(None, min_length=3, max_length=50, regex="^fixedquery$")
):
    results = {"items": [{"item_id": "Foo"}, {"item_id": "Bar"}]}
    if q:
        results.update({"q": q})
    return results

這個指定的正則表達(dá)式通過以下規(guī)則檢查接收到的參數(shù)值：

^：以該符號之后的字符開頭，符號之前沒有字符。
fixedquery: 值精確地等于 fixedquery。
$: 到此結(jié)束，在 fixedquery 之后沒有更多字符。

如果你對所有的這些「正則表達(dá)式」概念感到迷茫，請不要擔(dān)心。對于許多人來說這都是一個困難的主題。你仍然可以在無需正則表達(dá)式的情況下做很多事情。

但是，一旦你需要用到并去學(xué)習(xí)它們時，請了解你已經(jīng)可以在 FastAPI 中直接使用它們。

默認(rèn)值

你可以向 Query 的第一個參數(shù)傳入 None 用作查詢參數(shù)的默認(rèn)值，以同樣的方式你也可以傳遞其他默認(rèn)值。

假設(shè)你想要聲明查詢參數(shù) q，使其 min_length 為 3，并且默認(rèn)值為 fixedquery：

from fastapi import FastAPI, Query

app = FastAPI()


@app.get("/items/")
async def read_items(q: str = Query("fixedquery", min_length=3)):
    results = {"items": [{"item_id": "Foo"}, {"item_id": "Bar"}]}
    if q:
        results.update({"q": q})
    return results

Note

具有默認(rèn)值還會使該參數(shù)成為可選參數(shù)。

聲明為必需參數(shù)

當(dāng)我們不需要聲明額外的校驗或元數(shù)據(jù)時，只需不聲明默認(rèn)值就可以使 q 參數(shù)成為必需參數(shù)，例如：

q: str

代替：

q: str = None

但是現(xiàn)在我們正在用 Query 聲明它，例如：

q: str = Query(None, min_length=3)

因此，當(dāng)你在使用 Query 且需要聲明一個值是必需的時，可以將 ... 用作第一個參數(shù)值：

from fastapi import FastAPI, Query

app = FastAPI()


@app.get("/items/")
async def read_items(q: str = Query(..., min_length=3)):
    results = {"items": [{"item_id": "Foo"}, {"item_id": "Bar"}]}
    if q:
        results.update({"q": q})
    return results

Info

如果你之前沒見過 ... 這種用法：它是一個特殊的單獨(dú)值，它是 Python 的一部分并且被稱為「省略號」。

這將使 FastAPI 知道此查詢參數(shù)是必需的。

查詢參數(shù)列表 / 多個值

當(dāng)你使用 Query 顯式地定義查詢參數(shù)時，你還可以聲明它去接收一組值，或換句話來說，接收多個值。

例如，要聲明一個可在 URL 中出現(xiàn)多次的查詢參數(shù) q，你可以這樣寫：

from typing import List, Optional

from fastapi import FastAPI, Query

app = FastAPI()


@app.get("/items/")
async def read_items(q: Optional[List[str]] = Query(None)):
    query_items = {"q": q}
    return query_items

然后，輸入如下網(wǎng)址：

http://localhost:8000/items/?q=foo&q=bar

你會在路徑操作函數(shù)的函數(shù)參數(shù) q 中以一個 Python list 的形式接收到查詢參數(shù) q 的多個值（foo 和 bar）。

因此，該 URL 的響應(yīng)將會是：

{
  "q": [
    "foo",
    "bar"
  ]
}

Tip

要聲明類型為 list 的查詢參數(shù)，如上例所示，你需要顯式地使用 Query，否則該參數(shù)將被解釋為請求體。

交互式 API 文檔將會相應(yīng)地進(jìn)行更新，以允許使用多個值：

具有默認(rèn)值的查詢參數(shù)列表 / 多個值

你還可以定義在沒有任何給定值時的默認(rèn) list 值：

from typing import List

from fastapi import FastAPI, Query

app = FastAPI()


@app.get("/items/")
async def read_items(q: List[str] = Query(["foo", "bar"])):
    query_items = {"q": q}
    return query_items

如果你訪問：

http://localhost:8000/items/

q 的默認(rèn)值將為：["foo", "bar"]，你的響應(yīng)會是：

{
  "q": [
    "foo",
    "bar"
  ]
}

使用 list

你也可以直接使用 list 代替 List [str]：

from fastapi import FastAPI, Query

app = FastAPI()


@app.get("/items/")
async def read_items(q: list = Query([])):
    query_items = {"q": q}
    return query_items

Note

請記住，在這種情況下 FastAPI 將不會檢查列表的內(nèi)容。

例如，List[int] 將檢查（并記錄到文檔）列表的內(nèi)容必須是整數(shù)。但是單獨(dú)的 list 不會。

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

你可以添加更多有關(guān)該參數(shù)的信息。

這些信息將包含在生成的 OpenAPI 模式中，并由文檔用戶界面和外部工具所使用。

Note

請記住，不同的工具對 OpenAPI 的支持程度可能不同。

其中一些可能不會展示所有已聲明的額外信息，盡管在大多數(shù)情況下，缺少的這部分功能已經(jīng)計劃進(jìn)行開發(fā)。

你可以添加 title：

from typing import Optional

from fastapi import FastAPI, Query

app = FastAPI()


@app.get("/items/")
async def read_items(
    q: Optional[str] = Query(None, title="Query string", min_length=3)
):
    results = {"items": [{"item_id": "Foo"}, {"item_id": "Bar"}]}
    if q:
        results.update({"q": q})
    return results

以及 description：

from typing import Optional

from fastapi import FastAPI, Query

app = FastAPI()


@app.get("/items/")
async def read_items(
    q: Optional[str] = Query(
        None,
        title="Query string",
        description="Query string for the items to search in the database that have a good match",
        min_length=3,
    )
):
    results = {"items": [{"item_id": "Foo"}, {"item_id": "Bar"}]}
    if q:
        results.update({"q": q})
    return results

別名參數(shù)

假設(shè)你想要查詢參數(shù)為 item-query。

像下面這樣：

http://127.0.0.1:8000/items/?item-query=foobaritems

但是 item-query 不是一個有效的 Python 變量名稱。

最接近的有效名稱是 item_query。

但是你仍然要求它在 URL 中必須是 item-query...

這時你可以用 alias 參數(shù)聲明一個別名，該別名將用于在 URL 中查找查詢參數(shù)值：

from typing import Optional

from fastapi import FastAPI, Query

app = FastAPI()


@app.get("/items/")
async def read_items(q: Optional[str] = Query(None, alias="item-query")):
    results = {"items": [{"item_id": "Foo"}, {"item_id": "Bar"}]}
    if q:
        results.update({"q": q})
    return results

棄用參數(shù)

現(xiàn)在假設(shè)你不再喜歡此參數(shù)。

你不得不將其保留一段時間，因為有些客戶端正在使用它，但你希望文檔清楚地將其展示為已棄用。

那么將參數(shù) deprecated=True 傳入 Query：

from typing import Optional

from fastapi import FastAPI, Query

app = FastAPI()


@app.get("/items/")
async def read_items(
    q: Optional[str] = Query(
        None,
        alias="item-query",
        title="Query string",
        description="Query string for the items to search in the database that have a good match",
        min_length=3,
        max_length=50,
        regex="^fixedquery$",
        deprecated=True,
    )
):
    results = {"items": [{"item_id": "Foo"}, {"item_id": "Bar"}]}
    if q:
        results.update({"q": q})
    return results

文檔將會像下面這樣展示它：

總結(jié)

你可以為查詢參數(shù)聲明額外的校驗和元數(shù)據(jù)。

通用的校驗和元數(shù)據(jù)：

alias
title
description
deprecated

特定于字符串的校驗：

min_length
max_length
regex

在這些示例中，你了解了如何聲明對 str 值的校驗。

請參閱下一章節(jié)，以了解如何聲明對其他類型例如數(shù)值的校驗。

以上內(nèi)容是否對您有幫助：

← FastAPI教程請求體

FastAPI教程路徑參數(shù)和數(shù)值校驗 →

寫筆記

我要補(bǔ)充

FastAPI教程 查詢參數(shù)和字符串校驗

額外的校驗

導(dǎo)入 Query

使用 Query 作為默認(rèn)值

添加更多校驗

添加正則表達(dá)式

默認(rèn)值

聲明為必需參數(shù)

查詢參數(shù)列表 / 多個值

具有默認(rèn)值的查詢參數(shù)列表 / 多個值

使用 list

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

別名參數(shù)

棄用參數(shù)

總結(jié)

推薦文章

推薦教程

推薦課程

FastAPI教程查詢參數(shù)和字符串校驗