【JAVA】JAVA中对接外部接口的常用方法汇总-联盟战报-北境之锋活动联盟

【JAVA】JAVA中对接外部接口的常用方法汇总

前言

在现代的分布式系统和微服务架构中，Java应用程序经常需要与外部服务进行交互，调用其提供的API接口以获取数据或执行操作。这些接口可能遵循不同的设计风格和协议，例如常见的RESTful API、基于XML的SOAP服务，以及日益流行的GraphQL查询语言（通常也通过HTTP传输）。了解不同接口类型的特点对于选择合适的对接方法至关重要，您可以参考笔者的另一篇笔记【接口】接口类型总览与对比来获取更详细的信息。

无论是调用第三方服务（如支付接口、天气API、社交媒体API），还是内部不同微服务之间的通信，高效、稳定地对接外部接口是保证系统功能正常运行的关键。本文旨在介绍几种在Java中常用的对接外部HTTP接口的方法，重点讨论它们在处理不同类型接口（特别是RESTful API）时的特点、适用场景，并提供基本的使用示例，希望能帮助开发者根据实际需求选择最合适的工具。

一、HttpURLConnection

HttpURLConnection是Java标准库（java.net包）中提供的用于进行HTTP通信的基础类。它是JDK自带的，无需引入任何第三方依赖即可使用。

（一）特点

原生支持：作为JDK的一部分，具有良好的兼容性和普适性。

简单直接：对于简单的GET、POST请求，使用起来相对直接。

功能基础：功能相对基础，缺少连接池、复杂的请求配置、自动重试等高级特性。

性能一般：相比专门的HTTP客户端库，性能和效率可能较低，尤其在高并发场景下。 1

（二）使用示例

import java.io.BufferedReader;

import java.io.InputStreamReader;

import java.io.OutputStream;

import java.net.HttpURLConnection;

import java.net.URL;

public class HttpURLConnectionExample {

public static void main(String[] args) {

try {

// 发送GET请求

sendGetRequest("https://api.example.com/data");

// 发送POST请求

String postData = "{\"name\":\"John Doe\", \"age\":30}";

sendPostRequest("https://api.example.com/users", postData);

} catch (Exception e) {

e.printStackTrace();

}

// 发送GET请求

private static void sendGetRequest(String urlString) throws Exception {

URL url = new URL(urlString);

HttpURLConnection connection = (HttpURLConnection) url.openConnection();

// 设置请求方法为GET

connection.setRequestMethod("GET");

// 设置请求头 (可选)

connection.setRequestProperty("User-Agent", "Mozilla/5.0");

connection.setRequestProperty("Accept-Charset", "UTF-8");

int responseCode = connection.getResponseCode();

System.out.println("GET Response Code :: " + responseCode);

if (responseCode == HttpURLConnection.HTTP_OK) { // success

BufferedReader in = new BufferedReader(new InputStreamReader(connection.getInputStream()));

String inputLine;

StringBuffer response = new StringBuffer();

while ((inputLine = in.readLine()) != null) {

response.append(inputLine);

}

in.close();

// 打印结果

System.out.println("GET Response Body :: " + response.toString());

} else {

System.out.println("GET request not worked");

}

connection.disconnect();

}

// 发送POST请求

private static void sendPostRequest(String urlString, String postData) throws Exception {

URL url = new URL(urlString);

HttpURLConnection connection = (HttpURLConnection) url.openConnection();

// 设置请求方法为POST

connection.setRequestMethod("POST");

connection.setRequestProperty("Content-Type", "application/json; utf-8");

connection.setRequestProperty("Accept", "application/json");

connection.setDoOutput(true); // 允许写入请求体

// 写入请求体

try(OutputStream os = connection.getOutputStream()) {

byte[] input = postData.getBytes("utf-8");

os.write(input, 0, input.length);

}

int responseCode = connection.getResponseCode();

System.out.println("POST Response Code :: " + responseCode);

if (responseCode == HttpURLConnection.HTTP_CREATED || responseCode == HttpURLConnection.HTTP_OK) { // success

BufferedReader in = new BufferedReader(new InputStreamReader(connection.getInputStream()));

String inputLine;

StringBuffer response = new StringBuffer();

while ((inputLine = in.readLine()) != null) {

response.append(inputLine);

}

in.close();

System.out.println("POST Response Body :: " + response.toString());

} else {

System.out.println("POST request not worked");

}

connection.disconnect();

}

（三）注意事项

需要手动管理连接的打开和关闭。

错误处理和超时设置相对繁琐。

对于HTTPS请求，可能需要额外处理SSL证书。

接口类型适应性：

RESTful API：对于简单的RESTful API调用（如GET、POST请求，少量参数和头部），HttpURLConnection可以胜任，但所有请求构建、响应解析（如JSON或XML）都需要手动完成，较为繁琐。可以参考[【接口】RESTful API设计指南](../【接口】RESTful API设计指南.md)了解更多RESTful API的细节。

SOAP API：理论上可以手动构造SOAP信封并通过POST请求发送，但极其不便，需要手动处理XML的序列化和反序列化。通常对接SOAP服务会使用JAX-WS等专用框架。可以参考[【接口】SOAP API详解](../【接口】SOAP API详解.md)了解更多SOAP API的细节。

GraphQL API：由于GraphQL通常通过HTTP POST请求发送JSON格式的查询，HttpURLConnection可以用于发送这些请求。但同样，查询构建和响应处理需要手动进行，缺乏专用GraphQL客户端的便利性。可以参考[【接口】GraphQL API入门](../【接口】GraphQL API入门.md)了解更多GraphQL API的细节。

不建议在需要高性能和复杂交互的场景下作为首选，特别是对于需要复杂请求配置、自动重试、连接池管理的现代应用。 4

二、Apache HttpClient

Apache HttpClient是一个非常成熟和广泛使用的HTTP客户端库，提供了比HttpURLConnection更丰富的功能和更好的灵活性。

（一）特点

功能强大：支持连接池管理、连接复用、请求/响应拦截器、自定义重试机制、代理配置、Cookie管理、认证机制等。 1

高度可配置：提供了大量的配置选项，可以精细控制HTTP请求的各个方面。

成熟稳定：经过长时间的发展和广泛应用，稳定性和可靠性较高。

社区活跃：拥有庞大的用户社区和丰富的文档资源。 4

（二）使用示例

首先，需要在项目中添加Apache HttpClient的依赖（例如Maven）：

org.apache.httpcomponents

httpclient

4.5.13

然后，以下是一个基本的使用示例：

import org.apache.http.HttpEntity;

import org.apache.http.HttpResponse;

import org.apache.http.client.methods.HttpGet;

import org.apache.http.client.methods.HttpPost;

import org.apache.http.entity.StringEntity;

import org.apache.http.impl.client.CloseableHttpClient;

import org.apache.http.impl.client.HttpClients;

import org.apache.http.util.EntityUtils;

import java.io.IOException;

public class ApacheHttpClientExample {

public static void main(String[] args) {

// 创建默认的HttpClient实例

try (CloseableHttpClient httpClient = HttpClients.createDefault()) {

// 发送GET请求

sendGetRequest(httpClient, "https://api.example.com/data");

// 发送POST请求

String postData = "{\"name\":\"Jane Doe\", \"age\":25}";

sendPostRequest(httpClient, "https://api.example.com/users", postData);

} catch (IOException e) {

e.printStackTrace();

}

// 使用Apache HttpClient发送GET请求

private static void sendGetRequest(CloseableHttpClient httpClient, String url) throws IOException {

HttpGet httpGet = new HttpGet(url);

// httpGet.setHeader("User-Agent", "Apache HttpClient"); // 设置请求头

System.out.println("Executing GET request: " + httpGet.getRequestLine());

HttpResponse response = httpClient.execute(httpGet);

System.out.println("GET Response Status: " + response.getStatusLine().getStatusCode());

HttpEntity entity = response.getEntity();

if (entity != null) {

String responseBody = EntityUtils.toString(entity);

System.out.println("GET Response Body: " + responseBody);

}

EntityUtils.consume(entity); // 确保实体内容被完全消耗，或者关闭InputStream

}

// 使用Apache HttpClient发送POST请求

private static void sendPostRequest(CloseableHttpClient httpClient, String url, String jsonData) throws IOException {

HttpPost httpPost = new HttpPost(url);

httpPost.setHeader("Content-Type", "application/json");

httpPost.setHeader("Accept", "application/json");

StringEntity stringEntity = new StringEntity(jsonData);

httpPost.setEntity(stringEntity);

System.out.println("Executing POST request: " + httpPost.getRequestLine());

HttpResponse response = httpClient.execute(httpPost);

System.out.println("POST Response Status: " + response.getStatusLine().getStatusCode());

HttpEntity entity = response.getEntity();

if (entity != null) {

String responseBody = EntityUtils.toString(entity);

System.out.println("POST Response Body: " + responseBody);

}

EntityUtils.consume(entity);

}

（三）注意事项

需要正确管理CloseableHttpClient实例的生命周期，通常使用try-with-resources语句确保其关闭。

对于获取的HttpEntity，需要确保其内容被完全消费（例如通过EntityUtils.consume(entity)或读取其InputStream直到末尾），以便连接可以安全地返回到连接池中复用。

HttpClient的配置较为复杂，但同时也提供了强大的定制能力。 4

接口类型适应性：

RESTful API：Apache HttpClient非常适合对接RESTful API。它提供了灵活的请求构建（如设置方法、头部、请求体）、参数编码以及对JSON/XML等常见数据格式的良好支持（通常结合Jackson或JAXB等库进行序列化/反序列化）。其连接池和重试机制对于构建健壮的REST客户端非常有帮助。可以参考[【接口】RESTful API设计指南](../【接口】RESTful API设计指南.md)了解更多RESTful API的细节。

SOAP API：虽然HttpClient本身不直接处理SOAP协议的复杂性（如WSDL解析、SOAP信封构造），但它可以作为底层HTTP传输层。许多Java SOAP客户端库（如Apache CXF, JAX-WS RI）允许配置使用HttpClient作为其HTTP transport，从而利用HttpClient的连接管理、超时设置等高级特性。直接使用HttpClient对接SOAP服务需要手动构造XML请求体并解析响应，较为繁琐。可以参考[【接口】SOAP API详解](../【接口】SOAP API详解.md)了解更多SOAP API的细节。

GraphQL API：由于GraphQL API通常通过HTTP POST请求（包含JSON格式的查询）进行交互，HttpClient可以很好地支持。开发者需要手动构建JSON查询字符串作为请求体，并解析返回的JSON响应。HttpClient的灵活性使其能够轻松设置必要的头部（如Content-Type: application/json）。可以参考[【接口】GraphQL API入门](../【接口】GraphQL API入门.md)了解更多GraphQL API的细节。

三、OkHttp

OkHttp是由Square公司开发的一款高效的HTTP客户端，专注于性能和易用性。它在Android开发中非常流行，并且在Java服务端也有广泛应用。

（一）特点

高效性能：支持HTTP/2和SPDY，连接池和Gzip压缩，减少延迟和带宽消耗。 2

连接池与连接复用：自动管理连接池，有效复用连接。

请求/响应拦截器：强大的拦截器机制，可以轻松实现日志记录、请求重写、缓存等功能。

自动重试与故障恢复：当网络出现问题时，OkHttp会自动尝试连接到备用IP地址（如果可用）。 2

支持同步和异步调用：提供了简洁的API进行同步和异步请求。

缓存支持：内置响应缓存机制，可以避免不必要的网络请求。 2

（二）使用示例

首先，需要在项目中添加OkHttp的依赖（例如Maven）：

com.squareup.okhttp3

okhttp

4.9.3

然后，以下是一个基本的使用示例：

import okhttp3.*;

import java.io.IOException;

public class OkHttpExample {

// 创建OkHttpClient实例，建议全局共享一个实例

private static final OkHttpClient client = new OkHttpClient();

public static void main(String[] args) {

try {

// 发送GET请求

sendGetRequest("https://api.example.com/data");

// 发送POST请求

String jsonData = "{\"name\":\"OkHttp User\", \"job\":\"Tester\"}";

sendPostRequest("https://api.example.com/users", jsonData);

} catch (IOException e) {

e.printStackTrace();

}

// 使用OkHttp发送GET请求

private static void sendGetRequest(String url) throws IOException {

Request request = new Request.Builder()

.url(url)

// .addHeader("User-Agent", "OkHttp Example") // 添加请求头

.build();

try (Response response = client.newCall(request).execute()) {

if (!response.isSuccessful()) throw new IOException("Unexpected code " + response);

System.out.println("GET Response Code: " + response.code());

if (response.body() != null) {

System.out.println("GET Response Body: " + response.body().string());

}

// 使用OkHttp发送POST请求

private static void sendPostRequest(String url, String json) throws IOException {

RequestBody body = RequestBody.create(

json, MediaType.get("application/json; charset=utf-f")

);

Request request = new Request.Builder()

.url(url)

.post(body)

.build();

try (Response response = client.newCall(request).execute()) {

if (!response.isSuccessful()) throw new IOException("Unexpected code " + response);

System.out.println("POST Response Code: " + response.code());

if (response.body() != null) {

System.out.println("POST Response Body: " + response.body().string());

}

（三）注意事项

OkHttpClient实例是线程安全的，并且包含自己的连接池和线程池，建议在应用程序中共享同一个OkHttpClient实例以获得最佳性能。

使用try-with-resources语句来确保Response对象被正确关闭，即使在发生异常时也是如此。这对于释放底层资源（如连接）非常重要。

response.body().string()只能被调用一次。如果需要多次读取响应体，应先将其读取到内存中或使用peekBody()方法。

OkHttp提供了丰富的配置选项，如超时设置、代理、拦截器等，可以根据需要进行定制。 4

接口类型适应性：

RESTful API：OkHttp 是对接 RESTful API 的优秀选择。其简洁的API设计、高效的性能（HTTP/2支持、连接池）、强大的拦截器机制以及对请求/响应的精细控制，使其非常适合构建现代REST客户端。它能轻松处理JSON、XML等数据格式（通常结合Gson、Jackson等库）。可以参考[【接口】RESTful API设计指南](../【接口】RESTful API设计指南.md)了解更多RESTful API的细节。

SOAP API：与Apache HttpClient类似，OkHttp本身不直接处理SOAP协议的语义。但它可以作为高效的HTTP传输层。一些现代SOAP客户端库可能允许配置OkHttp作为底层HTTP客户端。若直接使用OkHttp对接SOAP，需要手动构造SOAP XML请求体并解析响应，这通常比较复杂。可以参考[【接口】SOAP API详解](../【接口】SOAP API详解.md)了解更多SOAP API的细节。

GraphQL API：OkHttp 非常适合用于调用GraphQL API。由于GraphQL查询通常作为JSON对象通过HTTP POST请求发送，OkHttp可以方便地构建此类请求（包括设置Content-Type: application/json头部和JSON请求体），并处理返回的JSON响应。其拦截器机制也可用于添加认证头部或日志记录。可以参考[【接口】GraphQL API入门](../【接口】GraphQL API入门.md)了解更多GraphQL API的细节。

四、Spring RestTemplate

RestTemplate是Spring框架提供的一个同步的、阻塞式的HTTP客户端，用于简化与RESTful服务的交互。它是Spring生态中非常常用的HTTP客户端之一。

（一）特点

Spring集成：与Spring框架无缝集成，易于配置和使用，尤其在Spring Boot项目中。

简化API调用：提供了多种便捷方法（如getForObject、postForEntity、exchange等）来执行HTTP请求并处理响应，大大简化了客户端代码。 1

自动转换：支持自动将请求体和响应体在Java对象和JSON/XML等格式之间进行转换（通过HttpMessageConverter）。

错误处理：提供了ResponseErrorHandler来自定义错误处理逻辑。

底层可替换：虽然默认使用HttpURLConnection，但可以配置为使用其他HTTP客户端库（如Apache HttpClient, OkHttp）作为底层实现。 4

（二）使用示例

首先，如果是在Spring Boot项目中使用，通常spring-boot-starter-web会包含RestTemplate。如果是非Spring Boot项目，需要添加spring-web依赖。

org.springframework.boot

spring-boot-starter-web

org.springframework

spring-web

5.3.23

然后，以下是一个基本的使用示例：

import org.springframework.http.*;

import org.springframework.web.client.RestTemplate;

import java.util.HashMap;

import java.util.Map;

public class RestTemplateExample {

// 通常通过依赖注入获取RestTemplate实例

private final RestTemplate restTemplate;

public RestTemplateExample(RestTemplate restTemplate) {

this.restTemplate = restTemplate;

}

// 示例：配置RestTemplate Bean (在Spring配置类中)

// @Bean

// public RestTemplate restTemplate() {

// return new RestTemplate();

// }

public static void main(String[] args) {

// 在非Spring管理的环境下，可以直接创建实例

RestTemplate staticRestTemplate = new RestTemplate();

RestTemplateExample example = new RestTemplateExample(staticRestTemplate);

// 发送GET请求

example.sendGetRequest("https://api.example.com/data");

// 发送POST请求

Map postData = new HashMap<>();

postData.put("name", "RestTemplate User");

postData.put("email", "user@example.com");

example.sendPostRequest("https://api.example.com/users", postData);

}

public void sendGetRequest(String url) {

try {

// getForObject: 直接获取响应体并转换为指定类型

String responseBody = restTemplate.getForObject(url, String.class);

System.out.println("GET Response Body (getForObject): " + responseBody);

// getForEntity: 获取包含完整响应信息（状态码、头、体）的ResponseEntity

ResponseEntity responseEntity = restTemplate.getForEntity(url, String.class);

System.out.println("GET Response Status (getForEntity): " + responseEntity.getStatusCode());

System.out.println("GET Response Headers (getForEntity): " + responseEntity.getHeaders());

System.out.println("GET Response Body (getForEntity): " + responseEntity.getBody());

} catch (Exception e) {

System.err.println("Error during GET request: " + e.getMessage());

}

public void sendPostRequest(String url, Object requestBody) {

try {

HttpHeaders headers = new HttpHeaders();

headers.setContentType(MediaType.APPLICATION_JSON);

HttpEntity