18 FastAPI路径参数与查询参数的类型定义与验证

在上一篇文章中，我们探讨了如何使用 FastAPI 创建查询参数，并通过实际示例来演示它们的用法。接下来，我们将深入了解如何定义路径参数和查询参数的参数类型，以及如何对这些参数进行验证。这一部分将为后续的数据验证与序列化的内容打下基础。

一、路径参数的定义与验证

路径参数是 URL 中的一部分，通常用于识别特定的资源。在 FastAPI 中，你可以在路由函数的参数中直接定义路径参数，FastAPI 会自动将 URL 路径中的相应部分解析为参数，并进行类型验证。

1.1 定义路径参数

以下是一个使用路径参数的基本示例：

from fastapi import FastAPI

app = FastAPI()

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

在上面的代码中，我们定义了一个名为 item_id 的路径参数。通过将其类型声明为 int，FastAPI 会自动验证传入的 item_id 是否为整数类型。如果请求的路径中 item_id 不是整数，FastAPI 将返回一个 422 Unprocessable Entity 错误。

1.2 类型验证

FastAPI 会根据参数的类型自动进行验证，例如：

• 如果你访问 /items/42，结果将是 {"item_id": 42}；
• 如果你访问 /items/foo，则会返回一个错误，类似于：

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

我们可以定义其他类型的路径参数，例如 str、float 等，也可以结合使用这些类型。

1.3 正则表达式参数

FastAPI 还支持路径参数的正则表达式。你可以使用 Path 来定义更复杂的路径参数。以下是一个示例，该示例限制了 item_name 参数只能包含字母和数字：

from fastapi import FastAPI, Path

app = FastAPI()

@app.get("/items/{item_name}")
async def read_item(item_name: str = Path(..., regex="^[a-zA-Z0-9]+$")):
    return {"item_name": item_name}

在这个示例中，如果请求的路径名包含其他字符，例如 /items/item-1，将会返回 422 错误。

二、查询参数的定义与验证

查询参数则是路径后附加的参数，通常用于过滤、排序等功能。FastAPI 也支持对查询参数进行类型定义和验证。

2.1 定义查询参数

以下是一个使用查询参数的基本示例：

from fastapi import FastAPI
from typing import Optional

app = FastAPI()

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

在这个示例中，skip 和 limit 是查询参数，分别表示跳过的条数和返回的条数。它们都有默认值，如果不提供，它们将分别默认为 0 和 10。

2.2 使用 Optional 类型

你还可以使用 Optional 来标记一个查询参数为可选。例如：

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

如果请求路径中没有携带 skip 或 limit 参数，FastAPI 会自动将它们设为 None。

2.3 合并路径参数与查询参数

接下来，我们可以将路径参数与查询参数结合使用。例如：

@app.get("/items/{item_id}")
async def read_item(item_id: int, q: Optional[str] = None):
    return {"item_id": item_id, "query": q}

在这个示例中，我们定义了一个路径参数 item_id 和一个可选的查询参数 q。请求路径 /items/5?q=example 将返回 {"item_id": 5, "query": "example"}。

三、总结

在本篇文章中，我们详细介绍了如何使用 FastAPI 定义和验证路径参数与查询参数。通过给路径参数和查询参数指定类型，FastAPI 能够进行自动验证，为 API 的使用提供了安全保障。接下来的文章，我们将进一步探讨如何使用 Pydantic 数据模型进行数据的验证与序列化，这将使我们的API更加健壮和易于使用。

通过这些基本的参数定义和验证机制，FastAPI 极大地提升了机构化和规范化 API 的能力，使得开发者能够专注于业务逻辑的实现而不是参数的处理。