FastAPI如何向端点传递含字符串与Bytes对象的字典？

你遇到的核心问题是：用requests.post(data=payload)发送请求时，data参数会把内容编码成application/x-www-form-urlencoded格式，但FastAPI的dict参数默认期望接收application/json格式的请求体；同时字节数据无法直接序列化为JSON，这是导致解析失败的根本原因。

以下是两种可行的解决方案：

方案1：用表单上传（推荐，适合大文件） #

这是处理文件上传的标准方式，支持同时传递字符串字段和文件字节：

FastAPI端点代码 #

from fastapi import FastAPI, File, Form

@app.post("/process_file/", tags=["File processing"])
def process_excel_file(file_name: str = Form(...), payload: bytes = File(...)):
    data = FlatFileParser(file_name, payload)
    logger.debug(f"Received: {data}")
    
    # 后续处理逻辑
    data = strip_cols(data)
    data = clean_columns(data)
    data = prep_schema_cols(data)
    data = drop_same_name_columns(data)
    
    return {"Validator Response": data}

客户端请求代码 #

import requests

url = "http://localhost:8000/process_file/"
file_path = r'sample_file.xlsx'

with open(file_path, 'rb') as f:
    # 用files参数传文件，data参数传文件名
    response = requests.post(
        url,
        data={"file_name": file_path},
        files={"payload": f}
    )

print(response.json())

方案2：用JSON+Base64编码（适合小文件） #

如果一定要用JSON格式传递，需要把字节数据编码为Base64字符串（JSON不支持原生字节类型）：

FastAPI端点代码 #

from fastapi import FastAPI
from pydantic import BaseModel
import base64

class FilePayload(BaseModel):
    file_name: str
    payload: str  # Base64编码的字符串

@app.post("/process_file/", tags=["File processing"])
def process_excel_file(payload: FilePayload):
    # 解码Base64字符串回字节
    file_bytes = base64.b64decode(payload.payload)
    data = FlatFileParser(payload.file_name, file_bytes)
    logger.debug(f"Received: {data}")
    
    # 后续处理逻辑
    data = strip_cols(data)
    data = clean_columns(data)
    data = prep_schema_cols(data)
    data = drop_same_name_columns(data)
    
    return {"Validator Response": data}

客户端请求代码 #

import requests
import base64

url = "http://localhost:8000/process_file/"
file_path = r'sample_file.xlsx'

with open(file_path, 'rb') as f:
    file_bytes = f.read()
    # 把字节编码为Base64字符串
    payload = {
        "file_name": file_path,
        "payload": base64.b64encode(file_bytes).decode('utf-8')
    }

response = requests.post(url, json=payload)
print(response.json())

原方式失败原因说明 #

• 方式1报错：data=payload发送的是表单数据，但FastAPI的dict参数期望JSON格式，格式不匹配导致解析错误。
• 方式2失败：Request.body()返回的是原始字节类型的请求体，需要先解析为JSON或表单数据（比如异步端点用await payload_dict.json()），直接用字典索引必然报错，这种方式也远不如FastAPI原生参数声明简洁可靠。

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