响应模型¶
使用 response_model
参数,即可在以下路径操作中声明响应模型:
@app.get()
@app.post()
@app.put()
@app.delete()
- 等……
from typing import List, Union
from fastapi import FastAPI
from pydantic import BaseModel
app = FastAPI()
class Item(BaseModel):
name: str
description: Union[str, None] = None
price: float
tax: Union[float, None] = None
tags: List[str] = []
@app.post("/items/", response_model=Item)
async def create_item(item: Item):
return item
from typing import Union
from fastapi import FastAPI
from pydantic import BaseModel
app = FastAPI()
class Item(BaseModel):
name: str
description: Union[str, None] = None
price: float
tax: Union[float, None] = None
tags: list[str] = []
@app.post("/items/", response_model=Item)
async def create_item(item: Item):
return item
from fastapi import FastAPI
from pydantic import BaseModel
app = FastAPI()
class Item(BaseModel):
name: str
description: str | None = None
price: float
tax: float | None = None
tags: list[str] = []
@app.post("/items/", response_model=Item)
async def create_item(item: Item):
return item
笔记
注意,response_model
是(get
、post
等)装饰器方法的参数。与之前的参数和请求体不同,它不是路径操作函数的参数。
response_model
接收的类型与声明 Pydantic 模型属性的类型相同,可以是 Pydantic 模型,也可以是 Pydantic 模型列表,例如 List[Item]
。
FastAPI 使用 response_model
:
- 转换为类型声明的输出数据。
- 校验数据。
- 在 OpenAPI 路径操作中,为响应添加 JSON Schema。
- 生成 API 文档。
但最重要的是:
- 把输出数据限制在该模型定义内。接下来,您就会知道这一点有多重要。
技术细节
响应模型是在装饰器参数中声明的,而不是返回类型注释的函数,因为路径函数没有真正返回该响应模型,而是返回 dict
、数据库对象或其他模型,然后再使用 response_model
执行字段约束和序列化。
返回相同的输入数据¶
声明 UserIn
模型,其中,包含明文密码:
from typing import Union
from fastapi import FastAPI
from pydantic import BaseModel, EmailStr
app = FastAPI()
class UserIn(BaseModel):
username: str
password: str
email: EmailStr
full_name: Union[str, None] = None
# Don't do this in production!
@app.post("/user/", response_model=UserIn)
async def create_user(user: UserIn):
return user
from fastapi import FastAPI
from pydantic import BaseModel, EmailStr
app = FastAPI()
class UserIn(BaseModel):
username: str
password: str
email: EmailStr
full_name: str | None = None
# Don't do this in production!
@app.post("/user/", response_model=UserIn)
async def create_user(user: UserIn):
return user
说明
要使用 EmailStr
,首先要安装 email_validator
。
如 pip install email-validator
,
或 pip install pydantic[email]
。
使用此模型声明输入对象,并使用同一个模型声明输出对象:
from typing import Union
from fastapi import FastAPI
from pydantic import BaseModel, EmailStr
app = FastAPI()
class UserIn(BaseModel):
username: str
password: str
email: EmailStr
full_name: Union[str, None] = None
# Don't do this in production!
@app.post("/user/", response_model=UserIn)
async def create_user(user: UserIn):
return user
from fastapi import FastAPI
from pydantic import BaseModel, EmailStr
app = FastAPI()
class UserIn(BaseModel):
username: str
password: str
email: EmailStr
full_name: str | None = None
# Don't do this in production!
@app.post("/user/", response_model=UserIn)
async def create_user(user: UserIn):
return user
现在,只要在浏览器中使用密码创建用户,API 就会在响应中返回相同的密码。
本例中,因为是用户本人发送密码,这种操作没什么问题。
但如果在其他路径操作中使用同一个模型,就会把用户的密码发送给每一个客户端。
危险
永远不要存储用户的明文密码,也不要在响应中发送密码。
添加输出模型¶
相对于包含明文密码的输入模型,创建不含明文密码的输出模型:
from typing import Union
from fastapi import FastAPI
from pydantic import BaseModel, EmailStr
app = FastAPI()
class UserIn(BaseModel):
username: str
password: str
email: EmailStr
full_name: Union[str, None] = None
class UserOut(BaseModel):
username: str
email: EmailStr
full_name: Union[str, None] = None
@app.post("/user/", response_model=UserOut)
async def create_user(user: UserIn):
return user
from fastapi import FastAPI
from pydantic import BaseModel, EmailStr
app = FastAPI()
class UserIn(BaseModel):
username: str
password: str
email: EmailStr
full_name: str | None = None
class UserOut(BaseModel):
username: str
email: EmailStr
full_name: str | None = None
@app.post("/user/", response_model=UserOut)
async def create_user(user: UserIn):
return user
这样,即便路径操作函数返回同样的输入用户:
from typing import Union
from fastapi import FastAPI
from pydantic import BaseModel, EmailStr
app = FastAPI()
class UserIn(BaseModel):
username: str
password: str
email: EmailStr
full_name: Union[str, None] = None
class UserOut(BaseModel):
username: str
email: EmailStr
full_name: Union[str, None] = None
@app.post("/user/", response_model=UserOut)
async def create_user(user: UserIn):
return user
from fastapi import FastAPI
from pydantic import BaseModel, EmailStr
app = FastAPI()
class UserIn(BaseModel):
username: str
password: str
email: EmailStr
full_name: str | None = None
class UserOut(BaseModel):
username: str
email: EmailStr
full_name: str | None = None
@app.post("/user/", response_model=UserOut)
async def create_user(user: UserIn):
return user
……但因为 response_model
中声明的 UserOut
模型没有包含密码:
from typing import Union
from fastapi import FastAPI
from pydantic import BaseModel, EmailStr
app = FastAPI()
class UserIn(BaseModel):
username: str
password: str
email: EmailStr
full_name: Union[str, None] = None
class UserOut(BaseModel):
username: str
email: EmailStr
full_name: Union[str, None] = None
@app.post("/user/", response_model=UserOut)
async def create_user(user: UserIn):
return user
from fastapi import FastAPI
from pydantic import BaseModel, EmailStr
app = FastAPI()
class UserIn(BaseModel):
username: str
password: str
email: EmailStr
full_name: str | None = None
class UserOut(BaseModel):
username: str
email: EmailStr
full_name: str | None = None
@app.post("/user/", response_model=UserOut)
async def create_user(user: UserIn):
return user
FastAPI 会使用 Pydantic 过滤掉所有未在输出模型中声明的数据。
查看文档¶
API 文档中,输入模型和输出模型都有自己的 JSON Schema:
并且,API 文档可以使用这两个模型:
响应模型编码参数¶
响应模型支持默认值,例如:
from typing import List, Union
from fastapi import FastAPI
from pydantic import BaseModel
app = FastAPI()
class Item(BaseModel):
name: str
description: Union[str, None] = None
price: float
tax: float = 10.5
tags: List[str] = []
items = {
"foo": {"name": "Foo", "price": 50.2},
"bar": {"name": "Bar", "description": "The bartenders", "price": 62, "tax": 20.2},
"baz": {"name": "Baz", "description": None, "price": 50.2, "tax": 10.5, "tags": []},
}
@app.get("/items/{item_id}", response_model=Item, response_model_exclude_unset=True)
async def read_item(item_id: str):
return items[item_id]
from typing import Union
from fastapi import FastAPI
from pydantic import BaseModel
app = FastAPI()
class Item(BaseModel):
name: str
description: Union[str, None] = None
price: float
tax: float = 10.5
tags: list[str] = []
items = {
"foo": {"name": "Foo", "price": 50.2},
"bar": {"name": "Bar", "description": "The bartenders", "price": 62, "tax": 20.2},
"baz": {"name": "Baz", "description": None, "price": 50.2, "tax": 10.5, "tags": []},
}
@app.get("/items/{item_id}", response_model=Item, response_model_exclude_unset=True)
async def read_item(item_id: str):
return items[item_id]
from fastapi import FastAPI
from pydantic import BaseModel
app = FastAPI()
class Item(BaseModel):
name: str
description: str | None = None
price: float
tax: float = 10.5
tags: list[str] = []
items = {
"foo": {"name": "Foo", "price": 50.2},
"bar": {"name": "Bar", "description": "The bartenders", "price": 62, "tax": 20.2},
"baz": {"name": "Baz", "description": None, "price": 50.2, "tax": 10.5, "tags": []},
}
@app.get("/items/{item_id}", response_model=Item, response_model_exclude_unset=True)
async def read_item(item_id: str):
return items[item_id]
description: Union[str, None] = None
(或 Python 3.10 中的str | None = None
)的默认值是None
。tax: float = 10.5
的默认值是10.5
。tags: List[str] = []
的默认值是空列表:[]
但如果没有为含默认值的属性另赋新值,输出结果会省略含默认值的属性。
例如,NoSQL 数据库的模型中往往包含很多可选属性,如果输出含默认值的属性,输出的 JSON 响应会特别长,此时,可以省略只含默认值的属性。
使用 response_model_exclude_unset
参数¶
把路径操作装饰器的参数设置为 response_model_exclude_unset=True
:
from typing import List, Union
from fastapi import FastAPI
from pydantic import BaseModel
app = FastAPI()
class Item(BaseModel):
name: str
description: Union[str, None] = None
price: float
tax: float = 10.5
tags: List[str] = []
items = {
"foo": {"name": "Foo", "price": 50.2},
"bar": {"name": "Bar", "description": "The bartenders", "price": 62, "tax": 20.2},
"baz": {"name": "Baz", "description": None, "price": 50.2, "tax": 10.5, "tags": []},
}
@app.get("/items/{item_id}", response_model=Item, response_model_exclude_unset=True)
async def read_item(item_id: str):
return items[item_id]
from typing import Union
from fastapi import FastAPI
from pydantic import BaseModel
app = FastAPI()
class Item(BaseModel):
name: str
description: Union[str, None] = None
price: float
tax: float = 10.5
tags: list[str] = []
items = {
"foo": {"name": "Foo", "price": 50.2},
"bar": {"name": "Bar", "description": "The bartenders", "price": 62, "tax": 20.2},
"baz": {"name": "Baz", "description": None, "price": 50.2, "tax": 10.5, "tags": []},
}
@app.get("/items/{item_id}", response_model=Item, response_model_exclude_unset=True)
async def read_item(item_id: str):
return items[item_id]
from fastapi import FastAPI
from pydantic import BaseModel
app = FastAPI()
class Item(BaseModel):
name: str
description: str | None = None
price: float
tax: float = 10.5
tags: list[str] = []
items = {
"foo": {"name": "Foo", "price": 50.2},
"bar": {"name": "Bar", "description": "The bartenders", "price": 62, "tax": 20.2},
"baz": {"name": "Baz", "description": None, "price": 50.2, "tax": 10.5, "tags": []},
}
@app.get("/items/{item_id}", response_model=Item, response_model_exclude_unset=True)
async def read_item(item_id: str):
return items[item_id]
响应中就不会再包含未修改过默认值的属性,而是只包含设置过值的属性。
因此,向路径操作发送 ID 为 foo
的商品的请求,则(不包括默认值的)响应为:
{
"name": "Foo",
"price": 50.2
}
说明
FastAPI 使用 Pydantic 模型中 .dict()
的 exclude_unset
参数 实现此功能。
说明
还可以使用:
response_model_exclude_defaults=True
response_model_exclude_none=True
详见 Pydantic 文档中 exclude_defaults
和 exclude_none
的说明。
默认值字段有实际值的数据¶
但如果为含默认值的模型字段赋予了新值,例如 ID 为 bar
的项:
{
"name": "Bar",
"description": "The bartenders",
"price": 62,
"tax": 20.2
}
这些值就会包含在返回的响应中。
与默认值相同的数据¶
如果新的数据与默认值相同,例如 ID 为 baz
的项:
{
"name": "Baz",
"description": None,
"price": 50.2,
"tax": 10.5,
"tags": []
}
虽然 FastAPI (其实是 Pydantic)能够识别出 description
、tax
和 tags
的值与默认值相同,这些值也会显式设置(而不是取自默认值)。
因此,这些值会包含在 JSON 响应里。
提示
注意,默认值可以是任何对象,不只是 None。
还可以是列表 ([]
)、float
(10.5)等。
response_model_include
和 response_model_exclude
¶
路径操作装饰器参数还有 response_model_include
和 response_model_exclude
。
这两个参数的值是由属性名 str
组成的 set
,用于包含(忽略其他属性)或排除(包含其他属性)集合中的属性名。
如果只有一个 Pydantic 模型,但又想从中移除某些输出数据,则可以使用这种快捷方法。
提示
但我们依然建议使用多个类,而不是这些参数。
因为就算使用 response_model_include
或 response_model_exclude
省略属性,但在 OpenAPI 生成的 JSON Schema (及文档)中仍会显示完整的模型。
这种操作也适用于类似的 response_model_by_alias
。
from typing import Union
from fastapi import FastAPI
from pydantic import BaseModel
app = FastAPI()
class Item(BaseModel):
name: str
description: Union[str, None] = None
price: float
tax: float = 10.5
items = {
"foo": {"name": "Foo", "price": 50.2},
"bar": {"name": "Bar", "description": "The Bar fighters", "price": 62, "tax": 20.2},
"baz": {
"name": "Baz",
"description": "There goes my baz",
"price": 50.2,
"tax": 10.5,
},
}
@app.get(
"/items/{item_id}/name",
response_model=Item,
response_model_include={"name", "description"},
)
async def read_item_name(item_id: str):
return items[item_id]
@app.get("/items/{item_id}/public", response_model=Item, response_model_exclude={"tax"})
async def read_item_public_data(item_id: str):
return items[item_id]
from fastapi import FastAPI
from pydantic import BaseModel
app = FastAPI()
class Item(BaseModel):
name: str
description: str | None = None
price: float
tax: float = 10.5
items = {
"foo": {"name": "Foo", "price": 50.2},
"bar": {"name": "Bar", "description": "The Bar fighters", "price": 62, "tax": 20.2},
"baz": {
"name": "Baz",
"description": "There goes my baz",
"price": 50.2,
"tax": 10.5,
},
}
@app.get(
"/items/{item_id}/name",
response_model=Item,
response_model_include={"name", "description"},
)
async def read_item_name(item_id: str):
return items[item_id]
@app.get("/items/{item_id}/public", response_model=Item, response_model_exclude={"tax"})
async def read_item_public_data(item_id: str):
return items[item_id]
提示
{"name", "description"}
语法用于创建包含这两个值的 set
。
等效于 set(["name", "description"])
。
用 list
代替 set
¶
不使用 set
,而是使用 list
或 tuple
,FastAPI 可以将其转换为 set
,并仍能正常运行:
from typing import Union
from fastapi import FastAPI
from pydantic import BaseModel
app = FastAPI()
class Item(BaseModel):
name: str
description: Union[str, None] = None
price: float
tax: float = 10.5
items = {
"foo": {"name": "Foo", "price": 50.2},
"bar": {"name": "Bar", "description": "The Bar fighters", "price": 62, "tax": 20.2},
"baz": {
"name": "Baz",
"description": "There goes my baz",
"price": 50.2,
"tax": 10.5,
},
}
@app.get(
"/items/{item_id}/name",
response_model=Item,
response_model_include=["name", "description"],
)
async def read_item_name(item_id: str):
return items[item_id]
@app.get("/items/{item_id}/public", response_model=Item, response_model_exclude=["tax"])
async def read_item_public_data(item_id: str):
return items[item_id]
from fastapi import FastAPI
from pydantic import BaseModel
app = FastAPI()
class Item(BaseModel):
name: str
description: str | None = None
price: float
tax: float = 10.5
items = {
"foo": {"name": "Foo", "price": 50.2},
"bar": {"name": "Bar", "description": "The Bar fighters", "price": 62, "tax": 20.2},
"baz": {
"name": "Baz",
"description": "There goes my baz",
"price": 50.2,
"tax": 10.5,
},
}
@app.get(
"/items/{item_id}/name",
response_model=Item,
response_model_include=["name", "description"],
)
async def read_item_name(item_id: str):
return items[item_id]
@app.get("/items/{item_id}/public", response_model=Item, response_model_exclude=["tax"])
async def read_item_public_data(item_id: str):
return items[item_id]
小结¶
使用路径操作装饰器的参数 response_model
定义响应模型,可以过滤数据,特别适合用来保护隐私数据。
只返回显式设置过的值时,可以使用 response_model_exclude_unset
参数。