跳到主要内容

Spring 内容协商

介绍​

在构建 RESTful API 时，客户端和服务器之间需要协商响应的格式。Spring 内容协商（Content Negotiation）是一种机制，允许服务器根据客户端的请求返回不同格式的响应，例如 JSON、XML 或 HTML。这种机制使得 API 更加灵活，能够满足不同客户端的需求。

Spring 内容协商的核心思想是根据请求的 Accept 头或 URL 后缀来决定响应的格式。通过这种方式，服务器可以动态地返回最适合客户端的响应格式。

内容协商的工作原理​

Spring 内容协商主要通过以下两种方式实现：

  1. 基于 Accept 头的协商：客户端在请求头中指定 Accept，服务器根据该头信息返回相应的格式。
  2. 基于 URL 后缀的协商：客户端在 URL 中添加后缀（如 .json 或 .xml），服务器根据后缀返回相应的格式。

基于 Accept 头的协商​

当客户端发送请求时，可以在 Accept 头中指定期望的响应格式。例如：

http
GET /api/resource HTTP/1.1
Accept: application/json

服务器会根据 Accept 头的值返回 JSON 格式的响应。

基于 URL 后缀的协商​

客户端还可以通过在 URL 中添加后缀来指定响应格式。例如：

http
GET /api/resource.json HTTP/1.1

服务器会根据 .json 后缀返回 JSON 格式的响应。

配置内容协商​

在 Spring 中，内容协商可以通过配置 ContentNegotiationConfigurer 来实现。以下是一个简单的配置示例：

java
@Configuration
@EnableWebMvc
public class WebConfig implements WebMvcConfigurer {

    @Override
    public void configureContentNegotiation(ContentNegotiationConfigurer configurer) {
        configurer
            .favorParameter(true) // 允许通过 URL 参数指定格式
            .parameterName("format") // 参数名称为 format
            .ignoreAcceptHeader(false) // 不忽略 Accept 头
            .defaultContentType(MediaType.APPLICATION_JSON) // 默认响应格式为 JSON
            .mediaType("json", MediaType.APPLICATION_JSON) // 支持 JSON 格式
            .mediaType("xml", MediaType.APPLICATION_XML); // 支持 XML 格式
    }
}

在这个配置中，我们允许通过 URL 参数 format 来指定响应格式，并且支持 JSON 和 XML 格式。

实际案例​

假设我们有一个简单的 REST 控制器，返回一个用户信息：

java
@RestController
@RequestMapping("/api/user")
public class UserController {

    @GetMapping
    public User getUser() {
        return new User("John Doe", "john.doe@example.com");
    }
}

请求示例​

  1. 基于 Accept 头的请求：
http
GET /api/user HTTP/1.1
Accept: application/xml

响应：

xml
<user>
    <name>John Doe</name>
    <email>john.doe@example.com</email>
</user>
  1. 基于 URL 后缀的请求：
http
GET /api/user.json HTTP/1.1

响应：

json
{
    "name": "John Doe",
    "email": "john.doe@example.com"
}

总结​

Spring 内容协商是一种强大的机制，允许服务器根据客户端的需求返回不同格式的响应。通过配置 ContentNegotiationConfigurer，我们可以轻松地支持多种响应格式，如 JSON 和 XML。这种机制使得 RESTful API 更加灵活，能够满足不同客户端的需求。

附加资源​

练习​

  1. 尝试在现有的 Spring Boot 项目中配置内容协商，支持 JSON 和 XML 格式。
  2. 创建一个 REST 控制器，返回一个简单的对象，并通过 Accept 头和 URL 后缀测试不同的响应格式。