SpringMVC 请求保姆级教程：路径映射、参数传递、JSON 交互、日期处理一网打尽（Spring系列12）

摘要SpringMVC 作为 Java Web 开发中最主流的 MVC 框架核心职责就是接收请求、处理数据、响应结果这也是 SpringMVC 学习的重中之重。本文将从环境搭建、请求映射、参数传递普通 / POJO / 数组 / 集合 / JSON / 日期、响应处理页面 / 文本 / JSON全流程拆解附完整代码、常见问题解决方案、核心注解总结帮你彻底搞懂 SpringMVC 请求的所有细节。一、请求映射路径RequestMapping1.1 环境准备首先我们搭建基础的 SpringMVC Web 项目步骤如下1.1.1 创建 Web Maven 项目创建 Maven 项目打包方式为war。1.1.2 pom.xml 依赖配置?xml version1.0 encodingUTF-8? project xmlnshttp://maven.apache.org/POM/4.0.0 xmlns:xsihttp://www.w3.org/2001/XMLSchema-instance xsi:schemaLocationhttp://maven.apache.org/POM/4.0.0 http://maven.apache.org/xsd/maven-4.0.0.xsd modelVersion4.0.0/modelVersion groupIdcom.itheima/groupId artifactIdspringmvc_03_request_mapping/artifactId version1.0-SNAPSHOT/version packagingwar/packaging dependencies dependency groupIdjavax.servlet/groupId artifactIdjavax.servlet-api/artifactId version3.1.0/version scopeprovided/scope /dependency dependency groupIdorg.springframework/groupId artifactIdspring-webmvc/artifactId version5.2.10.RELEASE/version /dependency /dependencies build plugins plugin groupIdorg.apache.tomcat.maven/groupId artifactIdtomcat7-maven-plugin/artifactId version2.1/version configuration port80/port path//path /configuration /plugin /plugins /build /project1.1.3 配置类编写Servlet 容器初始化配置替代 web.xml注册 DispatcherServletpublic class ServletContainersInitConfig extends AbstractAnnotationConfigDispatcherServletInitializer { Override protected Class?[] getServletConfigClasses() { return new Class[]{SpringMvcConfig.class}; }Override protected String[] getServletMappings() { return new String[]{/}; }Override protected Class?[] getRootConfigClasses() { return new Class[0]; } }SpringMVC 配置类开启组件扫描Configuration ComponentScan(com.itheima.controller) public class SpringMvcConfig { }1.1.4 编写 Controller我们先写两个 Controller模拟多人开发的场景Controller public class UserController { RequestMapping(/save) ResponseBody public String save(){ System.out.println(user save ...); return {\module\:\user save\}; }RequestMapping(/delete) ResponseBody public String delete(){ System.out.println(user delete ...); return {\module\:\user delete\}; } }Controller public class BookController { RequestMapping(/save) ResponseBody public String save(){ System.out.println(book save ...); return {\module\:\book save\}; } }1.1.5 项目结构springmvc_03_request_mapping ├── src │ └── main │ └── java │ └── com.itheima │ ├── config │ │ ├── ServletContainersInitConfig.java │ │ └── SpringMvcConfig.java │ └── controller │ ├── BookController.java │ └── UserController.java ├── webapp └── pom.xml1.2 问题请求路径冲突启动 Tomcat 服务器后台直接报错严重: Context initialization failed org.springframework.beans.factory.BeanCreationException: Error creating bean with name requestMappingHandlerMapping defined in org.springframework.context.annotation.ConfigurationClassPostProcessor$EnhancedConfigurationBeanPostProcessorPostProcessor5a3f60f: Invocation of init method failed; nested exception is java.lang.IllegalStateException: Ambiguous mapping. Cannot map bookController method com.itheima.controller.BookController#save() to { [/save]}: There is already userController bean method com.itheima.controller.UserController#save() mapped.1.2.1 问题分析两个 Controller 的save()方法都映射了/save路径导致 SpringMVC 无法区分请求该路由到哪个方法。1.2.2 解决方案 1方法级加前缀给每个方法的路径加模块前缀区分不同模块// UserController RequestMapping(/user/save) ResponseBody public String save(){...}RequestMapping(/user/delete) ResponseBody public String delete(){...}// BookController RequestMapping(/book/save) ResponseBody public String save(){...}缺点每个方法都要加前缀冗余代码多后期维护成本高路径修改需要改所有方法。1.2.3 解决方案 2类级加 RequestMapping推荐在类上添加RequestMapping作为模块前缀方法上写子路径自动拼接Controller RequestMapping(/user) // 类级前缀 public class UserController { RequestMapping(/save) // 最终路径 /user/save ResponseBody public String save(){ System.out.println(user save ...); return {\module\:\user save\}; }RequestMapping(/delete) // 最终路径 /user/delete ResponseBody public String delete(){ System.out.println(user delete ...); return {\module\:\user delete\}; } }Controller RequestMapping(/book) // 类级前缀 public class BookController { RequestMapping(/save) // 最终路径 /book/save ResponseBody public String save(){ System.out.println(book save ...); return {\module\:\book save\}; } }1.2.4 注意事项类和方法的RequestMapping会自动拼接请求路径必须和拼接后的路径完全匹配才能访问RequestMapping的value属性前加/或不加都可以SpringMVC 会自动处理PostMan 字体调整ctrl调大ctrl-调小二、请求参数请求路径配置完成后我们需要处理前端传递的请求参数分为 GET、POST 两种请求方式以及多种参数类型。2.1 环境准备新建项目springmvc_04_request_parampom 依赖、配置类和之前一致新增实体类User和Address// Address.java public class Address { private String province; private String city; // getter/setter省略 }// User.java public class User { private String name; private int age; private Address address; // getter/setter省略 }Controller 基础类Controller public class UserController { RequestMapping(/commonParam) ResponseBody public String commonParam(){ return {\module\:\commonParam\}; } }项目结构springmvc_04_request_param ├── src │ └── main │ └── java │ └── com.itheima │ ├── config │ │ ├── ServletContainersInitConfig.java │ │ └── SpringMvcConfig.java │ ├── controller │ │ └── UserController.java │ └── domain │ ├── Address.java │ └── User.java ├── webapp └── pom.xml2.2 GET/POST 基础参数传递2.2.1 GET 发送单个 / 多个参数发送请求单个参数http://localhost/commonParam?nameitcast多个参数http://localhost/commonParam?nameitcastage15接收参数方法形参名必须和请求参数名完全一致SpringMVC 自动绑定RequestMapping(/commonParam) ResponseBody public String commonParam(String name, int age){ System.out.println(普通参数传递 name name); System.out.println(普通参数传递 age age); return {\module\:\commonParam\}; }GET 中文乱码问题如果传递中文参数如name张三age18会出现乱码普通参数传递 name 寮犱笁 普通参数传递 age 18解决方案在 pom.xml 的 Tomcat7 插件中添加uriEncodingUTF-8plugin groupIdorg.apache.tomcat.maven/groupId artifactIdtomcat7-maven-plugin/artifactId version2.1/version configuration port80/port path//path uriEncodingUTF-8/uriEncoding /configuration /plugin2.2.2 POST 发送参数发送请求PostMan 选择POST请求Body选择x-www-form-urlencoded填写name和age参数接收参数和 GET 完全一致形参名一致即可无需修改代码RequestMapping(/commonParam) ResponseBody public String commonParam(String name, int age){...}POST 中文乱码问题POST 传递中文同样会乱码解决方案配置字符编码过滤器在ServletContainersInitConfig中重写getServletFiltersOverride protected Filter[] getServletFilters() { CharacterEncodingFilter filter new CharacterEncodingFilter(); filter.setEncoding(UTF-8); return new Filter[]{filter}; }CharacterEncodingFilter属于 spring-web 包无需额外导入依赖。2.3 五种类型参数传递2.3.1 普通参数场景前端传递简单的键值对参数规则形参名和请求参数名一致直接接收不一致时用RequestParam绑定不一致示例请求参数name形参userName// 错误参数名不一致userName为null RequestMapping(/commonParamDifferentName) ResponseBody public String commonParamDifferentName(String userName, int age){ System.out.println(普通参数传递 userName userName); System.out.println(普通参数传递 age age); return {\module\:\common param different name\}; }// 正确加RequestParam绑定参数名 RequestMapping(/commonParamDifferentName) ResponseBody public String commonParamDifferentName(RequestParam(name) String userName, int age){ System.out.println(普通参数传递 userName userName); System.out.println(普通参数传递 age age); return {\module\:\common param different name\}; }注意RequestParam无需手动解析参数提升框架处理性能还支持required是否必填、defaultValue默认值属性。2.3.2 POJO 类型参数场景参数较多用实体类封装规则请求参数名和 POJO 的属性名完全一致SpringMVC 自动封装到对象中// 发送请求http://localhost/pojoParam?nameitcastage15 RequestMapping(/pojoParam) ResponseBody public String pojoParam(User user){ System.out.println(pojo参数传递 user user); return {\module\:\pojo param\}; }注意GET/POST 请求方式都支持属性名必须一致否则无法封装。2.3.3 嵌套 POJO 类型参数场景POJO 中嵌套另一个 POJO如 User 包含 Address规则请求参数名按对象层级书写如address.city、address.province// 发送请求http://localhost/pojoContainPojoParam?nameitcastage15address.citybeijingaddress.provincebeijing RequestMapping(/pojoContainPojoParam) ResponseBody public String pojoContainPojoParam(User user){ System.out.println(pojo嵌套pojo参数传递 user user); return {\module\:\pojo contain pojo param\}; }注意同样要求属性名完全一致否则嵌套属性封装为 null。2.3.4 数组类型参数场景前端传递多个同名参数如爱好likesgamelikesmusiclikestravel规则用数组接收参数名一致无需RequestParamRequestMapping(/arrayParam) ResponseBody public String arrayParam(String[] likes){ System.out.println(数组参数传递 likes Arrays.toString(likes)); return {\module\:\array param\}; }原理数组是 Java 基本类型的容器SpringMVC 内置ServletRequestDataBinder自动识别并封装。2.3.5 集合类型参数问题直接用ListString likes接收会报错java.lang.IllegalStateException: No primary or single unique constructor found for interface java.util.List原因SpringMVC 将 List 视为复杂 POJO 对象尝试实例化接口导致失败解决方案添加RequestParam注解明确指定参数名RequestMapping(/listParam) ResponseBody public String listParam(RequestParam ListString likes){ System.out.println(集合参数传递 likes likes); return {\module\:\list param\}; }数组 vs List 接收的核心区别类型是否需要 RequestParam原理数组不需要简单类型容器SpringMVC 自动识别并封装List需要复杂集合对象SpringMVC 默认按 POJO 处理需 RequestParam 指定参数名SpringMVC将List看做是一个POJO对象来处理将其创建一个对象并准备把前端的数据封装到对象中。为什么集合有这种问题需要加注解RequestParam但是数组就不需要这涉及到 Spring MVC 中参数绑定的类型适配规则和封装逻辑差异核心原因在于 List 是“复杂对象集合”而数组是“简单类型的容器”下面详细拆解:1. 先看 数组参数为什么不需要 RequestParam对于基本类型数组如String[]、int[]Spring MVC 的处理逻辑是当请求参数名如likes与方法形参数组名String[] likes完全一致时Spring MVC会自动识别这是一个数组类型。它会遍历请求中所有同名参数如?likes游戏likes音乐将值按顺序封装到数组中。本质上数组属于“简单类型的批量封装”Spring MVC 内置的ServletRequestDataBinder能直接处理这种场景无需额外注解声明。2. 再看 List 参数为什么需要 RequestParam对于集合类型如ListStringSpring MVC 的处理逻辑不同:List 属于“复杂对象POJO或集合”Spring MVC 默认会把它当作一个需要实例化的对象类似User、Order这类自定义对象。如果不加RequestParamSpring MVC 会尝试按“对象属性”的方式去匹配请求参数 —— 但 List 没有明确的“属性名”无法直接映射请求参数。加上RequestParam后注解会强制指定“请求参数名”如RequestParam(likes)告诉 Spring MVC“把请求中名为 likes 的所有参数收集并封装到这个 List 里”。3. 本质区别“简单容器” vs “复杂对象”数组属于 Java 基本类型的“容器”Spring MVC对其内置的适配逻辑只要参数名匹配就能自动封装。List属于“复杂集合对象”Spring MVC 默认不会把它当作“简单容器”处理而是需要通过RequestParam明确告知“如何从请求中提取数据并封装”。4. 扩展RequestParam 还能解决哪些问题除了让 List 能正确绑定参数RequestParam还有其他关键作用:参数名不一致请求参数名是hobby但方法参数名是likes可通过RequestParam(hobby)手动映射。必传校验RequestParam(required true)可强制要求参数必须传递否则报错。默认值RequestParam(defaultValue 默认值)可设置参数未传递时的默认值。总结数组Spring MVC 内置支持参数名匹配即可自动封装无需额外注解。List属于复杂集合默认无法直接映射请求参数必须通过RequestParam明确“从请求中提取同名参数并封装”。这是 Spring MVC 为了区分“简单容器”和“复杂对象”的适配策略保证参数绑定的灵活性和明确性。2.4 JSON 数据传输参数前后端分离开发中主流用 JSON 格式传递数据SpringMVC 支持 JSON 数组、对象、对象数组的接收。2.4.1 JSON 格式基础对象结构{}包裹键值对形式如{name:Tom,age:20}数组结构[]包裹元素逗号分隔如[game,music,travel]字符串必须用双引号单引号不符合 JSON 规范2.4.2 JSON 普通数组步骤pom.xml 添加 Jackson 依赖SpringMVC 默认用 Jackson 做 JSON 转换dependency groupIdcom.fasterxml.jackson.core/groupId artifactIdjackson-databind/artifactId version2.9.0/version /dependencyPostMan 发送 JSON 数组Body选择raw-JSON填写[game,music,travel]配置类开启EnableWebMvc开启 JSON 自动转换等 SpringMVC 注解功能Configuration ComponentScan(com.itheima.controller) EnableWebMvc // 开启JSON自动转换 public class SpringMvcConfig { }Controller 方法添加RequestBody接收 JSON 请求体RequestMapping(/listParamForJson) ResponseBody public String listParamForJson(RequestBody ListString likes){ System.out.println(list common(json)参数传递 list likes); return {\module\:\list common for json param\}; }2.4.3 JSON 对象数据发送请求JSON 对象{name:itcast,age:15}接收参数RequestBody POJO 对象自动封装RequestMapping(/pojoParamForJson) ResponseBody public String pojoParamForJson(RequestBody User user){ System.out.println(pojo(json)参数传递 user user); return {\module\:\pojo for json param\}; }嵌套对象传递{name:itcast,age:15,address:{province:beijing,city:beijing}}自动封装 Address 属性。2.4.4 JSON 对象数组发送请求JSON 数组[{name:itcast,age:15},{name:itheima,age:12}]接收参数RequestBodyListUserRequestMapping(/listPojoParamForJson) ResponseBody public String listPojoParamForJson(RequestBody ListUser list){ System.out.println(list pojo(json)参数传递 list list); return {\module\:\list pojo for json param\}; }2.4.5 RequestBody vs RequestParam 核心区别注解接收数据类型适用场景RequestParamURL 地址参数、表单参数application/x-www-form-urlencoded传统表单提交、简单参数RequestBodyJSON 请求体application/json前后端分离、JSON 数据交互2.5 日期类型参数传递日期类型格式多样2088-08-18、08/18/2088、2088/08/08 08:08:08等SpringMVC 的处理方式如下2.5.1 默认日期格式SpringMVC默认支持yyyy/MM/dd格式直接用Date类型接收RequestMapping(/dataParam) ResponseBody public String dataParam(Date date){ System.out.println(参数传递 date date); return {\module\:\data param\}; }测试请求http://localhost/dataParam?date2088/08/08正常接收。2.5.2 自定义日期格式如果用其他格式如2088-08-08会报 400 错误Failed to convert value of type java.lang.String to required type java.util.Date解决方案用DateTimeFormat注解指定格式RequestMapping(/dataParam) ResponseBody public String dataParam( Date date, // 默认格式yyyy/MM/dd DateTimeFormat(pattern yyyy-MM-dd) Date date1, // 自定义格式yyyy-MM-dd DateTimeFormat(pattern yyyy-MM-dd HH:mm:ss) Date date2 // 带时间的格式 ){ System.out.println(参数传递 date date); System.out.println(参数传递 date1(yyyy-MM-dd) date1); System.out.println(参数传递 date2(yyyy-MM-dd HH:mm:ss) date2); return {\module\:\data param\}; }测试请求http://localhost/dataParam?date2088/08/08date12088-08-18date22088/08/28 8:08:08正常转换。2.5.3 类型转换原理SpringMVC 通过ConverterS,T接口实现类型转换如String-DateHttpMessageConverter实现对象与 JSON 的转换EnableWebMvc会自动注册这些转换器。三、核心总结与避坑指南3.1 全文核心知识点总结本篇教程覆盖了SpringMVC请求的全场景核心用法是后端开发必掌握的基础技能请求映射类级RequestMapping统一前缀解决路径冲突是模块化开发的标准写法参数传递普通/POJO/嵌套/数组/集合5种类型全覆盖数组无需注解List必须加RequestParamJSON交互依赖Jackson EnableWebMvcRequestBody前后端分离开发标配日期处理默认yyyy/MM/dd自定义格式用DateTimeFormat注解乱码解决GET修改Tomcat编码POST配置字符编码过滤器一劳永逸解决中文乱码3.2 核心注解速查表注解位置作用RequestMapping类/方法绑定请求路径支持路径拼接RequestParam方法参数绑定表单/URL参数解决List参数绑定、参数名不一致RequestBody方法参数接收JSON请求体数据ResponseBody方法/类直接返回数据字符串/JSON不跳转页面DateTimeFormat方法参数自定义日期参数格式3.3 开发常见避坑指南⚠️ 高频错误汇总避免踩坑集合参数绑定忘记加RequestParam直接报实例化异常JSON交互忘记添加Jackson依赖或EnableWebMvc无法解析JSON日期格式不匹配未使用DateTimeFormat导致400错误POST请求未配置字符编码过滤器中文参数乱码请求路径冲突未使用类级RequestMapping区分模块