Spring Boot 2.7: 简化控制器 JSON 交互的全局配置

在 spring boot 2.7 及更高版本中，为避免在每个控制器方法上重复指定 json 媒体类型，只需在控制器类上使用 `@restcontroller` 注解。该注解结合了 `@controller` 和 `@responsebody` 的功能，能够自动将所有处理方法的默认生产和消费媒体类型设置为 `application/json`，从而极大地简化了 restful api 的开发和配置。

引言：简化 Spring Boot 控制器的 JSON 交互

在开发 Spring Boot 应用程序时，特别是构建 RESTful API，控制器经常需要处理 JSON 格式的请求体和响应体。一个常见的实践是在每个 @RequestMapping 或更具体的 HTTP 方法注解（如 @GetMapping、@PostMapping）上显式地添加 consumes = MediaType.APPLICATION_JSON_VALUE 和 produces = MediaType.APPLICATION_JSON_VALUE 属性。这种做法虽然有效，但随着控制器方法数量的增加，会导致大量的重复代码，降低代码的可读性和维护性。

例如，以下是常见但冗余的写法：

import org.springframework.http.MediaType;
import org.springframework.web.bind.annotation.GetMapping;
import org.springframework.web.bind.annotation.PostMapping;
import org.springframework.web.bind.annotation.RequestBody;
import org.springframework.web.bind.annotation.RequestMapping;
import org.springframework.web.bind.annotation.RestController;

@RestController
@RequestMapping("/api/legacy")
public class LegacyController {

    @GetMapping(produces = MediaType.APPLICATION_JSON_VALUE)
    public MyResponse getData() {
        // ... logic
        return new MyResponse("Hello", "World");
    }

    @PostMapping(consumes = MediaType.APPLICATION_JSON_VALUE, produces = MediaType.APPLICATION_JSON_VALUE)
    public MyResponse createData(@RequestBody MyRequest request) {
        // ... logic
        return new MyResponse("Received", request.getMessage());
    }
}

这种重复配置不仅繁琐，而且一旦需要修改默认的媒体类型（尽管对于 JSON API 来说不常见），就需要修改每一个方法。

核心解决方案：@RestController 注解

Spring Framework 提供了一个更优雅、更符合 RESTful API 设计理念的解决方案：使用 @RestController 注解。这个注解是 @Controller 和 @ResponseBody 的组合，专门用于构建 RESTful Web 服务。

当一个类被 @RestController 注解时，Spring 会自动将其视为一个 REST 控制器，并默认将所有处理方法的返回值序列化为响应体，同时也将请求体反序列化为方法参数。对于大多数 Spring Boot Web 项目，由于默认包含了 Jackson 库，这意味着 JSON 将成为默认的生产和消费媒体类型，无需在每个方法上显式声明 consumes 和 produces 属性。

工作原理深入解析

理解 @RestController 如何实现这一功能，需要了解其背后的两个核心组件：

1. @Controller 的角色：@Controller 是 Spring MVC 的核心注解之一，用于标记一个类为请求处理组件。它负责处理传入的 HTTP 请求，并根据请求路径、方法等信息将请求路由到相应的处理方法。

   

   AI at Meta

   Facebook 旗下的AI研究平台

   下载

2. @ResponseBody 的角色：@ResponseBody 注解指示 Spring 将方法的返回值直接绑定到 HTTP 响应体。当一个方法被 @ResponseBody 注解时，Spring 不会尝试将其解析为视图名称，而是通过 HttpMessageConverter 机制将其内容写入响应流。

3. 消息转换器 (HttpMessageConverter)： Spring MVC 内部使用 HttpMessageConverter 接口来处理 HTTP 请求和响应体与 Java 对象之间的转换。对于 JSON 数据，Spring Boot 默认会配置 MappingJackson2HttpMessageConverter（如果 classpath 中包含 Jackson 库）。当 @ResponseBody 被激活时，Spring 会根据客户端请求的 Accept 头和服务器能够 produces 的媒体类型，以及请求的 Content-Type 头和服务器能够 consumes 的媒体类型，选择合适的 HttpMessageConverter 来进行数据转换。

当一个类被 @RestController 注解时，它隐式地为该类中的所有处理方法提供了 @ResponseBody 的功能。这意味着，对于典型的 RESTful API，当客户端发送 Content-Type: application/json 的请求并期望 Accept: application/json 的响应时，MappingJackson2HttpMessageConverter 将被自动启用，从而实现 JSON 数据的无缝处理。

代码示例：告别冗余配置

使用 @RestController 注解，我们可以极大地简化控制器代码，使其更加简洁和专注于业务逻辑。

推荐做法（简洁且符合规范）：

import org.springframework.web.bind.annotation.GetMapping;
import org.springframework.web.bind.annotation.PostMapping;
import org.springframework.web.bind.annotation.RequestBody;
import org.springframework.web.bind.annotation.RequestMapping;
import org.springframework.web.bind.annotation.RestController;

// 假设存在 MyRequest 和 MyResponse 类，它们是普通的POJO
class MyRequest {
    private String message;
    // Getters and Setters
    public String getMessage() { return message; }
    public void setMessage(String message) { this.message = message; }
}

class MyResponse {
    private String status;
    private String data;
    // Constructor, Getters and Setters
    public MyResponse(String status, String data) { this.status = status; this.data = data; }
    public String getStatus() { return status; }
    public String getData() { return data; }
    public void setStatus(String status) { this.status = status; }
    public void setData(String data) { this.data = data; }
}


@RestController // 关键：这个注解处理了JSON的默认行为
@RequestMapping("/api/v1")
public class MyRestController {

    @GetMapping("/data")
    public MyResponse getData() {
        System.out.println("Handling GET /api/v1/data");
        return new MyResponse("Success", "Data fetched successfully");
    }

    @PostMapping("/create")
    public MyResponse createData(@RequestBody MyRequest request) {
        System.out.println("Handling POST /api/v1/create with message: " + request.getMessage());
        return new MyResponse("Success", "Data created with message: " + request.getMessage());
    }
}

在这个优化后的示例中，我们移除了所有方法级别的 consumes 和 produces 属性。仅仅通过在类上添加 @RestController，Spring Boot 就能够智能地识别并处理 JSON 格式的请求和响应。这不仅让代码更加精炼，也减少了出错的可能性。

注意事项与最佳实践

1. 注解范围： @RestController 作用于整个类。这意味着该类中的所有 @RequestMapping 及其变体（如 @GetMapping, @PostMapping 等）都会默认以 JSON 格式处理请求和响应。
2. 局部覆盖： 尽管 @RestController 设置了全局默认值，但如果某个特定方法确实需要处理非 JSON 媒体类型（例如，返回纯文本、XML 或文件），你仍然可以在该方法上显式地使用 produces 或 consumes 属性来覆盖默认行为。

   @GetMapping(value = "/plainText", produces = MediaType.TEXT_PLAIN_VALUE)
   public String getPlainText() {
       return "This is plain text.";
   }

3. 依赖检查： 确保你的项目中包含了 JSON 处理库，如 Jackson。在 Spring Boot 的 spring-boot-starter-web 依赖中，Jackson 是默认包含的，因此通常无需额外配置。
4. @Controller 与 @RestController 的选择：
   • @Controller 通常用于传统的 Spring MVC 应用，它与视图解析器（View Resolver）协同工作，返回视图名称，用于渲染 HTML 页面。
   • @RestController 专为构建 RESTful API 设计，它返回的是数据（通常是 JSON 或 XML），这些数据直接写入 HTTP 响应体，不涉及视图解析。 因此，在开发纯后端 API 服务时，应始终优先选择 @RestController。
5. 内容协商： 默认情况下，Spring 会根据客户端请求头中的 Accept 字段进行内容协商。如果客户端请求 Accept: application/json，即使没有显式 produces 属性，Spring 也会尝试返回 JSON。同样，对于 Content-Type: application/json 的请求，Spring 会尝试将其反序列化为 Java 对象。

总结

@RestController 注解是 Spring Boot 中构建 RESTful API 的一个强大且便捷的工具。它通过结合 @Controller 和 @ResponseBody 的功能，极大地简化了 JSON 媒体类型的处理，消除了冗余的 consumes 和 produces 属性配置。采纳这种最佳实践不仅能让你的代码更简洁、更易读，还能提升开发效率，使你能够更专注于业务逻辑的实现。在任何 Spring Boot 2.7 或更高版本的 RESTful API 项目中，都应优先考虑使用 @RestController 来声明你的控制器。