一、核心定位：测试场景下的 HTTP 请求模拟工具
- 适用场景 ：在 Spring Boot 的
@SpringBootTest集成测试中，测试 Controller 层的接口（GET/POST/PUT/DELETE 等），验证接口的请求参数、响应状态、返回数据是否符合预期； - 核心优势 ：相比原生
RestTemplate，TestRestTemplate自动适配 Spring Boot 的测试环境（如自动识别测试端口、支持表单 / JSON 请求、简化响应处理），无需手动配置请求头、URL 拼接等； - 归属 ：属于
org.springframework.boot.test.web.client包，是 Spring Boot 测试 starter（spring-boot-starter-test）的核心组件，引入依赖后可直接使用。
二、基础使用：三步搞定接口测试
1. 前置条件（依赖 + 测试类注解）
首先确保项目引入测试依赖（Spring Boot 项目默认已引入）：
xml
<!-- pom.xml 核心测试依赖，包含TestRestTemplate -->
<dependency>
<groupId>org.springframework.boot</groupId>
<artifactId>spring-boot-starter-test</artifactId>
<scope>test</scope>
</dependency>测试类需添加@SpringBootTest，并指定webEnvironment（模拟 Web 环境）：
java
运行
import org.springframework.boot.test.context.SpringBootTest;
import org.springframework.boot.test.web.client.TestRestTemplate;
import org.springframework.beans.factory.annotation.Autowired;
import org.junit.jupiter.api.Test;
// webEnvironment = RANDOM_PORT：启动随机端口，避免端口冲突
@SpringBootTest(webEnvironment = SpringBootTest.WebEnvironment.RANDOM_PORT)
public class UserControllerTest {
// 自动注入TestRestTemplate（Spring测试上下文会自动创建实例）
@Autowired
private TestRestTemplate testRestTemplate;
}2. 核心 API：模拟各类 HTTP 请求
TestRestTemplate封装了常用的 4种HTTP 方法，语法简洁，贴合你熟悉的 RESTful 风格：
表格
| 请求类型 | 核心方法 | 适用场景 |
|---|---|---|
| GET | getForObject(String url, Class<T> responseType, Object... urlVariables) |
获取接口返回的对象（如查询用户信息） |
| POST | postForObject(String url, Object request, Class<T> responseType) |
提交 JSON / 表单数据（如创建用户） |
| PUT | put(String url, Object request) |
更新数据（如修改用户信息） |
| DELETE | delete(String url) |
删除数据（如删除用户） |
| 通用请求 | exchange(String url, HttpMethod method, HttpEntity<?> request, Class<T> responseType) |
自定义请求头 / 请求体（如带 Token 的请求） |
3. 实战示例（测试你熟悉的 UserController 接口）
假设你有一个用户登录接口POST /login，接收UserDTO参数，返回Result响应：
java
运行
// 第一步：定义和接口匹配的DTO、Result（和业务代码一致）
public class UserDTO {
private String username;
private String password;
// 省略getter/setter
}
public class Result {
private int code;
private String msg;
private Object data;
// 省略getter/setter
}
// 第二步：编写测试方法
@Test
public void testLogin() {
// 1. 构造请求参数（模拟前端传参）
UserDTO userDTO = new UserDTO();
userDTO.setUsername("admin");
userDTO.setPassword("123456");
// 2. 发送POST请求，调用/login接口，接收Result类型的响应
// 注意：url无需写端口，TestRestTemplate自动适配测试环境的端口
Result result = testRestTemplate.postForObject("/login", userDTO, Result.class);
// 3. 断言验证响应是否符合预期（核心：验证接口逻辑）
assert result != null;
assert result.getCode() == 200; // 验证响应码
assert "登录成功".equals(result.getMsg()); // 验证响应信息
}三、关键特性（适配测试场景的核心能力）
-
自动适配测试端口 ：使用
@SpringBootTest(webEnvironment = RANDOM_PORT)时，TestRestTemplate会自动拼接测试服务的实际端口，无需手动写http://localhost:8080； -
支持认证 / 请求头自定义 ：测试需要登录权限的接口时，可添加请求头（如 Token）：
java
运行
// 构造带Token的请求头 HttpHeaders headers = new HttpHeaders(); headers.set("Authorization", "Bearer " + token); // 封装请求体+请求头 HttpEntity<UserDTO> requestEntity = new HttpEntity<>(userDTO, headers); // 发送请求 Result result = testRestTemplate.postForObject("/user/add", requestEntity, Result.class); -
简化响应处理 ：除了
getForObject/postForObject（直接返回目标对象），还可使用getForEntity/postForEntity获取完整的响应（包含状态码、响应头）：java
运行
// 获取完整响应对象 ResponseEntity<Result> responseEntity = testRestTemplate.postForEntity("/login", userDTO, Result.class); // 验证响应状态码（200 OK） assert responseEntity.getStatusCode().is2xxSuccessful(); // 获取响应体 Result result = responseEntity.getBody(); -
兼容表单请求 ：测试表单提交接口时，可传入
MultiValueMap模拟表单参数：java
运行
MultiValueMap<String, String> formData = new LinkedMultiValueMap<>(); formData.add("username", "admin"); formData.add("password", "123456"); Result result = testRestTemplate.postForObject("/login", formData, Result.class);
四、和 RestTemplate 的核心区别（避免混淆）
表格
| 特性 | TestRestTemplate | RestTemplate |
|---|---|---|
| 核心用途 | 集成测试（模拟前端请求） | 业务代码中发送 HTTP 请求（调用第三方接口） |
| 环境适配 | 自动适配 Spring Boot 测试环境 | 需手动配置 URL、端口、请求头 |
| 依赖范围 | test 范围（仅测试代码中使用） | 主程序范围（业务代码中使用） |
| 异常处理 | 测试友好（返回详细的失败信息） | 需手动捕获处理异常 |
五、避坑点（新手易踩）
- 测试类必须加
@SpringBootTest，且webEnvironment不能为MOCK（MOCK 环境不启动真实 Web 服务，无法发送 HTTP 请求）； - 接口 URL 不要加端口和上下文路径，
TestRestTemplate会自动拼接； - 响应对象（如
Result）必须有无参构造器和 getter/setter，否则 JSON 反序列化会失败。
总结
TestRestTemplate是 Spring Boot 专为集成测试设计的 HTTP 客户端，核心用于测试 Controller 层接口；- 它封装了
RestTemplate，自动适配测试环境，简化了请求发送和响应处理； - 核心用法是：注入实例 → 构造请求参数 → 调用 HTTP 方法 → 断言验证响应；
- 仅在测试代码中使用，业务代码中仍用
RestTemplate/WebClient调用第三方接口。