03. FastAPI 路径参数(最基础版本 不要类型验证)

路径参数就是 URL 里的“空位”

/users/alice 与 /users/bob 可以共用一个接口，写成 /users/{username}。大括号部分表示变量。路径参数通常标识“操作哪个资源”，如用户、文章或订单。

本篇刻意不写参数类型、不使用 Path，只学习如何取值。

from fastapi import FastAPI

app = FastAPI()

@app.get("/users/me")
def myself():
    return {"username": "当前用户示例"}

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

@app.get("/shops/{shop_id}/products/{product_id}")
def read_product(shop_id, product_id):
    return {"shop_id": shop_id, "product_id": product_id}

保存为 main.py，执行 uv run uvicorn main:app --reload。访问 /users/alice 返回 {"username":"alice"}；访问 /shops/10/products/20，两个值都是字符串，即 "10" 和 "20"。

为什么不自动变成数字

URL 本质是文本。这里没有声明 int，所以不会自动获得“必须是整数”的限制。/shops/abc/products/xyz 也会进入函数。本阶段不做数字运算，类型转换留到第 06 篇。

路径模板中的名字应与函数参数名一致。把 {username} 写成 {name}，却保留 username 参数，会改变参数识别，导致意外的缺参错误。

路由顺序与边界

静态路径 /users/me 应放在 /users/{username} 前面，否则 me 可能先被当成普通用户名。路由按注册顺序匹配，并不是按“看起来更具体”自动排序。

路径中的必需片段不能省略：/users/ 不是 /users/{username} 的一个完整实例。尾部斜线还可能触发自动重定向，调用接口时最好统一风格。

普通路径参数不跨越 /。文件路径之类的特殊需求可以使用 {file_path:path} 路由转换器，但直接把外部路径拼到磁盘位置会引入越界访问问题，应另做受控映射。

如何选择路径与查询

GET /products/100 表示读取 100 号商品；GET /products?keyword=键盘 表示在商品集合中搜索。前者定位资源，后者附加筛选条件。URL 中不要放密码、密钥或其他需要保密的内容。

练习：创建 /cities/{city}/weather，原样返回城市名；再创建 /cities/hot 返回热门城市，观察不同注册顺序的结果。