当前位置：首页 > news >正文

Spring Boot项目通过RestTemplate调用三方接口详细教程

news 2025/8/13 16:04:41

一、简单说明

1. 准备工作

2. 添加依赖

3. 配置RestTemplate Bean

4. 使用RestTemplate发送请求

5. 处理响应

6. 错误处理

7. 完整示例：集成到Controller

8. 注意事项和最佳实践

二、抽象设计

1. 通用API服务类设计

2. 业务服务类实现

3. 控制器调用示例

4. 定时任务示例

5.关键设计说明：

在Spring Boot项目中，使用RestTemplate调用第三方接口是一种常见的HTTP客户端操作。RestTemplate是Spring框架提供的一个简单、同步的HTTP客户端工具，支持发送GET、POST等请求，并处理响应。本教程将逐步指导您完成整个过程，确保结构清晰、易于理解。教程基于Spring Boot 2.x版本（如2.7.x），如果您使用Spring Boot 3.x，部分配置可能需调整（例如，RestTemplate不再自动配置，需手动添加依赖和Bean）。

一、简单说明

1. 准备工作

确保项目已创建：如果您还没有Spring Boot项目，请先创建一个。可以使用Spring Initializr生成项目，选择以下依赖：
- Spring Web (spring-boot-starter-web)
项目结构：确保您的项目包含基本的Spring Boot结构，如src/main/java、pom.xml文件等。
第三方接口信息：准备好要调用的第三方接口URL、请求方法（GET/POST等）、请求参数和响应格式（如JSON）。例如，假设我们调用一个天气API：https://api.weather.com/data?city=Beijing。

2. 添加依赖

在Spring Boot 2.x中，spring-boot-starter-web已包含RestTemplate。打开pom.xml文件，添加或确认以下依赖：

<dependencies><dependency><groupId>org.springframework.boot</groupId><artifactId>spring-boot-starter-web</artifactId></dependency><!-- 如果需要JSON处理，添加Jackson依赖（通常已包含在starter-web中） -->
</dependencies>

保存文件后，运行mvn clean install或使用IDE重新加载项目。

3. 配置RestTemplate Bean

RestTemplate需要被Spring容器管理。创建一个配置类来定义Bean。

在项目中新建一个类，例如RestTemplateConfig.java：

import org.springframework.context.annotation.Bean;
import org.springframework.context.annotation.Configuration;
import org.springframework.web.client.RestTemplate;@Configuration
public class RestTemplateConfig {@Beanpublic RestTemplate restTemplate() {return new RestTemplate();}
}

说明：

@Configuration注解标记为配置类。
@Bean方法创建RestTemplate实例，Spring会自动注入到其他组件。

如果需要自定义（如设置超时），可以添加HttpComponentsClientHttpRequestFactory：

@Bean
public RestTemplate restTemplate() {HttpComponentsClientHttpRequestFactory factory = new HttpComponentsClientHttpRequestFactory();factory.setConnectTimeout(5000); // 连接超时5秒factory.setReadTimeout(5000);    // 读取超时5秒return new RestTemplate(factory);
}

4. 使用RestTemplate发送请求

现在，您可以在Service或Controller中使用RestTemplate。以下以发送GET和POST请求为例。
步骤：
- 注入RestTemplate实例。
- 使用getForObject、postForObject等方法发送请求。
- 处理响应数据（假设响应为JSON）。

示例1：GET请求

假设调用天气API：https://api.weather.com/data?city={city}，返回JSON数据。

创建一个Service类，例如WeatherService.java：

import org.springframework.beans.factory.annotation.Autowired;
import org.springframework.stereotype.Service;
import org.springframework.web.client.RestTemplate;@Service
public class WeatherService {private final RestTemplate restTemplate;@Autowiredpublic WeatherService(RestTemplate restTemplate) {this.restTemplate = restTemplate;}public String getWeatherData(String city) {String url = "https://api.weather.com/data?city={city}";// 发送GET请求，将响应解析为StringString response = restTemplate.getForObject(url, String.class, city);return response; // 实际项目中，应解析JSON为对象}
}

说明：
- getForObject方法：第一个参数是URL（使用占位符{city}），第二个是响应类型，第三个是占位符值。
- 响应直接返回字符串，实际中应使用POJO类解析JSON（见第5步）。

示例2：POST请求

假设调用登录API：https://api.example.com/login，需要发送JSON请求体。

在WeatherService中添加方法：

public String loginUser(String username, String password) {String url = "https://api.example.com/login";// 创建请求体（例如Map或自定义对象）Map<String, String> requestBody = new HashMap<>();requestBody.put("username", username);requestBody.put("password", password);// 发送POST请求，请求体自动序列化为JSONString response = restTemplate.postForObject(url, requestBody, String.class);return response;
}

说明：
- postForObject方法：第一个参数是URL，第二个是请求体对象，第三个是响应类型。
- Spring会自动使用Jackson库将对象序列化为JSON。

5. 处理响应

第三方接口通常返回JSON数据。建议定义POJO类来映射响应。
步骤：
- 创建响应实体类。
- 使用RestTemplate的getForObject或postForObject直接映射到对象。

示例：假设天气API返回{"city":"Beijing","temp":25}。

创建POJO类WeatherResponse.java：

public class WeatherResponse {private String city;private int temp;// Getters and Setterspublic String getCity() { return city; }public void setCity(String city) { this.city = city; }public int getTemp() { return temp; }public void setTemp(int temp) { this.temp = temp; }
}

在Service中修改方法：

public WeatherResponse getWeatherData(String city) {String url = "https://api.weather.com/data?city={city}";WeatherResponse response = restTemplate.getForObject(url, WeatherResponse.class, city);return response;
}

说明：getForObject会自动将JSON反序列化为WeatherResponse对象。

6. 错误处理

调用三方接口可能失败（如网络问题、接口错误）。使用try-catch捕获异常。
常见异常：
- HttpClientErrorException：4xx错误（如404 Not Found）。
- HttpServerErrorException：5xx错误（如500 Internal Server Error）。
- RestClientException：通用错误（如超时）。

示例：在Service中添加错误处理。

import org.springframework.web.client.HttpClientErrorException;
import org.springframework.web.client.RestClientException;public WeatherResponse getWeatherData(String city) {String url = "https://api.weather.com/data?city={city}";try {return restTemplate.getForObject(url, WeatherResponse.class, city);} catch (HttpClientErrorException e) {// 处理客户端错误（如参数无效）System.err.println("客户端错误: " + e.getStatusCode());return null;} catch (HttpServerErrorException e) {// 处理服务端错误System.err.println("服务端错误: " + e.getStatusCode());return null;} catch (RestClientException e) {// 处理其他错误（如超时）System.err.println("请求失败: " + e.getMessage());return null;}
}

最佳实践：使用全局异常处理（如@ControllerAdvice）统一管理错误。

7. 完整示例：集成到Controller

创建一个Controller来调用Service，并测试接口。

示例WeatherController.java：

import org.springframework.beans.factory.annotation.Autowired;
import org.springframework.web.bind.annotation.GetMapping;
import org.springframework.web.bind.annotation.PathVariable;
import org.springframework.web.bind.annotation.RestController;@RestController
public class WeatherController {private final WeatherService weatherService;@Autowiredpublic WeatherController(WeatherService weatherService) {this.weatherService = weatherService;}@GetMapping("/weather/{city}")public WeatherResponse getWeather(@PathVariable String city) {return weatherService.getWeatherData(city);}
}

测试：
- 启动Spring Boot应用。
- 访问http://localhost:8080/weather/Beijing，将返回天气数据。
- 使用Postman或curl测试POST请求。