ContiNew

切换日光/暗黑模式

web（Web 模块） ​

最后更新: 16 小时前
实践版本: v2.12.2

简介 ​

continew-starter-web 是 ContiNew Starter 库的 Web 模块，也是快速创建一个 Spring Boot Web 应用的可靠基石。

xml
<dependency>
    <groupId>top.continew</groupId>
    <artifactId>continew-starter-web</artifactId>
</dependency>

主要特性 ​

  • 版本锁定：涉及依赖已进行版本锁定，使用时无需配置版本
  • 跨域配置：通过配置文件配置跨域过滤器（CorsFilter）
  • 统一响应处理：统一返回结果、异常处理、错误码填充（基于 Graceful Response）
  • Query 参数转换器：Date、LocalDate、LocalTime、LocalDateTime、BaseEnum 类型参数自动转换
  • 调整 Tomcat 为 Undertow 服务器，并支持扩展配置：支持全局禁用请求方式

跨域配置 ​

前后端 Web 应用开发，跨域肯定是避不开的配置。

配置详情请查看：top.continew.starter.web.autoconfigure.cors.CorsProperties。

yaml
--- ### 跨域配置
continew-starter.web:
  cors:
    enabled: true
    # 配置允许跨域的域名
    allowed-origins: '*'
    # 配置允许跨域的请求方式
    allowed-methods: '*'
    # 配置允许跨域的请求头
    allowed-headers: '*'
    # 配置允许跨域的响应头
    exposed-headers: '*'

统一响应处理 ​

使用 Graceful Response 组件实现统一响应处理解决方案。

Graceful Response 是一个 Spring Boot 技术栈下的优雅响应处理组件，可以帮助开发者完成响应数据封装、异常处理、错误码填充等过程，提高开发效率，提高代码质量。

本模块仅仅对该组件做了一些简单处理，如：覆盖自动配置、指定配置默认值、自定义响应风格类、添加接口文档全局处理，所以详细文档你可以查阅 Graceful Response 文档（见参考资料链接）。

启用统一响应处理 ​

本模块覆盖了 Graceful Response 的自动配置，所以需要使用本模块的注解启用统一响应处理。原组件注解为：@EnableGracefulResponse。

java
@EnableGlobalResponse
@SpringBootApplication
public class ExampleApplication {
    public static void main(String[] args) {
        SpringApplication.run(ExampleApplication.class, args);
    }
}

全局配置 ​

配置详情请查看：top.continew.starter.web.autoconfigure.response.GlobalResponseProperties。原组件配置前缀为：graceful-response。

其实，我们已经做了一些默认配置，详情请查看：continew-starter-web/src/main/resources/default-web.yml，日常使用下方这些配置就够调整了。

yaml
--- ### 全局响应配置
continew-starter.web:
  response:
    # 是否开启国际化（默认：false）
    i18n: false
    # 自定义失败 HTTP 状态码（默认：200，建议业务和通信状态码区分）
    default-http-status-code-on-error: 200
    # 自定义成功响应码（默认：0）
    default-success-code: 0
    # 自定义成功提示（默认：ok）
    default-success-msg: ok
    # 自定义失败响应码（默认：1）
    default-error-code: 1
    # 自定义失败提示（默认：error）
    default-error-msg: error
    # 是否将原生异常错误信息填充到状态信息中
    origin-exception-using-detail-message: false
    # 响应类全名（配置后 response-style 将不再生效）
    response-class-full-name: top.continew.starter.web.model.R

自定义响应类 ​

我们已经定义了一套 top.continew.starter.web.model.R 统一结构，Graceful Response 也提供了两套风格，如果他们都不能满足你的要求。

你可以通过参考 top.continew.starter.web.model.R 来自定义响应类，并替换 response-class-full-name 配置值即可。

排除统一封装 ​

默认情况下，统一响应处理会包装原始响应数据，将原始数据嵌入到 response class 中统一结构返回。

但有些场景，我们不需要包装原始数据，只需要直接返回，如下载文件场景，可以在接口方法或类上添加 @ExcludeFromGracefulResponse 注解来排除统一封装。

Query 参数转换器 ​

默认情况下，Spring MVC 无法直接转换 Query 中的 Date 等日期类型参数，需要使用 @DateTimeFormat 注解进行转换。

现在我们添加了 Query 参数转换器，将 Date、LocalDate、LocalTime、LocalDateTime、BaseEnum 等类型参数自动转换，默认格式为 yyyy-MM-dd HH:mm:ss，如果这个格式无法满足你的要求，可以继续使用 @DateTimeFormat 注解进行转换。

Undertow 服务器扩展配置 ​

我们增强了 Undertow 服务器配置，用于支持全局禁用部分请求方式，而且我们还对 undertow 服务器的线程池增加了部分默认配置，详情请查看：continew-starter-web/src/main/resources/default-web.yml。

yaml
--- ### 服务器配置
server:
  extension:
    enabled: true
    # 默认禁止三个不安全的 HTTP 方法（CONNECT、TRACE、TRACK）
    disallowed-methods:
      - CONNECT
      - TRACE
      - TRACK

核心依赖 ​

依赖描述
top.continew:continew-starter-json-jackson
top.continew:continew-starter-api-doc
org.springframework.boot:spring-boot-starter-web提供 Spring MVC Web 开发能力，默认内置 Tomcat 服务器，我们调整为了默认 Undertow。
org.springframework.boot:spring-boot-starter-undertow采用 Java 开发的灵活的高性能 Web 服务器，提供包括阻塞和基于 NIO 的非堵塞机制。
com.feiniaojin:graceful-response一个Spring Boot技术栈下的优雅响应处理组件，可以帮助开发者完成响应数据封装、异常处理、错误码填充等过程，提高开发效率，提高代码质量

参考资料 ​

1.Graceful Response 项目主页：https://doc.feiniaojin.com/graceful-response/home.html