学习目标

• 了解接口参数的常见分类
• 理解路径参数的基本用法
• 学会在路由中接收动态参数

核心概念

接口参数通常分三类：

1. 路径参数 写在 URL 路径里，例如 /users/1
2. 查询参数 写在 ? 后面，例如 /users?page=1
3. 请求体参数 放在请求 body 里，常见于 POST/PUT

这一节重点是路径参数。

路径参数的特点：

• 通常用于标识某一个资源
• 会直接参与路由匹配
• 往往是 id、slug、分类名等

代码示例

from fastapi import FastAPI

app = FastAPI()


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


@app.get("/articles/{article_id}")
def get_article(article_id: int):
    return {"article_id": article_id}

上面代码里，user_id 和 article_id 都是路径参数。

如果访问：

/users/100

那么函数里接收到的 user_id 就是 100。

类型注解的作用

def get_user(user_id: int):

这里写 int 的好处是：

• FastAPI 会自动做类型转换
• 转换失败时自动返回校验错误
• 接口文档里也会显示这个参数是整数

易错点

• 函数参数名必须和路径里的名字一致
• /users/{user_id} 和函数里的 uid 不一致时会报错
• 路径参数是路由的一部分，不能随便漏写

我的补充

路径参数最适合用来表达“唯一标识”。
如果一个值更像筛选条件，例如页码、排序、关键词，它通常更适合放到查询参数里。