路径和查询参数是如何工作的？

Question

路径和查询参数是如何工作的？

Accepted Answer

FastAPI 从函数参数中提取 **path parameters**（URL 路径的一部分）和 **query parameters**（`?` 之后）,使用类型提示自动进行转换和验证。

## URL 中的路径参数

```python
@app.get("/items/{item_id}")        # {item_id} in the path
def get_item(item_id: int):          # matched by NAME; `int` converts & validates
    return {"item_id": item_id}
# GET /items/5 → item_id = 5 (int).  GET /items/abc → 422 error (not an int)
```

函数参数的名称与路径中的 `{placeholder}` 相匹配时,该参数就成为 **path parameter**。类型提示（`int`）会自动转换来自 URL 的字符串,如果不匹配则返回清晰的 422 错误。

## 查询参数——其他一切

```python
@app.get("/items")
def list_items(skip: int = 0, limit: int = 10, q: str | None = None):
    # parameters NOT in the path become QUERY parameters
    # GET /items?skip=20&limit=5&q=phone → skip=20, limit=5, q="phone"
    return {"skip": skip, "limit": limit, "q": q}
```

**不**在路径中的函数参数变成 **query parameters**。默认值使它们是可选的（`skip: int = 0`）；`str | None = None` 使可空的可选查询参数。没有默认值时,它们是必需的。

## 必需 vs 可选

```python
def search(q: str):              # REQUIRED query param (no default) → ?q=... must be present
def search(q: str = ""):          # optional, defaults to ""
def search(q: str | None = None): # optional, defaults to None
```

## 结合两者

```python
@app.get("/users/{user_id}/items")
def user_items(user_id: int, limit: int = 10):
    # user_id = path param, limit = query param — distinguished by the path
```

## 为什么这很重要

路径和查询参数是端点从 URL 接收输入的方式——对几乎每个 API 路由都是基础性的（按 id 获取资源、过滤、分页、搜索）。

FastAPI 的方法很优雅,也是它生产力高的关键原因：仅通过声明有类型的函数参数就能获得自动提取、**类型转换**、**验证**（对错误输入有清晰的 422 错误）和必需 vs 可选语义（通过默认值）——全部源自标准 Python 类型提示,无需手动解析。

理解这种区别（路径参数来自 `{placeholders}`,其他一切都是查询参数）以及默认值如何控制可选性,对于构建 FastAPI 端点来说是日常必备知识。