Feign接口传递复杂参数注解@ModelAttribute+@SpringQueryMap

背景介绍

在微服务架构中，服务间通信是开发中常见的场景。Spring Cloud OpenFeign 作为一种声明式的 HTTP 客户端调用工具，极大简化了服务间调用的开发工作。然而，当接口需要传递复杂参数（例如文件上传、JSON 字符串、复杂对象等）时，Feign 的注解选择和配置可能会成为开发中的难点。本文将结合实际案例，详细讲解如何在 Feign 接口中使用 @ModelAttribute 和 @SpringQueryMap 注解来处理复杂参数传递问题，并分享一些在工作中遇到的问题和解决方案。

本文的目标读者是对 Spring Cloud、Feign 和微服务调用有一定了解的开发者，希望通过本文能够帮助大家更好地理解 Feign 参数传递的细节，并提供可直接应用的代码示例。

问题场景

在开发知识库管理系统的过程中，我们需要实现一个文件上传接口，接口不仅需要传递文件（MultipartFile），还需要传递用户账户信息（通过请求头）、JSON 字符串形式的参数以及复杂的对象参数（KnowledgeFileDO）。服务端接口定义如下：

@PostMapping("/upload")
@Operation(summary = "知识库上传")
public ResultDTO<KnowledgeFileDO> uploadFile(
        @RequestHeader(X_ACCOUNT_HEADER_NAME) String userAccount,
        @RequestParam("multipartFile") MultipartFile multipartFile,
        @RequestParam(value = "knowledgeFile", required = false) String knowledgeFileDOStr,
        @ModelAttribute KnowledgeFileDO knowledgeFileDO) {
    // 从JSON字符串解析知识库文件信息
    if (StringUtils.isNotBlank(knowledgeFileDOStr)) {
        knowledgeFileDO = JSON.parseObject(knowledgeFileDOStr, KnowledgeFileDO.class);
    }
    // 业务逻辑处理
    // …………
}

在另一个微服务中，我们需要通过 Feign 客户端调用该接口。问题在于如何正确选择 Feign 注解以匹配服务端的参数形式，并确保文件上传、复杂对象传递等功能正常工作。

解决方案：Feign 接口定义

为了调用上述接口，我们在 Feign 客户端中定义了以下接口：

public interface KBManageUploadFeign {
   
    @PostMapping(value = "/kb-manage/v1/upload", consumes = MediaType.MULTIPART_FORM_DATA_VALUE)
    ResultDTO<KnowledgeFileDO> fileUpload(
        @RequestHeader(HEADER_ACCOUNT_KEY) String userAccount,
        @RequestPart("multipartFile") MultipartFile multipartFile,
        @RequestPart("knowledgeFile") String knowledgeFileDOStr,
        @SpringQueryMap KnowledgeFileDO knowledgeFileDO);
}

注解说明

@RequestHeader
用于传递请求头参数，例如用户账户信息 userAccount。此注解直接映射到 HTTP 请求头，确保服务端能够正确接收。
@RequestPart
用于处理 multipart/form-data 类型的请求，适合文件上传场景（MultipartFile）以及字符串参数（knowledgeFileDOStr）。@RequestPart 会将参数作为 multipart/form-data 的一部分发送，服务端通过 @RequestParam 或 @ModelAttribute 接收。
@SpringQueryMap
用于将复杂对象（KnowledgeFileDO）的字段自动展开为查询参数（query parameters）。相比 @ModelAttribute，@SpringQueryMap 更适合在 Feign 中处理复杂对象的 GET 或 POST 请求，因为它会将对象的字段序列化为查询字符串（例如 ?field1=value1&field2=value2）。
consumes = MediaType.MULTIPART_FORM_DATA_VALUE
明确指定请求的 Content-Type 为 multipart/form-data，这是文件上传场景中必须的配置。

Feign 配置

为了支持文件上传和长超时场景，我们需要自定义 Feign 客户端的配置：

@Configuration
@Import(FeignClientsConfiguration.class)
public class KBManageUploadFeignConf {
    private final KBManageUploadFeign kbManageUploadFeign;

    @Autowired
    public KBManageUploadFeignConf(
            @Value("${com.polarizon.feign.kb-manage-api-url:http://kb-manage:20501}") String kbManageApiUrl,
            @Value("${kb.upload.timeout-minutes:10}") Integer timeoutMinutes,
            Client client, Encoder encoder, Decoder decoder, Contract contract) {
        this.kbManageUploadFeign = Feign.builder()
                .client(client)
                .encoder(encoder)
                .decoder(decoder)
                .contract(contract)
                .options(new Request.Options(10, TimeUnit.SECONDS, timeoutMinutes, TimeUnit.MINUTES, false))
                .target(KBManageUploadFeign.class, kbManageApiUrl);
    }

    public KBManageUploadFeign getKbManageUploadFeign() {
        return this.kbManageUploadFeign;
    }
}

配置要点

长超时配置
文件上传通常需要较长的超时时间。我们通过 Request.Options 配置了连接超时（10秒）和读取超时（10分钟），以应对大文件上传的场景。
Feign 组件注入
使用 @Import(FeignClientsConfiguration.class) 引入默认的 Feign 配置，同时注入 Client、Encoder、Decoder 和 Contract，以确保 Feign 客户端能够正确处理 multipart/form-data 请求。
动态服务地址
通过 @Value 注解从配置文件中读取服务地址（kb-manage-api-url），提高了配置的灵活性。

调用示例

在实际调用时，我们通过 Spring 的 SpringBeanUtil 获取 Feign 客户端实例并调用接口：

// 上传到知识库（专用长超时 Feign）
ResultDTO<KnowledgeFileDO> knowledgeFileDOResultDTO = SpringBeanUtil
    .getBean(com.polarizon.rag.plugin.common.configs.KBManageUploadFeignConf.class)
    .getKbManageUploadFeign()
    .fileUpload(userAccount, multipartFile, knowledgeFileDOStr, knowledgeFileDO);

常见问题及解决方案

文件上传失败，提示 Content-Type 不匹配
确保 Feign 接口的 @PostMapping 中指定了 consumes = MediaType.MULTIPART_FORM_DATA_VALUE，并且服务端接口也支持 multipart/form-data。
复杂对象参数未正确传递
使用 @SpringQueryMap 时，检查对象字段是否正确序列化为查询参数。如果服务端需要 multipart/form-data 格式的复杂对象，考虑改为 @RequestPart 并将对象序列化为 JSON 字符串。
超时问题
文件上传可能因文件过大而超时，建议根据实际需求调整 Request.Options 的超时时间。