学习记录之Spring MVC

Spring MVC的作用

    Spring MVC框架主要解决了接收请求、响应结果的相关问题。

开发环境

在使用Spring MVC框架时，需要在项目中添加`spring-webmvc`的依赖项。

如果使用的是Spring Boot工程，只需要添加`spring-boot-starter-web`依赖项即可。

> 说明：在`spring-boot-starter-web`依赖项中，包含了`spring-boot-starter`，所以，在Spring Boot项目中，只需要将原有`spring-boot-starter`改为`spring-boot-starter-web`即可。

简单的接收请求

通常，会使用“控制器”组件来接收请求，这类组件通常使用`Controller`作为类名的后缀，例如类名为`CategoryController`、`BrandController`等。

控制器组件必须添加`@Controller`注解才会被框架视为控制器，才可以用于接收请求、响应结果。

在Spring MVC中，当需要接收请求时，只需要在控制器中：

- 自定义处理请求的方法

- 在方法上使用`@RequestMapping`系列注解配置请求路径

关于处理请求的方法：

- 访问权限：应该是`public`

- 返回值类型：当返回值类型为`String`时，表示返回“视图”的名称，这不是前后端分离的做法；当使用了“响应正文”的模式后，返回的字符串将作为“正文”响应到客户端，这是前后端分离的做法

- 方法名称：自定义

关于响应正文

当处理请求的方法是响应正文的，则方法的返回值会响应到客户端。

在处理请求的方法上添加`@ResponseBody`，则此方法响应的方式就是响应正文的。

在控制器类上添加`@ResponseBody`，则此**控制器类中所有方法**响应的方式都是响应正文的。

更**推荐**在控制器类上使用`@RestController`，它同时使用`@Controller`和`@ResponseBody`作为元注解，所以，同时具有这2个注解的效果！

附：`@RestController`源代码：

关于@RequestMapping

此注解的主要作用是配置“请求路径”与“处理请求的方法”的映射关系。

此注解还可以添加在控制器类上，例如：

则此类中任何一个处理请求的路径都必须以此为前缀，例如：

在配置路径时，其实，路径值并不需要使用`/`作为第1个字符，除非路径值只有`/`这1个字符，否则，配置值（字符串）两端的`/`都是可以无视的，最终拼接出来的完整URL会自动在中间添加`/`。

**推荐**每个配置值都使用`/`作为第1个字符（尽管可以不写）。

在`@RequestMapping`注解中，还有`method`属性，可以限制请求方式（GET / POST等），其语法大概是：

@RequestMapping(value = "/add-new", method = RequestMethod.POST)

以上配置表示“只允许使用POST方式提交请求”，如果使用其它请求方式，将出现405错误！

在Spring MVC框架中，定义一系列的限制请求方式的注解，例如：

- `@GetMapping`：将请求方式限制为GET，除了不能添加在类上，其它用法与`@RequestMapping`相同

- `@PostMapping`：将请求方式限制为POST，除了不能添加在类上，其它用法与`@RequestMapping`相同

- 其它

在开发实践中，控制器类上使用`@RequestMapping`，在方法上使用`@GetMapping`或`@PostMapping`，通常，以“获取数据”为主要目的的请求应该使用`@GetMapping`（例如查看订单列表、查看商品详情），否则，使用`@PostMapping`。

关于注解的源代码

每个注解的源代码中，其元注解`@Target`表示此注解可以添加在哪个位置，例如：

则表示此注解可以添加在`TYPE`（类）上，也可以添加在`METHOD`（方法）上。

在注解的内部，源代码例如：

以上`value`是注解中可配置的属性，`String[]`表示此属性的值类型，`default {}`表示此属性的默认值是空数组。

每个注解的`value`属性都是默认属性，在配置时，如果只配置这1个属性的值，并不需要显式的添加此属性名称，例如：

@RequestMapping({"/delete"})

和

以上2种配置是完全等效的！

如果属性的值类型是数组类型的，且如果需要配置的值只有1个时，可以不使用大括号框住值，例如：

和

以上2种配置是完全等效的！

所以，关于`@RequestMapping`的`value`属性，以下4种配置是完全等效的：

另外，在Spring系列框架的注解中，经常出现`@AliasFor`注解，例如：

以上代码表示`value`和`path`是等效的！

接收请求参数

在Spring MVC中，可以将“请求参数”直接设计为“处理请求的方法的参数”，在方法体内部可以直接使用。

以“增加品牌”为例，客户端需要提交的数据有：

- 名称

- 拼音

- LOGO图片

- 类别

- 简介

- 关键词

- 排序值

则处理请求的方法可以设计为：

当客户端提交的请求参数是有效值时（例如`?name=XiaoMi`），处理请求的方法中的参数也是有效值（就是提交过来的值）。

当客户端只提交了请求参数对应的名称却没有值时（例如`?name=`），处理请求的方法收到的将是长度为0的字符串，如果参数是`String`类型，则参数值就是`""`，如果参数不是`String`类型（例如`Integer`类型），也无法正确的实现转换，则参数值为`null`。

当客户端没有提交对应的参数时（无此参数，或名称不对应），处理请求的方法中的参数值为`null`。更推荐将各请求参数封装到自定义的类中，

关于POJO规范

所有的POJO类型都应该符合以下设计标准：

- 所有属性都是私有的（`private`）

- 每个属性都有对应的、命名规范的Setter & Getter

  - 通过专业的开发工具生成即可

- 应该生成`hashCode()`和`equals()`方法，且保证：2个对象中所有属性值都相同时，返回相同的`hashCode()`，且这2个对象的`equals()`对比结果为`true`

  - 通过专业的开发工具生成即可

  - 通过IntelliJ IDEA生成时，还有多种代码模版可选择，选择任何一个模版均可

- 实现序列化接口（`Serializable`）

  - 可以不生成序列化版本ID

以上规范是业内共同认可的，且认为你都会按此规范来编码，所以，许多框架都会自动调用其中的Setter & Getter方式，甚至会使用`Serializable`来声明你的对象。

关于POJO类的命名

在项目中，可能存在多种定位不同的POJO类型，例如某些类型中的属性是与数据库中的表字段一一对应的，这种类型通常称之“实体”，但是，它并不能解决此种数据类型的所有业务！

以“用户”数据为例，数据表中的字段可能有：

- ID

- 用户名

- 密码

- 昵称

当用户注册时，涉及的只有：用户名、密码、昵称，并不涉及ID

当用户登录时，涉及的只有：用户名、密码，并不涉及ID和昵称

用户登录时，可能还需要提交“验证码”，原本的实体类并没有

当用户需要修改密码时，需要提交的是：原密码、新密码、确认新密码，原本的实体类将不可用

所以，实体类型并不适用于每个业务！客户端发起的不同请求，需要提交的数据都是不同的！另外，从数据库中查询的数据，也不应该使用实体类型，因为每次查询所需要的数据是不同的！

综合来看，客户端提交的数据与实体可能是不同的，从数据库中查询的结果和实体可能也是不同的，所以，在项目中会存在多种定位不同的POJO类型，通常，不同定位的POJO类型，在命名时，应该添加一些后缀：

阿里巴巴的建议：

【参考】各层命名规约：

 数据对象：xxxDO，xxx 即为数据表名。

 DO = Data Object

数据传输对象：xxxDTO，xxx 为业务领域相关的名称。

DTO = Data Transfer Object

展示对象：xxxVO，xxx 一般为网页名称。

 VO = View Object

VO = Value Object

POJO 是 DO/DTO/BO/VO 的统称，禁止命名成 xxxPOJO。

【强制】类名使用 UpperCamelCase 风格，必须遵从驼峰形式，但以下情形例外：DO / BO /  DTO / VO / AO 

 正例：MarcoPolo / UserDO / XmlService / TcpUdpDeal / TaPromotion 

反例：macroPolo / UserDo / XMLService / TCPUDPDeal / TAPromotion

在项目中，每种定位的POJO到底使用什么后缀，并没有标准的约定，只要满足：

不使用`POJO`作为后缀

同种定位的多个类，使用相同的后缀

RESTful

RESTful是一种设计风格（并不是规范或标准）。

RESTful的典型表现为：将id或类似具有“唯一性”的参数值作为URL的一部分，而不像传统参数那样体现。例如：

以上URL，如果使用传统做法，通常会设计为：

注意：不具备“唯一性”的参数值通常不会设计为URL的一部分。

Spring MVC很好的支持了RESTful，在配置请求路径时，可以在路径中使用`{}`框住自定义的名称表示占位符，则客户端在提交请求时，占位符位置的内容可以是任意内容，在方法的参数列表中，接收参数时，需要在参数前添加`@PathVariable`注解，以表示此参数值是从URL中的占位符位置获取的值，例如：

同一个请求路径中，允许有多个`{}`占位符，则处理请求的方法也应该有多个对应的参数，每个参数前都添加`@PathVariable`即可。

如果占位符的名称与方法的参数名称不匹配，还可以在`@PathVariable`注解中配置参数名称，注解中配置的名称应该与占位符中的名称一致，例如：

在使用占位符时，还可以在占位符的名称之后添加冒号，再添加正则表达式，以匹配到符合格式的URL，例如：

后续，当客户端提交请求时，如果占位符位置的值不符合正则表达式，将响应404错误！

另外，不冲突的多个正则表达式配置的占位符是允许共存的，例如：

甚至，还可以存在精确匹配的路径与以上占位符的配置共存，例如：

关于RESTful，其实，还有一些其它的建议，例如，RESTful推荐根据要操作数据的方式来决定请求方式，例如：

- 请求的目标是增加数据时，推荐使用`POST`请求方式

- 请求的目标是删除数据时，推荐使用`DELETE`请求方式

- 请求的目标是修改数据时，推荐使用`PUT`请求方式

- 请求的目标是查询数据时，推荐使用`GET`请求方式

事实上，在主流的业务系统的开发中，仍只使用`GET`和`POST`请求方式。

最后，关于RESTful风格的URL，如果没有更好的选择，推荐设计为：

- `/数据类型的复数名称`表示查询列表，例如，查询品牌列表，URL设计为`/brands`

/数据类型的复数名称/{id}`表示根据id查询数据，例如，根据id查询品牌详情，URL设计为`/brands/{id}

/数据类型的复数名称/{id}/命令`表示根据id操作数据，例如，根据id删除品牌，，URL设计为`/brands/{id}/delete

@RestController

    @RequestMapping("/brands")

    public class BrandController {

        // http://localhost:8080/brands/9527/delete

        @PostMapping("/{id:[0-9]+}/delete")

        public ... // 处理请求的方法

    }

统一处理异常

Spring MVC框架在接收到请求后，会自动调用处理请求的方法，如果调用的控制器中方法抛出异常，Spring MVC会捕获到此异常对象，并尝试调用统一处理异常的机制，如果没有统一处理异常的机制，则会响应500错误。

关于统一处理异常，需要自定义类，在类上添加`@ControllerAdvice`注解，添加此注解的类中的注解方法将可以作用于每一次处理请求的过程。

然后，在类中添加处理异常的方法，关于此方法：

- 访问权限：应该使用`public`

- 返回值类型：参考控制器中处理请求的方法

  - 假设，需要响应某字符串到客户端，则使用`String`作为返回值类型，并结合`@ResponseBody`注解一起使用，或者，使用`@RestControllerAdvice`替代`@ControllerAdvice`，则此类中所有方法向客户端响应时，都是响应正文的

- 方法名称：自定义

- 参数列表：必须至少包含1个异常类型，此参数就是Spring MVC框架调用控制器的方法后捕获的异常，并且，可以按需添加`HttpServletRequest`、`HttpServletResponse`等少量指定类型的参数，不可以添加其它参数

- 注解：必须添加`@ExceptionHandler`注解

例如，在项目中，可以在`ex.handler`包下创建统一处理异常的类：

完成以上代码后，无论项目中的任何控制器在处理任何请求时，只要控制器的方法抛出了`ServiceException`（不捕获等同于抛出），都会执行以上方法！

在以上统一处理异常的类中，统一处理异常的方法可以有多个（处理的异常必须不同，但允许存在继承关系），通常，建议在此类中添加一个能够处理任何异常的方法，避免某些异常未被处理导致响应500错误（用户不明确错误的原因，可能继续尝试错误的操作）：

响应JSON格式的字符串

在Spring MVC框架中，当需要向客户端响应JSON格式的字符串时，需要：

- 在配置类上使用`@EnableWebMvc`开启增强模式

  - 在Spring Boot中不需要，默认已开启

- 添加`jackson-databind`依赖项

  - 在`spring-boot-starter-web`中已包含

- 处理请求的方法（或处理异常的方法）的返回值类型使用自定义的数据类型