04. FastAPI 查询参数(最基础版本 不要类型验证)

查询参数是 URL 后面的条件

/products?keyword=键盘&sort=price 中，? 后是查询字符串，多个键值用 & 连接。路径决定去哪一个窗口，查询参数说明筛选或展示要求。

本篇不写类型注解、不使用 Query，不做类型和数值范围验证。

from fastapi import FastAPI

app = FastAPI()

@app.get("/products")
def products(keyword=None, sort="default"):
    return {"keyword": keyword, "sort": sort}

@app.get("/search")
def search(q):
    return {"q": q}

@app.get("/users/{username}/articles")
def user_articles(username, category=None):
    return {"username": username, "category": category}

保存为 main.py，执行 uv run uvicorn main:app --reload。/products 返回 keyword=null、sort="default"；/products?keyword=鼠标&sort=price 返回传入的文本。/users/alice/articles?category=python 同时使用路径和查询参数。

默认值和“必须提供”

有默认值的 keyword=None 可以不传；没有默认值的 q 必须提供。/search 会得到缺少参数的 422 响应，这属于框架对参数是否存在的检查，本篇没有增加参数类型验证。

?keyword= 是传入空字符串，和完全不传产生的 None 不同。?enabled=false 在不声明类型时得到文本 "false"，不能直接用 if enabled 判断真假，因为非空字符串在 Python 中为真。

客户端如何正确拼接

关键词含空格、&、中文时，应由客户端编码参数，不要用字符串随意相加。在 PowerShell 中测试：

curl.exe -G "http://127.0.0.1:8000/products" --data-urlencode "keyword=键盘 & 鼠标"

同名键重复出现时，普通单值参数不适合表达多个筛选值；需要列表时，第 07 篇会用 Query 明确声明。未声明的其他查询键通常不会自动导致失败，因此有拼写错误时要检查实际函数参数。

常见混淆

• ?page=2 在本篇仍是字符串，不能直接用作列表切片下标。
• 查询参数不等于 JSON 请求体；GET 搜索条件通常放查询串。
• 参数名默认区分大小写；keyword 与 Keyword 不要混用。
• 查询串可能进入浏览器历史和代理日志，不适合装令牌。

练习：增加 /books?author=...&category=...，让两个条件都可以省略；观察“不传”“空值”“中文”三种情况。