如何用ExpediaGroup graphql-kotlin在Spring WebFlux实现多文件上传

• 入参类型不被schema识别：graphql-kotlin 是基于代码反向生成GraphQL Schema的框架，Spring WebFlux原生的FilePart没有对应的GraphQL标量定义，直接作为入参类型会被框架当成普通POJO解析，既无法匹配GraphQL文件上传的协议要求，也生成不了正确的schema字段定义。
• 参数结构不匹配多文件场景：你需要一次性上传5个文件，单值的FilePart入参根本承载不了多文件绑定逻辑，哪怕类型适配对了，也没法接收多个文件。
• 缺失核心适配逻辑：graphql-kotlin默认没有开启文件上传能力的标量注册，缺少对应的协议适配配置的话，哪怕代码写对了，请求也没法正常解析。

• 基础依赖确认：确保项目已经引入graphql-kotlin Spring Server Starter 以及 Spring GraphQL 核心依赖，WebFlux场景下不需要额外引入第三方文件上传组件。

• 标量注册配置：在graphql-kotlin的Schema生成配置中，手动注册Spring GraphQL提供的标准 Upload 标量，让框架能够识别GraphQL层面的文件类型。这个 Upload 类型是专门适配GraphQL Multipart上传协议的官方定义，是框架和客户端之间文件传输的标准类型。

• Mutation方法正确写法：入参使用List<Upload>类型直接对应多文件上传场景，框架会自动将客户端按照GraphQL Multipart规范上传的文件，绑定为对应位置的Upload实例；你可以在方法内部将每个Upload转换为WebFlux生态的FilePart对象，完成后续的存储、校验等业务逻辑。

  正确的Mutation代码示例：

  class UploadMutation : Mutation {
      // 入参为Upload集合，天然支持多文件上传，匹配5个文件的场景需求
      fun upload(files: List<Upload>): Boolean {
          files.forEach { upload ->
              // 将框架绑定的Upload实例转换为WebFlux的FilePart做业务处理
              val filePart = upload.getFilePart()
              println("成功接收文件：${filePart.filename}")
          }
          return true
      }
  }
  

• 请求格式要求：客户端调用时必须严格遵循GraphQL Multipart规范，以multipart/form-data格式组装请求，将查询语句、变量映射、二进制文件分块传输，不能使用普通JSON请求体发起上传请求。

• 不要直接使用Spring原生传输类作为GraphQL入参：不管是WebFlux的FilePart还是Servlet栈的MultipartFile，都属于服务端内部的传输对象，没有对应的GraphQL标量映射，直接当入参会生成完全不符合预期的schema结构。
• 多文件上传不需要拆分为多个入参字段：直接用List<Upload>作为入参，客户端只需要在文件映射部分把5个上传的文件依次绑定到variables.files[0]到variables.files[4]的路径即可，框架会自动完成绑定，不需要编写额外的解析逻辑。
• WebFlux场景下不要混用Servlet栈的文件类型：WebFlux是响应式栈，和Servlet栈的文件处理模型不兼容，统一用官方提供的Upload作为GraphQL入参类型，在业务层内部再转换为FilePart做处理即可。

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