fastapi 参数

fastapi 参数
FastAPI 参数
FastAPI 是一个现代的 Web 框架，它使用了许多Python 最新的语言特性和技术，因此也推荐在 Python 3.7+ 环境下使用。

FastAPI 可以轻松地创建高性能、易于维护的 Web API，使 Web 开发更加快速和高效。

在 FastAPI 中，常常需要获取客户端传来的参数，以此来决定 API 函数的行为。

FastAPI 提供了多种获取这些参数的方式，本文将一一介绍。

路径参数
路径参数，即 URL 中包含的参数，可以通过在路径中使用花括号 {} 来定义。

例如，下面的路径包含了一个名为 item_id 的路径参数：
``` @app.get("/items/{item_id}") async def read_item(item_id: int): return {"item_id": item_id} ```
当客户端请求路径 /items/25 时，FastAPI 会自动将25 转换成 int 类型，并将其赋值给 item_id。

路径参数支持多种类型，例如：
- str: 字符串，路径参数默认的数据类型。

- int, float, Decimal: 数值类型。

- bool: 布尔类型，可以接
收 True、true、False、false、1、0。

- UUID: UUID 类型，例如：`UUID("6b9a6e67-a2f2-4aad-b2cc-
8a67b08d0a55")`。

- Path: 路径类型，用于接收一个路
径字符串。

在路径参数后使用 `Path()` 可以将它们合并
到一起。

- enum.Enum: 枚举类型。

注意，路径参数必须出现在路径中，而不能出现在查
询参数中。

路径参数是必需的，例如：
``` @app.get("/items/{item_id}") async def
read_item(item_id: int): return {"item_id":
item_id} ```
而下面这个会报错：
``` @app.get("/items") async def
read_items(item_id: int): return {"item_id":
item_id} ```
查询参数
查询参数，即 URL 中通过 ? 拼接的参数，可以通过
使用 FastAPI 内置的 `Query` 类来进行定义。

例如，下
列代码定义了一个名为 q 的查询参数：
``` @app.get("/items/") async def read_items(q: str = None): if q: return {"items": q} return {"items": "all"} ```
上面的代码中，q 的默认值为 None，当接收到 q 的值时，会返回匹配到的结果；当 q 的值为 None 时，返回所有的 items。

`Query` 类接受多个参数：
- `default`: 参数的默认值，如果不传的话，它将是`None`。

- `title`: 参数的标题，用于将参数名美化。

如果未传，则标题将是参数名本身。

- `description`: 参数的文本描述。

- `min_length`: 参数的最小长度。

- `max_length`: 参数的最大长度。

- `ge`: 参数的最小值（greater than or equal）。

- `le`: 参数的最大值（less than or equal）。

- `gt`: 参数的最小值（greater than）。

- `lt`: 参数的最大值（less than）。

- `regex`: 参数应匹配的正则表达式。

-
`alias`: 参数名的别名。

如果设置了别名，那么 FastAPI 将使用别名作为参数名。

请求体
有时候我们需要通过请求体发送数据，例如 JSON 数据或者表单数据。

这些数据可以通过 FastAPI 内置的
`Body` 类获取。

默认情况下，FastAPI 支持使用 JSON 输入和输出，数据格式通过 Python 的 `dict` 结构来呈现。

因此，当
POST或PUT请求到达时，FastAPI 将自动解析数据并将其返回到函数中。

例如，下面的代码定义了一个名为 `create_item` 的POST 请求，它通过请求体传递一个 JSON：
``` from typing import Optional from pydantic import BaseModel
class Item(BaseModel): name: str price: float is_offer: Optional[bool] = None
@app.post("/items/") async def
create_item(item: Item): item_dict =
item.dict() if item.is_offer:
item_dict.update({"item_id": 1}) return
item_dict ```
上面代码中的 `Item` 类用于定义请求体的结构，
`name` 和 `price` 是必需的，`is_offer` 可选。

如果
`is_offer` 的值为 True，则将添加一个 `item_id` 到返回的 JSON 中。

请求体的结构还可以嵌套，例如：
``` class Item(BaseModel): name: str price: float
class User(BaseModel): name: str age: int
class Order(BaseModel): item: Item
user: User
@app.post("/orders/") async def
create_order(order: Order): return order ```这个 `create_order` 中需要的请求体数据是这样
的：
``` { "item": { "name": "foo", "price": 10.5 }, "user": { "name": "bar", "age": 20 } } ```
请求体也支持多种数据类型：
- `str`: 原始字符串。

- `bytes`: 原始字节。

-
`bytearray`: 可编辑字节。

- `FormData`: 用于处理带
有多部分编码/表单数据的请求体。

- `File`: 用于表示
文件与数据。

- `JSON`: 用于解析 JSON，使用完整的校
验和转换。

- `Any`: 用于禁用请求体解析和直接从请求
中获取原始数据。

请求头
一些数据无法放在 URL 或请求体中，需要放在请求头中，例如认证令牌。

FastAPI 使用 `Header` 类获取请求
头，如下例所示：
``` @app.get("/items/") async def
read_items( *, user_agent: Optional[str] =
Header(None)): return {"User-Agent":
user_agent} ```
上面的代码中，`Header` 函数用于获取请求头，其参数包括：
- `default`: 请求头的默认值，如果不传的话，它将是 `None`。

- `title`: 请求头的标题。

- `alias`: 请求头字符串的别名。

- `description`: 请求头的文本描述。

- `min_length`: 请求头的最小长度。

-
`max_length`: 请求头的最大长度。

依赖注入
依赖注入是 FastAPI 的一个强大特性，可以将常见的数据和方法注入到 API 中。

如果您不了解依赖注入，请查看 Python 的 `Depdency Injection` 库。

FastAPI 中使用 `Depends` 函数实现依赖注入。

其中，`Depends` 函数通常在参数列表的标准参数之后出
现，例如：
``` async def read_user_agent(user_agent: str = Header(None)): return {"User-Agent":
user_agent}
async def read_item( query: Optional[str] = None, user_agent: str =
Depends(read_user_agent)): return {"User-Agent": user_agent, "q": query} ```
上述代码中，`read_item` 的参数列表包括了一个被`Dependency Injection` 接管的参数 `user_agent`，这个参数使用了 `read_user_agent` 函数进行初始化。

这种方式允许您将一些 `setup` 代码或 `teardown` 代码渐近式地注入到 API 代码中，因此您可以快速修改程序的行为。

FastAPI 中使用 `Depends` 和普通参数一样，甚至支持嵌套注入。

在一个 Python HTTP 框架中实现这样的功能很困难，但在 FastAPI 中，这个操作就像如此简单。

总结
本文介绍了 FastAPI 中获取客户端参数的四种方法：路径参数、查询参数、请求体和请求头。

同时，介绍了FastAPI 湾关键功能之一：依赖注入。

FastAPI 可以轻松地创建出非常高效的 WebAPI 服务，适用于各种复杂场景，我们希望您喜欢这个框架，并使用它开发出优秀的WebApp。