restTemplate这个类，基本是Spring项目里绕不开的HTTP客户端工具。我接手过不少老项目，Controller里调第三方接口的代码十有八九是new RestTemplate然后getForObject，看起来一切正常，真跑到线上就开始出幺蛾子。这篇东西我想一次性把restTemplate的常规用法、文件上传、异常处理这些事讲透，尤其把multipart上传这种容易翻车的点单独拎出来说。适合平时要写接口调用的后端开发，也适合刚把Spring Boot项目跑起来、准备对接别人系统的新手。
我觉得很多人对restTemplate都有个误解，觉得它就是一个"能用就行的简单工具"，压根没去关注底层连接、错误处理、超时配置这些东西。但实际踩过坑之后你会发现，所有线上事故几乎都集中在几个固定的位置上。下面我就按自己平时写接口调用的顺序，把restTemplate从初始化到文件上传再到性能调优一次性讲清楚。
1. 先捋清楚RestTemplate在项目里的真实定位
1.1 它和HttpClient、OkHttp、Feign到底啥关系
RestTemplate是Spring框架提供的一个同步HTTP客户端，它的核心特点是把HttpURLConnection、Apache HttpClient、OkHttp这些底层客户端包装成了一层更友好的API。也就是说，RestTemplate本身并不发网络请求，真正干活的是底层那些客户端，RestTemplate做的是把URL、请求头、请求体、响应体这些Java对象和HTTP协议之间的转换工作。
我在项目里遇到过不少人直接说"我用RestTemplate不用HttpClient"，其实这种说法不太准确。RestTemplate默认走的是JDK自带的HttpURLConnection，但你完全可以给它换成Apache HttpClient或者OkHttp作为底层实现，换完之后API还是同一套，这就是Spring封装的价值。换个说法，RestTemplate好比是前台接待，HttpClient这些才是真正干活的人，你跟前台说话，前台帮你转达。
再对比一下Feign。Feign是声明式HTTP客户端，你只需要定义一个接口，配上注解，Spring Cloud会帮你生成代理实现。RestTemplate则更偏向于命令式，你手动拼URL、手动设置请求头。在很多Spring Boot项目里，如果只是简单调用一两个第三方接口，很多人懒得把整个Feign体系引进来，直接注入一个RestTemplate完事，这也是restTemplate到今天依然活得好好的原因。
1.2 什么时候该用RestTemplate、什么时候该换
我自己的判断标准很简单：同步、低频、业务逻辑简单，就用RestTemplate；异步、高并发、需要连接池精细化管控，就考虑WebClient或者自己封装HttpClient。
举个实际例子，我之前做过一个对接短信网关的服务，每天就发几万条短信，每条短信调用一次网关接口，这完全在RestTemplate的能力范围内。但如果你的服务是每秒几百上千次的调用，而且对时延敏感，那RestTemplate默认的HttpURLConnection就不太行了，这时候应该用带连接池的HttpComponentsClientHttpRequestFactory，或者干脆考虑WebClient走异步。
还有个场景也值得提，那就是老项目的技术债。很多老项目里躺着几百处RestTemplate调用，代码风格五花八门，这时候不是让你全部推倒重来，而是至少统一超时配置、统一错误处理、统一日志，把这些基础设施做扎实，RestTemplate本身完全够用。
2. 从零搭建：实例化方式与底层连接工厂的选择
2.1 直接new和Spring Boot自动装配的区别
最简单的用法是这样：
RestTemplate restTemplate = new RestTemplate();这行代码十秒钟就能写完，但它有两个问题。第一，每次new都会重新创建一个RestTemplate实例，如果是在工具类里每次调用都new一次，那连接资源完全没法复用；第二，所有配置都是默认值，连超时时间都没设置，一旦下游接口卡住，你的线程就可能一直挂着。
Spring Boot项目里我更推荐用RestTemplateBuilder来构建：
@Configuration public class RestTemplateConfig { @Bean public RestTemplate restTemplate(RestTemplateBuilder builder) { return builder .setConnectTimeout(Duration.ofSeconds(3)) .setReadTimeout(Duration.ofSeconds(10)) .build(); } }RestTemplateBuilder是Spring Boot自动配置里的好东西，它会根据你在application.yml里配置的spring.rest-template相关属性自动设置超时，也允许你在代码里链式追加设置。而且这样构建出来的RestTemplate是单例Bean，可以注入到任何地方使用。
这里有个特别重要的认知：RestTemplate本身是线程安全的，只要你不往里面塞有状态的拦截器或HttpMessageConverter，完全可以全局单例使用。我经常看到有人因为不知道这点，在Service里每次调用方法都new一个，这种习惯在高并发场景下很容易把连接资源打满。
2.2 三个ClientHttpRequestFactory的取舍
之前说了，RestTemplate底层可以换，靠的就是ClientHttpRequestFactory这个接口。实际项目中常见的三个实现，我整理了一个对比表格：
| 工厂实现 | 底层客户端 | 连接池 | 适用场景 |
|---|---|---|---|
| SimpleClientHttpRequestFactory | JDK HttpURLConnection | 无，复用较弱 | 开发调试、极低并发 |
| HttpComponentsClientHttpRequestFactory | Apache HttpClient | 有，可精细配置 | 生产环境、高并发 |
| OkHttp3ClientHttpRequestFactory | OkHttp | 有 | Android过来的团队常用 |
代码上来看，如果选HttpComponents，要先引入依赖：
<dependency> <groupId>org.apache.httpcomponents</groupId> <artifactId>httpclient</artifactId> </dependency>然后这样配置：
@Bean public RestTemplate restTemplate(RestTemplateBuilder builder) { HttpClient httpClient = HttpClientBuilder.create() .setMaxConnTotal(200) .setMaxConnPerRoute(50) .setConnectionTimeToLive(30, TimeUnit.SECONDS) .build(); HttpComponentsClientHttpRequestFactory factory = new HttpComponentsClientHttpRequestFactory(httpClient); factory.setConnectTimeout(3000); factory.setReadTimeout(10000); return new RestTemplate(factory); }如果用了HttpComponents，那默认情况下的连接管理就交给Apache HttpClient了，MaxConnPerRoute是每个路由的最大连接数，MaxConnTotal是整个客户端的总连接数。这个数量没有标准答案，要根据下游接口的并发量来评估，我一般先给一个保守值，再通过监控看连接池的实际使用率再调整。
有一点要提醒大家：SimpleClientHttpRequestFactory虽然简单，但它对PATCH请求的支持不友好，默认方式下想要发PATCH会报错。如果你的接口里恰好要调用PATCH方法，直接用Apache HttpClient那一套最省心。
3. 最常用方法拆解：getForObject、postForObject、exchange到底怎么选
3.1 URI传参的三种写法和坑
RestTemplate请求方法非常多，但高频的无非就是getForObject、postForObject、getForEntity、postForEntity、exchange这几个。我们先从最基础的方法签名说起。
我见过最多的问题是URL参数拼接错误。三种写法对比一下：
// 写法一：直接拼字符串，不推荐，容易出编码问题 String url1 = "http://localhost:8080/user?id=" + userId; // 写法二：占位符，推荐 String url2 = "http://localhost:8080/user?id={id}"; User user = restTemplate.getForObject(url2, User.class, userId); // 写法三：Map传参，适合参数多的情况 Map<String, Object> params = new HashMap<>(); params.put("id", userId); params.put("type", 1); User user = restTemplate.getForObject("http://localhost:8080/user?id={id}&type={type}", User.class, params);用占位符的好处是Spring会帮你做URL编码。有一次我在对接一个搜索接口，关键词里带了个中文逗号，用字符串拼接直接发出去，服务端那边收到的就是乱码，排查了很久才发现是URL没有编码。换成占位符写法之后就没再出过这个问题。
另外要注意：占位符可以传多个参数，restTemplate.getForObject(url, clazz, id, type)这种按顺序匹配没问题，但如果你传的是一个List或者数组，一定要确保数量和占位符数量一致。少了会直接抛异常，多了会静默忽略，后者更隐蔽。
3.2 想拿响应头怎么办：终于轮到exchange上场
getForObject和getForEntity的区别，一句话就能说清：getForObject只关心响应体，getForEntity把响应体和响应头、状态码一起包在ResponseEntity里。但如果你既要自定义请求头，又要读响应头，那最好还是用exchange。
我当年对接一个文件下载接口时就遇到这种情况，接口把文件的元信息放在响应头里，Content-Disposition里有文件名，响应体是文件流。用getForObject拿不到头信息，用exchange就非常方便：
HttpHeaders headers = new HttpHeaders(); headers.set("Authorization", "Bearer " + token); RequestEntity<Void> requestEntity = RequestEntity .get("http://localhost:8080/download") .headers(headers) .build(); ResponseEntity<byte[]> response = restTemplate.exchange(requestEntity, byte[].class); String contentDisposition = response.getHeaders().getFirst("Content-Disposition"); byte[] fileBytes = response.getBody();exchange的通用性很强，它既能带上自定义请求头，也能拿到完整的响应元数据，所以很多人在项目里干脆只封装exchange，其他方法都不用了。这种思路也没什么问题，只是代码会稍微啰嗦一点。
3.3 execute的底层到底在干嘛
再往底层挖一层，是execute方法。getForObject、postForObject、exchange这些方法，最后都会调用execute。execute允许你传入一个RequestCallback来加工请求，再用ResponseExtractor来解析响应。
我平时不直接写execute，但理解它的存在对排查问题很有帮助。有一次线上有个接口偶发超时，我在日志里看到restTemplate抛了ResourceAccessException，第一反应就是看底层连接工厂是什么、超时时间配了多少，顺着execute这条调用链很快就能定位到是哪一层出了问题。这也是我建议多了解一点底层机制的原因，遇到报错时能快速判断是连接问题、超时问题还是序列化问题。
4. multipart文件上传的完整姿势与翻车记录
4.1 为什么大部分人的第一次上传都失败
文件上传这块，是我见过踩坑最多的场景。很多人的第一反应是把File直接塞到Map里，像这样：
// 错误写法，别学 MultiValueMap<String, Object> body = new LinkedMultiValueMap<>(); body.add("file", new File("/tmp/test.txt"));这样写的问题在于：File不是Spring能识别为文件资源的类型，它会被当成form-data里的普通字符串字段处理，最终请求没有multipart结构，服务端用@RequestParam("file")自然接不到东西。
正确的做法是用Spring提供的Resource实现：
body.add("file", new FileSystemResource(new File("/tmp/test.txt")));或者读成字节后，用ByteArrayResource：
body.add("file", new ByteArrayResource(bytes));之所以要用Resource，是因为FormHttpMessageConverter在转换请求体时会检查value的类型，遇到Resource就会把它编码成文件part，其他类型都按普通字段处理。
4.2 一个能跑通的multipart上传模板
我直接把一个验证过能用的模板贴出来：
public String uploadFile(String url, File file, String remark) { HttpHeaders headers = new HttpHeaders(); headers.setContentType(MediaType.MULTIPART_FORM_DATA); LinkedMultiValueMap<String, Object> body = new LinkedMultiValueMap<>(); body.add("file", new FileSystemResource(file)); body.add("remark", remark); HttpEntity<LinkedMultiValueMap<String, Object>> requestEntity = new HttpEntity<>(body, headers); RestTemplate restTemplate = new RestTemplate(); return restTemplate.postForObject(url, requestEntity, String.class); }映射到服务端，接收方式大概是这样的：
@PostMapping("/upload") public String upload(@RequestPart("file") MultipartFile file, @RequestParam("remark") String remark) { // 业务逻辑 }body里的key必须和服务端的参数名一致，这个看起来不起眼的点，我见人踩过不止一次。你这里add("file")，服务端用@RequestPart("uploadFile")，两边对不上，接口直接报"Required request part is missing"。
还有一点要注意，头里的Content-Type虽然设了MULTIPART_FORM_DATA，但你千万不要手动去设置boundary。很多人为了让Content-Type看起来更完整，手动加了一句"boundary=xxx"，结果Spring在编码时又要自己生成boundary，两边不一致，服务端直接解析失败。正确做法就是只设置MediaType.MULTIPART_FORM_DATA，剩下交给FormHttpMessageConverter处理。
4.3 中文文件名、二次转码、超时这些暗坑
文件上传还有几个暗坑，我单独拿出来说。
第一个是中文文件名。如果直接new FileSystemResource，资源名就是文件路径，Spring在组装Content-Disposition头时会拿getFilename()当文件名，中文经常会被清理掉或者转成乱码，服务端收下来的文件名惨不忍睹。我的解决办法是自定义一个Resource子类：
public class Utf8FileNameResource extends ByteArrayResource { private final String fileName; public Utf8FileNameResource(byte[] byteArray, String fileName) { super(byteArray); this.fileName = fileName; } @Override public String getFilename() { return fileName; } }这样可以稳定控制文件名。不过如果对接的是比较老的服务端，对Content-Disposition里的UTF-8编码解析支持不好，可能还是会出现乱码。这种情况下最稳妥的办法是和服务端约定：文件名统一用ASCII字符，或者由调用方进行一次编解码处理。
第二个坑是异常导致的连接残留。文件上传属于耗时操作，如果服务端处理慢，响应时间很容易超过readTimeout。我建议给上传接口单独设置一个较大的超时时间，尤其是图片、视频这类资源。我的做法是给文件上传单独定义一个RestTemplate实例，专门配一个长一点的readTimeout，不带业务调用一个默认的断开。
第三个坑是内存占用。如果你用ByteArrayResource上传大文件，整个文件都会加载到内存，几百MB的文件直接可能OOM。大文件一般直接用FileSystemResource，避免一次性读进内存。
5. 拦截器、异常处理与消息转换器：让RestTemplate不再裸奔
5.1 用拦截器统一打日志和塞Token
RestTemplate支持拦截器，每次请求发出前、接收到响应后都会经过它。最常见的场景是两个：统一添加请求头、统一打印日志。
实现ClientHttpRequestInterceptor接口：
public class LoggingInterceptor implements ClientHttpRequestInterceptor { @Override public ClientHttpResponse intercept(HttpRequest request, byte[] body, ClientHttpRequestExecution execution) throws IOException { // 请求前打印日志 System.out.println("Request URI: " + request.getURI()); System.out.println("Request Method: " + request.getMethod()); System.out.println("Request Body: " + new String(body, StandardCharsets.UTF_8)); // 执行实际请求 ClientHttpResponse response = execution.execute(request, body); // 响应后打印状态码 System.out.println("Response Status: " + response.getStatusCode()); return response; } }注册也简单：
RestTemplate restTemplate = new RestTemplate(); restTemplate.getInterceptors().add(new LoggingInterceptor());用RestTemplateBuilder时，可以在构建的时候传入多个拦截器：builder.interceptors(loggingInterceptor, tokenInterceptor)。
要注意的是：拦截器里尽量不要做耗时操作，比如往远程日志服务发日志，因为在拦截器里做一次网络请求，会让你的主线程多等一次RTT，整个接口耗时直接翻倍。我自己吃过这个亏，后来改成了异步日志。
塞Token的拦截器也很常见：
public class TokenInterceptor implements ClientHttpRequestInterceptor { @Override public ClientHttpResponse intercept(HttpRequest request, byte[] body, ClientHttpRequestExecution execution) throws IOException { request.getHeaders().set("Authorization", "Bearer " + getToken()); return execution.execute(request, body); } }有了这样一个拦截器，你就不用在每个请求前都手动加Header了，对代码整洁度帮助很大。
5.2 别让默认异常处理吞掉你的排错信息
RestTemplate默认的错误处理是DefaultResponseErrorHandler，它对4xx和5xx响应会抛出HttpClientErrorException或HttpServerErrorException。这个默认行为看起来没什么，但实际排查问题的时候你会发现：异常里的响应体经常是一堆HTML或者过长的错误信息，真正对排查问题的关键字段反而被淹没了。
我一般会自定义一个ResponseErrorHandler，把错误体的内容读出来，在异常里附上接口地址和状态码：
public class CustomResponseErrorHandler implements ResponseErrorHandler { @Override public boolean hasError(ClientHttpResponse response) throws IOException { return response.getStatusCode().is4xxClientError() || response.getStatusCode().is5xxServerError(); } @Override public void handleError(ClientHttpResponse response) throws IOException { String body = new String(response.getBody().readAllBytes(), StandardCharsets.UTF_8); throw new CustomApiException( "HTTP " + response.getStatusCode().value() + ", body: " + body ); } }这样在catch异常的时候，错误信息里直接能看到第三方接口返回的具体内容，不用再去翻日志和抓包。还有一个细节：handleError里读完body之后，这个响应流就被消费了，如果你想在异常处理器之外再读一次，是读不到内容的。所以要么在handler里把所有信息都取出来完整地放进异常，要么就不要在handler外面继续依赖响应体了。
5.3 中文乱码的根源：StringHttpMessageConverter
中文乱码问题，很多人会归咎于"编码不对"，但RestTemplate里真正导致乱码的，往往是StringHttpMessageConverter默认使用ISO-8859-1来解码响应体。如果你的服务端返回的是UTF-8，而客户端用ISO-8859-1去解，中文自然就成了问号或乱码。
解决方案很简单，把StringHttpMessageConverter的默认编码改成UTF-8：
RestTemplate restTemplate = new RestTemplate(); // 移除默认的StringHttpMessageConverter，换成UTF-8版本的 List<HttpMessageConverter<?>> converters = restTemplate.getMessageConverters(); converters.removeIf(converter -> converter instanceof StringHttpMessageConverter); converters.add(0, new StringHttpMessageConverter(StandardCharsets.UTF_8)); restTemplate.setMessageConverters(converters);这个坑在对接一些老接口时特别常见，服务端明明返回的是规范的UTF-8 JSON，客户端却用ISO-8859-1去解码，导致JSON里所有中文全部乱码。排查的时候不要光盯着响应头里的Content-Type，也要看看项目里有没有人动过messageConverters。
6. 连接池与会话保持：性能和状态这两件事踩过才算懂
6.1 HttpURLConnection为什么不适合高并发
默认的RestTemplate底层是JDK自带HttpURLConnection。这个实现最大的问题在于连接复用能力弱，每个连接用完就关，频繁创建销毁TCP连接，在高并发场景下就是灾难。
我见过一个项目，线上接口平均响应时间是800ms，但调用方通过RestTemplate请求时，p99却到了5秒。后来一看，默认的SimpleClientHttpRequestFactory，每次请求都在建TCP连接，而目标服务端在带宽和句柄上都出现了瓶颈。换成了HttpComponents之后，连接池把连接复用起来，p99直接降到了1秒以内。
所以我在前面就强调过：生产环境尽量用HttpComponentsClientHttpRequestFactory，不要图省事用默认工厂。连接池配置方面，有两个参数必须心里有数：
| 参数 | 含义 | 建议 |
|---|---|---|
| setMaxConnTotal | 整个客户端的最大连接数 | 根据下游接口并发量评估 |
| setMaxConnPerRoute | 单个目标路由的最大连接数 | 一般小于等于MaxConnTotal |
我的经验是，刚开始可以按照目标接口预期QPS的1/10来配置，比如预期每秒100次调用，那每个路由可以先给10到20个连接，再配合超时和监控慢慢调优。
6.2 Cookie和Session怎么处理
很多内部系统之间调用时，接口依赖Session，要求客户端先登录拿Cookie，再带着Cookie访问业务接口。RestTemplate本身不会帮你管理Cookie，默认的HttpURLConnection虽然有一点Cookie存储机制，但一旦你切换到底层客户端，行为就不一样了。
我的做法是手动管理Cookie，在登录接口拿到Set-Cookie之后，手动塞到后续请求的Header里：
HttpHeaders headers = new HttpHeaders(); headers.set(HttpHeaders.COOKIE, "JSESSIONID=" + sessionId); HttpEntity<Void> requestEntity = new HttpEntity<>(headers); ResponseEntity<String> response = restTemplate.exchange(url, HttpMethod.GET, requestEntity, String.class);如果用的是Apache HttpClient那一套，也可以配置一个BasicCookieStore，让HttpClient自动管理Cookie。但我个人不太推荐为了Cookie引入复杂的会话状态管理，因为会降低接口调用的无状态性，更容易隐藏Bug。除非对接的是那种没法改的老系统，否则还是尽量让服务端支持基于Token的认证方式。
6.3 性能排查与超时参数的合理设置
超时配置是整个RestTemplate使用中最重要的一件事，没有之一。我的建议是，connectTimeout和readTimeout一定要显式设置，绝不能用默认值无限等。默认情况下，如果服务端一直不返回，你的线程就可能一直挂在那里，资源被占着不放，最终拖垮整个应用。
connectTimeout是指建立连接的超时时间，一般2到3秒就够了；readTimeout是指建立连接后等待响应数据的时间，这个要根据业务接口的耗时来定，一般内部接口给5秒，外部接口给10秒，文件上传给30秒甚至更长。
我曾经遇到一个情况：一个接口偶尔会触发服务端一个很慢的统计任务，3000ms的readTimeout经常被触发，导致线上偶发超时告警。后来把readTimeout调到10秒，配合重试机制，问题就消失了。这里要再提一句，重试要根据接口的幂等性谨慎开启。GET请求重试一般没问题，POST请求如果下游接口没做幂等，重试可能造成重复下单或重复扣款，我踩过的这个坑比超时本身更惨。
还有个性能排查的技巧，如果怀疑RestTemplate请求慢，先确认慢在哪个环节。用一个简单的办法：在拦截器里分别记录执行前、执行后的时间戳，打印到日志里，就能看出建连耗时、请求耗时、解析耗时分别是多少。实际上一次执行中时间主要花在等待响应上，如果建连那一步耗费了上百毫秒，多半是连接池不足或没有连接池，优先去优化连接复用，而不是盲目调大readTimeout。
最后再分享一个小习惯：我会在项目里把RestTemplate封装成一个Client类，统一放超时配置、拦截器、错误处理、消息转换器，业务代码只负责传URL和参数。这样做的好处是，线上出问题时，你只需要在一个地方改配置和逻辑，而不是去几百处调用点逐个排查。RestTemplate这个工具本身不算复杂，复杂的是你围绕它做的工程化设计是否到位。
