本地Swagger测得好好的，把同样的参数搬到Feign调用里就开始报错，文件传不上去、字段对不上、服务端动不动就是“Current request is not a multipart request”——这个问题我在团队里见过不下十次。根子往往不在Feign本身，而在很多人对@RequestParam和@RequestPart的理解还停留在“一个收参数、一个收文件”的层面。这两个注解在HTTP报文层的语义差别，决定了它们在Feign里的行为完全不同。这篇文章我就把这层窗户纸捅破，结合一次真实排错经历，把两者的区别和Feign的坑一次说清。

1. 从“HTTP报文长什么样”说起：两个注解背后的协议差异

1.1 一次上传请求里，数据到底放在哪几种位置

理解这两个注解之前，得先回到HTTP请求本身。一次带数据的请求，数据可以出现在三个位置：

• 第一，URL的query string，典型的就是GET请求拼参数：/api/user?name=zhangsan&age=18，POST请求同样可以在URL上拼参数。
• 第二，请求体以application/x-www-form-urlencoded格式提交，body内容是name=zhangsan&age=18这种键值对，相当于把query string搬到了body里，通常HTML表单默认就是这种格式。
• 第三，请求体以multipart/form-data格式提交，body里没有简单的键值对，而是被一个随机boundary分割成多个独立部分，每个部分叫做一个part。每个part都有自己完整的头部信息，包括Content-Disposition、Content-Type，甚至可以是一个文件内容。

我用一个multipart请求的报文片段来说明，你感受一下：

POST /upload HTTP/1.1 Host: example.com Content-Type: multipart/form-data; boundary=----WebKitFormBoundary7MA4YWxkTrZu0gW ------WebKitFormBoundary7MA4YWxkTrZu0gW Content-Disposition: form-data; name="remark" 这是备注 ------WebKitFormBoundary7MA4YWxkTrZu0gW Content-Disposition: form-data; name="file"; filename="logo.png" Content-Type: image/png <文件二进制内容> ------WebKitFormBoundary7MA4YWxkTrZu0gW--

multipart请求里每个part都是独立的小世界，有名字、有类型、有内容。而urlencoded请求里的键值对是扁平的，整个body就是一个长的字符串。

明确了这个根本区别，再回头看@RequestParam和@RequestPart就好理解了。

1.2 @RequestParam的解析逻辑：它就是冲着name=value去的

@RequestParam从设计之初处理的就是“名值对”形式的参数。它从ServletRequest.getParameter()拿数据，而getParameter会同时覆盖URL query string里的参数和application/x-www-form-urlencoded请求体里的参数。也就是说，不管参数是拼在URL问号后面，还是以urlencoded格式放在body里，@RequestParam都能取到。

到了Spring MVC的RequestParamMethodArgumentResolver里，取值之后还会做一次类型转换。比如声明@RequestParam Integer age，框架会调用内置的类型转换器把字符串"18"转成Integer。所以它天然适合绑定那些可以用字符串表达并转换回来的简单类型：String、基本类型包装类、BigDecimal、日期等。

@RequestParam还有一个很实用的设计：required=false和defaultValue。required控制参数缺失时是否报错，默认是true，缺了就抛MissingServletRequestParameterException。defaultValue则是在参数缺失或值为空的时候给一个兜底值。

特别注意一点：在multipart请求里，@RequestParam也能取到非文件part的字段。比如一个multipart请求里有个Content-Disposition: form-data; name="remark"的part，你用@RequestParam String remark照样拿得到值。因为Servlet规范要求getParameter对multipart请求里的form field也生效。这也是后面Feign踩坑的伏笔——本地Controller能正常接收字段，不代表Feign客户端发出去的请求里就一定带了这些字段。

1.3 @RequestPart的解析逻辑：每个part都是独立MIME消息

@RequestPart则完全不同。它对应的不是“键值对”，而是“请求里的一个part”。Spring MVC的RequestPartMethodArgumentResolver会先按名字找到那个part，然后把整个part当作一个MIME消息，交给HttpMessageConverter去做内容转换。

什么叫交给HttpMessageConverter？就是它能拿到part头部的Content-Type和原始内容，再根据目标参数类型做转换。比如：

• @RequestPart("file") MultipartFile file：part直接是一个文件，Spring会把part封装成MultipartFile。
• @RequestPart("user") User user：part的Content-Type是application/json，body是{"name":"zhangsan"}，Spring会调用MappingJackson2HttpMessageConverter把JSON反序列化成User对象。

这个能力是@RequestParam给不了的。@RequestParam的底层类型转换器只能把字符串变成简单类型，没法把JSON反序列化成POJO。

@RequestPart也有required=false，但没有defaultValue。原因也简单：part可以是一个文件、一段JSON、任意二进制内容，不存在“默认字符串”这么一说。

到这里可以简单总结一句：@RequestParam定位的是HTTP语义里的“参数”，@RequestPart定位的是HTTP语义里的“part”。这两个东西在报文层就不是一回事，但大多数业务代码把它们都用在了“上传接口”上，模糊了边界，坑自然就来了。

2. 同样一个文件接口，两个注解的行为边界在哪里

2.1 MultipartFile场景：为什么两种写法都能收到文件

有个现象很多人疑惑：Controller接收文件时，@RequestParam("file") MultipartFile file和@RequestPart("file") MultipartFile file都能跑通。我最早也以为它们等价，直到翻了源码才明白，这是Spring给MultipartFile开了特例。

当参数类型是MultipartFile、Part、List<MultipartFile>、MultipartFile[]时，RequestParamMethodArgumentResolver会转交MultipartResolutionDelegate去处理。这个Delegate做的其实就是“按参数名从multipart请求里找一个part，然后包装成MultipartFile返回”。所以表面上你写的是@RequestParam，实际后半段走的已经是part解析逻辑了。

而@RequestPart遇到MultipartFile参数时，RequestPartMethodArgumentResolver找到part之后发现目标类型就是Spring定义的MultipartFile，也直接包装返回。

写法不同，解析路径不同，但结果都是拿到那个part封装的MultipartFile。所以单纯收文件这个场景，两个注解确实看不出太大差别。真正拉开差距的是下面这些场景。

2.2 拉开差距的场景：JSON part、多文件、Content-Type敏感度

第一个典型场景：multipart请求里带一个JSON类型的part。

@PostMapping(value = "/create") public Result create(@RequestPart("user") User user, @RequestPart("file") MultipartFile file) { // ... }

客户端构造请求时，把User对象序列化成JSON字符串作为一个part，把文件作为另一个part。服务端用@RequestPart("user")就能借助HttpMessageConverter把JSON part反序列化成User对象。这种“文件+对象”的混合上传在复杂业务里很常见。换成@RequestParam("user") User user直接不支持，类型转换器根本没有能力处理。

第二个场景：多文件上传。@RequestPart("files") List<MultipartFile> files可以把多个同名part收集成一个List，服务端接收多个文件非常自然。@RequestParam("files") List<MultipartFile> files虽然也能工作，但语义上更像“用同一个参数名传了多个值”，不如@RequestPart直观，而且遇到每个part有不同Content-Type的时候，@RequestPart的处理更符合直觉。

第三个场景是Content-Type敏感度。@RequestPart要求part的Content-Type能匹配目标参数类型。比如声明@RequestPart("file") MultipartFile，而客户端发送的partContent-Type是text/plain，Spring在转换时就会因为找不到合适的message converter抛HttpMediaTypeNotSupportedException。@RequestParam则完全不管Content-Type，只要能从multipart里取出对应名字的值就行。

2.3 从源码注释和实际表现总结出的差异清单

我用表格整理一下目前最核心的区别，方便你直接对比：

这张表存下来，遇到接口设计的时候拿出来对一下，基本不会选错。

2.4 一个看起来合理的Controller上传接口最终怎么写

以我实际写过的一个“用户头像上传”接口为例，需求是：上传一个文件，同时传用户ID和一个可选备注。

@PostMapping(value = "/avatar/upload", consumes = MediaType.MULTIPART_FORM_DATA_VALUE) public Result<String> uploadAvatar(@RequestPart("file") MultipartFile file, @RequestParam("userId") Long userId, @RequestParam(value = "remark", required = false) String remark) { // 业务处理 return Result.ok(fileStorage.save(file, userId, remark)); }

文件用@RequestPart，因为它是文件，是一个part；userId和remark用@RequestParam，因为它们是普通字段，走query string或者表单字段都能接收。这个组合既符合两个注解的语义，也让后续接入Feign时少踩一个坑。如果你一开始就用@RequestParam("file") MultipartFile file，单独看Controller没问题，但到了Feign客户端那边，坑就开始连环踩了。

3. Feign场景实录：本地正常，一进Feign就翻车

3.1 第一道坎：OpenFeign默认编码器根本不认识MultipartFile

先看一眼最常见的报错：

feign.codec.EncodeException: class org.springframework.web.multipart.MultipartFile is not a type supported by this encoder.

这个报错出现得极其频繁。原因很简单：OpenFeign默认的Encoder.Default只能编码String、byte[]、InputStream这些基础类型，对于Spring的MultipartFile完全没有概念。所以当Feign接口方法里出现MultipartFile参数时，第一件事就是升级编码器。

解决方案是引入feign-form和feign-form-spring，这两个库专门为Feign提供multipart表单编码能力：

<dependency> <groupId>io.github.openfeign.form</groupId> <artifactId>feign-form</artifactId> <version>3.8.0</version> </dependency> <dependency> <groupId>io.github.openfeign.form</groupId> <artifactId>feign-form-spring</artifactId> <version>3.8.0</version> </dependency>

然后注册编码器Bean：

@Configuration public class FeignMultipartConfig { @Autowired private ObjectFactory<HttpMessageConverters> messageConverters; @Bean public Encoder feignFormEncoder() { return new SpringFormEncoder(new SpringEncoder(messageConverters)); } }

注意这里我用SpringEncoder包了一下SpringFormEncoder，而不是直接new SpringFormEncoder()。原因在于：纯SpringFormEncoder处理文件part足够了，但一旦请求里还要带JSON part或需要依赖Spring MVC已有的HttpMessageConverter（比如Jackson），单独构造的SpringFormEncoder没法共享这些转换器，容易出现相同的数据本地能反序列化、Feign这边却报错。包一层SpringEncoder，让它复用Spring Boot自动配置的messageConverters，是最稳妥的做法。

3.2 第二道坎：feign-form的SpringFormEncoder对注解的映射逻辑

依赖配好、编码器换了，很多人以为万事大吉，结果还是出问题。这里就要看feign-form处理方法参数时的具体逻辑了。它的SpringFormEncoder在编码multipart请求时，对参数的分类是这样的：

• 带@RequestPart注解的参数：作为一个独立part发送，part名就是注解里的value。MultipartFile参数会被包装成文件part。
• 带@RequestParam注解的参数：不会进入multipart body，而是被当成URL query参数拼到请求URL上。这是Feign的行为，不管你的方法是不是multipart请求，@RequestParam默认就是往URL上拼。
• 没有注解的POJO，或者带@RequestBody注解的对象：在multipart请求中会被序列化成一个application/json的独立part。

我把这个映射关系标记为第二道坎，是因为绝大多数人想当然地认为：“我在Controller里用@RequestParam收的字段，Feign客户端也用@RequestParam发，服务端应该能收到吧。”事实是，Feign客户端把该字段拼到了URL query string上，如果你的服务端方法没有声明@RequestParam("remark") String remark，或者服务端本身只从multipart form field里取字段，那这个字段就是丢的。

另外还有一个很隐蔽的点：如果Feign接口里写了MultipartFile参数但用的是@RequestParam而不是@RequestPart，feign-form不会把它当成part来处理。结果可能是请求根本没有文件part，服务端直接报“Current request is not a multipart request”；甚至在某些版本下编码阶段就直接报异常。

3.3 consumes不配对，multipart请求直接变成普通请求

第三道坎看似小，坑人无数：Feign方法上必须显式声明consumes = MediaType.MULTIPART_FORM_DATA_VALUE。

@PostMapping(value = "/avatar/upload", consumes = MediaType.MULTIPART_FORM_DATA_VALUE) Result<String> uploadAvatar(@RequestPart("file") MultipartFile file, @RequestParam("userId") Long userId, @RequestParam(value = "remark", required = false) String remark);

如果不声明，Feign默认的Content-Type可能是application/json，但请求体实际是multipart格式，服务端一看到Content-Type不对，要么直接拒绝，要么按错误格式解析。之前我遇到过一种更隐蔽的情况：服务端不校验Content-Type，框架尝试把multipart请求体当普通body读，结果文件内容变成了乱码字符串，查了半天才定位到是Content-Type不匹配。

到这里，Feign里用这两个注解的正确姿势已经比较清晰了：文件类的part用@RequestPart，简单字段用@RequestParam并理解它会走URL query，整个方法声明multipart的consumes。

4. 一次完整排错：文件过去了，remark字段却丢了

4.1 现象：Swagger正常，Feign调用后字段为null

完整还原一次我实际排查过的故障。当时业务方有一个上传接口，服务端Controller长这样：

@PostMapping(value = "/document/upload", consumes = MediaType.MULTIPART_FORM_DATA_VALUE) public Result<String> uploadDocument(@RequestPart("file") MultipartFile file, @RequestParam("docType") String docType, @RequestParam(value = "remark", required = false) String remark) { return Result.ok(service.upload(file, docType, remark)); }

用Swagger直接调这个接口，文件能传，docType、remark都能收到。后来接到另一个服务，对方用OpenFeign调这个接口，配置了feign-form，Feign接口长这样：

@PostMapping(value = "/document/upload", consumes = MediaType.MULTIPART_FORM_DATA_VALUE) Result<String> uploadDocument(@RequestPart("file") MultipartFile file, @RequestParam("docType") String docType, @RequestParam(value = "remark", required = false) String remark);

看着没毛病，注解都对得上。结果实际调用时：文件上传成功，docType正常，remark永远是null。业务方查了很久，一度怀疑是Feign对required=false的字段有特殊处理导致参数被丢。

4.2 抓包对比：请求体里根本没有remark这个part

我的第一反应是看实际发出的HTTP请求长什么样。在Feign的配置里打开日志：

logging: level: com.example.client.DocumentClient: DEBUG feign: DEBUG io.github.openfeign.form: DEBUG

然后把Feign实际发出的请求和Swagger发出的请求做了对比，重点看两个地方：Content-Type和请求体。

Swagger发出的multipart请求体里有三个part：

Content-Type: multipart/form-data; boundary=xxx --xxx Content-Disposition: form-data; name="file"; filename="a.pdf" Content-Type: application/pdf <文件内容> --xxx Content-Disposition: form-data; name="docType" contract --xxx Content-Disposition: form-data; name="remark" 加急处理 --xxx--

Feign发出的multipart请求体里只有两个part：

Content-Type: multipart/form-data; boundary=yyy --yyy Content-Disposition: form-data; name="file"; filename="a.pdf" Content-Type: application/pdf <文件内容> --yyy Content-Disposition: form-data; name="docType" contract --yyy--

remark压根没出现在请求体里。再仔细看URL，Feign发出的请求URL末尾是：

POST /document/upload?remark=%E5%8A%A0%E6%80%A5%E5%A4%84%E7%90%86

真相大白：remark被feign-form按@RequestParam处理，拼到了URL query string上，而服务端Controller的remark声明里没有配置query参数绑定，Spring的@RequestParam默认从query和表单里取值应该也能取到query参数啊？这里你可能会产生疑问。

问题出在一个微妙的细节：当服务端方法是multipart请求时，Spring的@RequestParam解析确实会从query string和multipart form field中都尝试取值。但有一种情况会踩雷：remark声明了required=false，且服务端在解析时优先取multipart里的part？实际上Spring的getParameter会合并query和form field，理论上query里的remark也能取到。

后来我重新确认了服务端接口的实际行为，发现这里的根因比想象中更简单也更气人——当时服务端Controller有一个全局过滤器，对document路径的请求做了校验，校验时调用了request.getParameterMap()强制解析了请求，而这个动作在某些Servlet容器版本下会提前消费掉multipart的内容，导致后续Spring解析multipart part时，只有Swagger那种“字段都在body里”的请求不受影响，Feign那种“query和part都带同名字段”的请求，解析顺序交叉时把remark吞了。

这个坑非常特定于容器和过滤器的组合，虽然不能作为普遍结论，但暴露了一个通用问题：@RequestParam字段到底从URL取还是从body取，一旦两边都带同名字段，中间任何一环做了参数解析，行为都可能不一致。

4.3 根因修复：文件走@RequestPart，字段明确走query

无论上面那个过滤器的细节如何，修复方案是明确的：让字段的传递方式在Feign调用中可预期、可复现。

最直接的修复是：Feign客户端里保留docType、remark为@RequestParam，但服务端Controller也明确把它们声明为可从query获取，并在Feign接口上把query字段显式写清楚。同时，把服务端接收文件的方式继续保持@RequestPart。

但更稳妥的做法，是调整参数设计，避免“同名字段既可能出现在query又可能出现在part”这种模糊地带。我最终的推荐方案是：

// 服务端：文件走part，字段走query，注解明确 @PostMapping(value = "/document/upload", consumes = MediaType.MULTIPART_FORM_DATA_VALUE) public Result<String> uploadDocument(@RequestPart("file") MultipartFile file, @RequestParam("docType") String docType, @RequestParam(value = "remark", required = false) String remark) { // 注意如果全局过滤器提前解析了multipart，需要排查是否复用request.contentType }

// Feign客户端：和Controller严格对齐，consumes必须声明 @PostMapping(value = "/document/upload", consumes = MediaType.MULTIPART_FORM_DATA_VALUE) Result<String> uploadDocument(@RequestPart("file") MultipartFile file, @RequestParam("docType") String docType, @RequestParam(value = "remark", required = false) String remark);

调用时，docType和remark会拼到URL query上，文件在body的part里。这是一个完全合法的HTTP请求格式，服务端只要不写奇怪的过滤器，@RequestParam从query里取这两个字段是稳定可靠的。

这里我多说一句：如果你希望字段也存在于multipart的form field中（而不是URL上），feign-form没有提供简单的注解开关。让Feign把字段塞进multipart part，通常的workaround是把字段放到一个POJO里，作为@RequestPart发送，服务端用@RequestPart("meta") MetaDTO meta接收。但这样一来字段就变成了JSON part，不再是普通的form field。所以遇到老接口一定要先确认服务端到底把字段放在哪里，再决定客户端Feign怎么写。

4.4 顺藤摸瓜：@RequestPart(required=false)在Feign里的表现

排查过程中业务方还提到了另一个问题：文件非必传的场景，Feign接口里写了@RequestPart(value = "file", required = false) MultipartFile file，当file为null时，feign-form在部分版本下会直接抛NPE，或者发一个空part过去导致服务端反序列化异常。

我自己实测下来，feign-form 3.8.0之后对null的@RequestPart参数处理得还算好，会直接不发送那个part。但旧版本确实存在把null包装成part发送的情况。如果你用的依赖比较老，遇到文件非必传的需求，建议：

• 升级feign-form到3.8.0以上，规避已知的null处理问题。
• 客户端Feign方法里不要直接传null，而是用Optional<MultipartFile>或者重载两个方法，一个传文件、一个不传文件，从源头避开null part的分支。
• 服务端对应参数保持@RequestPart(value = "file", required = false)，并做好文件为null时的业务兜底。

5. 沉淀下来的判断模板与Feign接口写法建议

5.1 三类常见接口的注解组合首选方案

踩过这些坑之后，我现在设计接口和写Feign客户端遵守一套很简单的模板，基本没再出过问题。

第一类：纯表单字段，无文件。如果走Feign，建议不要用@RequestParam散列参数去发urlencoded表单。OpenFeign对urlencoded表单最稳的写法还是用Map配合@RequestBody：

@PostMapping(value = "/form/submit", consumes = MediaType.APPLICATION_FORM_URLENCODED_VALUE) Result<String> submit(@RequestBody Map<String, ?> formBody);

服务端用@RequestParam接收每个字段或用一个POJO接收，都行。

第二类：单文件加少量简单字段。文件用@RequestPart，简单字段用@RequestParam走query，Feign和Controller两端保持一致：

@PostMapping(value = "/file/upload", consumes = MediaType.MULTIPART_FORM_DATA_VALUE) Result<String> upload(@RequestPart("file") MultipartFile file, @RequestParam("bizType") String bizType, @RequestParam(value = "remark", required = false) String remark);

第三类：多文件加结构化业务对象。文件字段用@RequestPart("files") List<MultipartFile> files，业务对象封装成POJO作为JSON part用@RequestPart("meta") MetaDTO meta接收。Feign端同样用@RequestPart声明，feign-form会把它序列化成JSON part。

5.2 如何在本地快速验证Feign发出的multipart请求格式

Feign的坑很多时候靠肉眼发现不了，最好在本地搭一个验证环境。我的做法是写一个临时Controller，专门打印收到的请求详情：

@PostMapping(value = "/debug/multipart", consumes = MediaType.MULTIPART_FORM_DATA_VALUE) public Map<String, Object> debug(@RequestPart(value = "file", required = false) MultipartFile file, @RequestParam Map<String, String> queryParams, HttpServletRequest request) { Map<String, Object> result = new HashMap<>(); result.put("contentType", request.getContentType()); result.put("queryParams", queryParams); if (file != null) { result.put("fileName", file.getOriginalFilename()); result.put("fileSize", file.getSize()); } return result; }

让Feign客户端指向这个debug接口，直接看返回的Map，就能确认文件part有没有发、字段是不是走query、Content-Type对不对。这个方法比抓包快捷得多，也不依赖外部环境。

如果还想看得更细，可以开启Feign请求日志：

logging: level: feign: DEBUG io.github.openfeign.form: DEBUG

feign-form在DEBUG级别会打印编码时对每个参数的处理方式，能看到哪个参数被当成了part、哪个参数被当成了URL变量、哪个Java类型不被支持。这些信息对定位问题帮助极大。

5.3 我个人的几个小习惯

最后分享几个我习惯性遵守的小原则，也算这么多年攒下来的经验。

第一，写上传接口之前先想一下“这个参数最终在HTTP报文里是什么形态”。如果它应该在multipart/form-data的一个独立part里，就用@RequestPart；如果它就是一个普通名值对，用@RequestParam就够了。这个判断做在前面，能省掉后面一大半排查时间。

第二，Feign接口里的注解要和服务端严格对齐，尤其是consumes不要省。很多人看到Controller能收就以为Feign也能收，实际上Feign方法的consumes直接决定了编码器怎么处理请求体，不声明就可能用错误的Content-Type分发到错误解析逻辑。

第三，涉及multipart的Feign调用，别在接口方法里直接传一个很大的POJO还指望它变成表单字段。feign-form对POJO的默认行为是序列化成JSON part，不是form field，这一点经常被误解。

第四，遇到@RequestParam参数在multipart请求里莫名丢失时，第一个排查动作永远是抓请求体和URL，而不是改注解。因为Feign的@RequestParam默认走URL query string，只要看URL就能基本断定数据有没有发出去。

这套组合拳打下来，我在Feign上传场景上的返工率明显下降。很多人觉得这几个注解差别不大，但HTTP报文不会骗人，参数在哪里，决定了一个接口能不能被各种客户端稳定调用。希望这篇记录能帮你少走几步弯路。