RestTemplate发送Post请求报错:414 URI Too Long问题及解决

黄金列车 · 发表于 2026-1-13 10:56:23

一、报错背景

使用RestTemplate发送http Post请求时，返回了一个报错 414 URI Too Long。

因为服务端是Post请求并用@RequestParam进行接收，所以我将参数都拼接在URL后面，如http://localhost:80/add?name=1&age=2 ,导致URL过长。

报错代码

RestTemplate restTemplate = new RestTemplate();

// 创建请求体
List<NameValuePair> params = new ArraysList<>();
params.add(new BasicNameValuePair("name","张三"));
params.add(new BasicNameValuePair("age","15"));
//....... 设置大量内容

// 设置请求头
HttpHeaders headers = new HttpHeaders();

// 创建HttpEntity对象
HttpEntity<String> httpEntity = new HttpEntity<>(null,headers);
URI uri = URI.create(url);
if(!CollectionUtils.isEmpty(params)){
	String param = URLEncodedUtils.format(params, StandardCharsets.UTF_8);
	uri = URI.create(url+"?"+param);
}
// 发送POST请求
String response = restTemplate.exchange(uri, HttpMethod.POST, httpEntity , String.class).getBody();

报错内容

org.springframework.web.client.HttpClientErrorException : 414 URI Too Long:"<h1>Bad Message 414</h1><pre>reason: URI Too Long</pre>"

二、问题分析：414 URI Too Long

HTTP状态码414表示客户端发送的请求URI过长，服务器拒绝处理。使用RestTemplate发送POST请求时出现该错误，通常是因为请求参数被错误地附加到URL中而非请求体中，导致URL超过服务器限制长度。

HTTP协议规定，请求的URI长度不能超过2083个字符。这是因为在HTTP/1.1协议中，请求行和请求头字段的总长度被限制在8192字节（不包括CRLF）。

2.1、常见原因

参数误放在URL中：POST请求本应将参数放在请求体（Body）中，但实际被拼接到了URL末尾。
RestTemplate配置问题：未正确配置HttpMessageConverter，导致参数无法序列化到请求体。
URL编码问题：参数中包含特殊字符未编码，进一步增加URL长度。

三、解决方法

本文报错是由于发送Post请求时，服务端的接口用的是@RequestParam接收参数，而不是json，所以以下整理几种方法发送@RequestParam入参类型的POST请求。

3.1、使用 LinkedMultiValueMap 处理表单数据(推荐)

本方法是将请求参数放到请求体中，不占用URI的长度，所以就算请求体比较大，也不会报414 URI Too Long的错误。

示例：

RestTemplate restTemplate = new RestTemplate();

HttpHeaders headers = new HttpHeaders();
// 设置内容类型为 application/x-www-form-urlencoded
headers.setContentType(MediaType.APPLICATION_FORM_URLENCODED);

// 使用 MultiValueMap 存放表单数据
MultiValueMap<String, String> formData = new LinkedMultiValueMap<>();
formData.add("key1", "value1");
formData.add("key2", "value2");
// ... 可以添加很多对，只要不超出服务器对Body大小的通常宽松限制

HttpEntity<MultiValueMap<String, String>> requestEntity = new HttpEntity<>(formData, headers);

ResponseEntity<String> response = restTemplate.postForEntity(
    "http://your-api-endpoint.com/api/resource", 
    requestEntity, 
    String.class
);

3.2、将参数拼接到URI上

如果你只是想在URL中包含查询参数，可以使用Uri来构建URL。

RestTemplate restTemplate = new RestTemplate();

// 创建请求体
List<NameValuePair> params = new ArraysList<>();
params.add(new BasicNameValuePair("name","张三"));
params.add(new BasicNameValuePair("age","15"));
//....... 设置大量内容

// 设置请求头
HttpHeaders headers = new HttpHeaders();

// 创建HttpEntity对象
HttpEntity<String> httpEntity = new HttpEntity<>(null,headers);
URI uri = URI.create(url);
if(!CollectionUtils.isEmpty(params)){
	String param = URLEncodedUtils.format(params, StandardCharsets.UTF_8);
	uri = URI.create(url+"?"+param);
}
// 发送POST请求
String response = restTemplate.exchange(uri, HttpMethod.POST, httpEntity , String.class).getBody();

四、避免误区

不要使用RestTemplate的getForObject发送 POST 请求（GET 请求参数只能在 URL 中，本身就容易触发 414）。
即使是 POST 请求，若通过url + “?key=” + value拼接参数，本质仍是将参数放在 URL 中，会导致同样的错误。
若接口必须要求参数在 URL 中（不符合 POST 规范，但某些旧接口可能如此），则需要缩短参数长度，或联系服务器端放宽 URL 长度限制（不推荐，因为 URL 长度本身有协议限制）。

五、总结

以上为个人经验，希望能给大家一个参考，也希望大家多多支持琼殿技术社区。

您可能感兴趣的文章:

Java RestTemplate post请求参数问题及解决
RestTemplate().postForEntity的参数使用及说明
使用restTemplate.postForEntity()的问题
RestTemplate如何使用JSON发送Post请求
RestTemplate报错I/O error on POST request for的解决办法
restTemplate发送get与post请求并且带参数问题
RestTemplate调用POST和GET请求示例详解
RestTemplate发送HTTP POST请求使用方法详解

[教程] RestTemplate发送Post请求报错:414 URI Too Long问题及解决

目录