fastapi 如何让 Query 参数支持默认值 None 但必填

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 不只是设置值，它直接决定参数是否参与校验。值为 ... 是开关，不是兜底值。

# 的是  # 你要  # 会让  # 自定义  # app  # default  # http  # js  # json  # 值为  # if  # 字符串  # 为什么  # red  # NULL  # 前端  # 封装  # 空字符串  # 类型转换  # 默认值  # undefined  # 转成  # union  # fastapi  # 必填  # 不传 

相关栏目： <？ｍｕｍａ $count = M('archives')->where(['typeid'=>$field['id']])->count(); ?> 【 AI推广<？ｍｕｍａ echo $count; ?> 】 <？ｍｕｍａ $count = M('archives')->where(['typeid'=>$field['id']])->count(); ?> 【 SEO优化<？ｍｕｍａ echo $count; ?> 】 <？ｍｕｍａ $count = M('archives')->where(['typeid'=>$field['id']])->count(); ?> 【 技术百科<？ｍｕｍａ echo $count; ?> 】 <？ｍｕｍａ $count = M('archives')->where(['typeid'=>$field['id']])->count(); ?> 【 谷歌推广<？ｍｕｍａ echo $count; ?> 】 <？ｍｕｍａ $count = M('archives')->where(['typeid'=>$field['id']])->count(); ?> 【 百度推广<？ｍｕｍａ echo $count; ?> 】 <？ｍｕｍａ $count = M('archives')->where(['typeid'=>$field['id']])->count(); ?> 【 网络营销<？ｍｕｍａ echo $count; ?> 】 <？ｍｕｍａ $count = M('archives')->where(['typeid'=>$field['id']])->count(); ?> 【 案例网站<？ｍｕｍａ echo $count; ?> 】 <？ｍｕｍａ $count = M('archives')->where(['typeid'=>$field['id']])->count(); ?> 【 精选文章<？ｍｕｍａ echo $count; ?> 】