FastAPI 中如何正确传递整数参数到 POST 端点-Python教程-PHP中文网

FastAPI 中如何正确传递整数参数到 POST 端点

FastAPI 默认将标量类型（如 int、str、bool）的路径/请求函数参数解析为查询参数（Query），而非请求体（Body），因此直接通过 JSON 提交会失败；需显式声明 Body(...) 才能从 JSON 正确接收。

fastapi 默认将标量类型（如 int、str、bool）的路径/请求函数参数解析为查询参数（query），而非请求体（body），因此直接通过 json 提交会失败；需显式声明 `body(...)` 才能从 json 正确接收。

在 FastAPI 中，函数参数的来源（查询参数、路径参数、请求体、表单等）并非由 HTTP 方法（如 POST）自动决定，而是由参数类型 + 类型注解的“可序列化性”共同推断。关键规则如下：

✅ 标量类型（scalar types）：int、str、float、bool、UUID 等基础类型，默认被识别为 Query 参数（即使在 POST 中）。
✅ 复合/非标量类型：list[int]、dict、Pydantic 模型等，默认被识别为 Body 参数，因此 json={'x': [1,2], 'y': [3,4]} 可正常解析。

这就是为什么你的 /lists 端点能成功接收 JSON，而 /ints 却报错 "x and y are missing" —— FastAPI 根本没从请求体中查找 x 和 y，而是去查询字符串（?x=1&y=2）里找它们。

✅ 正确做法：显式使用 `Body` 声明标量参数

修改 endpoints.py，导入 Body 并标注参数：

from fastapi import FastAPI, Body

app = FastAPI()

@app.post('/ints')
def post_int(x: int = Body(...), y: int = Body(...)):
    return {"x": x, "y": y}

@app.post('/lists')
def post_list(x: list[int] = Body(...), y: list[int] = Body(...)):
    return {"x": x, "y": y}

? Body(...) 表示该参数必须来自请求体（JSON 或表单），且为必填项；若允许可选，可写 Body(None)。

FastAPI Flask Proxy
FastAPI + Flask 混合部署最佳实践，解决路由定义、API 代理等常见问题，适用于同时运行 FastAPI API 与 Flask 前端的场景。

下载

此时，以下请求将成功：

import requests

# ✅ 现在可通过 JSON 正确提交
r = requests.post('http://127.0.0.1:8000/ints', json={"x": 1, "y": 2})
print(r.json())  # 输出: {"x": 1, "y": 2}

⚠️ 注意事项与最佳实践

不要依赖“HTTP 方法推断参数位置”：POST 不等于“自动读 body”，FastAPI 的设计哲学是显式优于隐式。
混合参数时需明确区分：例如同时需要路径 ID、查询过滤器和 JSON 数据体，应分别用 Path、Query、Body 显式标注。
推荐使用 Pydantic 模型封装请求体（更健壮、支持验证、文档自动生成）：

from pydantic import BaseModel

class IntPair(BaseModel):
    x: int
    y: int

@app.post('/ints-model')
def post_int_model(data: IntPair):  # 自动作为 Body 接收
    return data.model_dump()