路由与 HTTP 方法

路由是“方法 + 路径 + 处理函数”

同一个路径可以对应不同操作。例如：

方法和路径	常见含义
GET /todos	读取任务列表
POST /todos	创建任务
GET /todos/3	读取 3 号任务
PUT /todos/3	按接口约定完整替换 3 号任务
PATCH /todos/3	修改 3 号任务的部分字段
DELETE /todos/3	删除 3 号任务

HTTP 方法表达约定的语义。FastAPI 不会因为你写了 DELETE 就自动删除数据库记录，实际工作仍由函数完成。官方路径操作说明

完整示例：同一路径对应不同方法

from fastapi import FastAPI

app = FastAPI()


@app.get("/books")
def list_books():
    return [{"id": 1, "title": "Python 基础"}]


@app.post("/books", status_code=201)
def create_book():
    return {"id": 2, "title": "FastAPI 入门"}

这个示例只是演示路由，POST 没有实际保存数据。浏览器地址栏通常只能方便地发 GET；测试 POST 时请用 /docs。

固定路径放在动态路径前

以下是追加到本章 main.py 的示例：

@app.get("/users/me")
def current_user():
    return {"name": "当前用户"}


@app.get("/users/{user_id}")
def read_user(user_id: int):
    return {"user_id": user_id}

路由按登记顺序匹配。先登记 /users/{user_id} 时，/users/me 可能进入动态路由，再因 me 不是整数而校验失败。更具体的固定路径应先登记。官方路由顺序说明

路径命名习惯

优先使用表达资源的名词，例如 /books、/users；用方法表示操作。项目内部保持一致：是否使用复数、是否带结尾 /、是否有 /api/v1 前缀。

FastAPI 默认常会把缺少或多出的结尾斜杠重定向到已登记的路径。不要依赖客户端碰巧支持重定向来弥补接口命名混乱。

幂等先建立直觉

幂等可以理解为：相同操作重复执行，预期的最终资源状态相同。例如删除同一个任务两次，最终都应该是任务已删除。

它不要求每次响应都完全相同：第一次删除可返回 204，第二次可能返回 404。创建操作通常可能产生重复资源，实际业务中可以引入幂等键。

本章练习

为图书系统设计列表、详情、创建、修改、删除五类接口。

过关标准：能根据业务选择 HTTP 方法，能解释 PUT 与 PATCH 的常见区别。