FastAPIQuery参数必填设置技巧

积累知识，胜过积蓄金银！毕竟在文章开发的过程中，会遇到各种各样的问题，往往都是一些细节知识点还没有掌握好而导致的，因此基础知识点的积累是很重要的。下面本文《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 不只是设置值，它直接决定参数是否参与校验。值为 ... 是开关，不是兜底值。

终于介绍完啦！小伙伴们，这篇关于《FastAPIQuery参数必填设置技巧》的介绍应该让你收获多多了吧！欢迎大家收藏或分享给更多需要学习的朋友吧~golang学习网公众号也会发布文章相关知识，快来关注吧！