FastAPI中Query参数必填应设default=...而非None，因...表示必须提供、None表示可不传；配合Optional[str]类型注解，再在函数内手动处理空字符串或"null"转None。
FastAPI 中 Query 参数设为 None 却要求必填的矛盾点
直接写 Query(default=None) 会让 FastAPI 认为该参数可选，根本不会校验是否传入。这不是“默认值为 None 但必填”，而是“可不传，传了也可能是 None”——语义完全相反。
用 Ellipsis 代替 None 表示必填但无默认值
FastAPI 用 ...（即 Ellipsis）作为“显式标记必填”的信号。它和 None 语义不同：... 表示“必须提供，不允许缺省”，而 None 表示“允许不提供，缺省值为 None”。
实操建议：
- 写成
Query(default=...)，参数就变成必填，且不设具体默认值 - 如果还想在代码里体现“逻辑上接受 None 值”，需配合类型注解，比如
Optional[str] - 不要写
Query(default=None, required=True)——required参数在新版 FastAPI 中已被移除，会报错
示例：
from fastapi import FastAPI, Query
from typing import Optional
app = FastAPI()
@app.get("/items/")
def read_items(q: Optional[str] = Query(default=...)):
return {"q": q}
此时访问 /items/（不带 ?q=xxx）会返回 422 错误，提示 q 缺失；而 /items/?q= 是合法的（q 值为 ""），/items/?q=null 也不会自动转成 None，得靠你自己解析。
想让空字符串或 "null" 自动转成 None？得手动处理
FastAPI 不会把 ?q= 或 ?q=null 当作 None，它只按类型转换：字符串就是字符串，空值就是空字符串。
常见做法是封装一个自定义解析函数：
- 用
Query(default=...)保证必填 - 接收原始
str，再在函数体内判断if q == "" or q.lower() == "null": q = None - 或者用
Field+ 自定义 validator（需 Pydantic v2 的@field_validator）
注意：别依赖前端传 undefined 或 null 字面量，HTTP 查询参数全是字符串，JSON 解析那套不生效。
为什么不能用 Union[str, None] + default=None 实现“必填且可为 None”？
因为 Union[str, None] 等价于 Optional[str]，而 default=None 会让 FastAPI 放过校验——它认为“你已经给了默认值，那这个参数就不是必须的”。最终结果是：不传 ?q=xxx 也能过，q 就是 None，和你要的“必填”冲突。
真正要的是“必须传 key，value 可以是空、字符串、甚至字面量 null”，这只能靠 default=... 扛住校验，再靠业务逻辑做二次解释。
最容易被忽略的是：Query 的 default 不只是设置值，它直接决定参数是否参与校验。值为 ... 是开关，不是兜底值。
