一文帶你吃透FastAPI中的路徑參數(shù)

更新時(shí)間：2024年03月26日 09:27:02 作者：shengjk1

FastAPI中最核心的之一就是路徑參數(shù),所以這篇文章小編主要來和大家介紹一下FastAPI路徑參數(shù)的作用以及基本使用,有需要的小伙伴可以參考下

一、前言

FastAPI 最核心的之一就是路徑參數(shù)，今天我們一篇徹底搞 FaST 懂路徑參數(shù)

二、路徑參數(shù)定義

路徑操作裝飾器中對(duì)應(yīng)的值就是路徑參數(shù)，比如：

from fastapi import FastAPI
app = FastAPI()

@app.get("/hello/{name}")
def say_hello(name: str):
    return {"message": f"Hello {name}"}  

if __name__ == "__main__":
    import uvicorn
    uvicorn.run("quickstart.demo:app",reload=True,port=8001)

路徑操作裝飾器 @app.get("/hello/{name}") 中 name 就是路徑參數(shù)，這里我們也把路徑參數(shù) name 的值作為參數(shù) name 傳遞給了路徑操作函數(shù) say_hello，如果我們運(yùn)行示例并訪問 http://127.0.0.1:8001/hello/xiaoming，將會(huì)看到如下響應(yīng)：

{"message":"Hello xiaoming"}

2.1 路徑參數(shù)作用

路徑參數(shù)在 FastAPI 中的主要作用是從 URL 路徑中提取變量值，并將其傳遞給請(qǐng)求處理函數(shù)。并且提供了靈活的路由匹配和處理，還支持類型轉(zhuǎn)換和驗(yàn)證，使你能夠構(gòu)建強(qiáng)大和可靠的 API

2.2 路徑參數(shù)的基本使用

2.2.1 無(wú)類型的路徑參數(shù)

from fastapi import FastAPI

app = FastAPI()

@app.get("/items/{item_id}")
 def read_item(item_id):
    return {"item_id": item_id}

if __name__ == "__main__":
    import uvicorn
    uvicorn.run("quickstart.demo:app",reload=True,port=8001)

如果我們運(yùn)行示例并訪問 http://127.0.0.1:8001/items/xiaoming，將會(huì)看到如下響應(yīng)：

{"item_id": "xiaoming"}

如果我們運(yùn)行示例并訪問 http://127.0.0.1:8001/items/11，將會(huì)看到如下響應(yīng)：

{"item_id":"11"}

所以當(dāng)路徑參數(shù)是無(wú)類型時(shí)，F(xiàn)astAPI 會(huì)將其認(rèn)為為 str 類型

2.2.2有類型的路徑參數(shù)

為函數(shù)中的與路徑參數(shù)同名的參數(shù)聲明類型

比如申明函數(shù)中 item_id 為 int 類型

from fastapi import FastAPI

app = FastAPI()

@app.get("/items/{item_id}")
 def read_item(item_id:int):
    return {"item_id": item_id}

if __name__ == "__main__":
    import uvicorn
    uvicorn.run("quickstart.demo:app",reload=True,port=8001)

如果我們運(yùn)行示例并訪問 http://127.0.0.1:8001/items/11，將會(huì)看到如下響應(yīng)：

{"item_id":11}

注意函數(shù)接收（并返回）的值為 11，是一個(gè) Python int 值，而不是字符串 "11"。所以，F(xiàn)astAPI 通過上面的類型可以對(duì)參數(shù)進(jìn)行類型轉(zhuǎn)換。如果我們運(yùn)行示例并訪問 http://127.0.0.1:8001/items/xiaoming，將會(huì)看到如下響應(yīng)：

{
  "detail":[
    {
      "loc":[
        "path",
        "item_id"
      ],
      "msg":"value is not a valid integer",
      "type":"type_error.integer"
    }
  ]
}

因?yàn)槁窂絽?shù) item_id 傳入的值為 "xiaoming"，它不是一個(gè) int。如果你提供的是 float 而非整數(shù)也會(huì)出現(xiàn)同樣的錯(cuò)誤，比如：http://127.0.0.1:8001/items/11.1 所以，通過同樣的 Python 類型聲明，F(xiàn)astAPI 提供了數(shù)據(jù)校驗(yàn)功能。并且清楚地指出了校驗(yàn)未通過的具體原因。在開發(fā)和調(diào)試 API 時(shí)，這非常有用。

為路徑參數(shù)申明類型

from fastapi import FastAPI

app = FastAPI()

@app.get("/items/{item_id:int}")
 def read_item(item_id):
    return {"item_id": item_id}

if __name__ == "__main__":
    import uvicorn
    uvicorn.run("quickstart.demo:app",reload=True,port=8001)

如果我們運(yùn)行示例并訪問 http://127.0.0.1:8001/items/11，將會(huì)看到如下響應(yīng)：

{"item_id":11}

如果我們運(yùn)行示例并訪問 http://127.0.0.1:8001/items/xiaoming，將會(huì)看到如下響應(yīng)：

{"detail":"Not Found"}

上一篇文章中，我們講過 @app.get("/items/{item_id:int}") 為 **路徑操作裝飾器，它的作用就是匹配 URL ，**而傳給 FastAPI 的 URL 為 /items/xiaoming，它應(yīng)該匹配 @app.get("/items/{item_id:str}") 或者 @app.get("/items/{item_id}")，但代碼中并沒有這兩個(gè)地址，所以瀏覽器會(huì)返回 Not Found，而服務(wù)端也就是我們的 Code 打印出來的日志為 127.0.0.1:64512 - "GET /items/xiaoming HTTP/1.1" 404 Not Found 想要修復(fù)這個(gè)錯(cuò)誤其實(shí)也很容易，我們?cè)偌右粋€(gè) @app.get("/items/{item_id:str}") 路徑操作裝飾器即可

from fastapi import FastAPI

app = FastAPI()

@app.get("/items/{item_id:int}")
 def read_item(item_id):
    return {"item_id": item_id}

@app.get("/items/{item_id:str}")
 def read_item(item_id):
    return {"item_id": item_id}    

if __name__ == "__main__":
    import uvicorn
    uvicorn.run("quickstart.demo:app",reload=True,port=8001)

2.2.3 路徑參數(shù)順序

from fastapi import FastAPI

app = FastAPI()

@app.get("/items/{item_id}")
 def read_item(item_id):
    return {"item_id": item_id}

@app.get("/items/{item_id:int}")
 def read_item(item_id):
    return {"item_id_int": item_id}    

if __name__ == "__main__":
    import uvicorn
    uvicorn.run("quickstart.demo:app",reload=True,port=8001)

如果我們運(yùn)行示例并訪問http://127.0.0.1:8001/items/11，將會(huì)看到如下響應(yīng)：

{"item_id":"11"}

如果我們運(yùn)行示例并訪問 http://127.0.0.1:8001/items/xiaoming，將會(huì)看到如下響應(yīng)：

{"item_id":"xiaoming"}

會(huì)發(fā)現(xiàn)，不管怎么樣都沒有辦法訪問 @app.get("/items/{item_id:int}") 這個(gè)路徑操作裝飾器，除非將這兩個(gè)裝飾器調(diào)換一下位置。

2.3路徑參數(shù)高級(jí)用法

2.3.1 Pydantic 模型（請(qǐng)求體）作為路徑參數(shù)

在 FastAPI 中，使用 Pydantic 模型作為路徑參數(shù)的優(yōu)勢(shì)主要體現(xiàn)在以下幾個(gè)方面：

類型轉(zhuǎn)換和驗(yàn)證：通過使用 Pydantic 模型作為路徑參數(shù)，你可以指定參數(shù)的類型，并利用 Pydantic 的驗(yàn)證規(guī)則來確保傳入的參數(shù)值符合預(yù)期的格式和約束。這可以防止無(wú)效的參數(shù)值傳遞到請(qǐng)求處理函數(shù)中，提高了數(shù)據(jù)的有效性和安全性。
自動(dòng)生成文檔和 OpenAPI 規(guī)范：FastAPI 使用 Pydantic 模型作為路徑參數(shù)時(shí)，能夠自動(dòng)根據(jù)模型的定義生成路徑參數(shù)的文檔和 OpenAPI 規(guī)范。這樣，你不僅可以確保文檔與實(shí)際代碼保持同步，還可以獲得更詳細(xì)和準(zhǔn)確的文檔信息，包括參數(shù)類型、驗(yàn)證規(guī)則和示例值等。
代碼重用和可維護(hù)性：使用 Pydantic 模型作為路徑參數(shù)可以提高代碼的重用性和可維護(hù)性。你可以在多個(gè)路由中使用相同的模型作為路徑參數(shù)，避免了重復(fù)定義和驗(yàn)證參數(shù)的過程。這樣，如果需要更改參數(shù)的類型或驗(yàn)證規(guī)則，你只需要修改模型的定義，而不必在多個(gè)地方修改代碼。
更清晰的代碼結(jié)構(gòu)：通過使用 Pydantic 模型作為路徑參數(shù)，可以使代碼結(jié)構(gòu)更清晰和可讀。模型的定義提供了一種統(tǒng)一的方式來描述和組織參數(shù)，使得代碼更易于理解和維護(hù)。

以下是一個(gè)示例：

Server 端:

from fastapi import FastAPI
from pydantic import BaseModel

app = FastAPI()

class Item(BaseModel):
    item_id: int
    item_name: str
    
@app.put("/items/{item_id}")
def put_item(item_id:int,item_name:str):
    return {"item_id": item_id, "item_name":item_name}

if __name__ == "__main__":
    import uvicorn
    uvicorn.run("quickstart.demo:app", reload=True, port=8001)

Client端：

import requests

data={"item_id":1,"item_name":"xiaoming"}

respone=requests.put("http://127.0.0.1:8001/items/1",json=data)
print(respone.json())

respone的結(jié)果：

{'item_id': 1, 'item_name': 'xiaoming'}

在上述示例中，我們定義了一個(gè) Item 模型作為路徑參數(shù)，并且還定義了另一個(gè) user_id 的普通路徑參數(shù)。FastAPI 會(huì)自動(dòng)將路徑參數(shù)中的 user_id 值轉(zhuǎn)換為整數(shù)，并將其傳遞給 put_item 函數(shù)的 user_id 參數(shù)。同時(shí)，它還會(huì)根據(jù) Item 模型的定義，驗(yàn)證并轉(zhuǎn)換路徑參數(shù)中的 JSON 對(duì)象，并將其傳遞給 put_item 函數(shù)的 item 參數(shù)。

2.3.2 路徑參數(shù)校驗(yàn)

因?yàn)槭锹窂絽?shù)，所以需要使用 FastPAI 的 Path 模塊來進(jìn)行參數(shù)的校驗(yàn)

from fastapi import FastAPI

app = FastAPI()

@app.get("/items/{item_id}")
def read_item(item_id:int=Path(gt=0, le=100)):
    return {"item_id": item_id}

if __name__ == "__main__":
    import uvicorn
    uvicorn.run("quickstart.demo:app",reload=True,port=8001)

這個(gè)例子當(dāng)中，我們限制了 item_id 取值范圍為 [0,100] 如果我們運(yùn)行示例并訪問 http://127.0.0.1:8001/items/11，將會(huì)看到如下響應(yīng)：

{"item_id":"11"}

訪問 http://127.0.0.1:8001/items/101 ，將會(huì)看到如下響應(yīng)：

{
  "detail":[
    {
      "loc":[
        "path",
        "item_id"
      ],
      "msg":"ensure this value is less than or equal to 100",
      "type":"value_error.number.not_le",
      "ctx":{
        "limit_value":100
      }
    }
  ]
}

類似操作還有很多，比如：

數(shù)字：
gt：大于
ge：大于等于
lt：小于
le：小于等于

字符串：
min_length
max_length
pattern 正則表達(dá)式

如果使用 Pydantic 模型作為路徑參數(shù)，也可以進(jìn)行類似的校驗(yàn)，如：

class Item(BaseModel):
    name: str
    price: float = Path(gt=0.1, le=100.2)

2.3.3 路徑參數(shù)申明元數(shù)據(jù)

在 FastAPI 中，路徑參數(shù)的元數(shù)據(jù)用于提供關(guān)于該參數(shù)的額外信息，例如描述、示例值、別名等。這些元數(shù)據(jù)可以通過在路徑參數(shù)聲明中使用參數(shù)關(guān)鍵字參數(shù)的方式進(jìn)行設(shè)置。使用元數(shù)據(jù)可以提高代碼的可讀性和維護(hù)性。

FastAPI 使用元數(shù)據(jù)來生成自動(dòng)化的文檔，包括 API 文檔和交互式 API 文檔（Swagger UI 或 ReDoc）。元數(shù)據(jù)提供了關(guān)于路徑參數(shù)的描述、示例值和其他信息，使生成的文檔更加詳細(xì)和準(zhǔn)確。這樣，用戶可以在文檔中了解到如何正確使用路徑參數(shù)。

下面是一個(gè)示例，展示了在 FastAPI 中使用路徑參數(shù)元數(shù)據(jù)的方式：

from fastapi import FastAPI

app = FastAPI()

@app.get("/items/{item_id}")
def read_item(item_id:int=Path(description="item的ID,規(guī)定其值大于0，小于等于100",gt=0, le=100)):
    return {"item_id": item_id}

if __name__ == "__main__":
    import uvicorn
    uvicorn.run("quickstart.demo:app",reload=True,port=8001)

這樣的話，在跟上下游對(duì)接的過程中，如果還有人問你 item_id 是啥意思，直接甩一個(gè)鏈接 http://127.0.0.1:8001/docs 到他臉上，因?yàn)槲臋n中有詳細(xì)的信息，如：