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

2021-11-02 14:58 更新

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

讓我們以下面的應(yīng)用程序?yàn)槔?/p>

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,因此它是可選的。

額外的校驗(yàn)

我們打算添加約束條件:即使 q 是可選的,但只要提供了該參數(shù),則該參數(shù)值不能超過(guò)50個(gè)字符的長(zhǎng)度。

導(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 的第一個(gè)參數(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)

將會(huì)校驗(yàn)數(shù)據(jù),在數(shù)據(jù)無(wú)效時(shí)展示清晰的錯(cuò)誤信息,并在 OpenAPI 模式的路徑操作中記錄該參??數(shù)。

添加更多校驗(yàn)

你還可以添加 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á)式

你可以定義一個(gè)參數(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

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

  • ^:以該符號(hào)之后的字符開(kāi)頭,符號(hào)之前沒(méi)有字符。
  • fixedquery: 值精確地等于 fixedquery。
  • $: 到此結(jié)束,在 fixedquery 之后沒(méi)有更多字符。

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

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

默認(rèn)值

你可以向 Query 的第一個(gè)參數(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)值還會(huì)使該參數(shù)成為可選參數(shù)。

聲明為必需參數(shù)

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

q: str

代替:

q: str = None

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

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

因此,當(dāng)你在使用 Query 且需要聲明一個(gè)值是必需的時(shí),可以將 ... 用作第一個(gè)參數(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

如果你之前沒(méi)見(jiàn)過(guò) ... 這種用法:它是一個(gè)特殊的單獨(dú)值,它是 Python 的一部分并且被稱為「省略號(hào)」

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

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

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

例如,要聲明一個(gè)可在 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

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

因此,該 URL 的響應(yīng)將會(huì)是:

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

Tip

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

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

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

你還可以定義在沒(méi)有任何給定值時(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

如果你訪問(wèn):

http://localhost:8000/items/

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

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

請(qǐng)記住,在這種情況下 FastAPI 將不會(huì)檢查列表的內(nèi)容。

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

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

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

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

Note

請(qǐng)記住,不同的工具對(duì) OpenAPI 的支持程度可能不同。

其中一些可能不會(huì)展示所有已聲明的額外信息,盡管在大多數(shù)情況下,缺少的這部分功能已經(jīng)計(jì)劃進(jìn)行開(kāi)發(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 不是一個(gè)有效的 Python 變量名稱。

最接近的有效名稱是 item_query。

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

這時(shí)你可以用 alias 參數(shù)聲明一個(gè)別名,該別名將用于在 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í)間,因?yàn)橛行┛蛻舳苏谑褂盟?,但你希望文檔清楚地將其展示為已棄用。

那么將參數(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

文檔將會(huì)像下面這樣展示它:

總結(jié)

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

通用的校驗(yàn)和元數(shù)據(jù):

  • alias
  • title
  • description
  • deprecated

特定于字符串的校驗(yàn):

  • min_length
  • max_length
  • regex

在這些示例中,你了解了如何聲明對(duì) str 值的校驗(yàn)。

請(qǐng)參閱下一章節(jié),以了解如何聲明對(duì)其他類型例如數(shù)值的校驗(yàn)。


以上內(nèi)容是否對(duì)您有幫助:
在線筆記
App下載
App下載

掃描二維碼

下載編程獅App

公眾號(hào)
微信公眾號(hào)

編程獅公眾號(hào)