FastAPI中参数是否必填仅取决于是否有默认值，而非Optional类型注解；Query()包裹才能启用校验，嵌套模型需用Field()替代Query()。
FastAPI 中 Optional[str] 和默认值 None 的行为差异
声明 Optional[str] = None 看似是“可选”，但 FastAPI 实际仍会把该参数当作文本字段解析，且 None 是它的默认值 —— 这和直接写 job: str = None 语义不同（后者类型错误，Pydantic 不接受非可选类型配 None 默认值）。真正决定“是否必填”的，只有有没有默认值，而不是有没有写 Optional。
常见错误现象：
• 写成 job: Optional[str] = "engineer" → 参数变成“有默认值的可选字段”，前端不传也能过，但语义上它已不是“可选”，而是“有兜底值”
• 写成 job: str（无默认值）→ FastAPI 强制要求 URL 必须带 ?job=xxx，否则返回 422 错误，提示 field required
-
job: str = "default"：必填字段被覆盖为“有默认值”，实际等价于可选 -
job: Optional[str] = None：显式声明可选，且无业务默认值，适合做开关型参数（如?debug=true） -
job: str（无默认值）：真·必填，URL 查询串里必须出现job=xxx
Query() 包裹 Optional[str] = None 才能加校验
只靠类型注解无法触发长度、正则等校验。必须用 Query() 显式包裹，否则 min_length、max_length、regex 全部失效。比如：
from fastapi import Query
from typing import Optional
<p>@app.get("/users/")
async def read_users(job: Optional[str] = Query(None, min_length=3, max_length=20)):
...
</p>
注意：
• Query(None, ...) 中第一个参数是默认值，不能省略，即使你想让它为 None
• 如果写成 Query(..., min_length=3)（用 ... 占位），那这个参数就变成必填了，和类型注解 str 效果一致
• Query 的校验只在参数被传入时触发；如果 URL 根本没带 job，整个字段就跳过校验，直接为 None
bool 类型的 Optional 处理要特别小心
FastAPI 对 bool 查询参数有自动转换逻辑：字符串 "true"、"1"、"on"、"yes" 都转为 True；其余（包括空值、"false"、"0"）全转为 False。所以别指望 Optional[bool] = None 能区分“未传”和“传了 false”。
- 想表达三态（未传 / true / false），必须用
Optional[str]+ 手动解析 - 想让
?active（无等号）表示 true，?active=false表示 false，得用Query(default=None, alias="active")并自己判断字符串值 - 直接写
active: bool = False→ 所有非法输入都 fallback 到False，且无法感知“未传”
嵌套模型里的 Optional 字段和 Query 校验不兼容
如果你把查询参数收进 Pydantic 模型（比如用 class Params(BaseModel)），再作为路径函数参数接收，那 Query 的校验能力就失效了 —— 因为 Query 只作用于函数签名级的参数，不穿透到模型内部。
例如下面写法不会触发 max_length 校验：
class UserQuery(BaseModel):
job: Optional[str] = None # ← 这里加 Query() 没用
<p>@app.get("/users/")
async def read_users(params: UserQuery):
...
</p>
正确做法是：要么坚持用函数参数直写 + Query()，要么在模型里用 Field() 替代 Query()：
from pydantic import Field <p>class UserQuery(BaseModel): job: Optional[str] = Field(None, max_length=20) </p>
但注意：Field 不支持 regex 或 alias 等 Query 特有功能，而且模型方式下无法控制参数是否“必须出现在查询串中”。
最易被忽略的一点：当你混合使用路径参数、查询参数和请求体模型时，FastAPI 依赖参数名和类型推断来分发数据源 —— 一旦你用 Query() 显式声明，就等于告诉框架“这个必须从 URL 查询串来”，哪怕它名字和模型字段重名，也不会被合并进去。
大量免费API接口：立即使用
涵盖生活服务API、金融科技API、企业工商API、等相关的API接口服务。免费API接口可安全、合规地连接上下游，为数据API应用能力赋能！
