<parent>
    <groupId>org.springframework.boot</groupId>
    <artifactId>spring-boot-starter-parent</artifactId>
    <version>2.1.7</version>
    <relativePath/> <!-- lookup parent from update -->
</parent>

<properties>
    <project.build.sourceEncoding>UTF-8</project.build.sourceEncoding>
    <project.reporting.outputEncoding>UTF-8</project.reporting.outputEncoding>
    <spring-cloud.version>Finchley.RELEASE</spring-cloud.version>
    <java.version>1.8</java.version>
</properties>

<dependencies>
    <dependency>
        <groupId>org.springframework.boot</groupId>
        <artifactId>spring-boot-starter-web</artifactId>
    </dependency>
</dependencies>

<build>
    <pluginManagement>
        <plugins>
            <plugin>
                <groupId>org.springframework.boot</groupId>
                <artifactId>spring-boot-maven-plugin</artifactId>
            </plugin>
        </plugins>
    </pluginManagement>
</build>
<repositories>
    <repository>
        <id>spring-milestones</id>
        <name>Spring Milestones</name>
        <url>https://repo.spring.io/milestone</url>
        <snapshots>
            <enabled>false</enabled>
        </snapshots>
    </repository>
</repositories>

添加项目启动类Application.cass

@SpringBootApplication
public class Application {
    public static void main(String[] args) {
        SpringApplication.run(Application.class);
    }
}

在演示请求参数的解析实例中，我们使用终端的curl命令来发起http请求（主要原因是截图上传太麻烦，还是终端的文本输出比较方便；缺点是不太直观）

II. GET请求参数解析

接下来我们正式进入参数解析的妖娆姿势篇，会介绍一下常见的一些case（并不能说包含了所有的使用case）

下面所有的方法都放在 ParamGetRest 这个Controller中

@RestController
@RequestMapping(path = "get")
public class ParamGetRest {
}

1. HttpServletRequest

直接使用HttpServletRequest来获取请求参数，属于比较原始，但是灵活性最高的使用方法了。

常规使用姿势是方法的请求参数中有一个HttpServletRequest，我们通过ServletRequest#getParameter(参数名)来获取具体的请求参数，下面演示返回所有请求参数的case

@GetMapping(path = "req")
public String requestParam(HttpServletRequest httpRequest) {
    Map<String, String[]> ans = httpRequest.getParameterMap();
    return JSON.toJSONString(ans);
}

测试case，注意下使用curl请求参数中有中文时，进行了url编码（后续会针对这个问题进行说明）

➜  ~ curl 'http://127.0.0.1:8080/get/req?name=yihuihiu&age=19'
{"name":["yihuihiu"],"age":["19"]}

➜  ~ curl 'http://127.0.0.1:8080/get/req?name=%E4%B8%80%E7%81%B0%E7%81%B0&age=19'
{"name":["一灰灰"],"age":["19"]}%

使用HttpServletRequest获取请求参数，还有另外一种使用case，不通过参数传递的方式获取Request实例，而是借助RequestContextHolder；这样的一个好处就是，假设我们想写一个AOP，拦截GET请求并输出请求参数时，可以通过下面这种方式来处理

@GetMapping(path = "req2")
public String requestParam2() {
    HttpServletRequest request =
            ((ServletRequestAttributes) RequestContextHolder.currentRequestAttributes()).getRequest();
    String name = request.getParameter("name");
    return "param Name=" + name;
}

测试case

➜  ~ curl 'http://127.0.0.1:8080/get/req2?name=%E4%B8%80%E7%81%B0%E7%81%B0&age=19'
param Name=一灰灰%

2. 方法参数

这种解析方式比较厉害了，将GET参数与方法的参数根据参数名进行映射，从感官上来看，就像是直接调用这个一样

@GetMapping(path = "arg")
public String argParam(String name, Integer age) {
    return "name: " + name + " age: " + age;
}

针对上面提供的方式，我们的测试自然会区分为下面几种，看下会怎样

正好两个参数，与定义一直
缺少一个请求参数
多一个请求参数
参数类型不一致

# 参数解析正常
➜  ~ curl 'http://127.0.0.1:8080/get/arg?name=%E4%B8%80%E7%81%B0%E7%81%B0&age=19'
name: 一灰灰 age: 19%

# 缺少一个参数时，为null
➜  ~ curl 'http://127.0.0.1:8080/get/arg?name=%E4%B8%80%E7%81%B0%E7%81%B0'
name: 一灰灰 age: null% 

# 多了一个参数，无法被解析
➜  ~ curl 'http://127.0.0.1:8080/get/arg?name=%E4%B8%80%E7%81%B0%E7%81%B0&age=19&id=10'
name: 一灰灰 age: 19%                                                              

# 类型不一致，500 
➜  ~ curl 'http://127.0.0.1:8080/get/arg?name=%E4%B8%80%E7%81%B0%E7%81%B0&age=haha' -i
HTTP/1.1 500
Content-Length: 0
Date: Sat, 24 Aug 2019 01:45:14 GMT
Connection: close

从上面实际的case可以看出，利用方法参数解析GET传参时，实际效果是：

方法参数与GET传参，通过参数签名进行绑定
方法参数类型，需要与接收的GET传参类型一致
方法参数非基本类型时，若传参没有，则为null；（也就是说如果为基本类型，无法转null，抛异常）
实际的GET传参可以多于方法定义的参数

接下来给一个数组传参解析的实例

@GetMapping(path = "arg2")
public String argParam2(String[] names, int size) {
    return "name: " + (names != null ? Arrays.asList(names) : "null") + " size: " + size;
}

测试case如下，传数组时参数值用逗号分隔；基本类型，必须传参，否则解析异常

➜  ~ curl 'http://127.0.0.1:8080/get/arg2?name=yihui,erhui&size=2'
name: null size: 2%

➜  ~ curl 'http://127.0.0.1:8080/get/arg2?name=yihui,erhui' -i
HTTP/1.1 500
Content-Length: 0
Date: Sat, 24 Aug 2019 01:53:30 GMT
Connection: close

3. RequestParam 注解

这种方式看起来和前面有些相似，但更加灵活，我们先看一下注解

@Target(ElementType.PARAMETER)
@Retention(RetentionPolicy.RUNTIME)
@Documented
public @interface RequestParam {
  // 指定请求参数名
	String value() default "";
	// 指定请求参数名
	String name() default "";
	// true表示发起请求时这个参数必须存在
	boolean required() default true;
	String defaultValue() default ValueConstants.DEFAULT_NONE;
}

有两个参数需要注意，一个是name表示这个参数与GET传参的哪个关联；required表示这个参数是否可选

下面是一个简单的使用方式

@GetMapping(path = "ano")
public String anoParam(@RequestParam(name = "name") String uname,
        @RequestParam(name = "age", required = false) Integer age,
        @RequestParam(name = "uids", required = false) Integer[] uids) {
    return "name: " + uname + " age: " + age + " uids: " + (uids != null ? Arrays.asList(uids) : "null");
}

测试如下:

# 三个参数全在
➜  ~ curl 'http://localhost:8080/get/ano?name=%E4%B8%80%E7%81%B0%E7%81%B0blog&age=18&uids=1,3,4'
name: 一灰灰blog age: 18 uids: [1, 3, 4]%

# age不传
➜  ~ curl 'http://localhost:8080/get/ano?name=%E4%B8%80%E7%81%B0%E7%81%B0blog&uids=1,3,4'
name: 一灰灰blog age: null uids: [1, 3, 4]% 

# 必选参数name不传时
➜  ~ curl 'http://localhost:8080/get/ano?uids=1,3,4' -i
HTTP/1.1 500
Content-Length: 0
Date: Sat, 24 Aug 2019 13:09:07 GMT
Connection: close

使用RequestParam注解时，如果指定了name/value，这个参数就与指定的GETGET传参关联；如果不指定时，则根据参数签名来关联

下面给出两个更有意思的使用方式，一个是枚举参数解析，一个是Map容纳参数，一个是数组参数解析

public enum TYPE {
    A, B, C;
}

@GetMapping(path = "enum")
public String enumParam(TYPE type) {
    return type.name();
}

@GetMapping(path = "enum2")
public String enumParam2(@RequestParam TYPE type) {
    return type.name();
}

@GetMapping(path = "mapper")
public String mapperParam(@RequestParam Map<String, Object> params) {
    return params.toString();
}

// 注意下面这个写法，无法正常获取请求参数，这里用来对比列出
@GetMapping(path = "mapper2")
public String mapperParam2(Map<String, Object> params) {
    return params.toString();
}


@GetMapping(path = "ano1")
public String anoParam1(@RequestParam(name = "names") List<String> names) {
    return "name: " + names;
}

// 注意下面这个写法无法正常解析数组
@GetMapping(path = "arg3")
public String anoParam2(List<String> names) {
    return "names: " + names;
}

测试case如下

➜  ~ curl 'http://localhost:8080/get/enum?type=A'
A%

➜  ~ curl 'http://localhost:8080/get/enum2?type=A'
A%

➜  ~ curl 'http://localhost:8080/get/mapper?type=A&age=3'
{type=A, age=3}%

➜  ~ curl 'http://localhost:8080/get/mapper2?type=A&age=3'
{}%

➜  ~ curl 'http://localhost:8080/get/ano1?names=yi,hui,ha'
name: [yi, hui, ha]%

➜  ~ curl 'http://localhost:8080/get/arg3?names=yi,hui,ha' -i
HTTP/1.1 500
Content-Length: 0
Date: Sat, 24 Aug 2019 13:50:55 GMT
Connection: close

从测试结果可以知道：

GET传参映射到枚举时，根据enum.valueOf()来实例的
如果希望使用Map来容纳所有的传参，需要加上注解@RequestParam
如果参数为List类型，必须添加注解@RequestParam；否则用数组来接收

4. PathVariable

从请求的url路径中解析参数，使用方法和前面的差别不大

@GetMapping(path = "url/{name}/{index}")
public String urlParam(@PathVariable(name = "name") String name,
        @PathVariable(name = "index", required = false) Integer index) {
    return "name: " + name + " index: " + index;
}

上面是一个常见的使用方式，对此我们带着几个疑问设计case

只有name没有index，会怎样？
有name，有index，后面还有路径，会怎样？

➜  ~ curl http://127.0.0.1:8080/get/url/yihhuihui/1
name: yihhuihui index: 1%

➜  ~ curl 'http://127.0.0.1:8080/get/url/yihhuihui' -i
HTTP/1.1 500
Content-Length: 0
Date: Sat, 24 Aug 2019 13:27:08 GMT
Connection: close

➜  ~ curl 'http://127.0.0.1:8080/get/url/yihhuihui/1/test' -i
HTTP/1.1 500
Content-Length: 0
Date: Sat, 24 Aug 2019 13:27:12 GMT
Connection: close

从path中获取参数时，对url有相对严格的要求，注意使用

5. POJO

这种case，我个人用得比较多，特别是基于SpringCloud的生态下，借助Feign来调用第三方微服务，可以说是很舒爽了；下面看一下这种方式的使用姿势

首先定义一个POJO

@Data
public class BaseReqDO implements Serializable {
    private static final long serialVersionUID = 8706843673978981262L;

    private String name;

    private Integer age;

    private List<Integer> uIds;
}

提供一个服务

@GetMapping(path = "bean")
public String beanParam(BaseReqDO req) {
    return req.toString();
}

POJO中定义了三个参数，我们再测试的时候，看一下这些参数是否必选

# GET传参与POJO中成员名进行关联
➜  ~ curl 'http://127.0.0.1:8080/get/bean?name=yihuihui&age=18&uIds=1,3,4'
BaseReqDO(name=yihuihui, age=18, uIds=[1, 3, 4])%

# 没有传参的属性为null；因此如果POJO中成员为基本类型，则参数必传
➜  ~ curl 'http://127.0.0.1:8080/get/bean?name=yihuihui&age=18'
BaseReqDO(name=yihuihui, age=18, uIds=null)%

II. 其他

0. 项目

1.2 - 2.Post请求参数解析姿势汇总

作为一个常年提供各种Http接口的后端而言，如何获取请求参数可以说是一项基本技能了，本篇为《190824-SpringBoot系列教程web篇之Get请求参数解析姿势汇总》之后的第二篇，对于POST请求方式下，又可以怎样获取请求参数呢

本篇主要内容包括以下几种姿势

@RequestBody json格式
RequestEntity
MultipartFile 文件上传

I. 环境搭建

首先得搭建一个web应用才有可能继续后续的测试，借助SpringBoot搭建一个web应用属于比较简单的活;

创建一个maven项目，pom文件如下

<parent>
    <groupId>org.springframework.boot</groupId>
    <artifactId>spring-boot-starter-parent</artifactId>
    <version>2.1.7</version>
    <relativePath/> <!-- lookup parent from update -->
</parent>

<properties>
    <project.build.sourceEncoding>UTF-8</project.build.sourceEncoding>
    <project.reporting.outputEncoding>UTF-8</project.reporting.outputEncoding>
    <spring-cloud.version>Finchley.RELEASE</spring-cloud.version>
    <java.version>1.8</java.version>
</properties>

<dependencies>
    <dependency>
        <groupId>org.springframework.boot</groupId>
        <artifactId>spring-boot-starter-web</artifactId>
    </dependency>
</dependencies>

<build>
    <pluginManagement>
        <plugins>
            <plugin>
                <groupId>org.springframework.boot</groupId>
                <artifactId>spring-boot-maven-plugin</artifactId>
            </plugin>
        </plugins>
    </pluginManagement>
</build>
<repositories>
    <repository>
        <id>spring-milestones</id>
        <name>Spring Milestones</name>
        <url>https://repo.spring.io/milestone</url>
        <snapshots>
            <enabled>false</enabled>
        </snapshots>
    </repository>
</repositories>

添加项目启动类Application.cass

@SpringBootApplication
public class Application {
    public static void main(String[] args) {
        SpringApplication.run(Application.class);
    }
}

在演示请求参数的解析实例中，我们使用终端的curl命令来发起http请求（主要原因是截图上传太麻烦，还是终端的文本输出比较方便；缺点是不太直观）

II. POST请求参数解析

接下来我们正式进入参数解析的妖娆姿势篇，会介绍一下常见的一些case（并不能说包含了所有的使用case）

下面所有的方法都放在 ParamPostRest 这个Controller中

@RestController
@RequestMapping(path = "post")
public class ParamPostRest {
}

在正式介绍之前，强烈推荐看一下《190824-SpringBoot系列教程web篇之Get请求参数解析姿势汇总》, 因为get传参的姿势，在post参数解析中同样适用，下面的内容并不会再次详细介绍

1. HttpServletRequest

首先看一下最基本的使用case，和get请求里的case一样，我们先开一个接口

@PostMapping(path = "req")
public String requestParam(HttpServletRequest req) {
    return JSONObject.toJSONString(req.getParameterMap());
}

我们测试下两种post请求下，会出现怎样的结果

# 常规的表单提交方式
# content-type: application/x-www-form-urlencoded
➜  ~ curl 'http://127.0.0.1:8080/post/req' -X POST -d 'name=yihui&age=18'
{"name":["yihui"],"age":["18"]}% 

# json传提交
➜  ~ curl 'http://127.0.0.1:8080/post/req' -X POST -H 'content-type:application/json;charset:UTF-8' -d '{"name": "yihui", "age": 20}'
{}%

从上面的case中可以知道，通过传统的表达方式提交的数据时，获取参数和get获取参数使用姿势一样；然而当然传入的是json串格式的数据时，直接通过javax.servlet.ServletRequest#getParameter获取不到对应的参数

我们通过debug，来看一下在传json串数据的时候，如果我们要获取数据，可以怎么做

上面截图演示了我们从请求的InputStream中获取post参数；所以再实际使用的时候需要注意，流中的数据只能读一次，读完了就没了; 这个和我们使用GET传参是有很大的差别的

注意：如果您有一个打印请求参数日志的切面，在获取post传的参数时需要注意，是不是把流的数据读了，导致业务中无法获取到正确的数据！！！

2. RequestBody

上面说到传json串数据时，后端直接通过HttpServletRequest获取数据不太方便，那么有更优雅的使用姿势么？下面我们看一下@RequestBody注解的使用

@Data
public class BaseReqDO implements Serializable {
    private static final long serialVersionUID = 8706843673978981262L;

    private String name;

    private Integer age;

    private List<Integer> uIds;
}

@PostMapping(path = "body")
public String bodyParam(@RequestBody BaseReqDO req) {
    return req == null ? "null" : req.toString();
}

只需要在参数中添加@RequestBody注解即可，然后这个接口就支持json串的POST提交了

# json串数据提交
➜  ~ curl 'http://127.0.0.1:8080/post/body' -X POST -H 'content-type:application/json;charset:UTF-8' -d '{"name": "yihui", "age": 20}'
BaseReqDO(name=yihui, age=20, uIds=null)%

# 表单数据提交
➜  ~ curl 'http://127.0.0.1:8080/post/body' -X POST -d 'name=yihui&age=20'
{"timestamp":1566987651551,"status":415,"error":"Unsupported Media Type","message":"Content type 'application/x-www-form-urlencoded;charset=UTF-8' not supported","path":"/post/body"}%

说明：使用@RequestBody注解之后，可解析提交的json串；但不再支持表单提交参数方式(application/x-www-form-urlencoded)

3. RequestEntity

使用RequestEntity来解析参数，可能并不太常见，它用来解析json串提交的参数也比较合适，使用姿势也比较简单

@PostMapping(path = "entity")
public String entityParam(RequestEntity requestEntity) {
    return Objects.requireNonNull(requestEntity.getBody()).toString();
}

使用case如下

# json串数据提交
➜  ~ curl 'http://127.0.0.1:8080/post/entity' -X POST -H 'content-type:application/json;charset:UTF-8' -d '{"name": "yihui", "age": 20}'
{name=yihui, age=20}%

# 表单数据提交不行
➜  ~ curl 'http://127.0.0.1:8080/post/entity' -X POST -d 'name=yihui&age=19'
{"timestamp":1566988137298,"status":415,"error":"Unsupported Media Type","message":"Content type 'application/x-www-form-urlencoded;charset=UTF-8' not supported","path":"/post/entity"}%

4. MultipartFile 文件上传

文件上传也是一个比较常见的，支持起来也比较简单，有两种方式，一个是使用MultipartHttpServletRequest参数来获取上传的文件；一个是借助 @RequestParam注解

private String getMsg(MultipartFile file) {
    String ans = null;
    try {
        ans = file.getName() + " = " + new String(file.getBytes(), "UTF-8");
    } catch (IOException e) {
        e.printStackTrace();
        return e.getMessage();
    }
    System.out.println(ans);
    return ans;
}

/**
 * 文件上传
 *
 * curl 'http://127.0.0.1:8080/post/file' -X POST -F 'file=@hello.txt'
 *
 * @param file
 * @return
 */
@PostMapping(path = "file")
public String fileParam(@RequestParam("file") MultipartFile file) {
    return getMsg(file);
}

@PostMapping(path = "file2")
public String fileParam2(MultipartHttpServletRequest request) {
    MultipartFile file = request.getFile("file");
    return getMsg(file);
}

测试case如下

# 创建一个文本文件
➜  ~ vim hello.txt
hello, this is yhh's spring test!

# 使用curl -F 实现文件上传，注意使用姿势
➜  ~ curl 'http://127.0.0.1:8080/post/file' -F 'file=@hello.txt'
file = hello, this is yhh's spring test!

➜  ~ curl 'http://127.0.0.1:8080/post/file2' -F 'file=@hello.txt'
file = hello, this is yhh's spring test!

5. 其他

上面介绍的几种有别于GET篇中的请求姿势，请注意GET请求参数的解析方式，在POST请求中，可能也是适用的，为什么说可能？因为在post请求中，不同的content-type，对参数的解析影响还是有的；

需要注意的是，对于传统的表单提交(application/x-www-form-urlencoded)方式，post的参数解析依然可以使用

@RequsetParam
POJO（BEAN的解析方式）
@PathVariable参数解析
方法参数解析

II. 其他

0. 项目&相关博文

1.3 - 3.如何自定义参数解析器

SpringMVC提供了各种姿势的http参数解析支持，从前面的GET/POST参数解析篇也可以看到，加一个@RequsetParam注解就可以将方法参数与http参数绑定，看到这时自然就会好奇这是怎么做到的,我们能不能自己定义一种参数解析规则呢？

本文将介绍如何实现自定义的参数解析，并让其生效

I. 环境搭建

首先得搭建一个web应用才有可能继续后续的测试，借助SpringBoot搭建一个web应用属于比较简单的活;

创建一个maven项目，pom文件如下

<parent>
    <groupId>org.springframework.boot</groupId>
    <artifactId>spring-boot-starter-parent</artifactId>
    <version>2.1.7</version>
    <relativePath/> <!-- lookup parent from update -->
</parent>

<properties>
    <project.build.sourceEncoding>UTF-8</project.build.sourceEncoding>
    <project.reporting.outputEncoding>UTF-8</project.reporting.outputEncoding>
    <spring-cloud.version>Finchley.RELEASE</spring-cloud.version>
    <java.version>1.8</java.version>
</properties>

<dependencies>
    <dependency>
        <groupId>org.springframework.boot</groupId>
        <artifactId>spring-boot-starter-web</artifactId>
    </dependency>
</dependencies>

<build>
    <pluginManagement>
        <plugins>
            <plugin>
                <groupId>org.springframework.boot</groupId>
                <artifactId>spring-boot-maven-plugin</artifactId>
            </plugin>
        </plugins>
    </pluginManagement>
</build>
<repositories>
    <repository>
        <id>spring-milestones</id>
        <name>Spring Milestones</name>
        <url>https://repo.spring.io/milestone</url>
        <snapshots>
            <enabled>false</enabled>
        </snapshots>
    </repository>
</repositories>

II. 自定义参数解析器

对于如何自定义参数解析器，一个较推荐的方法是，先搞清楚springmvc接收到一个请求之后完整的处理链路，然后再来看在什么地方，什么时机，来插入自定义参数解析器，无论是从理解还是实现都会简单很多。遗憾的是，本篇主要目标放在的是使用角度，所以这里只会简单的提一下参数解析的链路，具体的深入留待后续的源码解析

1. 参数解析链路

http请求流程图，来自 SpringBoot是如何解析HTTP参数的

既然是参数解析，所以肯定是在方法调用之前就会被触发，在Spring中，负责将http参数与目标方法参数进行关联的，主要是借助org.springframework.web.method.support.HandlerMethodArgumentResolver类来实现

/**
 * Iterate over registered {@link HandlerMethodArgumentResolver}s and invoke the one that supports it.
 * @throws IllegalStateException if no suitable {@link HandlerMethodArgumentResolver} is found.
 */
@Override
@Nullable
public Object resolveArgument(MethodParameter parameter, @Nullable ModelAndViewContainer mavContainer,
		NativeWebRequest webRequest, @Nullable WebDataBinderFactory binderFactory) throws Exception {

	HandlerMethodArgumentResolver resolver = getArgumentResolver(parameter);
	if (resolver == null) {
		throw new IllegalArgumentException("Unknown parameter type [" + parameter.getParameterType().getName() + "]");
	}
	return resolver.resolveArgument(parameter, mavContainer, webRequest, binderFactory);
}

上面这段核心代码来自org.springframework.web.method.support.HandlerMethodArgumentResolverComposite#resolveArgument，主要作用就是获取一个合适的HandlerMethodArgumentResolver，实现将http参数(webRequest)映射到目标方法的参数上(parameter)

所以说，实现自定义参数解析器的核心就是实现一个自己的HandlerMethodArgumentResolver

2. HandlerMethodArgumentResolver

实现一个自定义的参数解析器，首先得有个目标，我们在get参数解析篇里面，当时遇到了一个问题，当传参为数组时，定义的方法参数需要为数组，而不能是List，否则无法正常解析；现在我们则希望能实现这样一个参数解析，以支持上面的场景

为了实现上面这个小目标，我们可以如下操作

a. 自定义注解ListParam

定义这个注解，主要就是用于表明，带有这个注解的参数，希望可以使用我们自定义的参数解析器来解析；

@Target(ElementType.PARAMETER)
@Retention(RetentionPolicy.RUNTIME)
@Documented
public @interface ListParam {
    /**
     * Alias for {@link #name}.
     */
    @AliasFor("name") String value() default "";

    /**
     * The name of the request parameter to bind to.
     *
     * @since 4.2
     */
    @AliasFor("value") String name() default "";
}

b. 参数解析器ListHandlerMethodArgumentResolver

接下来就是自定义的参数解析器了，需要实现接口HandlerMethodArgumentResolver

public class ListHandlerMethodArgumentResolver implements HandlerMethodArgumentResolver {
    @Override
    public boolean supportsParameter(MethodParameter parameter) {
        return parameter.hasParameterAnnotation(ListParam.class);
    }

    @Override
    public Object resolveArgument(MethodParameter parameter, ModelAndViewContainer mavContainer,
            NativeWebRequest webRequest, WebDataBinderFactory binderFactory) throws Exception {
        ListParam param = parameter.getParameterAnnotation(ListParam.class);
        if (param == null) {
            throw new IllegalArgumentException(
                    "Unknown parameter type [" + parameter.getParameterType().getName() + "]");
        }

        String name = "".equalsIgnoreCase(param.name()) ? param.value() : param.name();
        if ("".equalsIgnoreCase(name)) {
            name = parameter.getParameter().getName();
        }
        String ans = webRequest.getParameter(name);
        if (ans == null) {
            return null;
        }

        String[] cells = StringUtils.split(ans, ",");
        return Arrays.asList(cells);
    }
}

上面有两个方法：

supportsParameter就是用来表明这个参数解析器适不适用
- 实现也比较简单，就是看参数上有没有前面定义的ListParam注解
resolveArgument 这个方法就是实现将http参数粗转换为目标方法参数的具体逻辑
- 上面主要是为了演示自定义参数解析器的过程，实现比较简单，默认只支持List<String>

3. 注册

上面虽然实现了自定义的参数解析器，但是我们需要把它注册到HandlerMethodArgumentResolver才能生效，一个简单的方法如下

@SpringBootApplication
public class Application extends WebMvcConfigurationSupport {

    @Override
    protected void addArgumentResolvers(List<HandlerMethodArgumentResolver> argumentResolvers) {
        argumentResolvers.add(new ListHandlerMethodArgumentResolver());
    }

    public static void main(String[] args) {
        SpringApplication.run(Application.class);
    }
}

4. 测试

为了验证我们的自定义参数解析器ok，我们开两个对比的rest服务

@RestController
@RequestMapping(path = "get")
public class ParamGetRest {
    /**
     * 自定义参数解析器
     *
     * @param names
     * @param age
     * @return
     */
    @GetMapping(path = "self")
    public String selfParam(@ListParam(name = "names") List<String> names, Integer age) {
        return names + " | age=" + age;
    }

    @GetMapping(path = "self2")
    public String selfParam2(List<String> names, Integer age) {
        return names + " | age=" + age;
    }
}

演示demo如下，添加了ListParam注解的可以正常解析，没有添加注解的会抛异常

II. 其他

0. 项目&相关博文

1.4 - 4.自定义请求匹配条件RequestCondition

在spring mvc中，我们知道用户发起的请求可以通过url匹配到我们通过@RequestMapping定义的服务端点上；不知道有几个问题大家是否有过思考

一个项目中，能否存在完全相同的url？

有了解http协议的同学可能很快就能给出答案，当然可以，url相同，请求方法不同即可；那么能否出现url相同且请求方法l也相同的呢？

本文将介绍一下如何使用RequestCondition结合RequestMappingHandlerMapping，来实现url匹配规则的扩展，从而支持上面提出的case

I. 环境相关

本文介绍的内容和实际case将基于spring-boot-2.2.1.RELEASE版本，如果在测试时，发现某些地方没法兼容时，请确定一下版本

1. 项目搭建

首先我们需要搭建一个web工程，以方便后续的servelt注册的实例演示，可以通过spring boot官网创建工程，也可以建立一个maven工程，在pom.xml中如下配置

<parent>
    <groupId>org.springframework.boot</groupId>
    <artifactId>spring-boot-starter-parent</artifactId>
    <version>2.2.1.RELEASE</version>
    <relativePath/> <!-- lookup parent from repository -->
</parent>

<properties>
    <project.build.sourceEncoding>UTF-8</project.build.sourceEncoding>
    <project.reporting.outputEncoding>UTF-8</project.reporting.outputEncoding>
    <java.version>1.8</java.version>
</properties>

<dependencies>
    <dependency>
        <groupId>org.springframework.boot</groupId>
        <artifactId>spring-boot-starter-web</artifactId>
    </dependency>
</dependencies>

<build>
    <pluginManagement>
        <plugins>
            <plugin>
                <groupId>org.springframework.boot</groupId>
                <artifactId>spring-boot-maven-plugin</artifactId>
            </plugin>
        </plugins>
    </pluginManagement>
</build>
<repositories>
    <repository>
        <id>spring-snapshots</id>
        <name>Spring Snapshots</name>
        <url>https://repo.spring.io/libs-snapshot-local</url>
        <snapshots>
            <enabled>true</enabled>
        </snapshots>
    </repository>
    <repository>
        <id>spring-milestones</id>
        <name>Spring Milestones</name>
        <url>https://repo.spring.io/libs-milestone-local</url>
        <snapshots>
            <enabled>false</enabled>
        </snapshots>
    </repository>
    <repository>
        <id>spring-releases</id>
        <name>Spring Releases</name>
        <url>https://repo.spring.io/libs-release-local</url>
        <snapshots>
            <enabled>false</enabled>
        </snapshots>
    </repository>
</repositories>

2. RequestCondition介绍

在spring mvc中，通过DispatchServlet接收客户端发起的一个请求之后，会通过HanderMapping来获取对应的请求处理器；而HanderMapping如何找到可以处理这个请求的处理器呢，这就需要RequestCondition来决定了

接口定义如下，主要有三个方法，

public interface RequestCondition<T> {

	// 一个http接口上有多个条件规则时，用于合并
	T combine(T other);

	// 这个是重点，用于判断当前匹配条件和请求是否匹配；如果不匹配返回null
	// 如果匹配，生成一个新的请求匹配条件，该新的请求匹配条件是当前请求匹配条件针对指定请求request的剪裁
	// 举个例子来讲，如果当前请求匹配条件是一个路径匹配条件，包含多个路径匹配模板，
	// 并且其中有些模板和指定请求request匹配，那么返回的新建的请求匹配条件将仅仅
	// 包含和指定请求request匹配的那些路径模板。
	@Nullable
	T getMatchingCondition(HttpServletRequest request);

	// 针对指定的请求对象request发现有多个满足条件的，用来排序指定优先级，使用最优的进行响应
	int compareTo(T other, HttpServletRequest request);

}

简单说下三个接口的作用

combine: 某个接口有多个规则时，进行合并
- 比如类上指定了@RequestMapping的url为 root
- 而方法上指定的@RequestMapping的url为 method
- 那么在获取这个接口的url匹配规则时，类上扫描一次，方法上扫描一次，这个时候就需要把这两个合并成一个，表示这个接口匹配root/method
getMatchingCondition:
- 判断是否成功，失败返回null；否则，则返回匹配成功的条件
compareTo:
- 多个都满足条件时，用来指定具体选择哪一个

在Spring MVC中，默认提供了下面几种

类	说明
PatternsRequestCondition	路径匹配，即url
RequestMethodsRequestCondition	请求方法，注意是指http请求方法
ParamsRequestCondition	请求参数条件匹配
HeadersRequestCondition	请求头匹配
ConsumesRequestCondition	可消费MIME匹配条件
ProducesRequestCondition	可生成MIME匹配条件

II. 实例说明

单纯的看说明，可能不太好理解它的使用方式，接下来我们通过一个实际的case，来演示使用姿势

1. 场景说明

我们有个服务同时针对app/wap/pc三个平台，我们希望可以指定某些接口只为特定的平台提供服务

2. 实现

首先我们定义通过请求头中的x-platform来区分平台；即用户发起的请求中，需要携带这个请求头

定义平台枚举类

public enum PlatformEnum {
    PC("pc", 1), APP("app", 1), WAP("wap", 1), ALL("all", 0);

    @Getter
    private String name;

    @Getter
    private int order;

    PlatformEnum(String name, int order) {
        this.name = name;
        this.order = order;
    }

    public static PlatformEnum nameOf(String name) {
        if (name == null) {
            return ALL;
        }

        name = name.toLowerCase().trim();
        for (PlatformEnum sub : values()) {
            if (sub.name.equals(name)) {
                return sub;
            }
        }
        return ALL;
    }
}

然后定义一个注解@Platform，如果某个接口需要指定平台，则加上这个注解即可

@Documented
@Retention(RetentionPolicy.RUNTIME)
@Target({ElementType.TYPE, ElementType.METHOD})
public @interface Platform {
    PlatformEnum value() default PlatformEnum.ALL;
}

定义匹配规则PlatformRequestCondition继承自RequestCondition，实现三个接口，从请求头中获取平台，根据平台是否相同过来判定是否可以支持请求

public class PlatformRequestCondition implements RequestCondition<PlatformRequestCondition> {
    @Getter
    @Setter
    private PlatformEnum platform;

    public PlatformRequestCondition(PlatformEnum platform) {
        this.platform = platform;
    }

    @Override
    public PlatformRequestCondition combine(PlatformRequestCondition other) {
        return new PlatformRequestCondition(other.platform);
    }

    @Override
    public PlatformRequestCondition getMatchingCondition(HttpServletRequest request) {
        PlatformEnum platform = this.getPlatform(request);
        if (this.platform.equals(platform)) {
            return this;
        }

        return null;
    }

    /**
     * 优先级
     *
     * @param other
     * @param request
     * @return
     */
    @Override
    public int compareTo(PlatformRequestCondition other, HttpServletRequest request) {
        int thisOrder = this.platform.getOrder();
        int otherOrder = other.platform.getOrder();
        return otherOrder - thisOrder;
    }

    private PlatformEnum getPlatform(HttpServletRequest request) {
        String platform = request.getHeader("x-platform");
        return PlatformEnum.nameOf(platform);
    }
}

匹配规则指定完毕之后，需要注册到HandlerMapping上才能生效，这里我们自定义一个PlatformHandlerMapping

public class PlatformHandlerMapping extends RequestMappingHandlerMapping {
    @Override
    protected RequestCondition<?> getCustomTypeCondition(Class<?> handlerType) {
        return buildFrom(AnnotationUtils.findAnnotation(handlerType, Platform.class));
    }

    @Override
    protected RequestCondition<?> getCustomMethodCondition(Method method) {
        return buildFrom(AnnotationUtils.findAnnotation(method, Platform.class));
    }

    private PlatformRequestCondition buildFrom(Platform platform) {
        return platform == null ? null : new PlatformRequestCondition(platform.value());
    }
}

最后则是需要将我们的HandlerMapping注册到Spring MVC容器，在这里我们借助WebMvcConfigurationSupport来手动注册(注意一下，不同的版本，下面的方法可能会不太一样哦)

@Configuration
public class Config extends WebMvcConfigurationSupport {
    @Override
    public RequestMappingHandlerMapping requestMappingHandlerMapping(
            @Qualifier("mvcContentNegotiationManager") ContentNegotiationManager contentNegotiationManager,
            @Qualifier("mvcConversionService") FormattingConversionService conversionService,
            @Qualifier("mvcResourceUrlProvider") ResourceUrlProvider resourceUrlProvider) {
        PlatformHandlerMapping handlerMapping = new PlatformHandlerMapping();
        handlerMapping.setOrder(0);
        handlerMapping.setInterceptors(getInterceptors(conversionService, resourceUrlProvider));
        return handlerMapping;
    }
}

3. 测试

接下来进入实测环节，定义几个接口，分别指定不同的平台

@RestController
@RequestMapping(path = "method")
public class DemoMethodRest {
    @Platform
    @GetMapping(path = "index")
    public String allIndex() {
        return "default index";
    }

    @Platform(PlatformEnum.PC)
    @GetMapping(path = "index")
    public String pcIndex() {
        return "pc index";
    }


    @Platform(PlatformEnum.APP)
    @GetMapping(path = "index")
    public String appIndex() {
        return "app index";
    }

    @Platform(PlatformEnum.WAP)
    @GetMapping(path = "index")
    public String wapIndex() {
        return "wap index";
    }
}

如果我们的规则可以正常生效，那么在请求头中设置不同的x-platform，返回的结果应该会不一样，实测结果如下

注意最后两个，一个是指定了一个不匹配我们的平台的请求头，一个是没有对应的请求头，都是走了默认的匹配规则；这是因为我们在PlatformRequestCondition中做了兼容，无法匹配平台时，分配到默认的Platform.ALL

然后还有一个小疑问，如果有一个服务不区分平台，那么不加上@Platform注解是否可以呢?

@GetMapping(path = "hello")
public String hello() {
    return "hello";
}

当然是可以的实测结果如下:

在不加上@Platform注解时，有一点需要注意，这个时候就不能出现多个url和请求方法相同的，在启动的时候会直接抛出异常哦

III. 其他

web系列博文

项目源码

1.5 - 5.参数校验Validation

业务开发的小伙伴总有那么几个无法逃避的点，如大段if/else，接口的参数校验等。接下来将介绍几种使用Validation-Api的方式，来实现参数校验，让我们的业务代码更简洁

I. 基本知识点

1. validation-api

参数校验有自己的一个规范JSR303, 它是一套 JavaBean 参数校验的标准，它定义了很多常用的校验注解。

java开发环境中，可以通过引入validation-api包的相关注解，来实现参数的条件限定

<dependency>
  <groupId>jakarta.validation</groupId>
  <artifactId>jakarta.validation-api</artifactId>
  <version>2.0.1</version>
  <scope>compile</scope>
</dependency>

请注意上面这个包只是定义，如果项目中单独的引入上面的这个包，并没有什么效果，我们通常选用hibernate-validator来作为具体的实现

<dependency>
  <groupId>org.hibernate.validator</groupId>
  <artifactId>hibernate-validator</artifactId>
  <version>6.0.18.Final</version>
  <scope>compile</scope>
  <exclusions>
    <exclusion>
      <artifactId>validation-api</artifactId>
      <groupId>javax.validation</groupId>
    </exclusion>
  </exclusions>
</dependency>

下面给出一些常用的参数限定注解

注解	描述
`@AssertFalse`	被修饰的元素必须为 false
`@AssertTrue`	被修饰的元素必须是true
`@DecimalMax`	被修饰的元素必须是一个数字，其值必须小于等于指定的最大值
`@DecimalMin`	同DecimalMax
`@Digits`	被修饰的元素是数字
`@Email`	被修饰的元素必须是邮箱格式
`@Future`	将来的日期
`@Max`	被修饰的元素必须是一个数字，其值必须小于等于指定的最大值
`@Min`	被修饰的元素必须是一个数字，其值必须大于等于指定的最小值
`@NotNull`	不能是Null
`@Null`	元素是Null
`@Past`	被修饰的元素必须是一个过去的日期
`@Pattern`	被修饰的元素必须符合指定的正则表达式
`@Size`	被修饰的元素长度
`@Positive`	正数
`@PositiveOrZero`	0 or 正数
`@Negative`	负数
`@NegativeOrZero`	0 or 负数

2. 项目搭建

接下来我们创建一个SpringBoot项目，用于后续的实例演示

我们采用IDEA + JDK1.8 进行项目开发

SpringBoot: 2.2.1.RELEASE

pom核心依赖如下

<dependencies>
    <dependency>
        <groupId>org.springframework.boot</groupId>
        <artifactId>spring-boot-starter-web</artifactId>
    </dependency>
</dependencies>

请注意 并没有显示的添加上一小节的两个依赖，因为已经集成在start包中了

II. 实例演示

接下来我们进入实例演示环节，会给出几种常见的使用case，以及如何扩展参数校验，使其支持自己定制化的参数校验规则

1. 校验失败抛异常

如果我们的参数校验失败，直接抛异常，可以说是最简单的使用方式了；首先我们创建一个简单ReqDo，并对参数进行一些必要的限定

@Data
public class ReqDo {

    @NotNull
    @Max(value = 100, message = "age不能超过100")
    @Min(value = 18, message = "age不能小于18")
    private Integer age;

    @NotBlank(message = "name不能为空")
    private String name;

    @NotBlank
    @Email(message = "email非法")
    private String email;

}

然后提供一个rest接口

@RestController
public class RestDemo {

    @GetMapping(path = "exception")
    public String exception(@Valid ReqDo reqDo) {
        return reqDo.toString();
    }
}

参数左边有一个@Valid注解，用于表示这个对象需要执行参数校验，如果校验失败，会抛400错误

演示如下

2. BindingResult

将校验失败的结果塞入BindingResult，避免直接返回400，这种方式只需要在方法参数中，加一个对象即可，通过它来获取所有的参数异常错误

@GetMapping(path = "bind")
public String bind(@Valid ReqDo reqDo, BindingResult bindingResult) {
    if (bindingResult.hasErrors()) {
        return bindingResult.getAllErrors().stream().map(DefaultMessageSourceResolvable::getDefaultMessage)
                .collect(Collectors.toList()).toString();
    }

    return reqDo.toString();
}

3. 手动校验

除了上面两个借助 @Valid 注解修饰，自动实现参数校验之外，我们还可以手动校验一个DO是否准确，下面给出一个简单的实例

@GetMapping(path = "manual")
public String manual(ReqDo reqDo) {
    Set<ConstraintViolation<ReqDo>> ans =
            Validation.buildDefaultValidatorFactory().getValidator().validate(reqDo, new Class[0]);
    if (!CollectionUtils.isEmpty(ans)) {
        return ans.stream().map(ConstraintViolation::getMessage).collect(Collectors.toList()).toString();
    }

    return reqDo.toString();
}

4. 自定义参数校验

虽然JSR303规范中给出了一些常见的校验限定，但显示的业务场景千千万万，总会有覆盖不到的地方，比如最简单的手机号校验就没有，所以可扩展就很有必要了，接下来我们演示一下，自定义一个身份证校验的注解

首先定义注解 @IdCard

@Documented
@Target({ElementType.PARAMETER, ElementType.FIELD})
@Retention(RetentionPolicy.RUNTIME)
@Constraint(validatedBy = IdCardValidator.class)
public @interface IdCard {
    String message() default "身份证号码不合法";

    Class<?>[] groups() default {};

    Class<? extends Payload>[] payload() default {};
    
    @Target({METHOD, FIELD, ANNOTATION_TYPE, CONSTRUCTOR, PARAMETER, TYPE_USE})
    @Retention(RUNTIME)
    @Documented
    @interface List {

        IdCard[] value();
    }
}

上面的实现中，有几个需要注意的点

@Constraint 注解，指定校验器为 IdCardValidator, 即表示待有@IdCard直接的属性，由IdCardValidator来校验是否合乎规范
groups: 分组，主要用于不同场景下，校验方式不一样的case
- 如新增数据时，主键id可以为空；更新数据时，主键id不能为空
payload: 知道这个具体干嘛用的老哥请留言指点一下

接下来完成身份证号的校验器IdCardValidator

这里直接借助hutool工具集中的cn.hutool.core.util.IdcardUtil#isValidCard来实现身份证有效性判断

public class IdCardValidator implements ConstraintValidator<IdCard, String> {

    @Override
    public boolean isValid(String value, ConstraintValidatorContext context) {
        if (value == null) {
            return true;
        }

        return IdcardUtil.isValidCard(value);
    }
}

然后将我们前面的ReqDo修改一下，新增一个身份证的字段

@IdCard
private String idCard;

再次访问测试(说明，图1中身份证号是随便填的，图2中的身份证号是http://sfz.uzuzuz.com/这个网站生成的，并不指代真实的某个小伙伴)

IdCard校验

II. 其他

0. 项目

1.6 - 6.静态资源配置与读取

SpringWeb项目除了我们常见的返回json串之外，还可以直接返回静态资源（当然在现如今前后端分离比较普遍的情况下，不太常见了），一些简单的web项目中，前后端可能就一个人包圆了，前端页面，js/css文件也都直接放在Spring项目中，那么你知道这些静态资源文件放哪里么

I. 默认配置

1. 配置

静态资源路径，SpringBoot默认从属性spring.resources.static-locations中获取

默认值可以从org.springframework.boot.autoconfigure.web.ResourceProperties#CLASSPATH_RESOURCE_LOCATIONS获取

private static final String[] CLASSPATH_RESOURCE_LOCATIONS = { "classpath:/META-INF/resources/",
			"classpath:/resources/", "classpath:/static/", "classpath:/public/" };

/**
 * Locations of static resources. Defaults to classpath:[/META-INF/resources/,
 * /resources/, /static/, /public/].
 */
private String[] staticLocations = CLASSPATH_RESOURCE_LOCATIONS;

注意上面的默认值，默认有四个，优先级从高到低

/META-INF/resources/
/resources/
/static/
/public/

2. 实例演示

默认静态资源路径有四个，所以我们设计case需要依次访问这四个路径中的静态资源，看是否正常访问到；其次就是需要判定优先级的问题，是否和上面说的一致

首先创建一个SpringBoot web项目，工程创建流程不额外多说，pom中主要确保有下面依赖即可（本文使用版本为: 2.2.1.RELEASE)

<dependency>
    <groupId>org.springframework.boot</groupId>
    <artifactId>spring-boot-starter-web</artifactId>
</dependency>

在资源文件夹resources下，新建四个目录，并添加html文件，用于测试是否可以访问到对应的资源文件（主要关注下图中标红的几个文件）

a. META-INF/resources

静态文件 m.html

<html>
<title>META-INF/resource/m.html</title>
<body>
jar包内，META-INF/resources目录下 m.html
</body>
</html>

完成对应的Rest接口

@GetMapping(path = "m")
public String m() {
    return "m.html";
}

b. resources

静态文件 r.html

<html>
<title>resources/r.html</title>
<body>
jar包内，resouces目录下 r.html
</body>
</html>

对应的Rest接口

@GetMapping(path = "r")
public String r() {
    return "r.html";
}

c. static

静态文件 s.html

<html>
<title>static/s.html</title>
<body>
jar包内，static目录下 s.html
</body>
</html>

对应的Rest接口

@GetMapping(path = "s")
public String s() {
    return "s.html";
}

d. public

静态文件 p.html

<html>
<title>public/p.html</title>
<body>
jar包内，public目录下 p.html
</body>
</html>

对应的Rest接口

@GetMapping(path = "p")
public String p() {
    return "p.html";
}

e. 优先级测试

关于优先级的测试用例，主要思路就是在上面四个不同的文件夹下面放相同文件名的静态资源，然后根据访问时具体的返回来确定相应的优先级。相关代码可以在文末的源码中获取，这里就不赘述了

II. 自定义资源路径

一般来讲，我们的静态资源放在上面的四个默认文件夹下面已经足够，但总会有特殊情况，如果资源文件放在其他的目录下，应该怎么办？

1. 修改配置文件

第一种方式比较简单和实用，修改上面的spring.resources.static-locations配置，添加上自定义的资源目录，如在 application.yml 中，指定配置

spring:
  resources:
    static-locations: classpath:/out/,classpath:/META-INF/resources/,classpath:/resources/,classpath:/static/,classpath:/public/

上面指定了可以扫描/out目录下的静态资源文件，且它的优先级是最高的（上面的配置顺序中，优先级的高低从左到右）

实例演示

在资源目录下，新建文件/out/index.html

请注意在其他的四个资源目录下，也都存在 index.html这个文件（根据上面优先级的描述，返回的应该是/out/index.html）

@GetMapping(path = "index")
public String index() {
    return "index.html";
}

2. WebMvcConfigurer 添加资源映射

除了上述的配置指定之外，还有一种常见的使用姿势就是利用配置类WebMvcConfigurer来手动添加资源映射关系，为了简单起见，我们直接让启动类实现WebMvcConfigure接口

@SpringBootApplication
public class Application implements WebMvcConfigurer {
    @Override
    public void addResourceHandlers(ResourceHandlerRegistry registry) {
        // 请注意下面这个映射，将资源路径 /ts 下的资源，映射到根目录为 /ts的访问路径下
        // 如 ts下的ts.html, 对应的访问路径 /ts/ts
        registry.addResourceHandler("/ts/**").addResourceLocations("classpath:/ts/");
    }


    public static void main(String[] args) {
        SpringApplication.run(Application.class);
    }
}

根据上面的配置表示将/ts目录下的资源ts.html，映射到/ts/ts，而直接访问/ts会报404（这个逻辑可能有点绕，需要仔细想一想）

@GetMapping(path = "ts")
public String ts() {
    return "ts.html";
}

@GetMapping(path = "ts/ts")
public String ts2() {
    return "ts.html";
}

III. Jar包资源访问

前面描述的静态资源访问主要都是当前包内的资源访问，如果我们的静态资源是由第三方的jar包提供（比如大名鼎鼎的Swagger UI)，这种时候使用姿势是否有不一样的呢？

1. classpath 与 classpath*

在之前使用SpringMVC3+/4的时候，classpath:/META-INF/resources/表示只扫描当前包内的/META-INF/resources/路径，而classpath*:/META-INF/resources/则会扫描当前+第三方jar包中的/META-INF/resources/路径

那么在SpringBoot2.2.1-RELEASE版本中是否也需要这样做呢？（答案是不需要，且看后面的实例）

2. 实例

新建一个工程，只提供基本的html静态资源，项目基本结构如下（具体的html内容就不粘贴了，墙裂建议有兴趣的小伙伴直接看源码，阅读效果更优雅）

接着在我们上面常见的工程中，添加依赖

<dependency>
    <groupId>com.git.hui.boot</groupId>
    <artifactId>204-web-static-resources-ui</artifactId>
    <version>0.0.1-SNAPSHOT</version>
</dependency>

添加对应资源的访问端点

@GetMapping(path = "ui")
public String ui() {
    return "ui.html";
}

@GetMapping(path = "out")
public String out() {
    return "out.html";
}

// 第三方jar包的 META-INF/resources 优先级也高于当前包的 /static

@GetMapping(path = "s2")
public String s2() {
    return "s2.html";
}

请注意，这个时候我们是没有修改前面的spring.resources.static-locations配置的

上面的访问结果，除了说明访问第三方jar包中的静态资源与当前包的静态资源配置没有什么区别之外，还可以得出一点

相同资源路径下，当前包的资源优先级高于jar包中的静态资源
默认配置下，第三方jar包中META-INF/resources下的静态资源，优先级高于当前包的/resources, /static, /public

IV. 其他

0. 项目

1.7 - 7.xml传参与返回使用姿势

使用XML作为传参和返回结果，在实际的编码中可能不太常见，特别是当前json大行其道的时候；那么为什么突然来这么一出呢？源于对接微信公众号的消息接收，自动回复的开发时，惊奇的发现微信使用xml格式进行交互，所以也就不得不支持了

下面介绍一下SpringBoot中如何支持xml传参解析与返回xml文档

I. 项目环境

本文创建的实例工程采用SpringBoot 2.2.1.RELEASE + maven 3.5.3 + idea进行开发

1. pom依赖

具体的SpringBoot项目工程创建就不赘述了，对于pom文件中，需要重点关注下面两个依赖类

<dependencies>
    <dependency>
        <groupId>org.springframework.boot</groupId>
        <artifactId>spring-boot-starter-web</artifactId>
    </dependency>
    <dependency>
        <groupId>com.fasterxml.jackson.dataformat</groupId>
        <artifactId>jackson-dataformat-xml</artifactId>
        <version>2.10.0</version>
    </dependency>
</dependencies>

请注意jackson-dataformat-xml版本，不要选择太老的

II. 实例演示

1. 传参Bean

定义一个接受参数的bean对象，如下

@JacksonXmlRootElement(localName = "req")
@Data
public static class XmlBean {
    private String name;
    
    @JacksonXmlProperty(localName = "age")
    private Integer age;
}

请注意，我们使用@JacksonXmlRootElement注解来修饰这个bean，localName中的value，相当于xml的根标签；如果类中的属性成员名，和xml标签名不一样，可以使用注解@JacksonXmlProperty(localName = "xxx")来修饰

其次，请保留bean的默认无参构造函数，get/set方法（我上面为了简洁，使用了lombok（最近看到了不少抨击lombok的文章…），不希望使用lombok的小伙伴，可以利用IDEA的自动生成，来实现相关的代码）

2. Response Bean

定义返回的也是一个xml bean

@Data
@JacksonXmlRootElement(localName = "res")
public static class XmlRes {
    private String msg;

    private Integer code;

    private String data;
}

3. rest服务

然后像平常一样，实现一个"普通"的rest服务即可

@RestController
@RequestMapping(path = "xml")
public class XmlParamsRest {
    @PostMapping(path = "show", consumes = {MediaType.APPLICATION_XML_VALUE},
            produces = MediaType.APPLICATION_XML_VALUE)
    public XmlRes show(@RequestBody XmlBean bean) {
        System.out.println(bean);
        XmlRes res = new XmlRes();
        res.setCode(0);
        res.setMsg("success");
        res.setData(bean.toString());
        return res;
    }
}

注意三点

@RestController：返回的不是视图
@PostMapping注解中的 consumes 和 produces参数，指定了"application/xml"，表示我们接收和返回的都是xml文档
@RequestBody：不加这个注解时，无法获取传参哦（可以想一想why?)

接口测试

我个人倾向于万能的curl进行测试，打开终端即可使用，如下

# 测试命令
curl -X POST 'http://127.0.0.1:8080/xml/show' -H 'content-type:application/xml' -d '<req><name>一灰灰</name><age>18</age></req>' -i

考虑到有些小伙伴更青睐于Postman进行url测试，下面是具体的请求姿势

4. 解析异常问题

如果需要重新这个问题，可以参考项目: https://github.com/liuyueyi/spring-boot-demo/tree/master/spring-boot/202-web-params

某些场景下，直接使用上面的姿势貌似不能正常工作，会抛出一个Resolved [org.springframework.web.HttpMediaTypeNotSupportedException: Content type 'application/xml;charset=UTF-8' not supported]的异常信息

针对出现HttpMediaTypeNotSupportedException的场景，解决办法也很明确，增加一个xml的HttpMesssageConverter即可，依然是借助MappingJackson2XmlHttpMessageConverter，如

@Configuration
public class MvcConfig extends WebMvcConfigurationSupport {
    @Override
    public void configureMessageConverters(List<HttpMessageConverter<?>> converters) {
        super.configureMessageConverters(converters);
        converters.add(new MappingJackson2XmlHttpMessageConverter());
    }
}

II. 其他

0. 项目

1.8 - 8.xml传参与返回实战演练

最近在准备使用微信公众号来做个人站点的登录，发现微信的回调协议居然是xml格式的，之前使用json传输的较多，结果发现换成xml之后，好像并没有想象中的那么顺利，比如回传的数据始终拿不到，返回的数据对方不认等

接下来我们来实际看一下，一个传参和返回都是xml的SpringBoot应用，究竟是怎样的

I. 项目搭建

本文创建的实例工程采用SpringBoot 2.2.1.RELEASE + maven 3.5.3 + idea进行开发

1. pom依赖

具体的SpringBoot项目工程创建就不赘述了，对于pom文件中，需要重点关注下面两个依赖类

<dependencies>
    <dependency>
        <groupId>org.springframework.boot</groupId>
        <artifactId>spring-boot-starter-web</artifactId>
    </dependency>
    <dependency>
        <groupId>com.fasterxml.jackson.dataformat</groupId>
        <artifactId>jackson-dataformat-xml</artifactId>
    </dependency>
</dependencies>

2. 接口调研

我们直接使用微信公众号的回调传参、返回来搭建项目服务，微信开发平台文档如: 基础消息能力

其定义的推送参数如下

<xml>
  <ToUserName><![CDATA[toUser]]></ToUserName>
  <FromUserName><![CDATA[fromUser]]></FromUserName>
  <CreateTime>1348831860</CreateTime>
  <MsgType><![CDATA[text]]></MsgType>
  <Content><![CDATA[this is a test]]></Content>
  <MsgId>1234567890123456</MsgId>
  <MsgDataId>xxxx</MsgDataId>
  <Idx>xxxx</Idx>
</xml>

要求返回的结果如下

<xml>
  <ToUserName><![CDATA[toUser]]></ToUserName>
  <FromUserName><![CDATA[fromUser]]></FromUserName>
  <CreateTime>12345678</CreateTime>
  <MsgType><![CDATA[text]]></MsgType>
  <Content><![CDATA[你好]]></Content>
</xml>

上面的结构看起来还好，但是需要注意的是外层标签为xml，内层标签都是大写开头的；而微信识别返回是大小写敏感的

II. 实战

项目工程搭建完毕之后，首先定义一个接口，用于接收xml传参，并返回xml对象；

那么核心的问题就是如何定义传参为xml，返回也是xml呢？

没错：就是请求头 + 返回头

1.REST接口

@RestController
public class XmlRest {

    /**
     * curl -X POST 'http://localhost:8080/xml/callback' -H 'content-type:application/xml' -d '<xml><URL><![CDATA[https://hhui.top]]></URL><ToUserName><![CDATA[一灰灰blog]]></ToUserName><FromUserName><![CDATA[123]]></FromUserName><CreateTime>1655700579</CreateTime><MsgType><![CDATA[text]]></MsgType><Content><![CDATA[测试]]></Content><MsgId>11111111</MsgId></xml>' -i
     *
     * @param msg
     * @param request
     * @return
     */
    @PostMapping(path = "xml/callback",
            consumes = {"application/xml", "text/xml"},
            produces = "application/xml;charset=utf-8")
    public WxTxtMsgResVo callBack(@RequestBody WxTxtMsgReqVo msg, HttpServletRequest request) {
        WxTxtMsgResVo res = new WxTxtMsgResVo();
        res.setFromUserName(msg.getToUserName());
        res.setToUserName(msg.getFromUserName());
        res.setCreateTime(System.currentTimeMillis() / 1000);
        res.setMsgType("text");
        res.setContent("hello: " + LocalDateTime.now());
        return res;
    }
}

注意上面的接口定义，POST传参，请求头和返回头都是 application/xml

2.请求参数与返回结果对象定义

上面的接口中定义了WxTxtMsgReqVo来接收传参，定义WxTxtMsgResVo来返回结果，由于我们采用的是xml协议传输数据，这里需要借助JacksonXmlRootElement和JacksonXmlProperty注解；它们的实际作用与json传输时，使用JsonProperty来指定json key的作用相仿

下面是具体的实体定义

@Data
@JacksonXmlRootElement(localName = "xml")
public class WxTxtMsgReqVo {
    @JacksonXmlProperty(localName = "ToUserName")
    private String toUserName;
    @JacksonXmlProperty(localName = "FromUserName")
    private String fromUserName;
    @JacksonXmlProperty(localName = "CreateTime")
    private Long createTime;
    @JacksonXmlProperty(localName = "MsgType")
    private String msgType;
    @JacksonXmlProperty(localName = "Content")
    private String content;
    @JacksonXmlProperty(localName = "MsgId")
    private String msgId;
    @JacksonXmlProperty(localName = "MsgDataId")
    private String msgDataId;
    @JacksonXmlProperty(localName = "Idx")
    private String idx;
}

@Data
@JacksonXmlRootElement(localName = "xml")
public class WxTxtMsgResVo {

    @JacksonXmlProperty(localName = "ToUserName")
    private String toUserName;
    @JacksonXmlProperty(localName = "FromUserName")
    private String fromUserName;
    @JacksonXmlProperty(localName = "CreateTime")
    private Long createTime;
    @JacksonXmlProperty(localName = "MsgType")
    private String msgType;
    @JacksonXmlProperty(localName = "Content")
    private String content;
}

重点说明：

JacksonXmlRootElement 注解，定义返回的xml文档中最外层的标签名
JacksonXmlProperty 注解，定义每个属性值对应的标签名
无需额外添加<![CDATA[...]]>，这个会自动添加，防转义

3.测试

然后访问测试一下，直接通过curl来发送xml请求

curl -X POST 'http://localhost:8080/xml/callback' -H 'content-type:application/xml' -d '<xml><URL><![CDATA[https://hhui.top]]></URL><ToUserName><![CDATA[一灰灰blog]]></ToUserName><FromUserName><![CDATA[123]]></FromUserName><CreateTime>1655700579</CreateTime><MsgType><![CDATA[text]]></MsgType><Content><![CDATA[测试]]></Content><MsgId>11111111</MsgId></xml>' -i

实际响应如下

HTTP/1.1 200
Content-Type: application/xml;charset=utf-8
Transfer-Encoding: chunked
Date: Tue, 05 Jul 2022 01:20:32 GMT

<xml><ToUserName>123</ToUserName><FromUserName>一灰灰blog</FromUserName><CreateTime>1656984032</CreateTime><MsgType>text</MsgType><Content>hello: 2022-07-05T09:20:32.155</Content></xml>%

4.问题记录

4.1 HttpMediaTypeNotSupportedException异常

通过前面的方式搭建项目之后，在实际测试时，可能会遇到下面的异常情况Resolved [org.springframework.web.HttpMediaTypeNotSupportedException: Content type 'application/xml;charset=UTF-8' not supported]

当出现这个问题时，表明是没有对应的Convert来处理application/xml格式的请求头

对应的解决方案则是主动注册上

@Configuration
public class XmlWebConfig implements WebMvcConfigurer {
    @Override
    public void configureMessageConverters(List<HttpMessageConverter<?>> converters) {
        converters.add(new MappingJackson2XmlHttpMessageConverter());
    }
}

4.2 其他json接口也返回xml数据

另外一个场景则是配置了前面的xml之后，导致项目中其他正常的json传参、返回的接口也开始返回xml格式的数据了，此时解决方案如下

@Configuration
public class XmlWebConfig implements WebMvcConfigurer {
    /**
     * 配置这个，默认返回的是json格式数据；若指定了xml返回头，则返回xml格式数据
     *
     * @param configurer
     */
    @Override
    public void configureContentNegotiation(ContentNegotiationConfigurer configurer) {
        configurer.defaultContentType(MediaType.APPLICATION_JSON, MediaType.TEXT_XML, MediaType.APPLICATION_XML);
    }
}

4.3 微信实际回调参数一直拿不到

这个问题是在实际测试回调的时候遇到的，接口定义之后始终拿不到结果，主要原因就在于最开始没有在定义的实体类上添加 @JacksonXmlProperty

当我们没有指定这个注解时，接收的xml标签名与实体对象的fieldName完全相同，既区分大小写

所以为了解决这个问题，就是老老实实如上面的写法，在每个成员上添加注解，如下

@JacksonXmlProperty(localName = "ToUserName")
private String toUserName;
@JacksonXmlProperty(localName = "FromUserName")
private String fromUserName;

5.小结

本文主要介绍的是SpringBoot如何支持xml格式的传参与返回，大体上使用姿势与json格式并没有什么区别，但是在实际使用的时候需要注意上面提出的几个问题，避免采坑

关键知识点提炼如下：

Post接口上，指定请求头和返回头：
- consumes = {"application/xml", "text/xml"},
- produces = "application/xml;charset=utf-8"
实体对象，通过JacksonXmlRootElement和JacksonXmlProperty来重命名返回的标签名
注册MappingJackson2XmlHttpMessageConverter解决HttpMediaTypeNotSupportedException异常
指定ContentNegotiationConfigurer.defaultContentType 避免出现所有接口返回xml文档

III. 其他

0. 项目与源码

2 - Web花样返回

后端接口返回什么，json串？xml文档？html网页？文件？还是重定向？

2.1 - 1.Freemaker环境搭建

现在的开发现状比较流行前后端分离，使用springboot搭建一个提供rest接口的后端服务特别简单，引入spring-boot-starter-web依赖即可。那么在不分离的场景下，比如要开发一个后端使用的控制台，这时候可能并没有前端资源，由javaer自己来客串一把，我希望简单一点，前后端项目都集成在一起，一个jar包运行起来就完事，可以怎么搞呢？

本篇将介绍一下如何使用springboot集合freemaker引擎来搭建web应用

I. 准备

Freemaker是模板引擎，和jsp的作用差不多，对于它的不太清楚的同学可以参考一下官方文档 https://freemarker.apache.org/docs/index.html

1. 依赖

首先我们是需要一个springboot项目，基本的pom结构大都相似

<parent>
    <groupId>org.springframework.boot</groupId>
    <artifactId>spring-boot-starter-parent</artifactId>
    <version>2.0.4.RELEASE</version>
    <relativePath/> <!-- lookup parent from update -->
</parent>

<properties>
    <project.build.sourceEncoding>UTF-8</project.build.sourceEncoding>
    <project.reporting.outputEncoding>UTF-8</project.reporting.outputEncoding>
    <spring-cloud.version>Finchley.RELEASE</spring-cloud.version>
    <java.version>1.8</java.version>
</properties>

<build>
    <pluginManagement>
        <plugins>
            <plugin>
                <groupId>org.springframework.boot</groupId>
                <artifactId>spring-boot-maven-plugin</artifactId>
            </plugin>
        </plugins>
    </pluginManagement>
</build>
<repositories>
    <repository>
        <id>spring-milestones</id>
        <name>Spring Milestones</name>
        <url>https://repo.spring.io/milestone</url>
        <snapshots>
            <enabled>false</enabled>
        </snapshots>
    </repository>
</repositories>

在这个项目中，我们主要需要引入两个依赖包，一个web，一个freemaker

<dependencies>
    <dependency>
        <groupId>org.springframework.boot</groupId>
        <artifactId>spring-boot-starter-web</artifactId>
    </dependency>
    <dependency>
        <groupId>org.springframework.boot</groupId>
        <artifactId>spring-boot-starter-freemarker</artifactId>
    </dependency>
</dependencies>

2. 配置参数

通常我们直接使用默认的freemaker参数配置即可，下面给出几个常用的

spring:
  freemarker:
    charset: UTF-8
    # 本机测试时建议设置为false，上线时设置为true
    cache: true
    # 表示模板文件(类html文件)的后缀
    suffix: .ftl

freemaker的参数，主要对应的是org.springframework.boot.autoconfigure.freemarker.FreeMarkerProperties

II. 项目搭建演示

1. 项目结构

搭建一个web项目和我们之前的纯后端项目有点不一样，前端资源放在什么地方，依赖文件怎么处理都是有讲究的，下面是一个常规的项目结构

项目结构

如上图，前端资源文件默认放在resources目录下，下面有两个目录

templates：存放模板文件，可以理解为我们编写的html，注意这个文件名不能有问题
static: 存放静态资源文件，如js,css,image等

2. Rest服务

我们这里提供了三个接口，主要是为了演示三种不同的数据绑定方式

@Controller
public class IndexController {
    @GetMapping(path = {"", "/", "/index"})
    public ModelAndView index() {
        Map<String, Object> data = new HashMap<>(2);
        data.put("name", "YiHui Freemarker");
        data.put("now", LocalDateTime.now().toString());
        return new ModelAndView("index", data);
    }

    /**
     * 一般不建议直接使用jdk的String.split来分割字符串，内部实现是根据正则来处理的，虽然更强大，但在简单的场景下，性能开销更大
     */
    private static String[] contents =
            ("绿蚁浮觞香泛泛，黄花共荐芳辰。\n清霜天宇净无尘。\n登高宜有赋，拈笔戏成文。\n可奈园林摇落尽，悲秋意与谁论。\n眼中相识几番新。\n龙山高会处，落帽定何人。").split("\n");
    private static Random random = new Random();

    @GetMapping(path = "show1")
    public String showOne(Model model) {
        model.addAttribute("title", "临江仙");
        model.addAttribute("content", contents[random.nextInt(6)]);
        return "show1";
    }

    @GetMapping(path = "show2")
    public String showTow(Map<String, Object> data) {
        data.put("name", "Show2---->");
        data.put("now", LocalDateTime.now().toString());
        return "show2";
    }
}

上面的三种case中

第一个是最好理解的，在创建ModelAndView时，传入viewName和数据
第二个是通过接口参数Model，设置传递给view的数据
第三种则直接使用Map来传递数据

三个接口，对应的三个html文件，如下

index.ftl

<!DOCTYPE html>
<html lang="ch">
<head>
    <meta charset="UTF-8">
    <meta name="viewport" content="width=device-width, initial-scale=1">
    <meta name="description" content="SpringBoot FreeMaker"/>
    <meta name="author" content="YiHui"/>
    <meta name="viewport" content="width=device-width, initial-scale=1.0"/>
    <title>YiHui's SpringBoot Demo</title>
    <link rel="stylesheet" href="index.css"/>
</head>
<body>

<div>
    <div class="title">hello world!</div>
    <br/>
    <div class="content">欢迎访问 ${name}</div>
    <br/>
    <div class="sign">当前时间: ${now}</div>
    <br/>
    <a href="show1">传参2测试</a> &nbsp;&nbsp;&nbsp;&nbsp;
    <a href="show2">传参3测试</a>
</div>
</body>
</html>

show1.ftl

<!DOCTYPE html>
<html>
<head>
    <meta charset="UTF-8">
    <meta name="viewport" content="width=device-width, initial-scale=1">
    <meta name="description" content="SpringBoot thymeleaf"/>
    <meta name="author" content="YiHui"/>
    <meta name="viewport" content="width=device-width, initial-scale=1.0"/>
    <title>YiHui's SpringBoot Demo</title>
    <link rel="stylesheet" href="index.css"/>
</head>
<body>

<div>
    <div class="title">${title}</div>
    <div class="content">${content}</div>
</div>
</body>
</html>

show2.ft

<!DOCTYPE html>
<html xmlns:th="http://www.thymeleaf.org">
<head>
    <meta charset="UTF-8">
    <meta name="viewport" content="width=device-width, initial-scale=1">
    <meta name="description" content="SpringBoot thymeleaf"/>
    <meta name="author" content="YiHui"/>
    <meta name="viewport" content="width=device-width, initial-scale=1.0"/>
    <title>YiHui's SpringBoot Demo</title>
    <link rel="stylesheet" href="index.css"/>
</head>
<body>

<div>
    <div class="title">${name}</div>
    <div class="content">${now}</div>
</div>
</body>
</html>

在上面的模板文件中，需要注意引用css样式文件，路径前面并没有static，我们对应的css文件

index.css

.title {
    color: #c00;
    font-weight: normal;
    font-size: 2em;
}

.content {
    color: darkblue;
    font-size: 1.2em;
}

.sign {
    color: lightgray;
    font-size: 0.8em;
    font-style: italic;
}

3. 演示

启动项目后，可以看到三个页面的切换，模板中的数据根据后端的返回替换，特别是主页的时间，每次刷新都会随之改变

demo

II. 其他

0. 项目

工程：https://github.com/liuyueyi/spring-boot-demo
项目地址: https://github.com/liuyueyi/spring-boot-demo/blob/master/spring-boot/204-web-freemaker

2.2 - 2.Thymeleaf环境搭建

上一篇博文介绍了如何使用Freemaker引擎搭建web项目，这一篇我们则看一下另外一个常见的页面渲染引擎Thymeleaf如何搭建一个web项目

推荐结合Freemaker博文一起查看，效果更佳 190816-SpringBoot系列教程web篇之Freemaker环境搭建

I. 准备

Thymeleaf 是现代化服务器端的Java模板引擎，不同与JSP和FreeMarker，Thymeleaf的语法更加接近HTML，关于它的使用说明，可以参考官方文档 https://www.thymeleaf.org/documentation.html

1. 依赖

首先我们是需要一个springboot项目，基本的pom结构大都相似

<parent>
    <groupId>org.springframework.boot</groupId>
    <artifactId>spring-boot-starter-parent</artifactId>
    <version>2.0.4.RELEASE</version>
    <relativePath/> <!-- lookup parent from update -->
</parent>

<properties>
    <project.build.sourceEncoding>UTF-8</project.build.sourceEncoding>
    <project.reporting.outputEncoding>UTF-8</project.reporting.outputEncoding>
    <spring-cloud.version>Finchley.RELEASE</spring-cloud.version>
    <java.version>1.8</java.version>
</properties>

<build>
    <pluginManagement>
        <plugins>
            <plugin>
                <groupId>org.springframework.boot</groupId>
                <artifactId>spring-boot-maven-plugin</artifactId>
            </plugin>
        </plugins>
    </pluginManagement>
</build>
<repositories>
    <repository>
        <id>spring-milestones</id>
        <name>Spring Milestones</name>
        <url>https://repo.spring.io/milestone</url>
        <snapshots>
            <enabled>false</enabled>
        </snapshots>
    </repository>
</repositories>

在这个项目中，我们主要需要引入两个依赖包，一个web，一个thymeleaf

<dependencies>
    <dependency>
        <groupId>org.springframework.boot</groupId>
        <artifactId>spring-boot-starter-web</artifactId>
    </dependency>
    <dependency>
        <groupId>org.springframework.boot</groupId>
        <artifactId>spring-boot-starter-thymeleaf</artifactId>
    </dependency>
</dependencies>

2. 配置参数

通常我们直接使用默认的thymeleaf参数配置即可，下面给出几个常用的配置

spring:
  thymeleaf:
    mode: HTML
    encoding: UTF-8
    servlet:
      content-type: text/html
    cache: false

thymeleaf的参数，主要对应的是org.springframework.boot.autoconfigure.thymeleaf.ThymeleafProperties

II. 项目搭建演示

1. 项目结构

搭建一个web项目和我们之前的纯后端项目有点不一样，前端资源放在什么地方，依赖文件怎么处理都是有讲究的，下面是一个常规的项目结构

项目结构

如上图，前端资源文件默认放在resources目录下，下面有两个目录

templates：存放模板文件，可以理解为我们编写的html，注意这个文件名不能有问题
static: 存放静态资源文件，如js,css,image等

2. Rest服务

我们这里提供了三个接口，主要是为了演示三种不同的数据绑定方式（和Freemaker这篇博文基本一样）

@Controller
public class IndexController {

    @GetMapping(path = {"", "/", "/index"})
    public ModelAndView index() {
        Map<String, Object> data = new HashMap<>(2);
        data.put("name", "YiHui Thymeleaf");
        data.put("now", LocalDateTime.now().toString());
        return new ModelAndView("index", data);
    }

    /**
     * 一般不建议直接使用jdk的String.split来分割字符串，内部实现是根据正则来处理的，虽然更强大，但在简单的场景下，性能开销更大
     */
    private static String[] contents =
            ("绿蚁浮觞香泛泛，黄花共荐芳辰。\n清霜天宇净无尘。\n登高宜有赋，拈笔戏成文。\n可奈园林摇落尽，悲秋意与谁论。\n眼中相识几番新。\n龙山高会处，落帽定何人。").split("\n");
    private static Random random = new Random();

    @GetMapping(path = "show1")
    public String showOne(Model model) {
        model.addAttribute("title", "临江仙");
        model.addAttribute("content", contents[random.nextInt(6)]);
        return "show1";
    }

    @GetMapping(path = "show2")
    public String showTow(Map<String, Object> data) {
        data.put("name", "Show2---->");
        data.put("now", LocalDateTime.now().toString());
        return "show2";
    }
}

上面的三种case中

第一个是最好理解的，在创建ModelAndView时，传入viewName和数据
第二个是通过接口参数Model，设置传递给view的数据
第三种则直接使用Map来传递数据

三个接口，对应的三个html文件，如下

index.html

<!DOCTYPE html>
<html xmlns:th="http://www.thymeleaf.org">
<head>
    <meta charset="UTF-8">
    <meta name="viewport" content="width=device-width, initial-scale=1">
    <meta name="description" content="SpringBoot thymeleaf"/>
    <meta name="author" content="YiHui"/>
    <meta name="viewport" content="width=device-width, initial-scale=1.0"/>
    <title>YiHui's SpringBoot Demo</title>
    <link rel="stylesheet" href="index.css"/>
</head>
<body>

<div>
    <div class="title">hello world!</div>
    <br/>
    <div class="content" th:text="'欢迎访问' + ${name}">默认的内容</div>
    <br/>
    <div class="sign" th:text="'当前时间' + ${now}">默认的签名</div>
    <br/>
    <a href="show1">传参2测试</a> &nbsp;&nbsp;&nbsp;&nbsp;
    <a href="show2">传参3测试</a>
</div>
</body>
</html>

show1.html

<!DOCTYPE html>
<html xmlns:th="http://www.thymeleaf.org">
<head>
    <meta charset="UTF-8">
    <meta name="viewport" content="width=device-width, initial-scale=1">
    <meta name="description" content="SpringBoot thymeleaf"/>
    <meta name="author" content="YiHui"/>
    <meta name="viewport" content="width=device-width, initial-scale=1.0"/>
    <title>YiHui's SpringBoot Demo</title>
    <link rel="stylesheet" href="index.css"/>
</head>
<body>

<div>
    <div class="title" th:text="${title}">标题!</div>
    <div class="content" th:text="${content}">内容</div>
</div>
</body>
</html>

show2.html

<!DOCTYPE html>
<html xmlns:th="http://www.thymeleaf.org">
<head>
    <meta charset="UTF-8">
    <meta name="viewport" content="width=device-width, initial-scale=1">
    <meta name="description" content="SpringBoot thymeleaf"/>
    <meta name="author" content="YiHui"/>
    <meta name="viewport" content="width=device-width, initial-scale=1.0"/>
    <title>YiHui's SpringBoot Demo</title>
    <link rel="stylesheet" href="index.css"/>
</head>
<body>

<div>
    <div class="title" th:text="${name}">标题!</div>
    <div class="content" th:text="${now}">内容</div>
</div>
</body>
</html>

在上面的模板文件中，需要注意引用css样式文件，路径前面并没有static，我们对应的css文件

index.css

.title {
    color: #c00;
    font-weight: normal;
    font-size: 2em;
}

.content {
    color: darkblue;
    font-size: 1.2em;
}

.sign {
    color: lightgray;
    font-size: 0.8em;
    font-style: italic;
}

3. 演示

启动项目后，可以看到三个页面的切换，模板中的数据根据后端的返回替换，特别是主页的时间，每次刷新都会随之改变

II. 其他

0. 项目

工程：https://github.com/liuyueyi/spring-boot-demo
项目地址: https://github.com/liuyueyi/spring-boot-demo/blob/master/spring-boot/205-web-thymeleaf

2.3 - 3.Beetl环境搭建

前面两篇分别介绍了目前流行的模板引擎Freemaker和Thymeleaf构建web应用的方式，接下来我们看一下号称性能最好的国产模板引擎Beetl，如何搭建web环境

本文主要来自官方文档，如有疑问，推荐查看: http://ibeetl.com/guide/#beetl

I. 准备

1. 依赖

首先我们是需要一个springboot项目，基本的pom结构大都相似

<parent>
    <groupId>org.springframework.boot</groupId>
    <artifactId>spring-boot-starter-parent</artifactId>
    <version>2.0.4.RELEASE</version>
    <relativePath/> <!-- lookup parent from update -->
</parent>

<properties>
    <project.build.sourceEncoding>UTF-8</project.build.sourceEncoding>
    <project.reporting.outputEncoding>UTF-8</project.reporting.outputEncoding>
    <spring-cloud.version>Finchley.RELEASE</spring-cloud.version>
    <java.version>1.8</java.version>
</properties>

<build>
    <pluginManagement>
        <plugins>
            <plugin>
                <groupId>org.springframework.boot</groupId>
                <artifactId>spring-boot-maven-plugin</artifactId>
            </plugin>
        </plugins>
    </pluginManagement>
</build>
<repositories>
    <repository>
        <id>spring-milestones</id>
        <name>Spring Milestones</name>
        <url>https://repo.spring.io/milestone</url>
        <snapshots>
            <enabled>false</enabled>
        </snapshots>
    </repository>
</repositories>

在这个项目中，我们主要需要引入两个依赖包，一个web，一个官方提供的beetl-framework-starter，当前最新的版本为 1.2.12.RELEASE

<dependencies>
    <dependency>
        <groupId>org.springframework.boot</groupId>
        <artifactId>spring-boot-starter-web</artifactId>
    </dependency>
    <dependency>
        <groupId>com.ibeetl</groupId>
        <artifactId>beetl-framework-starter</artifactId>
        <version>1.2.12.RELEASE</version>
    </dependency>
</dependencies>

2. 配置参数

通常我们直接使用默认的thymeleaf参数配置即可，下面给出几个常用的配置

beetl:
  enabled: true
  suffix: btl
beetl-beetlsql:
  dev: true # 即自动检查模板变化

II. 项目搭建演示

1. 项目结构

搭建一个web项目和我们之前的纯后端项目有点不一样，前端资源放在什么地方，依赖文件怎么处理都是有讲究的，下面是一个常规的项目结构

项目结构

如上图，前端资源文件默认放在resources目录下，下面有两个目录

templates：存放模板文件，可以理解为我们编写的html，注意这个文件名不能有问题
static: 存放静态资源文件，如js,css,image等

2. Rest服务

我们这里提供了三个接口，主要是为了演示三种不同的数据绑定方式（和前面两篇博文基本一样）

@Controller
public class IndexController {

    @GetMapping(path = {"", "/", "/index"})
    public ModelAndView index() {
        Map<String, Object> data = new HashMap<>(2);
        data.put("name", "YiHui Beetl");
        data.put("now", LocalDateTime.now().toString());
        return new ModelAndView("index.btl", data);
    }

    private static String[] contents =
            ("绿蚁浮觞香泛泛，黄花共荐芳辰。\n清霜天宇净无尘。\n登高宜有赋，拈笔戏成文。\n可奈园林摇落尽，悲秋意与谁论。\n眼中相识几番新。\n龙山高会处，落帽定何人。").split("\n");
    private static Random random = new Random();

    @GetMapping(path = "show1")
    public String showOne(Model model) {
        model.addAttribute("title", "临江仙");
        model.addAttribute("content", contents[random.nextInt(6)]);
        return "show1.btl";
    }

    @GetMapping(path = "show2")
    public String showTow(Map<String, Object> data) {
        data.put("name", "Show2---->");
        data.put("now", LocalDateTime.now().toString());
        return "show2.btl";
    }
}

上面的三种case中

第一个是最好理解的，在创建ModelAndView时，传入viewName和数据
第二个是通过接口参数Model，设置传递给view的数据
第三种则直接使用Map来传递数据

注意

如果和前面两篇博文进行对比，会发现一个显著的区别，之前的Freemaker, Thymeleaf指定视图名的时候，都不需要后缀，但是这里，必须带上后缀，否则会500错误

三个接口，对应的三个btl文件，如下

index.btl

<!DOCTYPE html>
<html>
<head>
    <meta charset="UTF-8">
    <meta name="viewport" content="width=device-width, initial-scale=1">
    <meta name="description" content="SpringBoot Beetl"/>
    <meta name="author" content="YiHui"/>
    <meta name="viewport" content="width=device-width, initial-scale=1.0"/>
    <title>YiHui's SpringBoot Beetl Demo</title>
    <link rel="stylesheet" href="index.css"/>
</head>
<body>

<div>
    <div class="title">hello world!</div>
    <br/>
    <div class="content">欢迎访问  ${name}</div>
    <br/>
    <div class="sign">当前时间 ${now}</div>
    <br/>
    <a href="show1">传参2测试</a> &nbsp;&nbsp;&nbsp;&nbsp;
    <a href="show2">传参3测试</a>
</div>
</body>
</html>

show1.btl

<!DOCTYPE html>
<html>
<head>
    <meta charset="UTF-8">
    <meta name="viewport" content="width=device-width, initial-scale=1">
    <meta name="description" content="SpringBoot Beetl"/>
    <meta name="author" content="YiHui"/>
    <meta name="viewport" content="width=device-width, initial-scale=1.0"/>
    <title>YiHui's SpringBoot Beetl Demo</title>
    <link rel="stylesheet" href="index.css"/>
</head>
<body>

<div>
    <div class="title">${title}</div>
    <div class="content">${content}</div>
</div>
</body>
</html>

show2.btl

<!DOCTYPE html>
<html xmlns:th="http://www.thymeleaf.org">
<head>
    <meta charset="UTF-8">
    <meta name="viewport" content="width=device-width, initial-scale=1">
    <meta name="description" content="SpringBoot Beetl"/>
    <meta name="author" content="YiHui"/>
    <meta name="viewport" content="width=device-width, initial-scale=1.0"/>
    <title>YiHui's SpringBoot Beetl Demo</title>
    <link rel="stylesheet" href="index.css"/>
</head>
<body>

<div>
    <div class="title">${name}</div>
    <div class="content">${now}</div>
</div>
</body>
</html>

在上面的模板文件中，需要注意引用css样式文件，路径前面并没有static，我们对应的css文件

index.css

.title {
    color: #c00;
    font-weight: normal;
    font-size: 2em;
}

.content {
    color: darkblue;
    font-size: 1.2em;
}

.sign {
    color: lightgray;
    font-size: 0.8em;
    font-style: italic;
}

3. 演示

启动项目后，可以看到三个页面的切换，模板中的数据根据后端的返回替换，特别是主页的时间，每次刷新都会随之改变

demo

II. 其他

0. 项目

工程：https://github.com/liuyueyi/spring-boot-demo
项目地址: https://github.com/liuyueyi/spring-boot-demo/tree/master/spring-boot/206-web-beetl

2.4 - 4.返回文本、网页、图片的操作姿势

前面几篇博文介绍了如何获取get/post传参，既然是http请求，一般也都是有来有往，有请求参数传递，就会有数据返回。那么我们通过springboot搭建的web应用，可以怎样返回数据呢？

本篇将主要介绍以下几种数据格式的返回实例

返回文本
返回数组
返回json串
返回静态网页
返回图片

I. 环境搭建

首先得搭建一个web应用才有可能继续后续的测试，借助SpringBoot搭建一个web应用属于比较简单的活;

创建一个maven项目，pom文件如下

<parent>
    <groupId>org.springframework.boot</groupId>
    <artifactId>spring-boot-starter-parent</artifactId>
    <version>2.1.7</version>
    <relativePath/> <!-- lookup parent from update -->
</parent>

<properties>
    <project.build.sourceEncoding>UTF-8</project.build.sourceEncoding>
    <project.reporting.outputEncoding>UTF-8</project.reporting.outputEncoding>
    <spring-cloud.version>Finchley.RELEASE</spring-cloud.version>
    <java.version>1.8</java.version>
</properties>

<dependencies>
    <dependency>
        <groupId>org.springframework.boot</groupId>
        <artifactId>spring-boot-starter-web</artifactId>
    </dependency>
</dependencies>

<build>
    <pluginManagement>
        <plugins>
            <plugin>
                <groupId>org.springframework.boot</groupId>
                <artifactId>spring-boot-maven-plugin</artifactId>
            </plugin>
        </plugins>
    </pluginManagement>
</build>
<repositories>
    <repository>
        <id>spring-milestones</id>
        <name>Spring Milestones</name>
        <url>https://repo.spring.io/milestone</url>
        <snapshots>
            <enabled>false</enabled>
        </snapshots>
    </repository>
</repositories>

依然是一般的流程，pom依赖搞定之后，写一个程序入口

/**
 * Created by @author yihui in 15:26 19/9/13.
 */
@SpringBootApplication
public class Application {
    public static void main(String[] args) {
        SpringApplication.run(Application.class);
    }
}

II. 数据返回姿势实例

以下返回实例都放在同一个Controller中，具体定义如下

@Controller
@RequestMapping(path = "data")
public class DataRespRest {
}

1. 文本返回

这个属于基础功能了，发起请求，返回一串文本，在SpringMVC的体系中，要实现这种通常的写法通常是直接定义方法的返回为String；当然还有另外一种非常基础的写法，直接将返回的数据通过HttpServletResponse写入到输出流中

下面给出这两种写法的实例

@ResponseBody
@GetMapping(path = "str")
public String strRsp() {
    return "hello " + UUID.randomUUID().toString();
}

@ResponseBody
@GetMapping(path = "str2")
public void strRsp2(HttpServletResponse response) throws IOException {
    Map<String, String> ans = new HashMap<>(2);
    ans.put("a", "b");
    ans.put("b", "c");
    response.getOutputStream().write(JSON.toJSONString(ans).getBytes());
    response.getOutputStream().flush();
}

注意上面的实现中，方法上面多了一个注解@ResponseBody，这个表示返回数据，而不是视图（后面会详细说明）

strRsp2的输出借助了FastJson来实现将map序列化为json串，然后写入输出流

实例访问如下

从上面的输出也可以看出，第一种返回方式，ResponseHeaders的Content-Type: text/html;charset=UTF-8；而第二种方式则没有这个响应头，需要我们自己主动设置（这里注意一下即可，在后面的返回图片中有实例）

2，返回数组

前面请求参数的博文中，我们看到请求参数允许传入数组，那么我们返回可以直接返回数组么？讲道理的话，应该没啥问题

/**
 * 返回数组
 *
 * @return
 */
@ResponseBody
@GetMapping(path = "ary")
public String[] aryRsp() {
    return new String[]{UUID.randomUUID().toString(), LocalDateTime.now().toString()};
}

然后请求输出为

注意下响应头，为application/json, 也就是说SpringMVC将数组当成json串进行返回了

3. Bean返回

在我们实际的业务开发中，这种应该属于非常常见的使用姿势了，直接返回一个POJO，调用者接收的是一个json串，可以很容易的反序列化为需要的对象

/**
 * 返回POJO
 *
 * @return
 */
@ResponseBody
@GetMapping(path = "bean")
public DemoRsp beanRsp() {
    return new DemoRsp(200, "success", UUID.randomUUID().toString() + "--->data");
}

4. 网页返回

前面都是直接返回数据，但是我们平常在使用浏览器，更多的是发起一个请求，然后返回一个网页啊，难道说springmvc不能直接返回网页么？

当然返回网页怎么可能会不支持，（题外话：个人感觉在前后端分离逐渐流行之后，直接由后端返回网页的case不太多了，前端和后端作为独立的项目部署，两者之间通过json串进行交流；这里扯远了），我们下面看一下SpringMVC中如何返回网页

我们可以从上面直接返回字符串的case中，得到一个思路，如果我直接返回一个html文本，会怎样？既然返回content-type是text/html，那浏览器应该可以解析为网页的，下面实测一下

@ResponseBody
@GetMapping(path = "html")
public String strHtmlRsp() {
    return "<html>\n" + "<head>\n" + "    <title>返回数据测试</title>\n" + "</head>\n" + "<body>\n" +
            "<h1>欢迎欢迎，热烈欢迎</h1>\n" + "</body>\n" + "</html>";
}

测试如下

浏览器发起请求之后，将我们返回的html文本当做网页正常渲染了，所以我们如果想返回网页，就这么干，没毛病！

上面这种方式虽然说可以返回网页，然而在实际业务中，如果真要我们这么干，想想也是可怕，还干什么后端，分分钟全栈得了！！！

下面看一下更常规的写法，首先我们需要配置下返回视图的前缀、后缀, 在application.yml配置文件中添加如下配置

spring:
  mvc:
    view:
      prefix: /
      suffix: .html

然后我们的静态网页，放在资源文件的static目录下，下面是我们实际的项目截图，index.html为我们需要返回的静态网页

接下来就是我们的服务接口

/**
 * 返回视图
 *
 * @return
 */
@GetMapping(path = "view")
public String viewRsp() {
    return "index";
}

注意下上面的接口，没有@ResponseBody注解，表示这个接口返回的是一个视图，会从static目录下寻找名为index.html（前缀路径和后缀是上面的application.yml中定义）的网页返回

实测case如下

5. 图片返回

图片返回与前面的又不太一样了，上面介绍的几种case中，要么是返回文本，要么返回视图，而返回图片呢，更多的是返回图片的字符数组，然后告诉浏览器这是个图片，老哥你按照图片渲染

直接返回二进制流，上面在介绍文本返回的两种方式中，有个直接通过HttpServletResponse向输出流中写数据的方式，我们这里是不是可以直接这么用呢？

下面给出一个从网络下载图片并返回二进制流的实际case

/**
 * 返回图片
 */
@GetMapping(path = "img")
public void imgRsp(HttpServletResponse response) throws IOException {
    response.setContentType("image/png");
    ServletOutputStream outStream = response.getOutputStream();

    String path = "https://spring.hhui.top/spring-blog/imgs/info/info.png";
    URL uri = new URL(path);
    BufferedImage img = ImageIO.read(uri);
    ImageIO.write(img, "png", response.getOutputStream());
    System.out.println("--------");
}

注意下上面的实例case，首先设置了返回的ContentType，然后借助ImateIO来下载图片（个人不太建议这种写法，很容易出现403；这里演示主要是为了简单…），并将图片写入到输出流

实例演示如下

III 小结

1. 返回数据小结

本篇博文主要介绍了几种常见数据格式的返回使用姿势，本文更多的是一种使用方式的实例case演示，并没有涉及到底层的支持原理，也没有过多的提及如何设置响应头，web交互中常见的cookies/session也没有说到，这些将作为下篇的内容引入，恳请关注

下面做一个简单的小结

返回纯数据

添加@ResponseBody注解，则表示我们返回的是数据，而不需要进行视图解析渲染；
- 如果一个controller中全部都是返回数据，不会返回视图时，我们可以在添加@RestController注解，然后这个类中的接口都不需要添加@ResponseBody注解了
返回视图时，我们会根据接口返回的字符串，结合定义的前缀，后缀，到资源路径的static目录下寻找对应的静态文件返回
可以直接通过向HttpServletResponse的输出流中写数据的方式来返回数据，如返回图片常用这种case

2. 更多web系列博文

IV. 其他

0. 项目

2.5 - 5.请求重定向

前面介绍了spring web篇数据返回的几种常用姿势，当我们在相应一个http请求时，除了直接返回数据之外，还有另一种常见的case -> 重定向；

比如我们在逛淘宝，没有登录就点击购买时，会跳转到登录界面，这其实就是一个重定向。本文主要介绍对于后端而言，可以怎样支持302重定向

I. 环境搭建

首先得搭建一个web应用才有可能继续后续的测试，借助SpringBoot搭建一个web应用属于比较简单的活;

创建一个maven项目，pom文件如下

<parent>
    <groupId>org.springframework.boot</groupId>
    <artifactId>spring-boot-starter-parent</artifactId>
    <version>2.1.7</version>
    <relativePath/> <!-- lookup parent from update -->
</parent>

<properties>
    <project.build.sourceEncoding>UTF-8</project.build.sourceEncoding>
    <project.reporting.outputEncoding>UTF-8</project.reporting.outputEncoding>
    <spring-cloud.version>Finchley.RELEASE</spring-cloud.version>
    <java.version>1.8</java.version>
</properties>

<dependencies>
    <dependency>
        <groupId>org.springframework.boot</groupId>
        <artifactId>spring-boot-starter-web</artifactId>
    </dependency>
    <dependency>
        <groupId>com.alibaba</groupId>
        <artifactId>fastjson</artifactId>
        <version>1.2.45</version>
    </dependency>
</dependencies>

<build>
    <pluginManagement>
        <plugins>
            <plugin>
                <groupId>org.springframework.boot</groupId>
                <artifactId>spring-boot-maven-plugin</artifactId>
            </plugin>
        </plugins>
    </pluginManagement>
</build>
<repositories>
    <repository>
        <id>spring-milestones</id>
        <name>Spring Milestones</name>
        <url>https://repo.spring.io/milestone</url>
        <snapshots>
            <enabled>false</enabled>
        </snapshots>
    </repository>
</repositories>

依然是一般的流程，pom依赖搞定之后，写一个程序入口

/**
 * Created by @author yihui in 15:26 19/9/13.
 */
@SpringBootApplication
public class Application {
    public static void main(String[] args) {
        SpringApplication.run(Application.class);
    }
}

II. 302重定向

1. 返回redirect

这种case通常适用于返回视图的接口，在返回的字符串前面添加redirect:方式来告诉Spring框架，需要做302重定向处理

@Controller
@RequestMapping(path = "redirect")
public class RedirectRest {

    @ResponseBody
    @GetMapping(path = "index")
    public String index(HttpServletRequest request) {
        return "重定向访问! " + JSON.toJSONString(request.getParameterMap());
    }

    @GetMapping(path = "r1")
    public String r1() {
        return "redirect:/redirect/index?base=r1";
    }
}

上面给出了一个简单的demo，当我们访问/redirect/r1时，会重定向到请求/redirect/index?base=r1，实际测试结果如下

注意上面的截图，我们实际访问的连接是 http://127.0.0.1:8080/redirect/index?base=r1，在浏览器中的表现则是请求url变成了http://127.0.0.1:8080/redirect/index?base=r1；通过控制台查看到的返回头状态码是302

说明

使用这种方式的前提是不能在接口上添加@ResponseBody注解，否则返回的字符串被当成普通字符串处理直接返回，并不会实现重定向

2. HttpServletResponse重定向

前面一篇说到SpringMVC返回数据的时候，介绍到可以直接通过HttpServletResponse往输出流中写数据的方式，来返回结果；我们这里也是利用它，来实现重定向

@ResponseBody
@GetMapping(path = "r2")
public void r2(HttpServletResponse response) throws IOException {
    response.sendRedirect("/redirect/index?base=r2");
}

从上面的demo中，也可以看出这个的使用方式很简单了，直接调用javax.servlet.http.HttpServletResponse#sendRedirect，并传入需要重定向的url即可

3. 小结

这里主要介绍了两种常见的后端重定向方式，都比较简单，这两种方式也有自己的适用场景（当然并不绝对）

在返回视图的前面加上redirect的方式，更加适用于视图的跳转，从一个网页跳转到另一个网页
HttpServletResponse#sendRedirec的方式更加灵活，可以在后端接收一次http请求生命周期中的任何一个阶段来使用，比如有以下几种常见的场景
- 某个接口要求登录时，在拦截器层针对所有未登录的请求，重定向到登录页面
- 全局异常处理中，如果出现服务器异常，重定向到定制的500页面
- 不支持的请求，重定向到404页面

II. 其他

0. 项目

a. 系列博文

b. 项目源码

2.6 - 6.404、500异常页面配置

接着前面几篇web处理请求的博文，本文将说明，当出现异常的场景下，如404请求url不存在，，403无权，500服务器异常时，我们可以如何处理

I. 环境搭建

首先得搭建一个web应用才有可能继续后续的测试，借助SpringBoot搭建一个web应用属于比较简单的活;

创建一个maven项目，pom文件如下

<parent>
    <groupId>org.springframework.boot</groupId>
    <artifactId>spring-boot-starter-parent</artifactId>
    <version>2.1.7</version>
    <relativePath/> <!-- lookup parent from update -->
</parent>

<properties>
    <project.build.sourceEncoding>UTF-8</project.build.sourceEncoding>
    <project.reporting.outputEncoding>UTF-8</project.reporting.outputEncoding>
    <spring-cloud.version>Finchley.RELEASE</spring-cloud.version>
    <java.version>1.8</java.version>
</properties>

<dependencies>
    <dependency>
        <groupId>org.springframework.boot</groupId>
        <artifactId>spring-boot-starter-web</artifactId>
    </dependency>
    <dependency>
        <groupId>com.alibaba</groupId>
        <artifactId>fastjson</artifactId>
        <version>1.2.45</version>
    </dependency>
</dependencies>

<build>
    <pluginManagement>
        <plugins>
            <plugin>
                <groupId>org.springframework.boot</groupId>
                <artifactId>spring-boot-maven-plugin</artifactId>
            </plugin>
        </plugins>
    </pluginManagement>
</build>
<repositories>
    <repository>
        <id>spring-milestones</id>
        <name>Spring Milestones</name>
        <url>https://repo.spring.io/milestone</url>
        <snapshots>
            <enabled>false</enabled>
        </snapshots>
    </repository>
</repositories>

依然是一般的流程，pom依赖搞定之后，写一个程序入口

/**
 * Created by @author yihui in 15:26 19/9/13.
 */
@SpringBootApplication
public class Application {
    public static void main(String[] args) {
        SpringApplication.run(Application.class);
    }
}

II. 异常页面配置

在SpringBoot项目中，本身提供了一个默认的异常处理页面，当我们希望使用自定义的404,500等页面时，可以如何处理呢？

1. 默认异常页面配置

在默认的情况下，要配置异常页面非常简单，在资源路径下面，新建 error 目录，在下面添加400.html, 500html页面即可

项目结构如上，注意这里的实例demo是没有使用模板引擎的，所以我们的异常页面放在static目录下；如果使用了如FreeMaker模板引擎时，可以将错误模板页面放在template目录下

接下来实际测试下是否生效, 我们先定义一个可能出现服务器500的服务

@Controller
@RequestMapping(path = "page")
public class ErrorPageRest {

    @ResponseBody
    @GetMapping(path = "divide")
    public int divide(int sub) {
        System.out.println("divide1");
        return 1000 / sub;
    }
}

请求一个不存在的url，返回我们定义的400.html页面

<html>
<head>
    <title>404页面</title>
</head>
<body>
<h3>页面不存在</h3>
</body>
</html>

请求一个服务器500异常，返回我们定义的500.html页面

<html>
<head>
    <title>500页面</title>
</head>
<body>
<h2 style="color: red;">服务器出现异常!!!</h2>
</body>
</html>

2. BasicErrorController

看上面的使用比较简单，自然会有个疑问，这个异常页面是怎么返回的呢？

从项目启动的日志中，注意一下RequestMappingHandlerMapping

可以发现里面有个/error的路径不是我们自己定义的，从命名上来看，这个多半就是专门用来处理异常的Controller -> BasicErrorController，部分代码如下

@Controller
@RequestMapping("${server.error.path:${error.path:/error}}")
public class BasicErrorController extends AbstractErrorController {

	@Override
	public String getErrorPath() {
		return this.errorProperties.getPath();
	}

	@RequestMapping(produces = "text/html")
	public ModelAndView errorHtml(HttpServletRequest request,
			HttpServletResponse response) {
		HttpStatus status = getStatus(request);
		Map<String, Object> model = Collections.unmodifiableMap(getErrorAttributes(
				request, isIncludeStackTrace(request, MediaType.TEXT_HTML)));
		response.setStatus(status.value());
		ModelAndView modelAndView = resolveErrorView(request, response, status, model);
		return (modelAndView != null) ? modelAndView : new ModelAndView("error", model);
	}

	@RequestMapping
	@ResponseBody
	public ResponseEntity<Map<String, Object>> error(HttpServletRequest request) {
		Map<String, Object> body = getErrorAttributes(request,
				isIncludeStackTrace(request, MediaType.ALL));
		HttpStatus status = getStatus(request);
		return new ResponseEntity<>(body, status);
	}
}

这个Controller中，一个返回网页的接口，一个返回Json串的接口；我们前面使用的应该是第一个，那我们什么场景下会使用到第二个呢？

通过制定请求头的Accept，来限定我们只希望获取json的返回即可

3. 小结

本篇内容比较简单，归纳为两句话如下

将自定义的异常页面根据http状态码命名，放在/error目录下
在异常状况下，根据返回的http状态码找到对应的异常页面返回

II. 其他

0. 项目

a. 系列博文

b. 项目源码

2.7 - 7.全局异常处理

当我们的后端应用出现异常时，通常会将异常状况包装之后再返回给调用方或者前端，在实际的项目中，不可能对每一个地方都做好异常处理，再优雅的代码也可能抛出异常，那么在Spring项目中，可以怎样优雅的处理这些异常呢?

本文将介绍一种全局异常处理方式，主要包括以下知识点

@ControllerAdvice Controller增强
@ExceptionHandler 异常捕获
@ResponseStatus 返回状态码
NoHandlerFoundException处理（404异常捕获）

I. 环境搭建

首先得搭建一个web应用才有可能继续后续的测试，借助SpringBoot搭建一个web应用属于比较简单的活;

创建一个maven项目，pom文件如下

<parent>
    <groupId>org.springframework.boot</groupId>
    <artifactId>spring-boot-starter-parent</artifactId>
    <version>2.1.7</version>
    <relativePath/> <!-- lookup parent from update -->
</parent>

<properties>
    <project.build.sourceEncoding>UTF-8</project.build.sourceEncoding>
    <project.reporting.outputEncoding>UTF-8</project.reporting.outputEncoding>
    <spring-cloud.version>Finchley.RELEASE</spring-cloud.version>
    <java.version>1.8</java.version>
</properties>

<dependencies>
    <dependency>
        <groupId>org.springframework.boot</groupId>
        <artifactId>spring-boot-starter-web</artifactId>
    </dependency>
    <dependency>
        <groupId>com.alibaba</groupId>
        <artifactId>fastjson</artifactId>
        <version>1.2.45</version>
    </dependency>
</dependencies>

<build>
    <pluginManagement>
        <plugins>
            <plugin>
                <groupId>org.springframework.boot</groupId>
                <artifactId>spring-boot-maven-plugin</artifactId>
            </plugin>
        </plugins>
    </pluginManagement>
</build>
<repositories>
    <repository>
        <id>spring-milestones</id>
        <name>Spring Milestones</name>
        <url>https://repo.spring.io/milestone</url>
        <snapshots>
            <enabled>false</enabled>
        </snapshots>
    </repository>
</repositories>

依然是一般的流程，pom依赖搞定之后，写一个程序入口

/**
 * Created by @author yihui in 15:26 19/9/13.
 */
@SpringBootApplication
public class Application {
    public static void main(String[] args) {
        SpringApplication.run(Application.class);
    }
}

II. 异常处理

1. @ControllerAdvice

我们通常利用@ControllerAdvice配合注解@ExceptionHandler来实现全局异常捕获处理

@ControllerAdvice为所有的Controller织入增强方法
@ExceptionHandler标记在方法上，表示当出现对应的异常抛出到上层时（即没有被业务捕获），这个方法会被触发

下面我们通过实例进行功能演示

a. 异常捕获

我们定义两个异常捕获的case，一个是除0，一个是数组越界异常

@Slf4j
@ControllerAdvice
public class GlobalExceptionHandler {

    public static String getThrowableStackInfo(Throwable e) {
        ByteArrayOutputStream buf = new ByteArrayOutputStream();
        e.printStackTrace(new java.io.PrintWriter(buf, true));
        String msg = buf.toString();
        try {
            buf.close();
        } catch (Exception t) {
            return e.getMessage();
        }
        return msg;
    }

    @ResponseBody
    @ExceptionHandler(value = ArithmeticException.class)
    public String handleArithmetic(HttpServletRequest request, HttpServletResponse response, ArithmeticException e)
            throws IOException {
        log.info("divide error!");
        return "divide 0: " + getThrowableStackInfo(e);
    }

    @ResponseBody
    @ExceptionHandler(value = ArrayIndexOutOfBoundsException.class)
    public String handleArrayIndexOutBounds(HttpServletRequest request, HttpServletResponse response,
            ArrayIndexOutOfBoundsException e) throws IOException {
        log.info("array index out error!");
        return "aryIndexOutOfBounds: " + getThrowableStackInfo(e);
    }
}

在上面的测试中，我们将异常堆栈返回调用方

b. 示例服务

增加几个测试方法

@Controller
@RequestMapping(path = "page")
public class ErrorPageRest {

    @ResponseBody
    @GetMapping(path = "divide")
    public int divide(int sub) {
        return 1000 / sub;
    }

    private int[] ans = new int[]{1, 2, 3, 4};

    @ResponseBody
    @GetMapping(path = "ary")
    public int ary(int index) {
        return ans[index];
    }
}

c. 测试说明

实例测试如下，上面我们声明捕获的两种异常被拦截并输出对应的堆栈信息；

但是需要注意

404和未捕获的500异常则显示的SpringBoot默认的错误页面；
此外我们捕获返回的http状态码是200

2. @ResponseStatus

上面的case中捕获的异常返回的状态码是200，但是在某些case中，可能更希望返回更合适的http状态码，此时可以使用ResponseStatus来指定

使用方式比较简单，加一个注解即可

@ResponseBody
@ExceptionHandler(value = ArithmeticException.class)
@ResponseStatus(HttpStatus.INTERNAL_SERVER_ERROR)
public String handleArithmetic(HttpServletRequest request, HttpServletResponse response, ArithmeticException e)
        throws IOException {
    log.info("divide error!");
    return "divide 0: " + getThrowableStackInfo(e);
}

3. 404处理

通过@ControllerAdvice配合@ExceptionHandler可以拦截500异常，如果我希望404异常也可以拦截，可以如何处理？

首先修改配置文件application.properties，将NoHandlerFoundException抛出来

# 出现错误时, 直接抛出异常
spring.mvc.throw-exception-if-no-handler-found=true
# 设置静态资源映射访问路径，下面两个二选一，
spring.mvc.static-path-pattern=/statics/**
# spring.resources.add-mappings=false

其次是定义异常捕获

@ResponseBody
@ExceptionHandler(value = NoHandlerFoundException.class)
@ResponseStatus(HttpStatus.NOT_FOUND)
public String handleNoHandlerError(NoHandlerFoundException e, HttpServletResponse response) {
    return "noHandlerFound: " + getThrowableStackInfo(e);
}

再次测试如下，404被我们捕获并返回堆栈信息

II. 其他

0. 项目

web系列博文

项目源码

2.8 - 8.自定义异常处理HandlerExceptionResolver

关于Web应用的全局异常处理，上一篇介绍了ControllerAdvice结合@ExceptionHandler的方式来实现web应用的全局异常管理；

本篇博文则带来另外一种并不常见的使用方式，通过实现自定义的HandlerExceptionResolver，来处理异常状态

上篇博文链接: SpringBoot系列教程web篇之全局异常处理

I. 环境搭建

首先得搭建一个web应用才有可能继续后续的测试，借助SpringBoot搭建一个web应用属于比较简单的活;

创建一个maven项目，pom文件如下

<parent>
    <groupId>org.springframework.boot</groupId>
    <artifactId>spring-boot-starter-parent</artifactId>
    <version>2.1.7</version>
    <relativePath/> <!-- lookup parent from update -->
</parent>

<properties>
    <project.build.sourceEncoding>UTF-8</project.build.sourceEncoding>
    <project.reporting.outputEncoding>UTF-8</project.reporting.outputEncoding>
    <spring-cloud.version>Finchley.RELEASE</spring-cloud.version>
    <java.version>1.8</java.version>
</properties>

<dependencies>
    <dependency>
        <groupId>org.springframework.boot</groupId>
        <artifactId>spring-boot-starter-web</artifactId>
    </dependency>
    <dependency>
        <groupId>com.alibaba</groupId>
        <artifactId>fastjson</artifactId>
        <version>1.2.45</version>
    </dependency>
</dependencies>

<build>
    <pluginManagement>
        <plugins>
            <plugin>
                <groupId>org.springframework.boot</groupId>
                <artifactId>spring-boot-maven-plugin</artifactId>
            </plugin>
        </plugins>
    </pluginManagement>
</build>
<repositories>
    <repository>
        <id>spring-milestones</id>
        <name>Spring Milestones</name>
        <url>https://repo.spring.io/milestone</url>
        <snapshots>
            <enabled>false</enabled>
        </snapshots>
    </repository>
</repositories>

II. HandlerExceptionResolver

1. 自定义异常处理

HandlerExceptionResolver顾名思义，就是处理异常的类，接口就一个方法，出现异常之后的回调，四个参数中还携带了异常堆栈信息

@Nullable
ModelAndView resolveException(
		HttpServletRequest request, HttpServletResponse response, @Nullable Object handler, Exception ex);

我们自定义异常处理类就比较简单了，实现上面的接口，然后将完整的堆栈返回给调用方

public class SelfExceptionHandler implements HandlerExceptionResolver {
    @Override
    public ModelAndView resolveException(HttpServletRequest request, HttpServletResponse response, Object handler,
            Exception ex) {
        String msg = GlobalExceptionHandler.getThrowableStackInfo(ex);

        try {
            response.addHeader("Content-Type", "text/html; charset=UTF-8");
            response.getWriter().append("自定义异常处理!!! \n").append(msg).flush();
        } catch (Exception e) {
            e.printStackTrace();
        }
        return null;
    }
}

// 堆栈信息打印方法如下
public static String getThrowableStackInfo(Throwable e) {
    ByteArrayOutputStream buf = new ByteArrayOutputStream();
    e.printStackTrace(new java.io.PrintWriter(buf, true));
    String msg = buf.toString();
    try {
        buf.close();
    } catch (Exception t) {
        return e.getMessage();
    }
    return msg;
}

仔细观察上面的代码实现，有下面几个点需要注意

为了确保中文不会乱码，我们设置了返回头 response.addHeader("Content-Type", "text/html; charset=UTF-8"); 如果没有这一行，会出现中文乱码的情况
我们纯后端应用，不想返回视图，直接想Response的输出流中写入数据返回 response.getWriter().append("自定义异常处理!!! \n").append(msg).flush();；如果项目中有自定义的错误页面，可以通过返回ModelAndView来确定最终返回的错误页面
上面一个代码并不会直接生效，需要注册，可以在WebMvcConfigurer的子类中实现注册，实例如下

@SpringBootApplication
public class Application implements WebMvcConfigurer {
    @Override
    public void configureHandlerExceptionResolvers(List<HandlerExceptionResolver> resolvers) {
        resolvers.add(0, new SelfExceptionHandler());
    }

    public static void main(String[] args) {
        SpringApplication.run(Application.class);
    }
}

2. 测试case

我们依然使用上篇博文的用例来测试

@Controller
@RequestMapping(path = "page")
public class ErrorPageRest {

    @ResponseBody
    @GetMapping(path = "divide")
    public int divide(int sub) {
        return 1000 / sub;
    }
}

下面分别是404异常和500异常的实测情况

500异常会进入我们的自定义异常处理类, 而404依然走的是默认的错误页面，所以如果我们需要捕获404异常，依然需要在配置文件中添加

# 出现错误时, 直接抛出异常
spring.mvc.throw-exception-if-no-handler-found=true
# 设置静态资源映射访问路径
spring.mvc.static-path-pattern=/statics/**
# spring.resources.add-mappings=false

为什么404需要额外处理？

下面尽量以通俗易懂的方式说明下这个问题

java web应用，除了返回json类数据之外还可能返回网页，js，css
我们通过 @ResponseBody来表明一个url返回的是json数据（通常情况下是这样的，不考虑自定义实现）
我们的@Controller中通过@RequestMapping定义的REST服务，返回的是静态资源
那么js,css,图片这些文件呢，在我们的web应用中并不会定义一个REST服务
所以当接收一个http请求，找不到url关联映射时，默认场景下不认为这是一个NoHandlerFoundException，不抛异常，而是到静态资源中去找了(静态资源中也没有，为啥不抛NoHandlerFoundException呢？这个异常表示这个url请求没有对应的处理器，但是我们这里呢，给它分配到了静态资源处理器了ResourceHttpRequestHandler)

针对上面这点，如果有兴趣深挖的同学，这里给出关键代码位置

// 进入方法： `org.springframework.web.servlet.DispatcherServlet#doDispatch`

// debug 节点
Determine handler for the current request.
mappedHandler = getHandler(processedRequest);
if (mappedHandler == null) {
	noHandlerFound(processedRequest, response);
	return;
}

// 核心逻辑
// org.springframework.web.servlet.DispatcherServlet#getHandler
@Nullable
protected HandlerExecutionChain getHandler(HttpServletRequest request) throws Exception {
	if (this.handlerMappings != null) {
		for (HandlerMapping hm : this.handlerMappings) {
			if (logger.isTraceEnabled()) {
				logger.trace(
						"Testing handler map [" + hm + "] in DispatcherServlet with name '" + getServletName() + "'");
			}
			HandlerExecutionChain handler = hm.getHandler(request);
			if (handler != null) {
				return handler;
			}
		}
	}
	return null;
}

3. 小结

本篇博文虽然也介绍了一种新的全局异常处理方式，实现效果和ControllerAdvice也差不多，但是并不推荐用这种方法, 原因如下

HandlerExceptionResolver的方式没有ControllerAdvice方式简介优雅
官方提供的DefaultHandlerExceptionResolver已经非常强大了，基本上覆盖了http的各种状态码，我们自己再去定制的必要性不大

II. 其他

web系列博文

项目源码

2.9 - 9.开启GZIP数据压缩

本篇可以归纳在性能调优篇，虽然内容非常简单，但效果可能出乎预料的好；

分享一个真实案例，我们的服务部署在海外，国内访问时访问服务时，响应有点夸张；某些返回数据比较大的接口，耗时在600ms+上，然而我们的服务rt却是在20ms以下，绝大部分的开销都花在了网络传输上

针对这样的场景，除了买云服务商的网络通道之外，另外一个直观的想法就是减少数据包的大小，直接在nginx层配置gzip压缩是一个方案，本文主要介绍下，SpringBoot如何开启gzip压缩

I. gizp压缩配置

1. 配置

SpringBoot默认是不开启gzip压缩的，需要我们手动开启，在配置文件中添加两行

server:
  compression:
    enabled: true
    mime-types: application/json,application/xml,text/html,text/plain,text/css,application/x-javascript

注意下上面配置中的mime-types，在spring2.0+的版本中，默认值如下，所以一般我们不需要特意添加这个配置

// org.springframework.boot.web.server.Compression#mimeTypes
/**
 * Comma-separated list of MIME types that should be compressed.
 */
private String[] mimeTypes = new String[] { "text/html", "text/xml", "text/plain",
		"text/css", "text/javascript", "application/javascript", "application/json",
		"application/xml" };

2. 测试

写一个测试的demo

@RestController
public class HelloRest {
    @GetMapping("bigReq")
    public String bigReqList() {
        List<String> result = new ArrayList<>(2048);
        for (int i = 0; i < 2048; i++) {
            result.add(UUID.randomUUID().toString());
        }
        return JSON.toJSONString(result);
    }
}

下面是开启压缩前后的数据报对比

3. 说明

虽然加上了上面的配置，开启了gzip压缩，但是需要注意并不是说所有的接口都会使用gzip压缩，默认情况下，仅会压缩2048字节以上的内容

如果我们需要修改这个值，通过修改配置即可

server:
  compression:
    min-response-size: 1024

II. 其他

0. 项目

web系列博文

项目源码

2.10 - 10.RestTemplate 4xx/5xx 异常信息捕获

近期使用RestTemplate访问外部资源时，发现一个有意思的问题。因为权限校验失败，对方返回的401的http code，此外返回数据中也会包含一些异常提示信息；然而在使用RestTemplate访问时，却是直接抛了如下提示401的异常，并不能拿到提示信息

那么RestTemplate如果希望可以获取到非200状态码返回数据时，可以怎么操作呢？

I. 异常捕获

1. 问题分析

RestTemplate的异常处理，是借助org.springframework.web.client.ResponseErrorHandler来做的，先看一下两个核心方法

下面代码来自 spring-web.5.0.7.RELEASE版本

public interface ResponseErrorHandler {
  // 判断是否有异常
	boolean hasError(ClientHttpResponse response) throws IOException;
  // 如果有问题，进入这个方法，处理问题
	void handleError(ClientHttpResponse response) throws IOException;
}

简单来讲，当RestTemplate发出请求，获取到对方相应之后，会交给ResponseErrorHandler来判断一下，返回结果是否ok

因此接下来将目标瞄准到RestTemplate默认的异常处理器: org.springframework.web.client.DefaultResponseErrorHandler

a. 判定返回结果是否ok

从源码上看，主要是根据返回的http code来判断是否ok

// 根据返回的http code判断有没有问题
@Override
public boolean hasError(ClientHttpResponse response) throws IOException {
	HttpStatus statusCode = HttpStatus.resolve(response.getRawStatusCode());
	return (statusCode != null && hasError(statusCode));
}

// 具体的判定逻辑，简单来讲，就是返回的http code是标准的4xx, 5xx，那么就认为有问题了
protected boolean hasError(HttpStatus statusCode) {
	return (statusCode.series() == HttpStatus.Series.CLIENT_ERROR ||
			statusCode.series() == HttpStatus.Series.SERVER_ERROR);
}

请注意上面的实现，自定义的某些http code是不会被认为是异常的，因为无法转换为对应的HttpStatus （后面实例进行说明）

b. 异常处理

当上面的 hasError 返回ture的时候，就会进入异常处理逻辑

@Override
public void handleError(ClientHttpResponse response) throws IOException {
	HttpStatus statusCode = HttpStatus.resolve(response.getRawStatusCode());
	if (statusCode == null) {
		throw new UnknownHttpStatusCodeException(response.getRawStatusCode(), response.getStatusText(),
				response.getHeaders(), getResponseBody(response), getCharset(response));
	}
	handleError(response, statusCode);
}

protected void handleError(ClientHttpResponse response, HttpStatus statusCode) throws IOException {
	switch (statusCode.series()) {
		case CLIENT_ERROR:
			throw new HttpClientErrorException(statusCode, response.getStatusText(),
					response.getHeaders(), getResponseBody(response), getCharset(response));
		case SERVER_ERROR:
			throw new HttpServerErrorException(statusCode, response.getStatusText(),
					response.getHeaders(), getResponseBody(response), getCharset(response));
		default:
			throw new UnknownHttpStatusCodeException(statusCode.value(), response.getStatusText(),
					response.getHeaders(), getResponseBody(response), getCharset(response));
	}
}

从上面也可以看到，异常处理逻辑很简单，直接抛异常

2. 异常捕获

定位到上面的问题之后，再想解决问题就相对简单了，自定义一个异常处理类，不管状态码返回是啥，全都认为正常即可

RestTemplate restTemplate = new RestTemplate();
restTemplate.setErrorHandler(new DefaultResponseErrorHandler(){
    @Override
    protected boolean hasError(HttpStatus statusCode) {
        return super.hasError(statusCode);
    }

    @Override
    public void handleError(ClientHttpResponse response) throws IOException {
    }
});

3. 实测

首先写两个结果，返回的http状态码非200；针对返回非200状态码的case，有多种写法，下面演示两种常见的

@RestController
public class HelloRest {
  @GetMapping("401")
  public ResponseEntity<String> _401(HttpServletResponse response) {
      ResponseEntity<String> ans =
              new ResponseEntity<>("{\"code\": 401, \"msg\": \"some error!\"}", HttpStatus.UNAUTHORIZED);
      return ans;
  }
  
  @GetMapping("525")
  public String _525(HttpServletResponse response) {
      response.setStatus(525);
      return "{\"code\": 525, \"msg\": \"自定义错误码!\"}";
  }
}

首先来看一下自定义的525和标准的401 http code，直接通过RestTemplate访问的case

@Test
public void testCode() {
    RestTemplate restTemplate = new RestTemplate();
    HttpEntity<String> ans = restTemplate.getForEntity("http://127.0.0.1:8080/525", String.class);
    System.out.println(ans);

    ans = restTemplate.getForEntity("http://127.0.0.1:8080/401", String.class);
    System.out.println(ans);
}

从上面的输出结果也可以看出来，非标准http code不会抛异常（原因上面有分析），接下来看一下即便是标准的http code也不希望抛异常的case

@Test
public void testSend() {
    String url = "http://127.0.0.1:8080/401";
    RestTemplate restTemplate = new RestTemplate();
    restTemplate.setErrorHandler(new DefaultResponseErrorHandler(){
        @Override
        protected boolean hasError(HttpStatus statusCode) {
            return super.hasError(statusCode);
        }

        @Override
        public void handleError(ClientHttpResponse response) throws IOException {
        }
    });
    HttpEntity<String> ans = restTemplate.getForEntity(url, String.class);
    System.out.println(ans);
}

II. 其他

0. 项目

工程：https://github.com/liuyueyi/spring-boot-demo

2.11 - 11.自定义返回Http Code的n种姿势

虽然http的提供了一整套完整、定义明确的状态码，但实际的业务支持中，后端并不总会遵守这套规则，更多的是在返回结果中，加一个code字段来自定义业务状态，即便是后端5xx了，返回给前端的http code依然是200

那么如果我想遵守http的规范，不同的case返回不同的http code在Spring中可以做呢?

本文将介绍四种设置返回的HTTP CODE的方式

@ResponseStatus 注解方式
HttpServletResponse#sendError
HttpServletResponse#setStatus
ResponseEntity

I. 返回Http Code的n中姿势

0. 环境

进入正文之前，先创建一个SpringBoot项目，本文示例所有版本为 spring-boot.2.1.2.RELEASE

(需要测试的小伙伴，本机创建一个maven项目，在pom.xml文件中，拷贝下面的配置即可)

<parent>
    <groupId>org.springframework.boot</groupId>
    <artifactId>spring-boot-starter-parent</artifactId>
    <version>2.2.1.RELEASE</version>
    <relativePath/> <!-- lookup parent from repository -->
</parent>

<properties>
    <project.build.sourceEncoding>UTF-8</project.build.sourceEncoding>
    <project.reporting.outputEncoding>UTF-8</project.reporting.outputEncoding>
    <java.version>1.8</java.version>
</properties>

<dependencies>
    <dependency>
        <groupId>org.springframework.boot</groupId>
        <artifactId>spring-boot-starter-web</artifactId>
    </dependency>
</dependencies>

<build>
    <pluginManagement>
        <plugins>
            <plugin>
                <groupId>org.springframework.boot</groupId>
                <artifactId>spring-boot-maven-plugin</artifactId>
            </plugin>
        </plugins>
    </pluginManagement>
</build>
<repositories>
    <repository>
        <id>spring-snapshots</id>
        <name>Spring Snapshots</name>
        <url>https://repo.spring.io/libs-snapshot-local</url>
        <snapshots>
            <enabled>true</enabled>
        </snapshots>
    </repository>
    <repository>
        <id>spring-milestones</id>
        <name>Spring Milestones</name>
        <url>https://repo.spring.io/libs-milestone-local</url>
        <snapshots>
            <enabled>false</enabled>
        </snapshots>
    </repository>
    <repository>
        <id>spring-releases</id>
        <name>Spring Releases</name>
        <url>https://repo.spring.io/libs-release-local</url>
        <snapshots>
            <enabled>false</enabled>
        </snapshots>
    </repository>
</repositories>

下面所有的方法都放在ErrorCodeRest这个类中

@RestController
@RequestMapping(path = "code")
public class ErrorCodeRest {
}

1. ResponseStatus使用姿势

通过注解@ResponseStatus，来指定返回的http code, 一般来说，使用它有两种姿势，一个是直接加在方法上，一个是加在异常类上

a. 装饰方法

直接在方法上添加注解，并制定对应的code

/**
 * 注解方式，只支持标准http状态码
 *
 * @return
 */
@GetMapping("ano")
@ResponseStatus(code = HttpStatus.BAD_REQUEST, reason = "请求参数异常!")
public String ano() {
    return "{\"code\": 400, \"msg\": \"bad request!\"}";
}

实测一下，返回结果如下

➜  ~ curl 'http://127.0.0.1:8080/code/ano' -i
HTTP/1.1 400
Content-Type: application/json;charset=UTF-8
Transfer-Encoding: chunked
Date: Sun, 05 Jan 2020 01:29:04 GMT
Connection: close

{"timestamp":"2020-01-05T01:29:04.673+0000","status":400,"error":"Bad Request","message":"请求参数异常!","path":"/code/ano"}%

当我们发起请求时，返回的状态码为400，返回的数据为springboot默认的错误信息格式

虽然上面这种使用姿势可以设置http code，但是这种使用姿势有什么意义呢？

如果看过web系列教程中的：SpringBoot系列教程web篇之全局异常处理可能就会有一些映象，配合@ExceptionHandler来根据异常返回对应的状态码

一个推荐的使用姿势，下面表示当你的业务逻辑中出现数组越界时，返回500的状态码以及完整的堆栈信息

@ResponseBody
@ExceptionHandler(value = ArrayIndexOutOfBoundsException.class)
@ResponseStatus(HttpStatus.INTERNAL_SERVER_ERROR)
public String handleArrayIndexOutBounds(HttpServletRequest request, HttpServletResponse response,
        ArrayIndexOutOfBoundsException e) throws IOException {
    log.info("array index out conf!");
    return "aryIndexOutOfBounds: " + getThrowableStackInfo(e);
}

b. 装饰异常类

另外一种使用姿势就是直接装饰在异常类上，然后当你的业务代码中，抛出特定的异常类，返回的httpcode就会设置为注解中的值

/**
 * 异常类 + 注解方式，只支持标准http状态码
 *
 * @return
 */
@GetMapping("exception/500")
public String serverException() {
    throw new ServerException("内部异常哦");
}

@GetMapping("exception/400")
public String clientException() {
    throw new ClientException("客户端异常哦");
}

@ResponseStatus(code = HttpStatus.INTERNAL_SERVER_ERROR, reason = "服务器失联了，请到月球上呼叫试试~~")
public static class ServerException extends RuntimeException {
    public ServerException(String message) {
        super(message);
    }
}

@ResponseStatus(code = HttpStatus.BAD_REQUEST, reason = "老哥，你的请求有问题~~")
public static class ClientException extends RuntimeException {
    public ClientException(String message) {
        super(message);
    }
}

测试结果如下，在异常类上添加注解的方式，优点在于不需要配合@ExceptionHandler写额外的逻辑了；缺点则在于需要定义很多的自定义异常类型

➜  ~ curl 'http://127.0.0.1:8080/code/exception/400' -i
HTTP/1.1 400
Content-Type: application/json;charset=UTF-8
Transfer-Encoding: chunked
Date: Sun, 05 Jan 2020 01:37:07 GMT
Connection: close

{"timestamp":"2020-01-05T01:37:07.662+0000","status":400,"error":"Bad Request","message":"老哥，你的请求有问题~~","path":"/code/exception/400"}%

➜  ~ curl 'http://127.0.0.1:8080/code/exception/500' -i
HTTP/1.1 500
Content-Type: application/json;charset=UTF-8
Transfer-Encoding: chunked
Date: Sun, 05 Jan 2020 01:37:09 GMT
Connection: close

{"timestamp":"2020-01-05T01:37:09.389+0000","status":500,"error":"Internal Server Error","message":"服务器失联了，请到月球上呼叫试试~~","path":"/code/exception/500"}%

注意

ResponseStatus注解的使用姿势，只支持标准的Http Code（必须是枚举类org.springframework.http.HttpStatus）

2. ResponseEntity

这种使用姿势就比较简单了，方法的返回结果必须是ResponseEntity，下面给出两个实际的case

@GetMapping("401")
public ResponseEntity<String> _401() {
    return ResponseEntity.status(HttpStatus.UNAUTHORIZED).body("{\"code\": 401, \"msg\": \"未授权!\"}");
}

@GetMapping("451")
public ResponseEntity<String> _451() {
    return ResponseEntity.status(451).body("{\"code\": 451, \"msg\": \"自定义异常!\"}");
}

实测结果

➜  ~ curl 'http://127.0.0.1:8080/code/401' -i
HTTP/1.1 401
Content-Type: text/plain;charset=UTF-8
Content-Length: 34
Date: Sun, 05 Jan 2020 01:40:10 GMT

{"code": 401, "msg": "未授权!"}

➜  ~ curl 'http://127.0.0.1:8080/code/451' -i
HTTP/1.1 451
Content-Type: text/plain;charset=UTF-8
Content-Length: 40
Date: Sun, 05 Jan 2020 01:40:19 GMT

{"code": 451, "msg": "自定义异常!"}

从上面的使用实例上看，可以知道这种使用方式，不仅仅支持标准的http code，也支持自定义的code（如返回code 451)

3. HttpServletResponse

这种使用姿势则是直接操作HttpServletResponse对象，手动录入返回的结果

a. setStatus

/**
 * response.setStatus 支持自定义http code，并可以返回结果
 *
 * @param response
 * @return
 */
@GetMapping("525")
public String _525(HttpServletResponse response) {
    response.setStatus(525);
    return "{\"code\": 525, \"msg\": \"自定义错误码 525!\"}";
}

输出结果

➜  ~ curl 'http://127.0.0.1:8080/code/525' -i
HTTP/1.1 525
Content-Type: text/plain;charset=UTF-8
Content-Length: 47
Date: Sun, 05 Jan 2020 01:45:38 GMT

{"code": 525, "msg": "自定义错误码 525!"}%

使用方式比较简单，直接设置status即可，支持自定义的Http Code返回

b. sendError

使用这种姿势的时候需要注意一下，只支持标准的http code，而且response body中不会有你的业务返回数据，如

/**
 * send error 方式，只支持标准http状态码; 且不会带上返回的结果
 *
 * @param response
 * @return
 * @throws IOException
 */
@GetMapping("410")
public String _410(HttpServletResponse response) throws IOException {
    response.sendError(410, "send 410");
    return "{\"code\": 410, \"msg\": \"Gone 410!\"}";
}

@GetMapping("460")
public String _460(HttpServletResponse response) throws IOException {
    response.sendError(460, "send 460");
    return "{\"code\": 460, \"msg\": \"Gone 460!\"}";
}

输出结果

➜  ~ curl 'http://127.0.0.1:8080/code/410' -i
HTTP/1.1 410
Content-Type: application/json;charset=UTF-8
Transfer-Encoding: chunked
Date: Sun, 05 Jan 2020 01:47:52 GMT

{"timestamp":"2020-01-05T01:47:52.300+0000","status":410,"error":"Gone","message":"send 410","path":"/code/410"}% 

➜  ~ curl 'http://127.0.0.1:8080/code/460' -i
HTTP/1.1 500
Content-Type: application/json;charset=UTF-8
Transfer-Encoding: chunked
Date: Sun, 05 Jan 2020 01:47:54 GMT
Connection: close

{"timestamp":"2020-01-05T01:47:54.719+0000","status":460,"error":"Http Status 460","message":"send 460","path":"/code/460"}%

从上面的case也可以看出，当我们使用send error时，如果是标准的http code，会设置对响应头；如果是自定义的不被识别的code，那么返回的http code是500

4, 小结

上面介绍了几种常见的设置响应http code的姿势，下面小结一下使用时的注意事项

ResponseStatus

只支持标准的http code
装饰自定义异常类，使用时抛出对应的异常类，从而达到设置响应code的效果
- 缺点对非可控的异常类不可用
结合@ExceptionHandler，用来装饰方法

ResponseEntity

形如：

return ResponseEntity.status(451).body("{\"code\": 451, \"msg\": \"自定义异常!\"}");

我个人感觉是最强大的使用姿势，就是写起来没有那么简洁
支持自定义code，支持设置 response body

HttpServletResponse

setStatus: 设置响应code，支持自定义code，支持返回response body
sendError: 只支持标准的http code，如果传入自定义的code，返回的http code会是500

II. 其他

web系列博文

项目源码

2.12 - 12.异步请求知识点与使用姿势小结

在Servlet3.0就引入了异步请求的支持，但是在实际的业务开发中，可能用过这个特性的童鞋并不多？

本篇博文作为异步请求的扫盲和使用教程，将包含以下知识点

什么是异步请求，有什么特点，适用场景
四种使用姿势：
- AsyncContext方式
- Callable
- WebAsyncTask
- DeferredResult

I. 异步请求

异步对于我们而言，应该属于经常可以听到的词汇了，在实际的开发中多多少少都会用到，那么什么是异步请求呢

1. 异步请求描述

先介绍一下同步与异步：

一个正常调用，吭哧吭哧执行完毕之后直接返回，这个叫同步；

接收到调用，自己不干，新开一个线程来做，主线程自己则去干其他的事情，等后台线程吭哧吭哧的跑完之后，主线程再返回结果，这个就叫异步

异步请求：

我们这里讲到的异步请求，主要是针对web请求而言，后端响应请求的一种手段，同步/异步对于前端而言是无感知、无区别的

同步请求，后端接收到请求之后，直接在处理请求线程中，执行业务逻辑，并返回

来源于网络

异步请求，后端接收到请求之后，新开一个线程，来执行业务逻辑，释放请求线程，避免请求线程被大量耗时的请求沾满，导致服务不可用

来源于网络

2. 特点

通过上面两张图，可以知道异步请求的最主要特点

业务线程，处理请求逻辑
请求处理线程立即释放，通过回调处理线程返回结果

3. 场景分析

从特点出发，也可以很容易看出异步请求，更适用于耗时的请求，快速的释放请求处理线程，避免web容器的请求线程被打满，导致服务不可用

举一个稍微极端一点的例子，比如我以前做过的一个多媒体服务，提供图片、音视频的编辑，这些服务接口有同步返回结果的也有异步返回结果的；同步返回结果的接口有快有慢，大部分耗时可能<10ms，而有部分接口耗时则在几十甚至上百

这种场景下，耗时的接口就可以考虑用异步请求的方式来支持了，避免占用过多的请求处理线程，影响其他的服务

II. 使用姿势

接下来介绍四种异步请求的使用姿势，原理一致，只是使用的场景稍有不同

1. AsyncContext

在Servlet3.0+之后就支持了异步请求，第一种方式比较原始，相当于直接借助Servlet的规范来实现，当然下面的case并不是直接创建一个servlet，而是借助AsyncContext来实现

@RestController
@RequestMapping(path = "servlet")
public class ServletRest {

    @GetMapping(path = "get")
    public void get(HttpServletRequest request) {
        AsyncContext asyncContext = request.startAsync();
        asyncContext.addListener(new AsyncListener() {
            @Override
            public void onComplete(AsyncEvent asyncEvent) throws IOException {
                System.out.println("操作完成:" + Thread.currentThread().getName());
            }

            @Override
            public void onTimeout(AsyncEvent asyncEvent) throws IOException {
                System.out.println("超时返回!!!");
                asyncContext.getResponse().setCharacterEncoding("utf-8");
                asyncContext.getResponse().setContentType("text/html;charset=UTF-8");
                asyncContext.getResponse().getWriter().println("超时了！！！!");
            }

            @Override
            public void onError(AsyncEvent asyncEvent) throws IOException {
                System.out.println("出现了m某些异常");
                asyncEvent.getThrowable().printStackTrace();

                asyncContext.getResponse().setCharacterEncoding("utf-8");
                asyncContext.getResponse().setContentType("text/html;charset=UTF-8");
                asyncContext.getResponse().getWriter().println("出现了某些异常哦！！！!");
            }

            @Override
            public void onStartAsync(AsyncEvent asyncEvent) throws IOException {
                System.out.println("开始执行");
            }
        });

        asyncContext.setTimeout(3000L);
        asyncContext.start(new Runnable() {
            @Override
            public void run() {
                try {
                    Thread.sleep(Long.parseLong(request.getParameter("sleep")));
                    System.out.println("内部线程：" + Thread.currentThread().getName());
                    asyncContext.getResponse().setCharacterEncoding("utf-8");
                    asyncContext.getResponse().setContentType("text/html;charset=UTF-8");
                    asyncContext.getResponse().getWriter().println("异步返回!");
                    asyncContext.getResponse().getWriter().flush();
                    // 异步完成，释放
                    asyncContext.complete();
                } catch (Exception e) {
                    e.printStackTrace();
                }
            }
        });

        System.out.println("主线程over!!! " + Thread.currentThread().getName());
    }
}

完整的实现如上，简单的来看一下一般步骤

javax.servlet.ServletRequest#startAsync()获取AsyncContext
添加监听器 asyncContext.addListener(AsyncListener)（这个是可选的）
- 用户请求开始、超时、异常、完成时回调
设置超时时间 asyncContext.setTimeout(3000L) （可选）
异步任务asyncContext.start(Runnable)

2. Callable

相比较于上面的复杂的示例，SpringMVC可以非常easy的实现，直接返回一个Callable即可

@RestController
@RequestMapping(path = "call")
public class CallableRest {

    @GetMapping(path = "get")
    public Callable<String> get() {
        Callable<String> callable = new Callable<String>() {
            @Override
            public String call() throws Exception {
                System.out.println("do some thing");
                Thread.sleep(1000);
                System.out.println("执行完毕，返回!!!");
                return "over!";
            }
        };

        return callable;
    }


    @GetMapping(path = "exception")
    public Callable<String> exception() {
        Callable<String> callable = new Callable<String>() {
            @Override
            public String call() throws Exception {
                System.out.println("do some thing");
                Thread.sleep(1000);
                System.out.println("出现异常，返回!!!");
                throw new RuntimeException("some error!");
            }
        };

        return callable;
    }
}

请注意上面的两种case，一个正常返回，一个业务执行过程中，抛出来异常

分别请求，输出如下

# http://localhost:8080/call/get
do some thing
执行完毕，返回!!!

异常请求: http://localhost:8080/call/exception

do some thing
出现异常，返回!!!
2020-03-29 16:12:06.014 ERROR 24084 --- [nio-8080-exec-5] o.a.c.c.C.[.[.[/].[dispatcherServlet]    : Servlet.service() for servlet [dispatcherServlet] threw exception

java.lang.RuntimeException: some error!
	at com.git.hui.boot.async.rest.CallableRest$2.call(CallableRest.java:40) ~[classes/:na]
	at com.git.hui.boot.async.rest.CallableRest$2.call(CallableRest.java:34) ~[classes/:na]
	at org.springframework.web.context.request.async.WebAsyncManager.lambda$startCallableProcessing$4(WebAsyncManager.java:328) ~[spring-web-5.2.1.RELEASE.jar:5.2.1.RELEASE]
	at java.util.concurrent.Executors$RunnableAdapter.call(Executors.java:511) ~[na:1.8.0_171]
	at java.util.concurrent.FutureTask.run$$$capture(FutureTask.java:266) ~[na:1.8.0_171]
	at java.util.concurrent.FutureTask.run(FutureTask.java) ~[na:1.8.0_171]
	at java.util.concurrent.ThreadPoolExecutor.runWorker(ThreadPoolExecutor.java:1149) ~[na:1.8.0_171]
	at java.util.concurrent.ThreadPoolExecutor$Worker.run(ThreadPoolExecutor.java:624) ~[na:1.8.0_171]
	at java.lang.Thread.run(Thread.java:748) [na:1.8.0_171]

3. WebAsyncTask

callable的方式，非常直观简单，但是我们经常关注的超时+异常的处理却不太好，这个时候我们可以用WebAsyncTask，实现姿势也很简单，包装一下callable，然后设置各种回调事件即可

@RestController
@RequestMapping(path = "task")
public class WebAysncTaskRest {

    @GetMapping(path = "get")
    public WebAsyncTask<String> get(long sleep, boolean error) {
        Callable<String> callable = () -> {
            System.out.println("do some thing");
            Thread.sleep(sleep);

            if (error) {
                System.out.println("出现异常，返回!!!");
                throw new RuntimeException("异常了!!!");
            }

            return "hello world";
        };

        // 指定3s的超时
        WebAsyncTask<String> webTask = new WebAsyncTask<>(3000, callable);
        webTask.onCompletion(() -> System.out.println("over!!!"));

        webTask.onTimeout(() -> {
            System.out.println("超时了");
            return "超时返回!!!";
        });

        webTask.onError(() -> {
            System.out.println("出现异常了!!!");
            return "异常返回";
        });

        return webTask;
    }
}

4. DeferredResult

DeferredResult与WebAsyncTask最大的区别就是前者不确定什么时候会返回结果，

DeferredResult的这个特点，可以用来做实现很多有意思的东西，如后面将介绍的SseEmitter就用到了它

下面给出一个实例

@RestController
@RequestMapping(path = "defer")
public class DeferredResultRest {

    private Map<String, DeferredResult> cache = new ConcurrentHashMap<>();

    @GetMapping(path = "get")
    public DeferredResult<String> get(String id) {
        DeferredResult<String> res = new DeferredResult<>();
        cache.put(id, res);

        res.onCompletion(new Runnable() {
            @Override
            public void run() {
                System.out.println("over!");
            }
        });
        return res;
    }

    @GetMapping(path = "pub")
    public String publish(String id, String content) {
        DeferredResult<String> res = cache.get(id);
        if (res == null) {
            return "no consumer!";
        }

        res.setResult(content);
        return "over!";
    }
}

在上面的实例中，用户如果先访问http://localhost:8080/defer/get?id=yihuihui，不会立马有结果，直到用户再次访问http://localhost:8080/defer/pub?id=yihuihui&content=哈哈时，前面的请求才会有结果返回

那么这个可以设置超时么，如果一直把前端挂住，貌似也不太合适吧

在构造方法中指定超时时间: new DeferredResult<>(3000L)
设置全局的默认超时时间

@Configuration
@EnableWebMvc
public class WebConf implements WebMvcConfigurer {

    @Override
    public void configureAsyncSupport(AsyncSupportConfigurer configurer) {
        // 超时时间设置为60s
        configurer.setDefaultTimeout(TimeUnit.SECONDS.toMillis(10));
    }
}

II. 其他

0. 项目

相关博文

系列博文

源码

工程：https://github.com/liuyueyi/spring-boot-demo
项目源码: https://github.com/liuyueyi/spring-boot-demo/blob/master/spring-boot/219-web-asyn

2.13 - 13.SSE服务器发送事件详解

SSE全称Server Sent Event，直译一下就是服务器发送事件，一般的项目开发中，用到的机会不多，可能很多小伙伴不太清楚这个东西，到底是干啥的，有啥用

本文主要知识点如下：

SSE扫盲，应用场景分析
借助异步请求实现sse功能，加深概念理解
使用SseEmitter实现一个简单的推送示例

I. SSE扫盲

对于sse基础概念比较清楚的可以跳过本节

1. 概念介绍

sse(Server Sent Event)，直译为服务器发送事件，顾名思义，也就是客户端可以获取到服务器发送的事件

我们常见的http交互方式是客户端发起请求，服务端响应，然后一次请求完毕；但是在sse的场景下，客户端发起请求，连接一直保持，服务端有数据就可以返回数据给客户端，这个返回可以是多次间隔的方式

2. 特点分析

SSE最大的特点，可以简单规划为两个

长连接
服务端可以向客户端推送信息

了解websocket的小伙伴，可能也知道它也是长连接，可以推送信息，但是它们有一个明显的区别

sse是单通道，只能服务端向客户端发消息；而webscoket是双通道

那么为什么有了webscoket还要搞出一个sse呢？既然存在，必然有着它的优越之处

sse	websocket
http协议	独立的websocket协议
轻量，使用简单	相对复杂
默认支持断线重连	需要自己实现断线重连
文本传输	二进制传输
支持自定义发送的消息类型	-

3. 应用场景

从sse的特点出发，我们可以大致的判断出它的应用场景，需要轮询获取服务端最新数据的case下，多半是可以用它的

比如显示当前网站在线的实时人数，法币汇率显示当前实时汇率，电商大促的实时成交额等等…

II. 手动实现sse功能

sse本身是有自己的一套玩法的，后面会进行说明，这一小节，则主要针对sse的两个特点长连接 + 后端推送数据，如果让我们自己来实现这样的一个接口，可以怎么做？

1. 项目创建

借助SpringBoot 2.2.1.RELEASE来创建一个用于演示的工程项目，核心的xml依赖如下

<parent>
    <groupId>org.springframework.boot</groupId>
    <artifactId>spring-boot-starter-parent</artifactId>
    <version>2.2.1.RELEASE</version>
    <relativePath/> <!-- lookup parent from repository -->
</parent>

<properties>
    <project.build.sourceEncoding>UTF-8</project.build.sourceEncoding>
    <project.reporting.outputEncoding>UTF-8</project.reporting.outputEncoding>
    <java.version>1.8</java.version>
</properties>

<dependencies>
    <dependency>
        <groupId>org.springframework.boot</groupId>
        <artifactId>spring-boot-starter-web</artifactId>
    </dependency>
</dependencies>

<build>
    <pluginManagement>
        <plugins>
            <plugin>
                <groupId>org.springframework.boot</groupId>
                <artifactId>spring-boot-maven-plugin</artifactId>
            </plugin>
        </plugins>
    </pluginManagement>
</build>
<repositories>
    <repository>
        <id>spring-snapshots</id>
        <name>Spring Snapshots</name>
        <url>https://repo.spring.io/libs-snapshot-local</url>
        <snapshots>
            <enabled>true</enabled>
        </snapshots>
    </repository>
    <repository>
        <id>spring-milestones</id>
        <name>Spring Milestones</name>
        <url>https://repo.spring.io/libs-milestone-local</url>
        <snapshots>
            <enabled>false</enabled>
        </snapshots>
    </repository>
    <repository>
        <id>spring-releases</id>
        <name>Spring Releases</name>
        <url>https://repo.spring.io/libs-release-local</url>
        <snapshots>
            <enabled>false</enabled>
        </snapshots>
    </repository>
</repositories>

2. 功能实现

在Http1.1支持了长连接，请求头添加一个Connection: keep-alive即可

在这里我们借助异步请求来实现sse功能，至于什么是异步请求，推荐查看博文: 【WEB系列】异步请求知识点与使用姿势小结

因为后端可以不定时返回数据，所以我们需要注意的就是需要保持连接，不要返回一次数据之后就断开了；其次就是需要设置请求头Content-Type: text/event-stream;charset=UTF-8 （如果不是流的话会怎样？）

// 新建一个容器，保存连接，用于输出返回
private Map<String, PrintWriter> responseMap = new ConcurrentHashMap<>();

// 发送数据给客户端
private void writeData(String id, String msg, boolean over) throws IOException {
    PrintWriter writer = responseMap.get(id);
    if (writer == null) {
        return;
    }

    writer.println(msg);
    writer.flush();
    if (over) {
        responseMap.remove(id);
    }
}

// 推送
@ResponseBody
@GetMapping(path = "subscribe")
public WebAsyncTask<Void> subscribe(String id, HttpServletResponse response) {

    Callable<Void> callable = () -> {
        response.setHeader("Content-Type", "text/event-stream;charset=UTF-8");
        responseMap.put(id, response.getWriter());
        writeData(id, "订阅成功", false);
        while (true) {
            Thread.sleep(1000);
            if (!responseMap.containsKey(id)) {
                break;
            }
        }
        return null;
    };

    // 采用WebAsyncTask 返回 这样可以处理超时和错误 同时也可以指定使用的Excutor名称
    WebAsyncTask<Void> webAsyncTask = new WebAsyncTask<>(30000, callable);
    // 注意：onCompletion表示完成，不管你是否超时、是否抛出异常，这个函数都会执行的
    webAsyncTask.onCompletion(() -> System.out.println("程序[正常执行]完成的回调"));

    // 这两个返回的内容，最终都会放进response里面去===========
    webAsyncTask.onTimeout(() -> {
        responseMap.remove(id);
        System.out.println("超时了!!!");
        return null;
    });
    // 备注：这个是Spring5新增的
    webAsyncTask.onError(() -> {
        System.out.println("出现异常!!!");
        return null;
    });


    return webAsyncTask;
}

看一下上面的实现，基本上还是异步请求的那一套逻辑，请仔细看一下callable中的逻辑，有一个while循环，来保证长连接不中断

接下来我们新增两个接口，用来模拟后端给客户端发送消息，关闭连接的场景

@ResponseBody
@GetMapping(path = "push")
public String pushData(String id, String content) throws IOException {
    writeData(id, content, false);
    return "over!";
}

@ResponseBody
@GetMapping(path = "over")
public String over(String id) throws IOException {
    writeData(id, "over", true);
    return "over!";
}

我们简单的来演示下操作过程

III. SseEmitter

上面只是简单实现了sse的长连接 + 后端推送消息，但是与标准的SSE还是有区别的，sse有自己的规范，而我们上面的实现，实际上并没有管这个，导致的问题是前端按照sse的玩法来请求数据，可能并不能正常工作

1. sse规范

在html5的定义中，服务端sse，一般需要遵循以下要求

请求头

开启长连接 + 流方式传递

Content-Type: text/event-stream;charset=UTF-8
Cache-Control: no-cache
Connection: keep-alive

数据格式

服务端发送的消息，由message组成，其格式如下:

field:value\n\n

其中field有五种可能

空: 即以:开头，表示注释，可以理解为服务端向客户端发送的心跳，确保连接不中断
data：数据
event: 事件，默认值
id: 数据标识符用id字段表示，相当于每一条数据的编号
retry: 重连时间

2. 实现

SpringBoot利用SseEmitter来支持sse，可以说非常简单了，直接返回SseEmitter对象即可；重写一下上面的逻辑

@RestController
@RequestMapping(path = "sse")
public class SseRest {
    private static Map<String, SseEmitter> sseCache = new ConcurrentHashMap<>();
    @GetMapping(path = "subscribe")
    public SseEmitter push(String id) {
        // 超时时间设置为1小时
        SseEmitter sseEmitter = new SseEmitter(3600_000L);
        sseCache.put(id, sseEmitter);
        sseEmitter.onTimeout(() -> sseCache.remove(id));
        sseEmitter.onCompletion(() -> System.out.println("完成！！！"));
        return sseEmitter;
    }

    @GetMapping(path = "push")
    public String push(String id, String content) throws IOException {
        SseEmitter sseEmitter = sseCache.get(id);
        if (sseEmitter != null) {
            sseEmitter.send(content);
        }
        return "over";
    }

    @GetMapping(path = "over")
    public String over(String id) {
        SseEmitter sseEmitter = sseCache.get(id);
        if (sseEmitter != null) {
            sseEmitter.complete();
            sseCache.remove(id);
        }
        return "over";
    }
}

上面的实现，用到了SseEmitter的几个方法，解释如下

send(): 发送数据，如果传入的是一个非SseEventBuilder对象，那么传递参数会被封装到data中
complete(): 表示执行完毕，会断开连接
onTimeout(): 超时回调触发
onCompletion(): 结束之后的回调触发

同样演示一下访问请求

上图总的效果和前面的效果差不多，而且输出还待上了前缀，接下来我们写一个简单的html消费端，用来演示一下完整的sse的更多特性

<!doctype html>
<html lang="en">
<head>
    <title>Sse测试文档</title>
</head>
<body>
<div>sse测试</div>
<div id="result"></div>
</body>
</html>
<script>
    var source = new EventSource('http://localhost:8080/sse/subscribe?id=yihuihui');
    source.onmessage = function (event) {
        text = document.getElementById('result').innerText;
        text += '\n' + event.data;
        document.getElementById('result').innerText = text;
    };
    <!-- 添加一个开启回调 -->
    source.onopen = function (event) {
        text = document.getElementById('result').innerText;
        text += '\n 开启: ';
        console.log(event);
        document.getElementById('result').innerText = text;
    };
</script>

将上面的html文件放在项目的resources/static目录下；然后修改一下前面的SseRest

@Controller
@RequestMapping(path = "sse")
public class SseRest {
    @GetMapping(path = "")
    public String index() {
        return "index.html";
    }
    
    @ResponseBody
    @GetMapping(path = "subscribe", produces = {MediaType.TEXT_EVENT_STREAM_VALUE})
    public SseEmitter push(String id) {
        // 超时时间设置为3s，用于演示客户端自动重连
        SseEmitter sseEmitter = new SseEmitter(1_000L);
        // 设置前端的重试时间为1s
        sseEmitter.send(SseEmitter.event().reconnectTime(1000).data("连接成功"));
        sseCache.put(id, sseEmitter);
        System.out.println("add " + id);
        sseEmitter.onTimeout(() -> {
            System.out.println(id + "超时");
            sseCache.remove(id);
        });
        sseEmitter.onCompletion(() -> System.out.println("完成！！！"));
        return sseEmitter;
    }
}

我们上面超时时间设置的比较短，用来测试下客户端的自动重连，如下，开启的日志不断增加

其次将SseEmitter的超时时间设长一点，再试一下数据推送功能

请注意上面的演示，当后端结束了长连接之后，客户端会自动重新再次连接，不用写外的重试逻辑了，就这么神奇

3. 小结

本篇文章介绍了SSE的相关知识点，并对比websocket给出了sse的优点（至于啥优点请往上翻）

请注意，本文虽然介绍了两种sse的方式，第一种借助异步请求来实现，如果需要完成sse的规范要求，需要自己做一些适配，如果需要了解sse底层实现原理的话，可以参考一下；在实际的业务开发中，推荐使用SseEmitter

IV. 其他

0. 项目

系列博文

源码

工程：https://github.com/liuyueyi/spring-boot-demo
项目源码: https://github.com/liuyueyi/spring-boot-demo/blob/master/spring-boot/220-web-sse

2.14 - 14.thymeleaf foreach踩坑记录

话说自从前后端分离之后，前后端放在一起的场景就很少了，最近写个简单的后台，突然踩坑了，使用themeleaf模板渲染时，发现th:each来遍历生成表单数据，一直抛异常，提示Property or field 'xxx' cannot be found on null

接下来看一下这个问题到底是个什么情况

I. 项目搭建

1. 项目依赖

本项目借助SpringBoot 2.2.1.RELEASE + maven 3.5.3 + IDEA进行开发

开一个web服务用于测试

<dependencies>
    <!-- 邮件发送的核心依赖 -->
    <dependency>
        <groupId>org.springframework.boot</groupId>
        <artifactId>spring-boot-starter-web</artifactId>
    </dependency>
    <dependency>
        <groupId>org.springframework.boot</groupId>
        <artifactId>spring-boot-starter-thymeleaf</artifactId>
    </dependency>
</dependencies>

配置文件application.yml

server:
  port: 8080

spring:
  thymeleaf:
    mode: HTML
    encoding: UTF-8
    servlet:
      content-type: text/html
    cache: false

II. 问题复现与处理

1. 场景复现

一个最基础的demo，来演示一下问题

@Controller
public class IndexController {
  public Map<String, Object> newMap(String key, Object val, Object... kv) {
      Map<String, Object> map = new HashMap<>();
      map.put(key, val);
      for (int i = 0; i < kv.length; i += 2) {
          map.put(String.valueOf(kv[i]), kv[i + 1]);
      }
      return map;
  }

  @GetMapping(path = "list")
  public String list(Model model) {
      List<Map> list = new ArrayList<>();
      list.add(newMap("user", "yh", "name", "一灰"));
      list.add(newMap("user", "2h", "name", "2灰"));
      list.add(newMap("user", "3h", "name", "3灰"));
      model.addAttribute("list", list);
      return "list";
  }
}

对应的html文件如下(注意，放在资源目录 templates 下)

<!DOCTYPE html>
<html xmlns:th="http://www.thymeleaf.org">
<head>
    <meta charset="UTF-8">
</head>
<body>

<div>
    <div th:each="item: ${list}">
        <span th:text="${item.user}"></span>
        &nbsp;&nbsp;
        <span th:text="${item.name}"></span>
    </div>

    <hr/>

    <p th:each="item: ${list}">
        <p th:text="${item.user}"></p>
        &nbsp;&nbsp;
        <p th:text="${item.name}"></p>
    </p>
</div>
</body>
</html>

注意上面的模板，有两个each遍历，出现问题的是第二个

2. 原因说明

上面提示user没有，那么是否是语法问题呢？将html改成下面这个时

<!DOCTYPE html>
<html xmlns:th="http://www.thymeleaf.org">
<head>
    <meta charset="UTF-8">
</head>
<body>

<div>
    <div th:each="item: ${list}">
        <span th:text="${item.user}"></span>
        &nbsp;&nbsp;
        <span th:text="${item.name}"></span>
    </div>
</div>
</body>
</html>

相同的写法，上面这个就可以，经过多方尝试，发现出现问题的原因居然是<p>这个标签

简单来讲，就是<p>标签不能使用th:each，测试一下其他的标签之后发现<img>，<input>标签也不能用

那么问题来了，为啥这几个标签不能使用each呢？

这个原因可能就需要去瞅一下实现逻辑了，有知道的小伙伴可以科普一下

III. 不能错过的源码和相关知识点

0. 项目

工程：https://github.com/liuyueyi/spring-boot-demo
源码：https://github.com/liuyueyi/spring-boot-demo/tree/master/spring-boot/

1. 微信公众号: 一灰灰Blog

尽信书则不如，以上内容，纯属一家之言，因个人能力有限，难免有疏漏和错误之处，如发现bug或者有更好的建议，欢迎批评指正，不吝感激

下面一灰灰的个人博客，记录所有学习和工作中的博文，欢迎大家前去逛逛

一灰灰Blog个人博客 https://blog.hhui.top
一灰灰Blog-Spring专题博客 http://spring.hhui.top

一灰灰blog

2.15 - 15.如何支持下划线驼峰互转的传参与返回

SpringBoot系列之Web如何支持下划线驼峰互转的传参与返回

接下来介绍一个非常现实的应用场景，有些时候后端接口对外定义的传参/返回都是下划线命名风格，但是Java本身是推荐驼峰命名方式的，那么必然就存在一个传参下换线，转换成驼峰的场景；以及在返回时，将驼峰命名的转换成下划线

那么如何支持上面这种应用场景呢?

本文介绍几种常见的手段

I. 项目搭建

1. 项目依赖

本项目借助SpringBoot 2.2.1.RELEASE + maven 3.5.3 + IDEA进行开发

开一个web服务用于测试

<dependencies>
    <!-- 邮件发送的核心依赖 -->
    <dependency>
        <groupId>org.springframework.boot</groupId>
        <artifactId>spring-boot-starter-web</artifactId>
    </dependency>
</dependencies>

配置文件application.yml

server:
  port: 8080

2. 需求拆分

接下来为了更方便的理解我们要做的事情，对上面的应用场景进行一些拆分，方便理解

2.1 请求参数解析

对于请求参数，外部传递是下划线命名格式的方式，需要与项目中驼峰命名的对象进行映射，所以这里的问题点就是无法走默认的绑定规则，需要我们进行兼容处理

比如传参是 user_name = 一灰灰，但是我们接收的参数是 userName

2.2 返回结果处理

返回结果的处理，这里单指返回json对象的场景，一个普通的POJO对象，正常序列化为json字符串时，key实际上与对象的成员名是一致的，而现在则希望将key统一成下划线风格的方式

如，返回一个简单的实体对象

public class ViewDo {
  private Integer userId;
  private string userName;
}

对应期待返回的json串为

{
  "user_name" : "一灰灰",
  "user_id" : 110
}

II. 支持方式

为了简化后续的流程，我们这里的传参都确定两个userName + userId，对应项目中的实体类如

@Data
@NoArgsConstructor
@AllArgsConstructor
public static class ViewDo {

    private Integer userId;

    private String userName;
}

1. 请求参数解析

1.1 @RequestParam注解方式

最简单也是最容易想到的方式自然是直接使用RequestParam注解，将所有的请求参数都通过它来重命名

@GetMapping(path = "getV3")
public ViewDo getV3(@RequestParam("user_id") Integer userId, @RequestParam("user_name") String userName) {
    String str = "userId: " + userId + " userName: " + userName;
    System.out.println(str);
    return new ViewDo(userId, userName);
}

使用上面直接来写参数映射关系的方式属于比较常见的方法了，但是存在一个问题

通用性差（每个接口的每个参数都要这么整，如果工资是按照代码来付费的话，那还是可以接收的；否则这个写法，就真的有点难受了）
若接口参数定义的是Map、Java bean实体（POJO），这个映射关联就不太好处理了

除了上面这个问题之外，有个不是问题的问题（为什么这么说，且看下面的说法）

如果我的接口传参，希望同时接收驼峰和下划线命名的传参（现实中还真有这种神经病似的场景，别问我怎么知道的），上面这个是不行的

1.2 Json传参指定命名策略

上面的case，适用于常见的get请求，post表单传参，然后在接口处一一定义参数；对于post json传参时，我们可以考虑通过定义json序列化的命名策略，来支持下划线与驼峰的互转

比如SpringMVC默认使用的jackson来实现json序列化，那么我们可以直接通过指定jackson的PropertyNamingStrategy来完成

配置文件中 application.yml，添加下面这行

spring:
  jackson:
    # 使用jackson进行json序列化时，可以将下划线的传参设置给驼峰的非简单对象成员上；并返回下划线格式的json串
    # 特别注意。使用这种方式的时候，要求不能有自定义的WebMvcConfigurationSupport，因为会覆盖默认的处理方式
    # 解决办法就是 拿到ObjectMapper的bean对象，手动塞入进去
    property-naming-strategy: SNAKE_CASE

对应的接口定义如下

/**
 * post json串
 *  curl 'http://127.0.0.1:8080/postV2' -X POST -H 'content-type:application/json' -d '{"user_id": 123, "user_name": "一灰灰"}'
 * @param viewDo
 * @return
 */
@PostMapping(path = "postV2")
public ViewDo postV2(@RequestBody ViewDo viewDo) {
    System.out.println(viewDo);
    return viewDo;
}

实际请求之后，看一下效果

注意

使用上面这种配置的方式，需要特比注意的，如果在项目中自己定义了WebMvcConfigurationSupport，那么上面的配置将不会生效（至于具体的原因，后面有机会单独说明）

当我们实际的项目中，无法直接使用上面这种配置时，可以考虑使用下面的方式

@SpringBootApplication
public class Application  extends WebMvcConfigurationSupport {
    /**
     * 下面这个设置，可以实现json参数解析/返回时，传入的下划线转驼峰；输出的驼峰转下划线
     * @param converters
     */
    @Override
    protected void extendMessageConverters(List<HttpMessageConverter<?>> converters) {
        MappingJackson2HttpMessageConverter converter = new MappingJackson2HttpMessageConverter();
        ObjectMapper objectMapper = converter.getObjectMapper();

        // 设置驼峰标志转下划线
        objectMapper.setPropertyNamingStrategy(PropertyNamingStrategy.SNAKE_CASE);

        // 设置格式化内容
        converter.setObjectMapper(objectMapper);
        converters.add(0, converter);
        super.extendMessageConverters(converters);
    }
}

使用jackson的命名策略来支持驼峰下划线的转换虽好，但是存在一个非常明显的缺陷

它只适用于json传参

1.3 自定义DataBinder

对于非json的传承，比如普通的get请求，post表单传参，然后在接口处通过定义一个POJO参数类来接收，此时又应该怎么处理呢?

比如接口定义如下

/**
 * POJO 对应Spring中的参数转换是 ServletModelAttributeMethodProcessor | RequestParamMethodArgumentResolver
 * @param viewDo
 * @return
 */
@GetMapping(path = "getV5")
public ViewDo getV5(ViewDo viewDo) {
    System.out.println("v5: " + viewDo);
    return viewDo;
}


/**
 *  curl 'http://127.0.0.1:8080/postV1' -X POST -d 'user_id=123&user_name=一灰灰'
 *  注意：非json传参，jackson的配置将不会生效，即上面这个请求是不会实现下划线转驼峰的； 但是返回结果会是下划线的
 * @param viewDo
 * @return
 */
@PostMapping(path = "postV1")
public ViewDo post(ViewDo viewDo) {
    System.out.println(viewDo);
    return viewDo;
}

对于上面这种场景，一个想法就是是否可以在ViewDo的成员上，添加一个注解，指定参数名，一如RequestParam，不过Spring貌似并没有提供这种支持能力

因此我们可以考虑自己来实现数据绑定，下面提供一个基础的实现, 来演示这种方式改怎么玩（相对完整的基于注解的映射方式，下篇博文介绍）

public class SimpleDataBinder extends ExtendedServletRequestDataBinder {

    public SimpleDataBinder(Object target, String objectName) {
        super(target, objectName);
    }

    @Override
    protected void addBindValues(MutablePropertyValues mpvs, ServletRequest request) {
        super.addBindValues(mpvs, request);
        if (!mpvs.contains("userName")) {
            mpvs.add("userName", getVal(mpvs, "user_name"));
        }
        if (!mpvs.contains("userId")) {
            mpvs.add("userId", getVal(mpvs, "user_id"));
        }
    }

    private Object getVal(MutablePropertyValues mpvs, String key) {
        PropertyValue pv = mpvs.getPropertyValue(key);
        return pv != null ? pv.getValue() : null;
    }
}

然后在参数解析中，使用这个DataBinder

public class SimpleArgumentProcessor extends ServletModelAttributeMethodProcessor {
    public SimpleArgumentProcessor(boolean annotationNotRequired) {
        super(annotationNotRequired);
    }

    @Override
    protected void bindRequestParameters(WebDataBinder binder, NativeWebRequest nativeWebRequest) {
        Object target = binder.getTarget();
        SimpleDataBinder dataBinder = new SimpleDataBinder(target, binder.getObjectName());
        super.bindRequestParameters(dataBinder, nativeWebRequest);
    }
}

接着就是注册这个参数解析

@SpringBootApplication
public class Application  extends WebMvcConfigurationSupport {
    @Override
    protected void addArgumentResolvers(List<HandlerMethodArgumentResolver> argumentResolvers) {
        argumentResolvers.add(new SimpleArgumentProcessor(true));
    }
}

再次请求时，可以发现下划线的传参也可以映射到ViewDo对象上(无论是get请求还是post请求，都可以正确映射)

2.返回结果

对于返回结果，希望返回下划线格式的json串，除了上面介绍到的设置json序列化的命名策略之外，还有下面几种配置方式

2.1 属性注解 @JsonProperty

直接在POJO对象的成员上，指定希望输出的name

public static class ViewDo {
    @JsonProperty("user_id")
    private Integer userId;
    @JsonProperty("user_name")
    private String userName;
}

2.2 实体类注解 @JsonNaming

直接在类上添加注解，指定驼峰策略

@JsonNaming(value = PropertyNamingStrategy.SnakeCaseStrategy.class)
public static class ViewDo {
    private Integer userId;
    private String userName;
}

2.3 全局配置

上面两种缺点比较明显，不太通用；更通用的选择和前面传参的json序列化配置方式一样，两种姿势

配置文件指定

spring:
  jackson:
    # 使用jackson进行json序列化时，可以将下划线的传参设置给驼峰的非简单对象成员上；并返回下划线格式的json串
    # 特别注意。使用这种方式的时候，要求不能有自定义的WebMvcConfigurationSupport，因为会覆盖默认的处理方式
    # 解决办法就是 拿到ObjectMapper的bean对象，手动塞入进去
    property-naming-strategy: SNAKE_CASE

前面也说到，上面这种配置可能会失效（比如你设置了自己的WebMvcConfig)，推荐使用下面的方式

public class Application  extends WebMvcConfigurationSupport {
    /**
     * 下面这个设置，可以实现json参数解析/返回时，传入的下划线转驼峰；输出的驼峰转下划线
     * @param converters
     */
    @Override
    protected void extendMessageConverters(List<HttpMessageConverter<?>> converters) {
        MappingJackson2HttpMessageConverter converter = new MappingJackson2HttpMessageConverter();
        ObjectMapper objectMapper = converter.getObjectMapper();

        // 设置驼峰标志转下划线
        objectMapper.setPropertyNamingStrategy(PropertyNamingStrategy.SNAKE_CASE);

        // 设置格式化内容
        converter.setObjectMapper(objectMapper);
        converters.add(0, converter);
        super.extendMessageConverters(converters);
    }
}

3. 小结

本文主要介绍了几种实例case，用于实现传参/返回的驼峰与下划线的互转，核心策略，有下面几种

传参：@RequestParam 指定真正的传参name
Json传参、返回：通过定义json序列化框架的PropertyNamingStrategy，来实现
普通表单传参/get传参，映射POJO时：通过自定义的DataBinder，来实现映射

虽然上面几种姿势，可以满足我们的基本诉求，但是如果我希望实现一个通用的下划线/驼峰互转策略，即不管传参是下划线还是驼峰，都可以正确无误的绑定到接口的参数变量上，可以怎么实现呢？

最后再抛出一个问题，如果接收参数是Map，上面的几种实现姿势会生效么？又可以如何怎么处理map这种场景呢？

III. 不能错过的源码和相关知识点

0. 项目

1. 微信公众号: 一灰灰Blog

尽信书则不如，以上内容，纯属一家之言，因个人能力有限，难免有疏漏和错误之处，如发现bug或者有更好的建议，欢迎批评指正，不吝感激

下面一灰灰的个人博客，记录所有学习和工作中的博文，欢迎大家前去逛逛

一灰灰Blog个人博客 https://blog.hhui.top
一灰灰Blog-Spring专题博客 http://spring.hhui.top

一灰灰blog

2.16 - 16.定义接口返回类型的几种方式

实现一个web接口返回json数据，基本上是每一个javaer非常熟悉的事情了；那么问题来了，如果我有一个接口，除了希望返回json格式的数据之外，若也希望可以返回xml格式数据可行么？

答案当然是可行的，接下来我们将介绍一下，一个接口的返回数据类型，可以怎么处理

I. 项目搭建

本文创建的实例工程采用SpringBoot 2.2.1.RELEASE + maven 3.5.3 + idea进行开发

1. pom依赖

具体的SpringBoot项目工程创建就不赘述了，对于pom文件中，需要重点关注下面两个依赖类

<dependencies>
    <dependency>
        <groupId>org.springframework.boot</groupId>
        <artifactId>spring-boot-starter-web</artifactId>
    </dependency>
    <dependency>
        <groupId>com.fasterxml.jackson.dataformat</groupId>
        <artifactId>jackson-dataformat-xml</artifactId>
    </dependency>
</dependencies>

注意 jackson-datafromat-xml这个依赖，加上这个主要时为了支持返回xml格式的数据

II. 返回类型设置的多种方式

正常来讲，一个RestController的接口，默认返回的是Json格式数据，当我们引入了上面的xml包之后，会怎样呢？返回的还是json么？

1.通过produce设置返回类型

如果一个接口希望返回json或者xml格式的数据，最容易想到的方式就是直接设置RequestMapping注解中的produce属性

这个值主要就是用来设置这个接口响应头中的content-type；如我们现在有两个接口，一个指定返回json格式数据，一个指定返回xml格式数据，可以如下写

@RestController
public class IndexRest {

    @Data
    public static class ResVo<T> {
        private int code;
        private String msg;
        private T data;

        public ResVo(int code, String msg, T data) {
            this.code = code;
            this.msg = msg;
            this.data = data;
        }
    }
    @GetMapping(path = "/xml", produces = {MediaType.APPLICATION_XML_VALUE})
    public ResVo<String> xml() {
        return new ResVo<>(0, "ok", "返回xml");
    }

    @GetMapping(path = "/json", produces = {MediaType.APPLICATION_JSON_VALUE})
    public ResVo<String> json() {
        return new ResVo<>(0, "ok", "返回json");
    }
}

上面的实现中

xml接口，指定produces = application/xml
json接口，指定produces = applicatin/json

接下来我们访问一下看看返回的是否和预期一致

从上面截图也可以看出，xml接口返回的是xml格式数据；json接口返回的是json格式数据

2. 通过请求头accept设置返回类型

上面的方式，非常直观，自然我们就会有一个疑问，当接口上不指定produces属性时，直接访问会怎么表现呢？

@GetMapping(path = "/")
public ResVo<String> index() {
    return new ResVo<>(0, "ok", "简单的测试");
}

请注意上面的截图，两种访问方式返回的数据类型不一致

curl请求：返回json格式数据
浏览器请求：返回 application/xhtml+xml响应头的数据（实际上还是xml格式）

那么问题来了，为什么两者的表现形式不一致呢？

对着上面的图再看三秒，会发现主要的差别点就在于请求头Accept不同；我们可以通过这个请求头参数，来要求服务端返回我希望的数据类型

如指定返回json格式数据

curl 'http://127.0.0.1:8080' -H 'Accept:application/xml' -iv

curl 'http://127.0.0.1:8080' -H 'Accept:application/json' -iv

从上面的执行结果也可以看出，返回的类型与预期的一致；

说明

请求头可以设置多种MediaType，用英文逗号分割，后端接口会根据自己定义的produce与请求头希望的mediaType取交集，至于最终选择的顺序则以accept中出现的顺序为准

看一下实际的表现来验证下上面的说法

通过请求头来控制返回数据类型的方式可以说是非常经典的策略了，（遵循html协议还有什么好说的呢！）

3. 请求参数来控制返回类型

除了上面介绍的两种方式之外，还可以考虑为所有的接口，增加一个根据特定的请求参数来控制返回的类型的方式

比如我们现在定义，所有的接口可以选传一个参数 mediaType，如果值为xml，则返回xml格式数据；如果值为json，则返回json格式数据

当不传时，默认返回json格式数据

基于此，我们主要借助mvc配置中的内容协商ContentNegotiationConfigurer来实现

@SpringBootApplication
public class Application implements WebMvcConfigurer {
    @Override
    public void configureContentNegotiation(ContentNegotiationConfigurer configurer) {
        configurer.favorParameter(true)
                // 禁用accept协商方式，即不关心前端传的accept值
//                .ignoreAcceptHeader(true)
                // 哪个放在前面，哪个的优先级就高； 当上面这个accept未禁用时，若请求传的accept不能覆盖下面两种，则会出现406错误
                .defaultContentType(MediaType.APPLICATION_JSON, MediaType.APPLICATION_XML)
                // 根据传参mediaType来决定返回样式
                .parameterName("mediaType")
                // 当acceptHeader未禁用时，accept的值与mediaType传参的值不一致时，以mediaType的传值为准
                // mediaType值可以不传，为空也行，但是不能是json/xml之外的其他值
                .mediaType("json", MediaType.APPLICATION_JSON)
                .mediaType("xml", MediaType.APPLICATION_XML);
    }

    public static void main(String[] args) {
        SpringApplication.run(Application.class);
    }
}

上面的实现中，添加了很多注释，先别急；我来逐一进行说明

.parameterName("mediaType")
// 当acceptHeader未禁用时，accept的值与mediaType传参的值不一致时，以mediaType的传值为准
// mediaType值可以不传，为空也行，但是不能是json/xml之外的其他值
.mediaType("json", MediaType.APPLICATION_JSON)
.mediaType("xml", MediaType.APPLICATION_XML);

上面这三行代码，主要就是说，现在可以根据传参 mediaType 来控制返回的类型，我们新增一个接口来验证一下

@GetMapping(path = "param")
public ResVo<String> params(@RequestParam(name = "mediaType", required = false) String mediaType) {
    return new ResVo<>(0, "ok", String.format("基于传参来决定返回类型：%s", mediaType));
}

我们来看下几个不同的传参表现

# 返回json格式数据
curl 'http://127.0.0.1:8080/param?mediaType=json' -iv
# 返回xml格式数据
curl 'http://127.0.0.1:8080/param?mediaType=xml' -iv
# 406错误
curl 'http://127.0.0.1:8080/param?mediaType=text' -iv
# 走默认的返回类型，json在前，所以返回json格式数据（如果将xml调整到前面，则返回xml格式数据，主要取决于 `.defaultContentType(MediaType.APPLICATION_JSON, MediaType.APPLICATION_XML)`）
curl 'http://127.0.0.1:8080/param' -iv

疑问：若请求头中传递了Accept或者接口上定义了produce，会怎样?

当指定了accept时，并且传参中指定了mediaType，则以传参为准

如accept: application/json,application.xml，此时mediaType=json, 返回json格式
如accept: application/json, 此时 mediaTyep=xml，返回xml格式
如accept: text/html，此时mediaType=xml ，此时返回的也是xml格式
如accept: text/html，此时mediaType不传时，因为无法处理text/html类型，所以会出现406
如accept: application/xml，但是mediaType不传，虽然默认优先是json，此时返回的也是xml格式，与请求头希望的保持一致

但是若传参与produce冲突了，那么就直接406异常，不会选择mediaType设置的类型

如produce = applicatin/json，但是 mediaType=xml，此时就会喜提406

细心的小伙伴可能发现了上面的配置中，注释了一行 .ignoreAcceptHeader(true)，当我们把它打开之后，前面说的Accept请求头可以随意传，我们完全不care，当做没有传这个参数进行处理即可开

4.小结

本文介绍了三种方式，控制接口返回数据类型

方式一

接口上定义produce, 如 @GetMapping(path = "p2", produces = {"application/xml", "application/json"})

注意produces属性值是有序的，即先定义的优先级更高；当一个请求可以同时接受xml/json格式数据时，上面这个定义会确保这个接口现有返回xml格式数据

方式二

借助标准的请求头accept，控制希望返回的数据类型；但是需要注意的时，使用这种方式时，要求后端不能设置ContentNegotiationConfigurer.ignoreAcceptHeader(true)

在实际使用这种方式的时候，客户端需要额外注意，Accept请求头中定义的MediaType的顺序，是优于后端定义的produces顺序的，因此用户需要将自己实际希望接受的数据类型放在前面，或者干脆就只设置一个

方式三

借助ContentNegotiationConfigurer实现通过请求参数来决定返回类型，常见的配置方式形如

configurer.favorParameter(true)
        // 禁用accept协商方式，即不关心前端传的accept值
      //                .ignoreAcceptHeader(true)
        // 哪个放在前面，哪个的优先级就高； 当上面这个accept未禁用时，若请求传的accept不能覆盖下面两种，则会出现406错误
        .defaultContentType(MediaType.APPLICATION_JSON, MediaType.APPLICATION_XML)
        // 根据传参mediaType来决定返回样式
        .parameterName("mediaType")
        // 当acceptHeader未禁用时，accept的值与mediaType传参的值不一致时，以mediaType的传值为准
        // mediaType值可以不传，为空也行，但是不能是json/xml之外的其他值
        .mediaType("json", MediaType.APPLICATION_JSON)
        .mediaType("xml", MediaType.APPLICATION_XML);

即添加这个设置之后，最终的表现为：

请求参数指定的返回类型，优先级最高，返回指定参数对应的类型
没有指定参数时，选择defaultContentType定义的默认返回类型与接口 produce中支持的求交集，优先级则按照defaultContentType中定义的顺序来选择
没有指定参数时，若此时还有accept请求头，则请求头中定义顺序的优先级高于 defaultContentType，高于 produce

注意注意：当配置中忽略了AcceptHeader时，.ignoreAcceptHeader(true)，上面第三条作废

最后的最后，本文所有的源码可以再下面的git中获取；本文的知识点已经汇总在《一灰灰的Spring专栏》两百多篇的原创系列博文，你值得拥有；我是一灰灰，咱们下次再见

III. 不能错过的源码和相关知识点

0. 项目

3 - RestTemplate

天天与网络打交道，那么你知道Spring中哪个工具类是最好用的么？没错就是RestTemplate，系列文章教你用好这个利器，解决网络资源访问的难点

3.1 - 1.基础用法小结

在Spring项目中，通常会借助RestTemplate来实现网络请求，RestTemplate封装得很完善了，基本上可以非常简单的完成各种HTTP请求，本文主要介绍一下基本操作，最常见的GET/POST请求的使用姿势

I. 项目搭建

1. 配置

借助SpringBoot搭建一个SpringWEB项目，提供一些用于测试的REST服务

SpringBoot版本: 2.2.1.RELEASE
核心依赖: spring-boot-stater-web

<dependencies>
    <dependency>
        <groupId>org.springframework.boot</groupId>
        <artifactId>spring-boot-starter-web</artifactId>
    </dependency>
</dependencies>

为了后续输出的日志更直观，这里设置了一下日志输出格式，在配置文件application.yml中，添加

logging:
  pattern:
    console: (%msg%n%n){blue}

2. Rest服务

添加三个接口，分别提供GET请求，POST表单，POST json对象，然后返回请求头、请求参数、cookie，具体实现逻辑相对简单，也不属于本篇重点，因此不赘述说明

@RestController
public class DemoRest {


    private String getHeaders(HttpServletRequest request) {
        Enumeration<String> headerNames = request.getHeaderNames();
        String name;

        JSONObject headers = new JSONObject();
        while (headerNames.hasMoreElements()) {
            name = headerNames.nextElement();
            headers.put(name, request.getHeader(name));
        }
        return headers.toJSONString();
    }

    private String getParams(HttpServletRequest request) {
        return JSONObject.toJSONString(request.getParameterMap());
    }

    private String getCookies(HttpServletRequest request) {
        Cookie[] cookies = request.getCookies();
        if (cookies == null || cookies.length == 0) {
            return "";
        }

        JSONObject ck = new JSONObject();
        for (Cookie cookie : cookies) {
            ck.put(cookie.getName(), cookie.getValue());
        }
        return ck.toJSONString();
    }

    private String buildResult(HttpServletRequest request) {
        return buildResult(request, null);
    }

    private String buildResult(HttpServletRequest request, Object obj) {
        String params = getParams(request);
        String headers = getHeaders(request);
        String cookies = getCookies(request);

        if (obj != null) {
            params += " | " + obj;
        }

        return "params: " + params + "\nheaders: " + headers + "\ncookies: " + cookies;
    }

    @GetMapping(path = "get")
    public String get(HttpServletRequest request) {
        return buildResult(request);
    }


    @PostMapping(path = "post")
    public String post(HttpServletRequest request) {
        return buildResult(request);
    }

    @Data
    @NoArgsConstructor
    public static class ReqBody implements Serializable {
        private static final long serialVersionUID = -4536744669004135021L;
        private String name;
        private Integer age;
    }

    @PostMapping(path = "body")
    public String postBody(@RequestBody ReqBody body) {
        HttpServletRequest request =
                ((ServletRequestAttributes) RequestContextHolder.getRequestAttributes()).getRequest();
        return buildResult(request, body);
    }
}

II. RestTemplate示例

1. Get请求

使用RestTemplate发起GET请求，通常有两种常见的方式

getForEntity: 返回的正文对象包装在HttpEntity实体中，适用于获取除了返回的正文之外，对返回头、状态码有需求的场景
getForObject: 返回正文，适用于只对正文感兴趣的场景

上面这两种方法除了返回结果不同之外，其他的使用姿势基本一样，有三种

@Nullable
public <T> T getForObject(String url, Class<T> responseType, Object... uriVariables) throws RestClientException;

@Nullable
public <T> T getForObject(String url, Class<T> responseType, Map<String, ?> uriVariables) throws RestClientException;

@Nullable
public <T> T getForObject(URI url, Class<T> responseType) throws RestClientException;

上面三个重载方法，区别仅在于GET参数如何处理，下面给出一个实例进行说明

/**
 * 基本的get请求
 */
public void basicGet() {
    RestTemplate restTemplate = new RestTemplate();

    HttpEntity<String> res =
            restTemplate.getForEntity("http://127.0.0.1:8080/get?name=一灰灰Blog&age=20", String.class);
    res.get
    log.info("Simple getForEntity res: {}", res);

    // 直接在url中拼参数，调用的是前面对应的方法1; 当然这里也可以将url转成URI格式，这样调用的是方法3
    String response = restTemplate.getForObject("http://127.0.0.1:8080/get?name=一灰灰Blog&age=20", String.class);
    log.info("Simple getForObject res: {}", response);

    // 通过可变参数，填充url参数中的{?}, 注意顺序是对应的
    response = restTemplate.getForObject("http://127.0.0.1:8080/get?name={?}&age={?}", String.class, "一灰灰Blog", 20);
    log.info("Simple getForObject by uri params: {}", respons