您如何向参数添加验证约束？

Question

您如何向参数添加验证约束？

Accepted Answer

除了类型检查，FastAPI 允许您使用 `Query`、`Path` 和 `Field` 向 path/query 参数和模型字段添加**约束**——强制执行长度、范围和模式等规则，违反时自动生成 422 错误和文档。 ## Query 和 Path 约束 ```python from fastapi import Query, Path @app.get("/items") def search( q: str = Query(min_length=3, max_length=50), # string length bounds page: int = Query(default=1, ge=1), # >= 1 limit: int = Query(default=10, ge=1, le=100), # 1 <= limit <= 100 code: str = Query(pattern=r"^[A-Z]{3}$"), # regex pattern ): ... @app.get("/items/{item_id}") def get(item_id: int = Path(ge=1)): # path param must be >= 1 ... ``` `Query()` 和 `Path()` 向 query 和 path 参数添加约束。常见的有：`min_length`/`max_length`（字符串）、`ge`/`gt`/`le`/`lt`（数字）、`pattern`（正则表达式）。违反约束会自动产生清晰的 422 错误。 ## Pydantic 模型上的 Field 约束 ```python from pydantic import BaseModel, Field, EmailStr class User(BaseModel): name: str = Field(min_length=1, max_length=100) age: int = Field(ge=0, le=120) email: EmailStr # format validation via a type bio: str = Field(default="", max_length=500, description="User bio") ``` 相同的约束通过 `Field()` 适用于模型字段，验证请求体。特殊类型（`EmailStr`、`HttpUrl`、`UUID`）验证格式。 ## 约束也丰富了文档 ```python q: str = Query(min_length=3, description="Search query", example="phone") # the constraints + description + example appear in the auto-generated API docs ``` 您声明的每个约束也反映在 OpenAPI 文档中，因此使用者可以看到规则。 ## 为什么这很重要添加验证约束对于**安全性/健壮性**和良好的 API 设计都很重要——声明规则（长度限制、数值范围、正则表达式模式、格式类型）确保格式错误或恶意的输入在到达您的逻辑之前就被拒绝并显示清晰错误，这是必要的，因为您不能信任原始输入。 FastAPI 使这一切变得声明式和轻松：`Query`/`Path`/`Field` 约束自动验证（产生结构化的 422 错误）并同时记录在 API 文档中，因此规则从单个声明中得到执行和传达。了解常见约束和专门的验证类型是构建安全、良好定义的端点的日常知识——这就是如何超越基本类型检查来强制执行数据必须满足的实际业务规则。