FastAPI 入门（二）：定义你的第一个路由

在上一节中，我们已经完成了 FastAPI 的安装，并写了一个最简单的示例。这一篇我们来系统地看看：如何在 FastAPI 中定义路由。

一、什么是“路由”？

简单理解：路由就是 URL 与后端函数之间的映射关系。

当请求 GET / 时，执行哪个函数？
当请求 GET /items/1 时，如何拿到 1 并作为参数传给函数？

在 FastAPI 中，这些都通过装饰器（如 @app.get(...)、@app.post(...)）来完成。

二、最基础的 GET 路由

我们从一个最简单的例子开始（仍然在 main.py 中）：

from fastapi import FastAPI

app = FastAPI()


@app.get("/")
def read_root():
    return {"message": "Hello FastAPI"}

说明：

@app.get("/") 表示：当客户端以 GET 方法 访问 / 时，调用下面的 read_root 函数
函数返回的字典会自动被转成 JSON 返回给客户端

你可以再增加一个新的路由，例如 /hello：

1
2
3

@app.get("/hello")
def say_hello():
    return {"message": "Hello, this is /hello"}

此时访问：

http://127.0.0.1:8000/ 返回 {"message": "Hello FastAPI"}
http://127.0.0.1:8000/hello 返回 {"message": "Hello, this is /hello"}

三、路径参数（Path Parameters）

当你希望 URL 中的一部分是变量时，就需要用到路径参数，例如：

/users/1
/users/2

可以这样定义路由：

1
2
3

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

说明：

路径中的 {user_id} 是一个占位符
函数参数 user_id: int 会自动从 URL 中解析出来并转换为 int
访问 GET /users/10 会返回：

1	{"user_id": 10}

再看一个稍微复杂一点的例子：

@app.get("/items/{item_id}")
def read_item(item_id: str, q: str | None = None):
    if q:
        return {"item_id": item_id, "q": q}
    return {"item_id": item_id}

这里把路径参数和查询参数结合在一起使用，下面会详细讲查询参数。

四、查询参数（Query Parameters）

查询参数就是 URL 中 ? 后面那一串，例如：

/search?keyword=fastapi&page=1

在 FastAPI 中，只要在函数里增加普通的参数（并且不出现在路径里），就会被当作查询参数：

@app.get("/search")
def search(keyword: str, page: int = 1, size: int = 10):
    return {
        "keyword": keyword,
        "page": page,
        "size": size,
    }

访问示例：

GET /search?keyword=fastapi
返回：

1	{"keyword": "fastapi", "page": 1, "size": 10}

GET /search?keyword=python&page=2&size=5
返回：

1	{"keyword": "python", "page": 2, "size": 5}

可以看到：

未提供的参数会使用默认值（如 page=1、size=10）
必填参数（例如上面例子中的 keyword）如果不传，FastAPI 会返回 422 错误并提示缺少参数

五、不同 HTTP 方法：GET / POST / PUT / DELETE

FastAPI 支持常见的 HTTP 方法，只需要换装饰器即可：

@app.post("/items")
def create_item():
    return {"message": "create item"}


@app.put("/items/{item_id}")
def update_item(item_id: int):
    return {"message": f"update item {item_id}"}


@app.delete("/items/{item_id}")
def delete_item(item_id: int):
    return {"message": f"delete item {item_id}"}

这样，一个简单的“增删改查”接口骨架就有了。
在后续文章中，我们可以再引入请求体（Body）、数据模型（Pydantic）等概念，让这些路由真正操作数据。

六、通过自动文档查看路由

FastAPI 的一个很大优势，就是自动生成接口文档。

启动项目后（例如使用命令）：

1	uvicorn main:app --reload

打开：

你可以看到所有已经定义的路由、方法、路径参数、查询参数等信息，并且可以直接在浏览器里调试请求，非常适合开发和学习。

本篇主要介绍了 FastAPI 中最基础的路由定义方式：

最简单的 GET 路由
路径参数
查询参数
不同 HTTP 方法的用法

掌握这些内容之后，你已经可以写出一个小型 API 服务了。接下来可以继续学习如何接收和校验请求体、使用 Pydantic 定义数据模型，以及如何组织更复杂的项目结构等内容。