你如何定义路由（路径操作）？

Question

你如何定义路由（路径操作）？

Accepted Answer

在FastAPI中，**路径操作**是一个路由——一个用HTTP方法装饰器（`@app.get`、`@app.post`等）装饰的函数，用于处理对某个路径的请求。该函数的返回值会自动序列化为JSON。

## 为每个HTTP方法定义路由

```python
from fastapi import FastAPI
app = FastAPI()

@app.get("/items")                # GET /items
def list_items():
    return [{"id": 1}, {"id": 2}]  # dict/list → automatically JSON-serialized

@app.get("/items/{item_id}")      # GET /items/5 — path parameter
def get_item(item_id: int):        # type hint converts "5" → int (and validates)
    return {"id": item_id}

@app.post("/items")               # POST /items
def create_item(item: Item):
    return item

@app.put("/items/{item_id}")      # PUT, PATCH, DELETE work the same way
@app.delete("/items/{item_id}")
def delete_item(item_id: int):
    return {"deleted": item_id}
```

每个装饰器将一个HTTP方法+路径映射到一个处理程序。函数名由你决定；装饰器定义路由。返回的字典/列表/Pydantic模型会自动序列化为JSON——无需手动调用`json.dumps`。

## 重叠路径的顺序很重要

```python
@app.get("/users/me")            # ✅ specific route FIRST
def read_me(): ...
@app.get("/users/{user_id}")     # dynamic AFTER — else "me" matches {user_id}
def read_user(user_id: int): ...
```

FastAPI按声明顺序匹配路由，因此将静态路径放在动态路径之前。

## 操作元数据（驱动文档生成）

```python
@app.get("/items", tags=["items"], summary="List items", status_code=200)
def list_items(): ...
```

装饰器参数（`tags`、`summary`、`status_code`、`response_model`）配置行为并丰富自动生成的文档。

## 为什么这很重要

路径操作是每个FastAPI应用程序的基础——它们定义你的API端点和处理请求的方式。

理解每个HTTP方法对应一个装饰器的模式、返回值自动序列化为JSON（无需样板代码）、参数上的类型提示驱动转换和验证、以及重叠路径的路由顺序很重要，这些都是构建任何端点的日常必需知识。

装饰器元数据还会feed到FastAPI的自动文档中，将路由直接关联到文档。

这是在FastAPI中首先要掌握和最基础的内容。