使用RestTemplate调用API报401 Unauthorized未授权异常排查

使用RestTemplate调用接口时抛出401未授权异常，业务代码如下：

@GetMapping("/testapi1")
public String testapiq(UriComponentsBuilder builder) {
    String uri = "http://xxxxx/api/TestCases/4";
    RestTemplate restTemplate = new RestTemplate();
        
    HttpHeaders headers = new HttpHeaders();
    headers.set("Accept", MediaType.APPLICATION_JSON_VALUE);
    HttpEntity<String> request = new HttpEntity<String>(headers);
    ResponseEntity<TestCase> responseTC = restTemplate.exchange(uri, HttpMethod.GET, request, TestCase.class);
    System.out.println(responseTC.getBody());
    return "list-testcases";
}

核心报错关键信息：

org.springframework.web.client.HttpClientErrorException$Unauthorized: 401 Unauthorized: "401 - 未授权：因凭据无效导致访问被拒绝。你无权使用所提供的凭据查看该目录或页面。"
异常抛出位置：com.sse.controller.HomeController.testapiq(HomeController.java:127)，即RestTemplate调用exchange方法的代码行。

401 Unauthorized是HTTP标准状态码，含义是请求缺少有效的身份认证凭证。当前构造的请求仅设置了Accept头声明接收JSON格式响应，完全没有携带目标接口要求的身份校验信息，因此被服务端鉴权拦截，拒绝返回资源。

先查阅目标接口的文档，确认其要求的认证方式，在请求头中补充合法的认证凭证即可，常见场景的代码示例：

• Basic 基础认证

import java.nio.charset.StandardCharsets;
import java.util.Base64;

String account = "接口分配的用户名:接口分配的密码";
String encodedAccount = Base64.getEncoder().encodeToString(account.getBytes(StandardCharsets.UTF_8));
headers.set("Authorization", "Basic " + encodedAccount);

• Bearer Token认证（JWT、开放平台令牌最常用的方式）

headers.set("Authorization", "Bearer 你获取到的有效访问令牌");

• 自定义请求头传API Key的认证模式

// 替换为接口文档指定的头字段名和你的密钥
headers.set("X-API-Key", "你的接口访问密钥");

额外优化建议：

• 不要在接口方法内部每次调用都新建RestTemplate实例，建议在配置类中将RestTemplate注册为单例Bean统一复用，减少连接资源浪费
• 补充凭证有效性校验：确认使用的账号/令牌没有过期、没有拼写错误，且持有目标接口路径的访问权限
• 如果目标服务是IIS托管、开启了Windows集成认证，需要额外给RestTemplate配置NTLM认证工厂，仅传头信息无法通过校验

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