AXIOS PUT请求无法向FastAPI端点传递JSON参数问题排查

首先明确：FastAPI返回422 Unprocessable Entity，本质是请求数据不符合后端Pydantic模型的校验规则。Swagger能正常调用，是因为它会自动根据后端接口定义生成格式完全匹配的请求，而前端Axios/fetch的请求构造大概率存在格式或字段匹配问题。

下面是具体排查和解决步骤：

1. 检查请求体的传递方式 #

FastAPI用Pydantic BaseModel接收PUT请求参数时，默认要求参数放在请求体里，且Content-Type为application/json。很多前端会犯把PUT参数用GET的params方式传递（拼在URL里）的错误，导致后端根本接收不到请求体。

• 错误示例（参数拼URL，后端用Body接收不到）：

axios.put('/api/location', {}, { params: { name: '北京', address: '朝阳区' } })

• 正确示例（参数放请求体，Axios自动转JSON并设置头）：

axios.put('/api/location', { name: '北京', address: '朝阳区' })

如果用fetch，需要手动设置请求头并序列化JSON：

fetch('/api/location', {
  method: 'PUT',
  headers: { 'Content-Type': 'application/json' },
  body: JSON.stringify({ name: '北京', address: '朝阳区' })
})

2. 严格核对前后端字段名 #

FastAPI对Pydantic模型的字段名是严格大小写、拼写匹配的，差一个字符都会触发校验失败。比如后端模型字段是address，前端传addr，后端就会判定该字段缺失，返回422。

• 后端模型示例：

from pydantic import BaseModel

class LocationCreate(BaseModel):
    name: str
    address: str  # 字段名是address，不是addr

@app.put('/api/location')
def create_location(location: LocationCreate):
    return location

前端必须严格传address字段，不能随意简写。

3. 检查必填字段是否齐全 #

如果Pydantic模型里的字段没有设置默认值，前端必须传全所有字段，否则会触发校验错误。如果某些字段是可选的，后端可以给字段加Optional和默认值：

from typing import Optional

class LocationCreate(BaseModel):
    name: str  # 必填字段，前端必须传
    address: Optional[str] = None  # 可选字段，允许不传

4. 查看FastAPI的详细错误响应 #

FastAPI的422错误会返回具体的校验失败原因，前端可以打印响应体定位问题：

axios.put('/api/location', yourParams)
  .catch(err => {
    console.log(err.response.data)  // 打印详细错误信息
  })

比如响应会显示类似："detail": [{"loc": ["body", "name"], "msg": "field required", "type": "value_error.missing"}]，直接指出是name字段缺失。

5. 确认后端端点的参数接收方式 #

如果后端是用Query接收URL参数（而非请求体），那前端用请求体传参就会失败。这种情况下Swagger会让你在URL里填参数，前端也需要对应调整传参方式：

• 后端用Query接收的示例：

@app.put('/api/location')
def create_location(name: str = Query(...), address: str = Query(...)):
    return {"name": name, "address": address}

• 前端对应传参方式：

axios.put('/api/location', {}, { params: { name: '北京', address: '朝阳区' } })

内容的提问来源于stack exchange，提问作者schwitzky