Flutter执行GraphQL Mutation时触发HttpLinkParserException异常

一、排查.NET GraphQL服务端问题 #

• 确认Multipart请求处理配置：GraphQL文件上传必须依赖Multipart中间件，检查你的.NET服务配置中是否添加了以下代码：

  // Program.cs/Startup.cs 中启用Multipart中间件
  app.UseMultipartRequestMiddleware();
  
  // 配置GraphQL时添加上传类型支持
  services.AddGraphQL(options =>
  {
      options.EnableMetrics = false;
  })
  .AddSystemTextJson()
  .AddUploadType();
  

  缺少上述配置会导致服务端无法解析文件上传请求，进而返回空响应或错误格式内容。
• 验证服务端响应有效性：用Postman手动模拟multipart请求测试接口：
  • 构造operations参数（JSON格式）：{"query":"mutation UploadFiles($files: [Upload!]!) { uploadFiles(files: $files) }","variables":{"files":[null]}}
  • 构造map参数：{"0":["variables.files.0"]}
  • 添加文件，key设为0
    如果返回的不是标准GraphQL JSON响应（比如空内容、HTML错误页），说明服务端逻辑存在问题，需要排查Azure Blob上传代码是否有未捕获的异常，导致服务端无法生成有效响应。
• 检查Mutation参数定义：确保.NET中Mutation方法的参数类型为List<IFormFile>，且GraphQL Schema中对应字段标注为[Upload]类型，比如：

  public async Task<bool> UploadFiles([FromServices] IBlobStorageService blobService, List<IFormFile> files)
  {
      // 上传逻辑
  }
  

二、排查Flutter端GraphQL客户端配置 #

• 启用MultipartLink支持：普通HttpLink无法处理文件上传，必须使用MultipartLink包装HttpLink，示例代码：

  final HttpLink httpLink = HttpLink('https://your-api-domain/graphql');
  final MultipartLink multipartLink = MultipartLink(httpLink: httpLink);
  final GraphQLClient client = GraphQLClient(
    link: multipartLink,
    cache: GraphQLCache(),
  );
  

• 确认文件变量构造正确：必须用MultipartFile包装本地文件，变量名要和服务端Mutation参数完全匹配，示例：

  List<MultipartFile> prepareUploadFiles(List<File> selectedFiles) {
    return selectedFiles.map((file) => MultipartFile(
      'files',
      file.readAsBytes().asStream(),
      file.lengthSync(),
      filename: file.path.split('/').last,
    )).toList();
  }
  
  // 调用Mutation时传入变量
  final options = MutationOptions(
    document: gql(r'''
      mutation UploadFiles($files: [Upload!]!) {
        uploadFiles(files: $files)
      }
    '''),
    variables: {'files': prepareUploadFiles(selectedFiles)},
  );
  

• 捕获原始响应排查：添加日志拦截查看服务端返回的原始内容，定位是否是响应格式问题：

  final Link link = Link.from([
    multipartLink,
    LogLink(
      onResponse: (response) => print('Raw Response: ${response.data}'),
      onError: (error) => print('Link Error: $error'),
    ),
  ]);
  

三、通用修复步骤 #

1. 优先确保服务端独立可用：通过Postman验证服务端能正确处理文件上传并返回标准GraphQL响应，排除服务端问题后再排查Flutter端。
2. 处理服务端异常：在.NET的Mutation方法中添加异常捕获，返回明确的GraphQL错误，避免服务端崩溃返回空响应：

   public async Task<bool> UploadFiles([FromServices] IBlobStorageService blobService, List<IFormFile> files)
   {
       try
       {
           foreach (var file in files)
           {
               await blobService.UploadAsync(file);
           }
           return true;
       }
       catch (Exception ex)
       {
           throw new GraphQLException(new ErrorMessage
           {
               Message = $"上传失败: {ex.Message}",
               Code = "UPLOAD_FAILED"
           });
       }
   }
   

3. 核对变量名与类型：确保Flutter端Mutation的变量名、类型和服务端Schema完全一致，比如[Upload!]!对应Flutter的List<MultipartFile>。

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