此版本仍在开发中，尚未被视为稳定版本。对于最新的稳定版本，请使用 Spring Framework 6.2.7！spring-doc.cadn.net.cn

REST 客户端

Spring 框架提供了以下选项来调用 REST 端点：spring-doc.cadn.net.cn

RestClient- 具有 Fluent API 的同步客户端。spring-doc.cadn.net.cn
WebClient- 具有 Fluent API 的非阻塞响应式客户端。spring-doc.cadn.net.cn
RestTemplate- 与模板方法 API 同步客户端。spring-doc.cadn.net.cn
HTTP 接口 - 带有生成的动态代理实现的带注释的接口。spring-doc.cadn.net.cn

`RestClient`

RestClient是一个同步 HTTP 客户端，它提供 Fluent API 来执行请求。它用作 HTTP 库的抽象，并处理 HTTP 请求和响应内容与更高级别 Java 对象之间的转换。spring-doc.cadn.net.cn

创建一个`RestClient`

RestClient具有静态create快捷方法。它还公开了builder()有更多选项：spring-doc.cadn.net.cn

选择要使用的 HTTP 库，请参阅客户端请求工厂 spring-doc.cadn.net.cn
配置消息转换器，请参见 HTTP 消息转换 spring-doc.cadn.net.cn
设置 baseUrlspring-doc.cadn.net.cn
设置默认请求标头、Cookie、路径变量、API 版本spring-doc.cadn.net.cn
配置ApiVersionInserterspring-doc.cadn.net.cn
寄存器拦截器spring-doc.cadn.net.cn
注册请求初始值设定项spring-doc.cadn.net.cn

创建后，RestClient可以安全地在多个线程中使用。spring-doc.cadn.net.cn

下面显示了如何创建或构建RestClient:spring-doc.cadn.net.cn

Javaspring-doc.cadn.net.cn
Kotlinspring-doc.cadn.net.cn

RestClient defaultClient = RestClient.create();

RestClient customClient = RestClient.builder()
	.requestFactory(new HttpComponentsClientHttpRequestFactory())
	.messageConverters(converters -> converters.add(new MyCustomMessageConverter()))
	.baseUrl("https://example.com")
	.defaultUriVariables(Map.of("variable", "foo"))
	.defaultHeader("My-Header", "Foo")
	.defaultCookie("My-Cookie", "Bar")
	.defaultVersion("1.2")
	.apiVersionInserter(ApiVersionInserter.fromHeader("API-Version").build())
	.requestInterceptor(myCustomInterceptor)
	.requestInitializer(myCustomInitializer)
	.build();

val defaultClient = RestClient.create()

val customClient = RestClient.builder()
	.requestFactory(HttpComponentsClientHttpRequestFactory())
	.messageConverters { converters -> converters.add(MyCustomMessageConverter()) }
	.baseUrl("https://example.com")
	.defaultUriVariables(mapOf("variable" to "foo"))
	.defaultHeader("My-Header", "Foo")
	.defaultCookie("My-Cookie", "Bar")
       .defaultVersion("1.2")
       .apiVersionInserter(ApiVersionInserter.fromHeader("API-Version").build())
	.requestInterceptor(myCustomInterceptor)
	.requestInitializer(myCustomInitializer)
	.build()

使用`RestClient`

要执行 HTTP 请求，请首先指定要使用的 HTTP 方法。使用方便的方法，如get(),head(),post()和其他method(HttpMethod).spring-doc.cadn.net.cn

请求 URL

接下来，使用uri方法。这是可选的，如果您通过生成器配置了 baseUrl，则可以跳过此步骤。 URL 通常指定为String，其中包含可选的 URI 模板变量。下面显示了如何执行请求：spring-doc.cadn.net.cn

Javaspring-doc.cadn.net.cn
Kotlinspring-doc.cadn.net.cn

int id = 42;
restClient.get()
	.uri("https://example.com/orders/{id}", id)
	// ...

val id = 42
restClient.get()
	.uri("https://example.com/orders/{id}", id)
	// ...

函数还可用于更多控制，例如指定请求参数。spring-doc.cadn.net.cn

默认情况下，String URL 是编码的，但这可以通过使用自定义uriBuilderFactory. URL 也可以随函数一起提供，也可以作为java.net.URI，这两者都未编码。有关使用 URI 和编码 URI 的更多详细信息，请参阅 URI 链接。spring-doc.cadn.net.cn

请求标头和正文

如有必要，可以通过添加请求标头来作 HTTP 请求header(String, String),headers(Consumer<HttpHeaders>或使用便捷方法accept(MediaType…),acceptCharset(Charset…)等等。对于可以包含正文（POST,PUT和PATCH），还有其他方法可用：contentType(MediaType)和contentLength(long). 如果客户端配置了ApiVersionInserter.spring-doc.cadn.net.cn

请求正文本身可以由body(Object)，它在内部使用 HTTP 消息转换。或者，可以使用ParameterizedTypeReference，允许您使用泛型。最后，可以将 body 设置为一个回调函数，该函数写入OutputStream.spring-doc.cadn.net.cn

检索响应

设置请求后，可以在retrieve(). 例如，可以使用retrieve().body(Class)或retrieve().body(ParameterizedTypeReference)对于参数化类型（如 lists）。这body方法将响应内容转换为各种类型——例如，字节可以转换为String、JSON 可以使用 Jackson 转换为对象，依此类推（请参阅 HTTP 消息转换）。spring-doc.cadn.net.cn

响应也可以转换为ResponseEntity，可以访问响应标头和正文，使用retrieve().toEntity(Class)spring-doc.cadn.net.cn

叫retrieve()本身是一个 no-op 并返回一个ResponseSpec. 应用程序必须在ResponseSpec产生任何副作用。如果使用响应对您的使用案例没有兴趣，您可以使用retrieve().toBodilessEntity().

此示例展示了如何RestClient可用于执行简单的GET请求。spring-doc.cadn.net.cn

Javaspring-doc.cadn.net.cn
Kotlinspring-doc.cadn.net.cn

String result = restClient.get() (1)
	.uri("https://example.com") (2)
	.retrieve() (3)
	.body(String.class); (4)

System.out.println(result); (5)

1	设置 GET 请求
2	指定要连接的 URL
3	检索响应
4	将响应转换为字符串
5	打印结果

val result= restClient.get() (1)
	.uri("https://example.com") (2)
	.retrieve() (3)
	.body<String>() (4)

println(result) (5)

1	设置 GET 请求
2	指定要连接的 URL
3	检索响应
4	将响应转换为字符串
5	打印结果

对响应状态代码和标头的访问是通过ResponseEntity:spring-doc.cadn.net.cn

Javaspring-doc.cadn.net.cn
Kotlinspring-doc.cadn.net.cn

ResponseEntity<String> result = restClient.get() (1)
	.uri("https://example.com") (1)
	.retrieve()
	.toEntity(String.class); (2)

System.out.println("Response status: " + result.getStatusCode()); (3)
System.out.println("Response headers: " + result.getHeaders()); (3)
System.out.println("Contents: " + result.getBody()); (3)

1	为指定 URL 设置 GET 请求
2	将响应转换为`ResponseEntity`
3	打印结果

val result = restClient.get() (1)
	.uri("https://example.com") (1)
	.retrieve()
	.toEntity<String>() (2)

println("Response status: " + result.statusCode) (3)
println("Response headers: " + result.headers) (3)
println("Contents: " + result.body) (3)

1	为指定 URL 设置 GET 请求
2	将响应转换为`ResponseEntity`
3	打印结果

RestClient可以使用 Jackson 库将 JSON 转换为对象。请注意此示例中 URI 变量的用法，以及Acceptheader 设置为 JSON。spring-doc.cadn.net.cn

Javaspring-doc.cadn.net.cn
Kotlinspring-doc.cadn.net.cn

int id = ...;
Pet pet = restClient.get()
	.uri("https://petclinic.example.com/pets/{id}", id) (1)
	.accept(APPLICATION_JSON) (2)
	.retrieve()
	.body(Pet.class); (3)

1	使用 URI 变量
2	将`Accept`header 设置为`application/json`
3	将 JSON 响应转换为`Pet`domain 对象

val id = ...
val pet = restClient.get()
	.uri("https://petclinic.example.com/pets/{id}", id) (1)
	.accept(APPLICATION_JSON) (2)
	.retrieve()
	.body<Pet>() (3)

1	使用 URI 变量
2	将`Accept`header 设置为`application/json`
3	将 JSON 响应转换为`Pet`domain 对象

在下一个示例中，RestClient用于执行包含 JSON 的 POST 请求，该请求同样使用 Jackson 进行转换。spring-doc.cadn.net.cn

Javaspring-doc.cadn.net.cn
Kotlinspring-doc.cadn.net.cn

Pet pet = ... (1)
ResponseEntity<Void> response = restClient.post() (2)
	.uri("https://petclinic.example.com/pets/new") (2)
	.contentType(APPLICATION_JSON) (3)
	.body(pet) (4)
	.retrieve()
	.toBodilessEntity(); (5)

1	创建一个`Pet`domain 对象
2	设置 POST 请求和要连接到的 URL
3	将`Content-Type`header 设置为`application/json`
4	用`pet`作为请求正文
5	将响应转换为没有正文的响应实体。

val pet: Pet = ... (1)
val response = restClient.post() (2)
	.uri("https://petclinic.example.com/pets/new") (2)
	.contentType(APPLICATION_JSON) (3)
	.body(pet) (4)
	.retrieve()
	.toBodilessEntity() (5)

1	创建一个`Pet`domain 对象
2	设置 POST 请求和要连接到的 URL
3	将`Content-Type`header 设置为`application/json`
4	用`pet`作为请求正文
5	将响应转换为没有正文的响应实体。

错误处理

默认情况下，RestClient抛出RestClientException检索具有 4xx 或 5xx 状态代码的响应时。可以使用onStatus.spring-doc.cadn.net.cn

Javaspring-doc.cadn.net.cn
Kotlinspring-doc.cadn.net.cn

String result = restClient.get() (1)
	.uri("https://example.com/this-url-does-not-exist") (1)
	.retrieve()
	.onStatus(HttpStatusCode::is4xxClientError, (request, response) -> { (2)
		throw new MyCustomRuntimeException(response.getStatusCode(), response.getHeaders()); (3)
	})
	.body(String.class);

1	为返回 404 状态代码的 URL 创建 GET 请求
2	为所有 4xx 状态代码设置状态处理程序
3	引发自定义异常

val result = restClient.get() (1)
	.uri("https://example.com/this-url-does-not-exist") (1)
	.retrieve()
	.onStatus(HttpStatusCode::is4xxClientError) { _, response -> (2)
		throw MyCustomRuntimeException(response.getStatusCode(), response.getHeaders()) } (3)
	.body<String>()

1	为返回 404 状态代码的 URL 创建 GET 请求
2	为所有 4xx 状态代码设置状态处理程序
3	引发自定义异常

交换

对于更高级的场景，RestClient通过exchange()方法，该 API 可以代替retrieve(). 使用exchange()，因为 exchange 函数已经提供了对完整响应的访问，从而允许您执行任何必要的错误处理。spring-doc.cadn.net.cn

Javaspring-doc.cadn.net.cn
Kotlinspring-doc.cadn.net.cn

Pet result = restClient.get()
	.uri("https://petclinic.example.com/pets/{id}", id)
	.accept(APPLICATION_JSON)
	.exchange((request, response) -> { (1)
		if (response.getStatusCode().is4xxClientError()) { (2)
			throw new MyCustomRuntimeException(response.getStatusCode(), response.getHeaders()); (2)
		}
		else {
			Pet pet = convertResponse(response); (3)
			return pet;
		}
	});

1	`exchange`提供请求和响应
2	当响应具有 4xx 状态代码时引发异常
3	将响应转换为 Pet 域对象

val result = restClient.get()
	.uri("https://petclinic.example.com/pets/{id}", id)
	.accept(MediaType.APPLICATION_JSON)
	.exchange { request, response -> (1)
		if (response.getStatusCode().is4xxClientError()) { (2)
			throw MyCustomRuntimeException(response.getStatusCode(), response.getHeaders()) (2)
		} else {
			val pet: Pet = convertResponse(response) (3)
			pet
		}
	}

1	`exchange`提供请求和响应
2	当响应具有 4xx 状态代码时引发异常
3	将响应转换为 Pet 域对象

HTTP 消息转换

请参阅专用部分中支持的 HTTP 消息转换器。spring-doc.cadn.net.cn

Jackson JSON 视图

要仅序列化对象属性的子集，您可以指定 Jackson JSON 视图，如下例所示：spring-doc.cadn.net.cn

MappingJacksonValue value = new MappingJacksonValue(new User("eric", "7!jd#h23"));
value.setSerializationView(User.WithoutPasswordView.class);

ResponseEntity<Void> response = restClient.post() // or RestTemplate.postForEntity
	.contentType(APPLICATION_JSON)
	.body(value)
	.retrieve()
	.toBodilessEntity();

多部分

要发送多部分数据，您需要提供MultiValueMap<String, Object>其值可以是Object对于部件内容，一个Resource对于文件部分，或者HttpEntity对于带有标题的 Part Content 进行翻译。例如：spring-doc.cadn.net.cn

MultiValueMap<String, Object> parts = new LinkedMultiValueMap<>();

parts.add("fieldPart", "fieldValue");
parts.add("filePart", new FileSystemResource("...logo.png"));
parts.add("jsonPart", new Person("Jason"));

HttpHeaders headers = new HttpHeaders();
headers.setContentType(MediaType.APPLICATION_XML);
parts.add("xmlPart", new HttpEntity<>(myBean, headers));

// send using RestClient.post or RestTemplate.postForEntity

在大多数情况下，您不必指定Content-Type对于每个部分。内容类型是根据HttpMessageConverter选择将其序列化，或者在Resource，具体取决于文件扩展名。如有必要，您可以显式提供MediaType替换为HttpEntity包装纸。spring-doc.cadn.net.cn

一旦MultiValueMap已准备就绪，您可以将其用作POSTrequest，使用RestClient.post().body(parts)（或RestTemplate.postForObject).spring-doc.cadn.net.cn

如果MultiValueMap包含至少一个非String值、Content-Type设置为multipart/form-data由FormHttpMessageConverter. 如果MultiValueMap具有Stringvalues 中，Content-Type默认为application/x-www-form-urlencoded. 如有必要，Content-Type也可以显式设置。spring-doc.cadn.net.cn

客户端请求工厂

要执行 HTTP 请求，RestClient使用客户端 HTTP 库。这些库通过ClientRequestFactory接口。有多种实现可供选择：spring-doc.cadn.net.cn

JdkClientHttpRequestFactory对于 Java 的HttpClientspring-doc.cadn.net.cn
HttpComponentsClientHttpRequestFactory用于 Apache HTTP 组件HttpClientspring-doc.cadn.net.cn
JettyClientHttpRequestFactoryJetty's （Jetty）HttpClientspring-doc.cadn.net.cn
ReactorNettyClientRequestFactory用于 Reactor Netty'sHttpClientspring-doc.cadn.net.cn
SimpleClientHttpRequestFactory作为简单的默认值spring-doc.cadn.net.cn

如果未指定请求工厂，则当RestClient构建时，它将使用 Apache 或 JettyHttpClient如果它们在 Classpath 上可用。否则，如果java.net.http模块，它将使用 Java 的HttpClient. 最后，它将采用简单的默认值。spring-doc.cadn.net.cn

请注意，SimpleClientHttpRequestFactory在访问表示错误的响应的状态（例如 401）时，可能会引发异常。如果这是一个问题，请使用任何替代请求工厂。

`WebClient`

WebClient是执行 HTTP 请求的非阻塞响应式客户端。它是在 5.0 中引入，并提供了RestTemplate，支持同步、异步和流式处理方案。spring-doc.cadn.net.cn

WebClient支持以下内容：spring-doc.cadn.net.cn

非阻塞 I/Ospring-doc.cadn.net.cn
反应流背压spring-doc.cadn.net.cn
高并发性，硬件资源更少spring-doc.cadn.net.cn
利用 Java 8 lambda 的函数式 Fluent APIspring-doc.cadn.net.cn
同步和异步交互spring-doc.cadn.net.cn
向服务器流式传输或从服务器向式传输spring-doc.cadn.net.cn

有关更多详细信息，请参阅 WebClient 。spring-doc.cadn.net.cn

`RestTemplate`

这RestTemplate以经典的 Spring Template 类的形式通过 HTTP 客户端库提供高级 API。它公开了以下重载方法组：spring-doc.cadn.net.cn

这RestClient为同步 HTTP 访问提供更现代的 API。对于异步和流式处理方案，请考虑响应式 WebClient。

表 1.RestTemplate 方法
“方法”组	描述
`getForObject`spring-doc.cadn.net.cn	通过 GET 检索表示形式。spring-doc.cadn.net.cn
`getForEntity`spring-doc.cadn.net.cn	检索`ResponseEntity`（即 status、headers 和 body）。spring-doc.cadn.net.cn
`headForHeaders`spring-doc.cadn.net.cn	使用 HEAD 检索资源的所有标头。spring-doc.cadn.net.cn
`postForLocation`spring-doc.cadn.net.cn	使用 POST 创建新资源并返回`Location`标头。spring-doc.cadn.net.cn
`postForObject`spring-doc.cadn.net.cn	使用 POST 创建新资源，并从响应中返回表示形式。spring-doc.cadn.net.cn
`postForEntity`spring-doc.cadn.net.cn	使用 POST 创建新资源，并从响应中返回表示形式。spring-doc.cadn.net.cn
`put`spring-doc.cadn.net.cn	使用 PUT 创建或更新资源。spring-doc.cadn.net.cn
`patchForObject`spring-doc.cadn.net.cn	使用 PATCH 更新资源并从响应中返回表示形式。请注意，JDK`HttpURLConnection`不支持`PATCH`，但 Apache HttpComponents 和其他组件可以。spring-doc.cadn.net.cn
`delete`spring-doc.cadn.net.cn	使用 DELETE 删除指定 URI 处的资源。spring-doc.cadn.net.cn
`optionsForAllow`spring-doc.cadn.net.cn	使用 ALLOW 检索资源允许的 HTTP 方法。spring-doc.cadn.net.cn
`exchange`spring-doc.cadn.net.cn	上述方法的更通用（且不那么固执己见）版本，可在需要时提供额外的灵活性。它接受一个`RequestEntity`（包括 HTTP 方法、URL、标头和正文作为输入）并返回一个`ResponseEntity`.spring-doc.cadn.net.cn 这些方法允许使用`ParameterizedTypeReference`而不是`Class`以指定具有泛型的响应类型。spring-doc.cadn.net.cn
`execute`spring-doc.cadn.net.cn	执行请求的最通用方式，可完全控制请求通过回调接口进行准备和响应提取。spring-doc.cadn.net.cn

初始化

RestTemplate使用与RestClient. 默认情况下，它使用SimpleClientHttpRequestFactory，但这可以通过构造函数进行更改。参见客户端请求工厂。spring-doc.cadn.net.cn

RestTemplate可以进行检测以实现可观测性，以便生成指标和跟踪。请参阅 RestTemplate 可观察性支持部分。

身体

传入和返回的对象RestTemplate方法在 HTTP 消息的帮助下与 HTTP 消息相互转换HttpMessageConverter，请参阅 HTTP 消息转换。spring-doc.cadn.net.cn

迁移自`RestTemplate`自`RestClient`

下表显示了RestClient的等效项RestTemplate方法。它可用于从后者迁移到前者。spring-doc.cadn.net.cn

表 2.RestTemplate 方法的 RestClient 等效项
`RestTemplate`方法	`RestClient`等效
`getForObject(String, Class, Object…)`spring-doc.cadn.net.cn	`get() .uri(String, Object…) .retrieve() .body(Class)`spring-doc.cadn.net.cn
`getForObject(String, Class, Map)`spring-doc.cadn.net.cn	`get() .uri(String, Map) .retrieve() .body(Class)`spring-doc.cadn.net.cn
`getForObject(URI, Class)`spring-doc.cadn.net.cn	`get() .uri(URI) .retrieve() .body(Class)`spring-doc.cadn.net.cn
`getForEntity(String, Class, Object…)`spring-doc.cadn.net.cn	`get() .uri(String, Object…) .retrieve() .toEntity(Class)`spring-doc.cadn.net.cn
`getForEntity(String, Class, Map)`spring-doc.cadn.net.cn	`get() .uri(String, Map) .retrieve() .toEntity(Class)`spring-doc.cadn.net.cn
`getForEntity(URI, Class)`spring-doc.cadn.net.cn	`get() .uri(URI) .retrieve() .toEntity(Class)`spring-doc.cadn.net.cn
`headForHeaders(String, Object…)`spring-doc.cadn.net.cn	`head() .uri(String, Object…) .retrieve() .toBodilessEntity() .getHeaders()`spring-doc.cadn.net.cn
`headForHeaders(String, Map)`spring-doc.cadn.net.cn	`head() .uri(String, Map) .retrieve() .toBodilessEntity() .getHeaders()`spring-doc.cadn.net.cn
`headForHeaders(URI)`spring-doc.cadn.net.cn	`head() .uri(URI) .retrieve() .toBodilessEntity() .getHeaders()`spring-doc.cadn.net.cn
`postForLocation(String, Object, Object…)`spring-doc.cadn.net.cn	`post() .uri(String, Object…) .body(Object).retrieve() .toBodilessEntity() .getLocation()`spring-doc.cadn.net.cn
`postForLocation(String, Object, Map)`spring-doc.cadn.net.cn	`post() .uri(String, Map) .body(Object) .retrieve() .toBodilessEntity() .getLocation()`spring-doc.cadn.net.cn
`postForLocation(URI, Object)`spring-doc.cadn.net.cn	`post() .uri(URI) .body(Object) .retrieve() .toBodilessEntity() .getLocation()`spring-doc.cadn.net.cn
`postForObject(String, Object, Class, Object…)`spring-doc.cadn.net.cn	`post() .uri(String, Object…) .body(Object) .retrieve() .body(Class)`spring-doc.cadn.net.cn
`postForObject(String, Object, Class, Map)`spring-doc.cadn.net.cn	`post() .uri(String, Map) .body(Object) .retrieve() .body(Class)`spring-doc.cadn.net.cn
`postForObject(URI, Object, Class)`spring-doc.cadn.net.cn	`post() .uri(URI) .body(Object) .retrieve() .body(Class)`spring-doc.cadn.net.cn
`postForEntity(String, Object, Class, Object…)`spring-doc.cadn.net.cn	`post() .uri(String, Object…) .body(Object) .retrieve() .toEntity(Class)`spring-doc.cadn.net.cn
`postForEntity(String, Object, Class, Map)`spring-doc.cadn.net.cn	`post() .uri(String, Map) .body(Object) .retrieve() .toEntity(Class)`spring-doc.cadn.net.cn
`postForEntity(URI, Object, Class)`spring-doc.cadn.net.cn	`post() .uri(URI) .body(Object) .retrieve() .toEntity(Class)`spring-doc.cadn.net.cn
`put(String, Object, Object…)`spring-doc.cadn.net.cn	`put() .uri(String, Object…) .body(Object) .retrieve() .toBodilessEntity()`spring-doc.cadn.net.cn
`put(String, Object, Map)`spring-doc.cadn.net.cn	`put() .uri(String, Map) .body(Object) .retrieve() .toBodilessEntity()`spring-doc.cadn.net.cn
`put(URI, Object)`spring-doc.cadn.net.cn	`put() .uri(URI) .body(Object) .retrieve() .toBodilessEntity()`spring-doc.cadn.net.cn
`patchForObject(String, Object, Class, Object…)`spring-doc.cadn.net.cn	`patch() .uri(String, Object…) .body(Object) .retrieve() .body(Class)`spring-doc.cadn.net.cn
`patchForObject(String, Object, Class, Map)`spring-doc.cadn.net.cn	`patch() .uri(String, Map) .body(Object) .retrieve() .body(Class)`spring-doc.cadn.net.cn
`patchForObject(URI, Object, Class)`spring-doc.cadn.net.cn	`patch() .uri(URI) .body(Object) .retrieve() .body(Class)`spring-doc.cadn.net.cn
`delete(String, Object…)`spring-doc.cadn.net.cn	`delete() .uri(String, Object…) .retrieve() .toBodilessEntity()`spring-doc.cadn.net.cn
`delete(String, Map)`spring-doc.cadn.net.cn	`delete() .uri(String, Map) .retrieve() .toBodilessEntity()`spring-doc.cadn.net.cn
`delete(URI)`spring-doc.cadn.net.cn	`delete() .uri(URI) .retrieve() .toBodilessEntity()`spring-doc.cadn.net.cn
`optionsForAllow(String, Object…)`spring-doc.cadn.net.cn	`options() .uri(String, Object…) .retrieve() .toBodilessEntity() .getAllow()`spring-doc.cadn.net.cn
`optionsForAllow(String, Map)`spring-doc.cadn.net.cn	`options() .uri(String, Map) .retrieve() .toBodilessEntity() .getAllow()`spring-doc.cadn.net.cn
`optionsForAllow(URI)`spring-doc.cadn.net.cn	`options() .uri(URI) .retrieve() .toBodilessEntity() .getAllow()`spring-doc.cadn.net.cn
`exchange(String, HttpMethod, HttpEntity, Class, Object…)`spring-doc.cadn.net.cn	`method(HttpMethod) .uri(String, Object…) .headers(Consumer<HttpHeaders>) .body(Object) .retrieve() .toEntity(Class)` ^[1]spring-doc.cadn.net.cn
`exchange(String, HttpMethod, HttpEntity, Class, Map)`spring-doc.cadn.net.cn	`method(HttpMethod) .uri(String, Map) .headers(Consumer<HttpHeaders>) .body(Object) .retrieve() .toEntity(Class)` ^[1]spring-doc.cadn.net.cn
`exchange(URI, HttpMethod, HttpEntity, Class)`spring-doc.cadn.net.cn	`method(HttpMethod) .uri(URI) .headers(Consumer<HttpHeaders>) .body(Object) .retrieve() .toEntity(Class)` ^[1]spring-doc.cadn.net.cn
`exchange(String, HttpMethod, HttpEntity, ParameterizedTypeReference, Object…)`spring-doc.cadn.net.cn	`method(HttpMethod) .uri(String, Object…) .headers(Consumer<HttpHeaders>) .body(Object) .retrieve() .toEntity(ParameterizedTypeReference)` ^[1]spring-doc.cadn.net.cn
`exchange(String, HttpMethod, HttpEntity, ParameterizedTypeReference, Map)`spring-doc.cadn.net.cn	`method(HttpMethod) .uri(String, Map) .headers(Consumer<HttpHeaders>) .body(Object) .retrieve() .toEntity(ParameterizedTypeReference)` ^[1]spring-doc.cadn.net.cn
`exchange(URI, HttpMethod, HttpEntity, ParameterizedTypeReference)`spring-doc.cadn.net.cn	`method(HttpMethod) .uri(URI) .headers(Consumer<HttpHeaders>) .body(Object) .retrieve() .toEntity(ParameterizedTypeReference)` ^[1]spring-doc.cadn.net.cn
`exchange(RequestEntity, Class)`spring-doc.cadn.net.cn	`method(HttpMethod) .uri(URI) .headers(Consumer<HttpHeaders>) .body(Object) .retrieve() .toEntity(Class)` ^[2]spring-doc.cadn.net.cn
`exchange(RequestEntity, ParameterizedTypeReference)`spring-doc.cadn.net.cn	`method(HttpMethod) .uri(URI) .headers(Consumer<HttpHeaders>) .body(Object) .retrieve() .toEntity(ParameterizedTypeReference)` ^[2]spring-doc.cadn.net.cn
`execute(String, HttpMethod, RequestCallback, ResponseExtractor, Object…)`spring-doc.cadn.net.cn	`method(HttpMethod) .uri(String, Object…) .exchange(ExchangeFunction)`spring-doc.cadn.net.cn
`execute(String, HttpMethod, RequestCallback, ResponseExtractor, Map)`spring-doc.cadn.net.cn	`method(HttpMethod) .uri(String, Map) .exchange(ExchangeFunction)`spring-doc.cadn.net.cn
`execute(URI, HttpMethod, RequestCallback, ResponseExtractor)`spring-doc.cadn.net.cn	`method(HttpMethod) .uri(URI) .exchange(ExchangeFunction)`spring-doc.cadn.net.cn

HTTP 接口

Spring Framework 允许您将 HTTP 服务定义为 Java 接口，其中@HttpExchange方法。您可以将此类接口传递给HttpServiceProxyFactory创建通过 HTTP 客户端（如RestClient或WebClient.您还可以从@Controller服务器请求处理。spring-doc.cadn.net.cn

首先使用@HttpExchange方法：spring-doc.cadn.net.cn

public interface RepositoryService {

	@GetExchange("/repos/{owner}/{repo}")
	Repository getRepository(@PathVariable String owner, @PathVariable String repo);

	// more HTTP exchange methods...

}

现在，您可以创建一个代理，在调用方法时执行请求。spring-doc.cadn.net.cn

为RestClient:spring-doc.cadn.net.cn

RestClient restClient = RestClient.builder().baseUrl("https://api.github.com/").build();
RestClientAdapter adapter = RestClientAdapter.create(restClient);
HttpServiceProxyFactory factory = HttpServiceProxyFactory.builderFor(adapter).build();

RepositoryService service = factory.createClient(RepositoryService.class);

为WebClient:spring-doc.cadn.net.cn

WebClient webClient = WebClient.builder().baseUrl("https://api.github.com/").build();
WebClientAdapter adapter = WebClientAdapter.create(webClient);
HttpServiceProxyFactory factory = HttpServiceProxyFactory.builderFor(adapter).build();

RepositoryService service = factory.createClient(RepositoryService.class);

为RestTemplate:spring-doc.cadn.net.cn

RestTemplate restTemplate = new RestTemplate();
restTemplate.setUriTemplateHandler(new DefaultUriBuilderFactory("https://api.github.com/"));
RestTemplateAdapter adapter = RestTemplateAdapter.create(restTemplate);
HttpServiceProxyFactory factory = HttpServiceProxyFactory.builderFor(adapter).build();

RepositoryService service = factory.createClient(RepositoryService.class);

@HttpExchange在类型级别受支持，它适用于所有方法：spring-doc.cadn.net.cn

@HttpExchange(url = "/repos/{owner}/{repo}", accept = "application/vnd.github.v3+json")
public interface RepositoryService {

	@GetExchange
	Repository getRepository(@PathVariable String owner, @PathVariable String repo);

	@PatchExchange(contentType = MediaType.APPLICATION_FORM_URLENCODED_VALUE)
	void updateRepository(@PathVariable String owner, @PathVariable String repo,
			@RequestParam String name, @RequestParam String description, @RequestParam String homepage);

}

方法参数

带注释的 HTTP 交换方法支持灵活的方法签名，包括以下内容方法参数：spring-doc.cadn.net.cn

Method 参数描述

Method 参数	描述
`URI`spring-doc.cadn.net.cn	动态设置请求的 URL，覆盖注释的`url`属性。spring-doc.cadn.net.cn
`UriBuilderFactory`spring-doc.cadn.net.cn	提供`UriBuilderFactory`以展开 URI 模板和 URI 变量。实际上，将`UriBuilderFactory`（及其基 URL）的 URL。spring-doc.cadn.net.cn
`HttpMethod`spring-doc.cadn.net.cn	动态设置请求的 HTTP 方法，覆盖注释的`method`属性spring-doc.cadn.net.cn
`@RequestHeader`spring-doc.cadn.net.cn	添加一个或多个请求标头。参数可以是单个值一个`Collection<?>`的值，`Map<String, ?>`,`MultiValueMap<String, ?>`. 非 String 值支持类型转换。添加标头值，并且不要覆盖已添加的标头值。spring-doc.cadn.net.cn
`@PathVariable`spring-doc.cadn.net.cn	在请求 URL 中添加用于扩展占位符的变量。参数可以是`Map<String, ?>`具有多个变量或单个值。类型转换支持非 String 值。spring-doc.cadn.net.cn
`@RequestAttribute`spring-doc.cadn.net.cn	提供`Object`添加为 request 属性。仅支持`RestClient`和`WebClient`.spring-doc.cadn.net.cn
`@RequestBody`spring-doc.cadn.net.cn	将请求的主体作为要序列化的对象或响应式流`Publisher`如`Mono`,`Flux`或任何其他异步类型支持的通过配置的`ReactiveAdapterRegistry`.spring-doc.cadn.net.cn
`@RequestParam`spring-doc.cadn.net.cn	添加一个或多个请求参数。参数可以是`Map<String, ?>`或`MultiValueMap<String, ?>`如果有多个参数，则`Collection<?>`of 值或单个值。非 String 值支持类型转换。spring-doc.cadn.net.cn 什么时候`"content-type"`设置为`"application/x-www-form-urlencoded"`请求参数在请求正文中编码。否则，它们将被添加为 URL 查询参数。spring-doc.cadn.net.cn
`@RequestPart`spring-doc.cadn.net.cn	添加请求部分，可以是 String （表单字段），`Resource`（文件部分）、对象（要编码的实体，例如，作为 JSON），`HttpEntity`（部分内容和标题）、弹簧`Part`或 Reactive Streams`Publisher`属于上述任何一项。spring-doc.cadn.net.cn
`MultipartFile`spring-doc.cadn.net.cn	从`MultipartFile`，通常用于 Spring MVC 控制器其中，它表示上传的文件。spring-doc.cadn.net.cn
`@CookieValue`spring-doc.cadn.net.cn	添加一个或多个 Cookie。参数可以是`Map<String, ?>`或`MultiValueMap<String, ?>`对于多个 Cookie，则`Collection<?>`的值，或者 individual value 的非 String 值支持类型转换。spring-doc.cadn.net.cn

URIspring-doc.cadn.net.cn

动态设置请求的 URL，覆盖注释的url属性。spring-doc.cadn.net.cn

UriBuilderFactoryspring-doc.cadn.net.cn

提供UriBuilderFactory以展开 URI 模板和 URI 变量。实际上，将UriBuilderFactory（及其基 URL）的 URL。spring-doc.cadn.net.cn

HttpMethodspring-doc.cadn.net.cn

动态设置请求的 HTTP 方法，覆盖注释的method属性spring-doc.cadn.net.cn

@RequestHeaderspring-doc.cadn.net.cn

添加一个或多个请求标头。参数可以是单个值一个Collection<?>的值，Map<String, ?>,MultiValueMap<String, ?>. 非 String 值支持类型转换。添加标头值，并且不要覆盖已添加的标头值。spring-doc.cadn.net.cn

@PathVariablespring-doc.cadn.net.cn

在请求 URL 中添加用于扩展占位符的变量。参数可以是Map<String, ?>具有多个变量或单个值。类型转换支持非 String 值。spring-doc.cadn.net.cn

@RequestAttributespring-doc.cadn.net.cn

提供Object添加为 request 属性。仅支持RestClient和WebClient.spring-doc.cadn.net.cn

@RequestBodyspring-doc.cadn.net.cn

将请求的主体作为要序列化的对象或响应式流Publisher如Mono,Flux或任何其他异步类型支持的通过配置的ReactiveAdapterRegistry.spring-doc.cadn.net.cn

@RequestParamspring-doc.cadn.net.cn

添加一个或多个请求参数。参数可以是Map<String, ?>或MultiValueMap<String, ?>如果有多个参数，则Collection<?>of 值或单个值。非 String 值支持类型转换。spring-doc.cadn.net.cn

什么时候"content-type"设置为"application/x-www-form-urlencoded"请求参数在请求正文中编码。否则，它们将被添加为 URL 查询参数。spring-doc.cadn.net.cn

@RequestPartspring-doc.cadn.net.cn

添加请求部分，可以是 String （表单字段），Resource（文件部分）、对象（要编码的实体，例如，作为 JSON），HttpEntity（部分内容和标题）、弹簧Part或 Reactive StreamsPublisher属于上述任何一项。spring-doc.cadn.net.cn

MultipartFilespring-doc.cadn.net.cn

从MultipartFile，通常用于 Spring MVC 控制器其中，它表示上传的文件。spring-doc.cadn.net.cn

@CookieValuespring-doc.cadn.net.cn

添加一个或多个 Cookie。参数可以是Map<String, ?>或MultiValueMap<String, ?>对于多个 Cookie，则Collection<?>的值，或者 individual value 的非 String 值支持类型转换。spring-doc.cadn.net.cn

方法参数不能为null除非required属性（在 parameter annotation）设置为false，或者参数标记为 optional （可选），由MethodParameter#isOptional.spring-doc.cadn.net.cn

自定义参数解析器

对于更复杂的情况，HTTP 接口不支持RequestEntity类型作为方法参数。这将接管整个 HTTP 请求，而不是改进接口的语义。开发人员可以将它们组合成一个自定义类型，而不是添加许多方法参数并配置专用的HttpServiceArgumentResolver实现。spring-doc.cadn.net.cn

在下面的 HTTP 接口中，我们使用了一个自定义的Searchtype 作为参数：spring-doc.cadn.net.cn

Javaspring-doc.cadn.net.cn
Kotlinspring-doc.cadn.net.cn

public interface RepositoryService {

	@GetExchange("/repos/search")
	List<Repository> searchRepository(Search search);

}

interface RepositoryService {

	@GetExchange("/repos/search")
	fun searchRepository(search: Search): List<Repository>

}

我们可以实施自己的HttpServiceArgumentResolver支持我们的自定义Search类型并将其数据写入传出 HTTP 请求中。spring-doc.cadn.net.cn

Javaspring-doc.cadn.net.cn
Kotlinspring-doc.cadn.net.cn

static class SearchQueryArgumentResolver implements HttpServiceArgumentResolver {
	@Override
	public boolean resolve(Object argument, MethodParameter parameter, HttpRequestValues.Builder requestValues) {
		if (parameter.getParameterType().equals(Search.class)) {
			Search search = (Search) argument;
			requestValues.addRequestParameter("owner", search.owner());
			requestValues.addRequestParameter("language", search.language());
			requestValues.addRequestParameter("query", search.query());
			return true;
		}
		return false;
	}
}

class SearchQueryArgumentResolver : HttpServiceArgumentResolver {
	override fun resolve(
		argument: Any?,
		parameter: MethodParameter,
		requestValues: HttpRequestValues.Builder
	): Boolean {
		if (parameter.getParameterType() == Search::class.java) {
			val search = argument as Search
			requestValues.addRequestParameter("owner", search.owner)
				.addRequestParameter("language", search.language)
				.addRequestParameter("query", search.query)
			return true
		}
		return false
	}
}

最后，我们可以在设置过程中使用这个参数解析器，并使用我们的 HTTP 接口。spring-doc.cadn.net.cn

Javaspring-doc.cadn.net.cn
Kotlinspring-doc.cadn.net.cn

RestClient restClient = RestClient.builder().baseUrl("https://api.github.com/").build();
RestClientAdapter adapter = RestClientAdapter.create(restClient);
HttpServiceProxyFactory factory = HttpServiceProxyFactory
		.builderFor(adapter)
		.customArgumentResolver(new SearchQueryArgumentResolver())
		.build();
RepositoryService repositoryService = factory.createClient(RepositoryService.class);

Search search = Search.create()
		.owner("spring-projects")
		.language("java")
		.query("rest")
		.build();
List<Repository> repositories = repositoryService.searchRepository(search);

val restClient = RestClient.builder().baseUrl("https://api.github.com/").build()
val adapter = RestClientAdapter.create(restClient)
val factory = HttpServiceProxyFactory
	.builderFor(adapter)
	.customArgumentResolver(SearchQueryArgumentResolver())
	.build()
val repositoryService = factory.createClient<RepositoryService>(RepositoryService::class.java)

val search = Search(owner = "spring-projects", language = "java", query = "rest")
val repositories = repositoryService.searchRepository(search)

返回值

支持的返回值取决于底层客户端。spring-doc.cadn.net.cn

适应HttpExchangeAdapter如RestClient和RestTemplate支持同步返回值：spring-doc.cadn.net.cn

方法返回值描述

方法返回值	描述
`void`spring-doc.cadn.net.cn	执行给定的请求。spring-doc.cadn.net.cn
`HttpHeaders`spring-doc.cadn.net.cn	执行给定的请求并返回响应标头。spring-doc.cadn.net.cn
`<T>`spring-doc.cadn.net.cn	执行给定的请求并将响应内容解码为声明的返回类型。spring-doc.cadn.net.cn
`ResponseEntity<Void>`spring-doc.cadn.net.cn	执行给定的请求并返回一个`ResponseEntity`替换为 Status 和 Headers。spring-doc.cadn.net.cn
`ResponseEntity<T>`spring-doc.cadn.net.cn	执行给定的请求，将响应内容解码为声明的返回类型，然后返回一个`ResponseEntity`替换为 status、Headers 和 Decoded body。spring-doc.cadn.net.cn

voidspring-doc.cadn.net.cn

执行给定的请求。spring-doc.cadn.net.cn

HttpHeadersspring-doc.cadn.net.cn

执行给定的请求并返回响应标头。spring-doc.cadn.net.cn

<T>spring-doc.cadn.net.cn

执行给定的请求并将响应内容解码为声明的返回类型。spring-doc.cadn.net.cn

ResponseEntity<Void>spring-doc.cadn.net.cn

执行给定的请求并返回一个ResponseEntity替换为 Status 和 Headers。spring-doc.cadn.net.cn

ResponseEntity<T>spring-doc.cadn.net.cn

执行给定的请求，将响应内容解码为声明的返回类型，然后返回一个ResponseEntity替换为 status、Headers 和 Decoded body。spring-doc.cadn.net.cn

适应ReactorHttpExchangeAdapter如WebClient，支持以上所有以及响应式变体。下表显示了 Reactor 类型，但您也可以使用其他响应式类型，这些类型通过ReactiveAdapterRegistry:spring-doc.cadn.net.cn

方法返回值描述

方法返回值	描述
`Mono<Void>`spring-doc.cadn.net.cn	执行给定的请求，并发布响应内容（如果有）。spring-doc.cadn.net.cn
`Mono<HttpHeaders>`spring-doc.cadn.net.cn	执行给定的请求，释放响应内容（如果有），并返回响应标头。spring-doc.cadn.net.cn
`Mono<T>`spring-doc.cadn.net.cn	执行给定的请求并将响应内容解码为声明的返回类型。spring-doc.cadn.net.cn
`Flux<T>`spring-doc.cadn.net.cn	执行给定的请求，并将响应内容解码为声明的元素类型。spring-doc.cadn.net.cn
`Mono<ResponseEntity<Void>>`spring-doc.cadn.net.cn	执行给定的请求，并释放响应内容（如果有），并返回一个`ResponseEntity`替换为 Status 和 Headers。spring-doc.cadn.net.cn
`Mono<ResponseEntity<T>>`spring-doc.cadn.net.cn	执行给定的请求，将响应内容解码为声明的返回类型，然后返回一个`ResponseEntity`替换为 status、Headers 和 Decoded body。spring-doc.cadn.net.cn
`Mono<ResponseEntity<Flux<T>>`spring-doc.cadn.net.cn	执行给定的请求，将响应内容解码为声明的元素类型，并返回一个`ResponseEntity`替换为 status、headers 和 decoded 响应正文流。spring-doc.cadn.net.cn

Mono<Void>spring-doc.cadn.net.cn

执行给定的请求，并发布响应内容（如果有）。spring-doc.cadn.net.cn

Mono<HttpHeaders>spring-doc.cadn.net.cn

执行给定的请求，释放响应内容（如果有），并返回响应标头。spring-doc.cadn.net.cn

Mono<T>spring-doc.cadn.net.cn

执行给定的请求并将响应内容解码为声明的返回类型。spring-doc.cadn.net.cn

Flux<T>spring-doc.cadn.net.cn

执行给定的请求，并将响应内容解码为声明的元素类型。spring-doc.cadn.net.cn

Mono<ResponseEntity<Void>>spring-doc.cadn.net.cn

执行给定的请求，并释放响应内容（如果有），并返回一个ResponseEntity替换为 Status 和 Headers。spring-doc.cadn.net.cn

Mono<ResponseEntity<T>>spring-doc.cadn.net.cn

执行给定的请求，将响应内容解码为声明的返回类型，然后返回一个ResponseEntity替换为 status、Headers 和 Decoded body。spring-doc.cadn.net.cn

Mono<ResponseEntity<Flux<T>>spring-doc.cadn.net.cn

执行给定的请求，将响应内容解码为声明的元素类型，并返回一个ResponseEntity替换为 status、headers 和 decoded 响应正文流。spring-doc.cadn.net.cn

默认情况下，同步返回值的超时时间ReactorHttpExchangeAdapter取决于底层 HTTP 客户端的配置方式。您可以设置blockTimeout值，但我们建议依赖底层 HTTP 客户端，它在较低级别运行并提供更多控制。spring-doc.cadn.net.cn

错误处理

要自定义错误响应处理，您需要配置底层 HTTP 客户端。spring-doc.cadn.net.cn

为RestClient:spring-doc.cadn.net.cn

默认情况下，RestClient提高RestClientException对于 4xx 和 5xx HTTP 状态代码。要自定义此功能，请注册适用于所有响应的响应状态处理程序通过客户端执行：spring-doc.cadn.net.cn

RestClient restClient = RestClient.builder()
		.defaultStatusHandler(HttpStatusCode::isError, (request, response) -> ...)
		.build();

RestClientAdapter adapter = RestClientAdapter.create(restClient);
HttpServiceProxyFactory factory = HttpServiceProxyFactory.builderFor(adapter).build();

有关更多详细信息和选项（例如禁止显示错误状态代码），请参阅 JavadocdefaultStatusHandler在RestClient.Builder.spring-doc.cadn.net.cn

为WebClient:spring-doc.cadn.net.cn

默认情况下，WebClient提高WebClientResponseException对于 4xx 和 5xx HTTP 状态代码。要自定义此功能，请注册适用于所有响应的响应状态处理程序通过客户端执行：spring-doc.cadn.net.cn

WebClient webClient = WebClient.builder()
		.defaultStatusHandler(HttpStatusCode::isError, resp -> ...)
		.build();

WebClientAdapter adapter = WebClientAdapter.create(webClient);
HttpServiceProxyFactory factory = HttpServiceProxyFactory.builder(adapter).build();

有关更多详细信息和选项（例如禁止显示错误状态代码），请参阅 JavadocdefaultStatusHandler在WebClient.Builder.spring-doc.cadn.net.cn

为RestTemplate:spring-doc.cadn.net.cn

默认情况下，RestTemplate提高RestClientException对于 4xx 和 5xx HTTP 状态代码。要自定义此设置，请注册一个适用于所有响应的错误处理程序通过客户端执行：spring-doc.cadn.net.cn

RestTemplate restTemplate = new RestTemplate();
restTemplate.setErrorHandler(myErrorHandler);

RestTemplateAdapter adapter = RestTemplateAdapter.create(restTemplate);
HttpServiceProxyFactory factory = HttpServiceProxyFactory.builderFor(adapter).build();

有关更多详细信息和选项，请参阅 JavadocsetErrorHandler在RestTemplate和这ResponseErrorHandler等级制度。spring-doc.cadn.net.cn

1.HttpEntityheaders 和 body 必须提供给RestClient通过headers(Consumer<HttpHeaders>)和body(Object).

2.RequestEntitymethod、URI、headers 和 body 必须提供给RestClient通过method(HttpMethod),uri(URI),headers(Consumer<HttpHeaders>)和body(Object).

REST 客户端

RestClient

创建一个RestClient

使用RestClient

请求 URL

请求标头和正文

检索响应

错误处理

交换

HTTP 消息转换

Jackson JSON 视图

多部分

客户端请求工厂

WebClient

RestTemplate

初始化

身体

迁移自RestTemplate自RestClient

HTTP 接口

方法参数

自定义参数解析器

返回值

错误处理

`RestClient`

创建一个`RestClient`

使用`RestClient`

`WebClient`

`RestTemplate`

迁移自`RestTemplate`自`RestClient`