CC大煊

【java】@RestController和@Controller的区别

文章目录

1. 引言
- 常用Web开发注解
- @Controller 与 @RestController 的定位
2. @Controller详解
- 2.1 概念解析及使用场景
- 2.2 核心原理及底层实现
- 2.3 示例代码及必需的import展示
- 2.4 使用注意事项
3. @RestController详解
- 3.1 概念解析及使用场景
- 3.2 相较@Controller的便捷性
- 3.3 内部原理及@ResponseBody的自动注入机制
- 3.4 示例代码及必需的import展示
- 3.5 使用注意事项
4. @Controller vs @RestController对比分析
- 4.1 功能及底层实现的异同
- 4.2 使用场景和业务需求解读
- 4.3 注意事项总结
5. 实战案例分析
- 5.1 使用@Controller构建传统Web应用案例
- 5.2 使用@RestController构建RESTful API案例
- 5.3 对比代码结构及开发体验
6. 常见问题与解决方案
- 6.1 两种注解混用时的注意点
- 6.2 JSON返回格式和页面解析的常见问题
- 6.3 多模块项目中使用的坑和调试技巧

1. 引言

常用Web开发注解

@Controller
- 用于标记一个类作为Spring MVC中的控制器，主要服务于传统的基于页面跳转的请求处理。
- 通常与视图解析器（View Resolver）一起使用，将处理结果以页面的形式展示给用户。
@RestController
- 是一个组合注解，包含了@Controller和@ResponseBody。
- 主要用于开发RESTful API接口，返回的数据不会经过视图解析器处理，而是直接写入HTTP响应体中（通常是JSON或XML格式）。
@RequestMapping
- 用于指定请求的URL路径，可以在类或方法上进行注解，使得请求映射更加灵活。
@GetMapping, @PostMapping, @PutMapping, @DeleteMapping
- 这些注解是@RequestMapping的快捷方式，明确标识HTTP请求的特定方式，使代码更加直观和易于维护。
@ResponseBody
- 表示返回结果直接写入HTTP响应体中，不通过视图解析器处理，通常用于返回JSON数据。
@RequestParam, @PathVariable, @RequestBody
- 用于从请求中提取参数或者直接绑定请求体内容到方法参数上，从而简化请求参数解析过程。

@Controller 与 @RestController 的定位

在开发中，我们经常会遇到两种不同的业务场景，这时我们需要根据实际需求选择不同的注解：

传统页面交互（MVC模式）
- 业务一般需要返回视图页面，例如跳转到一个HTML页面或JSP页面。此时我们倾向使用@Controller。
- 开发人员同时可以根据需要在方法中使用@ResponseBody注解来返回JSON数据，但这会让方法的风格不一致。
RESTful API开发
- 当应用主要提供API接口服务（如前后端分离架构），返回的数据类型通常为JSON、XML等格式，不需要视图解析。
- 使用@RestController会更方便，因为它默认添加了@ResponseBody效果，简化了代码结构，减少了重复注解的写法。

2. @Controller详解

在Spring MVC框架中，@Controller主要用于标记一个类为控制器，从而接收和处理来自客户端的请求，返回视图名称或ModelAndView对象，供视图解析器解析后生成最终页面。

2.1 概念解析及使用场景

@Controller注解的类主要用于传统的MVC开发模式。
开发者通过在方法中返回视图名称（如JSP、Thymeleaf模板）供视图解析器处理，最终渲染页面。
使用场景：
- 返回完整的HTML页面，例如用户注册、登录或展示数据。
- 与前端模板技术结合，如JSP、Freemarker、Thymeleaf等。

2.2 核心原理及底层实现

在Spring MVC架构中，DispatcherServlet扮演了前端控制器的角色，整个请求处理流程如下：

客户端发起请求，DispatcherServlet接收该请求。
DispatcherServlet根据请求URL通过HandlerMapping查找对应的@Controller。
找到某个方法后，通过反射调用该方法，执行完后获得返回值。
如果方法返回的是视图名称，将根据配置的ViewResolver解析视图（例如将字符串"home"映射到/home.jsp或home.html）。
最后ViewResolver将返回的Model数据与视图模板合并，生成最终HTML页面返回给客户端。

这种流程就类似于一个快递分拣中心：DispatcherServlet是分拣中心，通过查找和分发将包裹（请求）分发到正确的分拣员（Controller），最终将包裹送达收件人（客户端）。

2.3 示例代码及必需的import展示

下面是一个简单的@Controller示例代码，展示如何处理一个GET请求并返回一个视图页面：

package com.example.demo.controller;

import org.springframework.stereotype.Controller;
import org.springframework.web.bind.annotation.GetMapping;
import org.springframework.ui.Model;

@Controller
public class SampleController {

    // 处理GET请求，访问网址：http://localhost:8080/hello
    @GetMapping("/hello")
    public String hello(Model model) {
        // 添加数据到Model，供前端页面使用
        model.addAttribute("message", "Hello, World!");
        // 返回视图名称，视图解析器将根据该名称查找实际视图（例如hello.jsp、hello.html）
        return "hello";
    }
}

在上面的代码中，需要注意：

必须引入的包：
- org.springframework.stereotype.Controller
- org.springframework.web.bind.annotation.GetMapping
- org.springframework.ui.Model
通过@GetMapping注解，Spring将该方法映射到"/hello"路径。
返回的字符串"hello"是视图名，最终由ViewResolver处理后渲染为一个页面。

2.4 使用注意事项

确保视图解析器(ViewResolver)配置正确，否则返回的视图名称可能无法找到对应的页面模板。
当需要返回JSON数据时，不建议在@Controller类中直接返回对象，除非在方法上标注@ResponseBody。如果混合使用可能会导致视图解析错误。
注意请求路径和视图名称的命名规范，避免出现路径冲突或解析异常。
在大型项目中，合理划分Controller和Service的职责，保证Controller仅负责请求分发和视图返回，而业务逻辑应移至Service层。

3. @RestController详解

在现代Web开发中，@RestController注解为构建RESTful API提供了极大的便利，使得Controller中的方法可以直接返回数据而无需额外的视图解析处理。下面我们详细讲解@RestController的概念、优势、内部原理以及使用中的注意事项。

3.1 概念解析及使用场景

@RestController是Spring 4.0之后推出的注解，它标识一个类是REST风格的控制器。
它是@Controller与@ResponseBody的组合注解，所有的方法默认都带上@ResponseBody的效果。
使用场景：
- 开发微服务或前后端分离架构时，服务端通常只需要返回JSON或XML等结构化数据。
- 当需要构建RESTful API接口，返回数据而不是HTML页面时，非常适合使用@RestController。

3.2 相较@Controller的便捷性

在使用@Controller时，如果方法需要返回JSON数据，就必须在方法上额外声明@ResponseBody注解，使得代码略显冗余。
@RestController将@ResponseBody自动应用于所有方法，简化了开发流程，减少了代码量和出错机会。

3.3 内部原理及@ResponseBody的自动注入机制

@RestController实际内部就是一个组合注解，其本质上等同于在类上同时声明了@Controller和@ResponseBody。
当Spring容器扫描到@RestController标识的类时，它会识别该类下所有@RequestMapping方法，并自动在响应时调用消息转换器（MessageConverter）。
消息转换器负责将返回的Java对象序列化为客户端所需要的JSON或XML格式数据，最终写入HTTP响应体中。
这种自动注入@ResponseBody的机制确保了开发者无需手动添加@ResponseBody注解，从而使得代码更加清晰易读。

3.4 示例代码及必需的import展示

下面提供一段使用@RestController构建RESTful API接口的示例代码，展示如何返回JSON数据以及必须的import包信息：

package com.example.demo.controller;

import org.springframework.web.bind.annotation.GetMapping;
import org.springframework.web.bind.annotation.RestController;

// @RestController组合了@Controller和@ResponseBody
@RestController
public class UserController {

    // 处理 GET 请求，并返回一个用户示例（自动转换为JSON格式输出）
    @GetMapping("/user")
    public User getUser() {
        return new User(1, "Alice");
    }
}

// 示例用户实体类
package com.example.demo.model;

public class User {
    private int id;
    private String name;

    // 必须的无参构造器
    public User() {}

    public User(int id, String name) {
        this.id = id;
        this.name = name;
    }

    // Getter和Setter方法
    public int getId() {
        return id;
    }

    public void setId(int id) {
        this.id = id;
    }

    public String getName() {
        return name;
    }

    public void setName(String name) {
        this.name = name;
    }
}

在上述代码中，注意以下几点：

package声明确保了代码结构的规范性。
必须导入org.springframework.web.bind.annotation.RestController和GetMapping等包以支持注解功能。
返回的User对象将通过Spring内置的消息转换器转为JSON（默认依赖Jackson库）。
任何需要使用JSON转换的Java对象，都需要标准的getter和setter方法。

3.5 使用注意事项

确保项目中已经引入了JSON处理相关的依赖（例如Jackson），否则可能会出现转换异常。
当与传统的@Controller混用时，要注意@ResponseBody是否被正确处理，避免返回错误的视图信息。
对于复杂对象，如果需要定制JSON序列化行为，可以考虑使用@JsonView或编写自定义的HttpMessageConverter。
避免在@RestController中混入页面跳转相关逻辑，保持接口单一职责，便于维护和测试。

4. @Controller vs @RestController对比分析

在Spring MVC开发中，@Controller和@RestController都是用来标识控制器类，但它们在功能和底层实现上存在一定的差异，适用于不同的业务场景。下面对两者进行详细的对比分析。

4.1 功能及底层实现的异同

功能：
- @Controller：用于处理Web请求，主要服务于传统的MVC开发模式，通常需要返回视图名称，然后由ViewResolver去解析和渲染页面。
- @RestController：用于构建RESTful API接口，返回结果直接写入HTTP响应体中（如JSON或XML），适用于前后端分离或微服务场景。
底层实现：
- @Controller：仅仅标识一个类为控制器，方法返回值需要通过视图解析器处理，如果要返回JSON数据，需要在方法上添加@ResponseBody注解。
- @RestController：是@Controller和@ResponseBody的组合注解，它在类层面上自动应用@ResponseBody效果，使得所有方法返回的对象都直接被序列化为HTTP响应体中的数据，简化了开发流程。

4.2 使用场景和业务需求解读

使用场景：
- 当应用需要提供完整的HTML页面服务时，应首选使用@Controller，此时视图层逻辑和模板引擎是必不可少的部分。
- 如果开发RESTful API或仅需要返回JSON/XML数据，@RestController更适合，它避免了多次使用@ResponseBody，保持代码的简洁和一致性。
业务需求：
- 传统的Web应用（例如需要服务端渲染页面、通过JSP、Thymeleaf等动态模板实现页面内容渲染）的核心逻辑，推荐使用@Controller。
- 当系统是前后端分离架构，后端主要负责提供接口、数据处理和返回数据时，@RestController更符合业务需求。

4.3 注意事项总结

全局配置：
- 确保配置正确的视图解析器(ViewResolver)在@Controller环境下能找到正确的视图页面。
- 在@RestController环境下，需引入合适的消息转换器（如Jackson）来支持对象与JSON格式之间的转换。
混用和方法标识：
- 避免在@RestController中混合返回视图和数据，否则可能导致响应内容不符合预期。
- 当需要在@Controller中部分方法返回JSON数据时，只需在对应方法上添加@ResponseBody注解，但这种做法应谨慎使用，保证代码风格的一致性。
性能和扩展：
- 对于RESTful接口，@RestController避免了额外的视图解析步骤，能够在一定程度上提高接口响应速度和资源利用效率。
- 使用过程中注意方法异常处理和全局统一异常配置，避免因异常转换造成返回格式混乱，尤其是在复杂业务逻辑的开发中。

5. 实战案例分析

在实际开发中，我们经常面临两类不同需求：一类是传统的页面渲染应用，另一类是RESTful API服务。下面分别通过案例展示如何使用@Controller和@RestController，并对比其代码结构及开发体验。

5.1 使用@Controller构建传统Web应用案例

场景描述：构建一个简单的用户登录页面。Controller接收到请求后返回一个JSP或Thymeleaf页面，页面上包含一个表单，用户提交登录数据后服务器进行相应处理。

示例代码：

// 文件路径：com.example.demo.controller.LoginController.java

package com.example.demo.controller;

import org.springframework.stereotype.Controller;
import org.springframework.ui.Model;
import org.springframework.web.bind.annotation.GetMapping;
import org.springframework.web.bind.annotation.PostMapping;
import org.springframework.web.bind.annotation.RequestParam;

@Controller
public class LoginController {

    // 展示登录页面
    @GetMapping("/login")
    public String showLoginPage() {
        // 返回视图名称，视图解析器将查找对应的login.html或login.jsp
        return "login";
    }

    // 处理登录请求
    @PostMapping("/login")
    public String processLogin(@RequestParam("username") String username,
                               @RequestParam("password") String password,
                               Model model) {
        // 简单的用户名和密码校验（示例场景，实际应用需更安全的处理）
        if("admin".equals(username) && "123456".equals(password)) {
            model.addAttribute("message", "登录成功！");
            return "welcome"; // 返回欢迎页视图
        } else {
            model.addAttribute("error", "用户名或密码错误！");
            return "login";  // 返回登录页以便重新登录
        }
    }
}

在上面的@Controller案例中：

我们定义了两个处理方法，分别响应GET（展示页面）和POST（处理表单提交）请求。
方法返回的是一个字符串，这个字符串代表视图名称，交由配置好的ViewResolver解析，最终渲染出包含HTML的页面。

5.2 使用@RestController构建RESTful API案例

场景描述：构建一个简单的用户信息查询API。请求接口返回JSON格式的用户数据，供前端或其他服务调用。