FastAPI手册01

2024-05-20

FASTAPI是Python中最常用的WEB框架，工作中也常用该框架去做服务端，这篇博客记录FastAPI手册中比较有意思的一些点

路径参数

路径参数手册中下面几点比较有意思：

使用Python字符串格式化声明路径参数，然后使用Python标准类型注解，对路径参数类型自动进行格式检查

示例：

from fastapi import FastAPI

app = FastAPI()


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

访问 http://127.0.0.1:8000/items/3，返回的响应如下：

1	{"item_id":3}

然而，访问 http://127.0.0.1:8000/items/foo ：

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

也可以通过Enum类限制可接受到的路径参数

Note: ModeName从str继承了，API文档就能把值的类型定义为字符串，并且能正确渲染。

from enum import Enum

from fastapi import FastAPI


class ModelName(str, Enum):
    alexnet = "alexnet"
    resnet = "resnet"
    lenet = "lenet"


app = FastAPI()


@app.get("/models/{model_name}")
async def get_model(model_name: ModelName):
    if model_name is ModelName.alexnet:
        return {"model_name": model_name, "message": "Deep Learning FTW!"}

    if model_name.value == "lenet":
        return {"model_name": model_name, "message": "LeCNN all the images"}

    return {"model_name": model_name, "message": "Have some residuals"}

查看API文档

查看自动生成的API文档：http://127.0.0.1:8000/docs

此外，还内置了 ReDoc 生成的备选 API 文档： http://127.0.0.1:8000/redoc

FastAPI路径操作是按顺序执行的

要在 /users/{user_id} 之前声明 /users/me, 否则，/users/{user_id} 将匹配 /users/me，FastAPI 会认为正在接收值为 “me” 的 user_id 参数。

from fastapi import FastAPI

app = FastAPI()


@app.get("/users/me")
async def read_user_me():
    return {"user_id": "the current user"}


@app.get("/users/{user_id}")
async def read_user(user_id: str):
    return {"user_id": user_id}

查询参数

声明的参数不是路径参数时，路径操作函数会把该参数自动解释为查询参数。

from fastapi import FastAPI

app = FastAPI()

fake_items_db = [{"item_name": "Foo"}, {"item_name": "Bar"}, {"item_name": "Baz"}]


@app.get("/items/")
async def read_item(skip: int = 0, limit: int = 10):
    return fake_items_db[skip : skip + limit]

通过访问http://127.0.0.1:8000/items/?skip=0&limit=10等价于查询参数为：

skip = 0
limit = 10
同时如果没有提供，也是支持默认值的

可选的查询参数

通过把默认值设为None，可以声明可选的查询参数

FastAPI 可以识别出 item_id 是路径参数，q 不是路径参数，而是查询参数。

from fastapi import FastAPI

app = FastAPI()


@app.get("/items/{item_id}")
async def read_item(item_id: str, q: str | None = None):
    if q:
        return {"item_id": item_id, "q": q}
    return {"item_id": item_id}

如果要把查询参数设置为必选，就不要声明默认值

请求体

使用Pydantic BaseModel构建请求体

与声明查询参数一样，包含默认值的模型属性是可选的，否则就是必选的。默认值为 None 的模型属性也是可选的。

仅使用Python的类型声明，FastAPI 就可以：

JSON 形式读取请求体
-（在必要时）把请求体转换为对应的类型
校验数据：数据无效时返回错误信息，并指出错误数据的确切位置和内容
把接收的数据赋值给参数 item
把函数中请求体参数的类型声明为 Item，还能获得代码补全等编辑器支持
为模型生成 JSON Schema，在项目中所需的位置使用
用于 API 文档 UI

from fastapi import FastAPI
from pydantic import BaseModel


class Item(BaseModel):
    name: str
    description: str | None = None
    price: float
    tax: float | None = None


app = FastAPI()


@app.post("/items/")
async def create_item(item: Item):
    return item