.NetCore下GraphQL API接收multipart/form-data文件上传400错误如何解决

1. 服务注册配置 #

首先确保你已安装对应版本的GraphQL.Upload.AspNetCore NuGet包，在Program.cs（.NET 6+）的服务注册环节添加上传支持，同时给GraphQL端点配置允许的内容类型：

// 注册GraphQL服务时添加上传支持
builder.Services.AddGraphQL()
    .AddUploadSupport() // 核心：启用文件上传支持
    .AddSystemTextJson(); // 你当前用的序列化器配置保持不变

// 其他服务注册逻辑...

var app = builder.Build();

// 其他中间件配置（如CORS、身份认证等）...

// 核心：上传中间件必须放在UseGraphQL之前执行
app.UseGraphQLUpload();

// 配置GraphQL端点，添加multipart/form-data为允许的内容类型
app.MapGraphQL("/graphql", options =>
{
    options.AcceptedMediaTypes.Add("multipart/form-data");
});

如果是.NET 5及更早版本用Startup.cs的场景，对应配置如下：

// ConfigureServices方法中
public void ConfigureServices(IServiceCollection services)
{
    services.AddGraphQL()
        .AddUploadSupport()
        .AddSystemTextJson();
    // 其他服务注册
}

// Configure方法中
public void Configure(IApplicationBuilder app, IWebHostEnvironment env)
{
    // 其他中间件（CORS、认证等）
    app.UseGraphQLUpload<ISchema>();
    app.UseGraphQL("/graphql", options =>
    {
        options.AcceptedMediaTypes.Add("multipart/form-data");
    });
}

2. 版本兼容性检查 #

确保GraphQL核心包和GraphQL.Upload.AspNetCore的主版本号一致，比如7.x版本的核心包对应7.x版本的上传包，8.x版本对应8.x版本，版本不匹配会导致上传功能失效。

3. 客户端请求格式校验 #

客户端发送的multipart/form-data请求必须符合GraphQL multipart请求规范，请求的FormData需要包含三个字段：

• operations：序列化后的JSON字符串，包含GraphQL查询语句和变量，示例值：

  {"query":"mutation testImageUpload($testArg: String, $file: Upload) { fileUpload{ testImageUpload(testArg: $testArg, file: $file) } }","variables":{"testArg":"测试参数","file":null}}
  

• map：序列化后的JSON字符串，用于映射文件和变量的对应关系，单文件上传示例值：

  {"0": ["variables.file"]}
  

• 0：对应map中key的文件二进制内容，就是你要上传的头像文件
  如果使用Angular的Apollo客户端，建议集成apollo-upload-client链路，它会自动按规范构造请求，不需要手动拼接FormData。

常见排查点 #

• 检查中间件顺序，UseGraphQLUpload必须放在UseGraphQL之前，否则上传请求会被GraphQL默认逻辑直接拦截返回400
• 确认没有其他自定义中间件提前拦截了multipart/form-data类型的请求，修改了请求头或者内容
• 检查CORS配置是否允许multipart/form-data为合法的请求内容类型

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