导航 URL: 路径参数和查询参数

导航 URL：路径参数与查询参数

路径参数

路径参数是 URL 路径的可变部分。它们用于识别特定资源，例如用户 ID 或项目 ID。在 FastAPI 中，您可以使用 Python 格式字符串语法 {} 来定义它们。

from fastapi import FastAPI

app = FastAPI()

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

如果您访问 http://127.0.0.1:8000/items/foo，应用程序将捕获 foo 并将其作为参数 item_id 传递给 read_item 函数。

类型声明与自动转换

您可以使用标准 Python 类型提示（type hints）来声明路径参数的类型。这使得 FastAPI 能够自动验证和转换数据。

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

通过添加 : int，FastAPI 为您提供了以下几个特性：

• 数据转换：如果您访问 /items/5，FastAPI 会将字符串 “5” 转换为整数 5。
• 数据验证：如果您访问 /items/foo，FastAPI 将返回一个可读的错误，因为 “foo” 不是一个有效的整数。
• 文档：API 文档将正确显示 item_id 必须是整数。

查询参数

查询参数是出现在 URL 中 ? 之后，由 & 分隔的键值对。当您声明的函数参数不是路径参数的一部分时，FastAPI 会将其解释为查询参数。

@app.get("/items/")
def read_items(skip: int = 0, limit: int = 10):
    return {"skip": skip, "limit": limit}

对于 URL http://127.0.0.1:8000/items/?skip=0&limit=10，函数将接收 0 和 10。

默认值与可选参数

在上面的例子中，skip 的默认值为 0，limit 的默认值为 10。这意味着如果客户端在 URL 中没有发送它们，FastAPI 会自动使用这些值。

要使参数真正可选（即它可以是 None），您可以使用 Python 的 Optional 或现代的 | 语法（Python 3.10+）：

from typing import Union

@app.get("/items/{item_id}")
def read_item(item_id: str, q: Union[str, None] = None):
    # q 是可选的，默认为 None
    if q:
        return {"item_id": item_id, "q": q}
    return {"item_id": item_id}

在这种情况下，q 是一个查询参数，因为它不在路径中。由于它具有 = None，因此不是必需的。