Python Academy · 课时

路径参数、查询参数与请求体

Q: 「路径参数、查询参数与请求体」这节课中我会学到什么？

使用 Pydantic 定义带类型的参数和请求体模式。 你通过在浏览器中直接运行的动手代码来练习 Python Academy，全天候 AI 导师会在你学习这节课的过程中回答你的问题。

使用 Pydantic 定义带类型的参数和请求体模式。

路径参数、查询参数与请求体 是 CoddyKit 上的免费 Python Academy 课时。这是第 2 节课，共 4 节。你可以在下方免费阅读本课时的完整内容 — 然后在浏览器中使用内置代码编辑器和全天候 AI 导师进行实践。这是 Python Academy 学习路径的一部分，你的进度在网页和 CoddyKit 应用中同步。 Python Academy 课程共包含 4 节课。

路径参数验证

使用 Path() 为路径参数添加验证器，并设置 ge、le、gt 和 lt 约束。

from fastapi import FastAPI, Path
app = FastAPI()

@app.get("/items/{item_id}")
def get_item(item_id: int = Path(ge=1, le=1000)):
    return {"item_id": item_id}

# GET /items/0  → 422 (must be >= 1)

查询参数验证

使用 Query() 为查询参数添加验证、默认值、别名和描述。

from fastapi import FastAPI, Query
app = FastAPI()

@app.get("/search")
def search(
    q: str = Query(min_length=2, max_length=50),
    page: int = Query(default=1, ge=1),
):
    return {"q": q, "page": page}

可选查询参数

使用 | None = None（Python 3.10 及更高版本）或 Optional[str] = None，将查询参数设为可选。

from fastapi import FastAPI
app = FastAPI()

@app.get("/users")
def list_users(
    dept: str | None = None,
    active: bool = True
):
    return {"dept": dept, "active": active}

# GET /users → dept=None, active=True
# GET /users?dept=HR&active=false

一个查询参数接受多个值

使用 list[str] 和 Query()，让单个查询参数接受值列表。

from fastapi import FastAPI, Query
from typing import Annotated
app = FastAPI()

@app.get("/filter")
def filter_items(tags: Annotated[list[str], Query()] = []):
    return {"tags": tags}

# GET /filter?tags=python&tags=web

嵌套请求体

Pydantic 模型可以嵌套。FastAPI 会自动处理嵌套 JSON。

from fastapi import FastAPI
from pydantic import BaseModel
app = FastAPI()

class Address(BaseModel):
    street: str
    city: str

class User(BaseModel):
    name: str
    address: Address

@app.post("/users")
def create_user(user: User):
    return user.model_dump()

Pydantic 中的字段约束

在模型中使用 Field()，为各个字段添加约束、默认值和描述。

from pydantic import BaseModel, Field

class Product(BaseModel):
    name: str = Field(min_length=1, max_length=100)
    price: float = Field(gt=0)
    quantity: int = Field(ge=0, default=0, description="Items in stock")

请求体、路径参数和查询参数一起使用

可以在一个端点中混合使用这三种参数类型。FastAPI 会根据位置区分它们：路径参数位于 URL 中，简单类型作为查询参数，模型作为请求体。

from fastapi import FastAPI
from pydantic import BaseModel
app = FastAPI()

class ItemUpdate(BaseModel):
    name: str
    price: float

@app.put("/shops/{shop_id}/items/{item_id}")
def update_item(
    shop_id: int,
    item_id: int,
    item: ItemUpdate,
    notify: bool = False,
):
    return {"shop": shop_id, "item": item_id,
            "data": item.model_dump(), "notify": notify}

文件上传

使用 UploadFile 和 File() 接受文件上传。使用 await file.read() 访问内容。

from fastapi import FastAPI, UploadFile, File
app = FastAPI()

@app.post("/upload")
async def upload(file: UploadFile = File(...)):
    content = await file.read()
    return {"filename": file.filename, "size": len(content)}

表单数据

使用 Form() 接受 HTML 表单数据（application/x-www-form-urlencoded 或 multipart/form-data）。

# pip install python-multipart
from fastapi import FastAPI, Form
app = FastAPI()

@app.post("/login")
def login(username: str = Form(...), password: str = Form(...)):
    return {"username": username}

请求验证总结

FastAPI 会自动验证所有参数类型。无效输入会在处理函数调用之前返回带有详细信息的 HTTP 422 错误。

# Auto-validated:
# - Path params: type coercion, Path() constraints
# - Query params: Query() constraints, type coercion
# - Request body: Pydantic model validation
# - All errors → HTTP 422 Unprocessable Entity
# - No manual validation needed

别名与弃用

在 Query() 或 Field() 中使用 alias=，即可接受请求中的其他名称；使用 deprecated=True 标记旧参数。

from fastapi import FastAPI, Query
app = FastAPI()

@app.get("/items")
def get_items(
    q: str | None = Query(default=None, alias="search-query"),
    old: str | None = Query(default=None, deprecated=True),
):
    return {"q": q, "old": old}

# GET /items?search-query=python

快速检查

FastAPI 如何区分路径参数、查询参数和请求体？

回顾

使用 Path()/Query() 设置参数约束。嵌套 Pydantic 模型以表示复杂请求体。可以自由组合路径参数、查询参数和请求体参数。UploadFile 处理文件，Form() 处理 HTML 表单。FastAPI 会在处理函数运行前验证所有内容。

常见问题解答

「路径参数、查询参数与请求体」课时是免费的吗？

是的 — 「路径参数、查询参数与请求体」的完整文本可在网页上免费阅读。要进行交互式练习（内置代码编辑器和全天候 AI 导师）并解锁 Python Academy 课程的其余内容，请升级到 CoddyKit PRO。 Python Academy 课程共包含 4 节课。

「路径参数、查询参数与请求体」这节课中我会学到什么？

使用 Pydantic 定义带类型的参数和请求体模式。你通过在浏览器中直接运行的动手代码来练习 Python Academy，全天候 AI 导师会在你学习这节课的过程中回答你的问题。

学习 Python Academy 需要有经验吗？

无需任何先前经验。CoddyKit 上的 Python Academy 课程适合初学者到高级学习者，你可以从这里开始或从头开始，按照自己的节奏学习。这是第 2 节课，共 4 节。

「路径参数、查询参数与请求体」课时需要多长时间？

大多数 CoddyKit 课程大约需要 5–10 分钟。每节课都很精短且互动，所以你能稳步进步，并在网页和应用中从离开的地方继续。

我能在这节 Python Academy 课中编写并运行代码吗？

能。每节 Python Academy 课都包含内置代码编辑器，你可以在浏览器中直接编写并运行真实代码，并获得即时 AI 反馈 — 无需本地设置。

此课程中的所有课时

← 返回 Python Academy