Spring Boot 入门实操：Controller 接收参数 + Thymeleaf 简单使用

本文记录 Spring Boot 入门实操全流程，从项目创建、资源目录认知，到 Controller 层请求映射、参数接收，再到 Thymeleaf 动态页面渲染。

第一步:创建新项目（附配置与依赖说明）

依赖配置说明

项目创建后，pom.xml 文件会自动引入勾选的依赖，本次实操中注释掉了几个无需使用的依赖，减少项目冗余，具体依赖如下：

小提示：注释无用依赖可降低项目打包体积，减少启动耗时。

第二步:认知 resources 资源目录

resources 是 Spring Boot 项目的核心资源目录，里面包含两个常用文件夹，分工明确：

1. static：存放静态资源（CSS、JS、图片、静态 HTML 等），可直接通过「域名：端口 / 资源名」访问（例如 localhost:8080/page1.jpg）。
2. templates：存放动态资源（需模板引擎渲染的页面，如 Thymeleaf 格式的 HTML），不能直接访问，必须通过 Controller 层映射后跳转访问。
   

第三步: Controller 层开发（核心：请求映射与参数接收）

Controller 是 Spring Boot 接收前端请求、处理业务逻辑的核心层

1.控制器类基础配置

Controller类上先添加 @Controller 注解，该注解的作用是：

• 标记此类为 Spring MVC 的控制器，负责处理前端请求。
• 让 Spring 容器 （IOC 容器）自动扫描并创建该类的实例，无需手动 new 对象。

2. 常用请求映射注解：

请求映射注解用于绑定前端请求路径和后端 Controller 方法，常用的有 3 种:

• @RequestMapping：支持接收所有类型的 HTTP 请求（GET、POST、PUT 等），功能最全面。
• @GetMapping：仅接收 GET 类型请求（简化写法，推荐用于查询数据）。
• @PostMapping：仅接收 POST 类型请求（简化写法，推荐用于提交表单、提交数据）。

3. 多请求方式兼容配置：

如果需要一个接口同时支持 GET 和 POST 请求，有两种实现方式：
// 方式1： @GetMapping("/page2") @PostMapping("/page2")
// 方式2：@RequestMapping 显式指定 method 属性 @RequestMapping(value = "/page2",method = {RequestMethod.GET, RequestMethod.POST})

其中 method = {RequestMethod.GET, RequestMethod.POST} ,可同时指定多种支持的 HTTP 请求方式。

4.完整访问地址说明：

若控制器类上无统一路径注解，方法上的路径即为最终访问路径（例如 @GetMapping("/page2") 对应 localhost:8080/page2）；
若类上添加了 @RequestMapping("/page")，则最终完整地址为「类路径 + 方法路径」，即 localhost:8080/page/page2。

5.Controller 接收参数的几种常用方式

前端向后端传递参数时，可根据参数数量、参数格式，选择不同的接收方式:

（Controller 接收参数的几种常用方式）

	// 方式1：基础接收（前端参数名与方法参数名一致，直接绑定）
public String page2(String username, String password, Map<String,Object> map){}
	// 方式2：指定前端参数名（@RequestParam 注解，解决前后端参数名不一致问题）
// 注解内的 "username12" 是前端传递的参数名，绑定到后端的 username 变量上
public String page2(@RequestParam("username12") String username, String password, Map<String,Object> map){}

	// 方式3：实体类接收（推荐，参数较多时简化代码）
// User 是 domain 包下的实体类（需包含与前端参数对应的属性 + getter/setter 方法）
// 自动将前端参数封装到 User 对象中，替代多个单独的字符串参数
public String page2(User user, Map<String,Object> map){}

	// 方式4：接收 JSON 格式参数（@RequestBody 注解）
// 前端传递的是 JSON 对象时，需用该注解将 JSON 数据封装到 User 实体类中
public String page2(@RequestBody User user, Map<String,Object> map){}

	// 方式5：返回数据而非页面（@ResponseBody 注解）
// 加 @ResponseBody 后，返回值不再是逻辑地址，而是直接返回数据（此处返回 Map 格式数据）
public Map<String,String> page2(@RequestBody User user, Map<String,Object> map){}

6. 补充：前端发送 JSON 数据说明

当使用 @RequestBody 接收参数时，前端需发送 JSON 格式数据，示例如下：

关键注意点：前后端参数必须对应

1. 实体类的属性名需与 JSON 中的键名一致（大小写敏感）。
2. 实体类必须提供无参构造方法和对应的 getter/setter 方法，否则无法完成数据封装。

参数对应示例图示：

7. Map 存放数据（用于传递到前端页面）

在 Controller 方法中定义 Map<String,Object> map，可用于存储数据并传递到前端动态页面，后续通过 Thymeleaf 取出渲染。有两种常用赋值方式，对应不同的参数接收场景：

点击查看代码

// 方式1：基础参数接收时，手动存入单个参数（注释掉的基础用法）
// map.put("username", username);
// map.put("password", password);

// 方式2：实体类接收时，直接存入整个实体对象
map.put("user", user);

除了实体对象，也可向 Map 中存放其他类型数据（如字符串集合），这些数据均可在前端页面取出使用：

核心总结：返回值的区别

控制器方法的返回值类型，取决于是否添加 @ResponseBody 注解：
不加 @ResponseBody：返回视图逻辑地址。
加 @ResponseBody：返回数据（例如 Map、JSON 等），不跳转页面，常用于前后端分离场景。

第四步: templates->page2.html（Thymeleaf 模板引擎使用）

Thymeleaf 是 Spring Boot 推荐的模板引擎，用于渲染动态页面，可直接读取 Controller 传递的 Map 数据，步骤简单，新手易上手。

1. 页面创建与 Thymeleaf 启用

• 在 resources/templates 目录下，创建 page2.html 文件（动态页面，无法直接访问，需通过 Controller 映射）。
• 启用 Thymeleaf 语法：在 HTML 根标签中添加命名空间
  xmlns:th="http://www.thymeleaf.org"，添加后即可使用 Thymeleaf 的表达式和标签，实现数据渲染。
  命名空间添加图示：
  

常见报错信息排查

报错状态码	报错原因	排查方向
404	页面找不到	1. 访问网址输入错误；2. Controller 方法返回的视图名与 templates 下的页面名不一致；3. 静态资源放错目录
500	后端程序异常	1. Java 代码有语法错误；2. 实体类缺少 getter/setter 或无参构造方法；3. Thymeleaf 表达式语法错误。
405	请求方法不匹配	1. 前端发送的请求方式（GET/POST）与后端 Controller 注解不匹配（例如前端 POST，后端用 @GetMapping 接收）；

报错示例图示：

总结

Spring Boot 从项目创建到动态页面渲染的全流程，核心重点：

• 分清 static（静态资源，可直接访问）和 templates（动态资源，需 Controller 映射）的区别。

• 掌握 3 种请求映射注解的用法，以及多请求方式兼容的配置。

• 5 种参数接收方式，分清 @RequestParam 和 @RequestBody 的适用场景。

• 记住 @ResponseBody 的作用，分清「返回页面」和「返回数据」的区别。

• 掌握常见报错的排查方法。