前言
SpringBoot作为一款优秀的框架,不仅提供了快速开发的能力,同时也提供了丰富的文档和示例,让开发者更加容易上手。在本博客中,我们将介绍如何使用SpringBoot来整合Web应用程序的相关技术,并通过实例代码来演示如何实现这些功能。本篇博客是系列文章的第一篇,主要介绍SpringBoot整合Web模块的概述和基础知识,方便读者进一步深入学习和应用。
本次案例讲解替换默认的白色错误页面、JSON日期格式化、文件上传、自定义过滤器、open-api设置。
一、替换默认的白色页面
error:
whitelabel:
enabled: true
whitelabel.enabled
:这是一个Spring Boot特定的配置项,用于控制默认的错误页面。当应用程序发生错误时,默认情况下,Spring Boot会显示一个简单的错误页面,其中包含错误的详细信息。通过设置whitelabel.enabled
为true
,您可以启用这个默认错误页面,如果设置为false
,则禁用它。
error.whitelabel.enabled
:与上述配置项类似,这是另一个Spring Boot的配置项,用于控制错误页面的显示。通过设置error.whitelabel.enabled
为true
,您可以启用默认的错误页面,如果设置为false
,则禁用它。这些配置项通常用于自定义错误处理和错误页面的行为。您可以根据您的需求,选择是否使用默认的错误页面,或者根据自己的设计来创建自定义的错误页面。
禁用或打开springboot的白色错误页面,默认是打开的,如果禁用后当产生404或者500错误时候将返回容器默认的错误页面,如果想替换默认的白色错误页面,只要在静态资源目录下新建一个error文件夹,并在文件夹中创建404.html或者500.html即可
项目目录:
没有替换前的白色页面:
替换后:
这个路径是我随便打的,打一个错误的路径引发404,就可以查看我们自定义的404错误页面。
二、替换白色页面(默认错误页面)的好处如下:
-
品牌一致性:通过使用自定义的错误页面,您可以将应用程序的外观与品牌一致。这有助于提升用户体验和让用户更容易识别应用程序。
-
用户友好性:自定义错误页面可以提供更友好和易于理解的错误信息,以便用户能够快速了解发生了什么问题,并采取适当的行动。默认的白色页面可能只提供简单的错误信息,而自定义页面可以提供更具体和有用的提示。
-
错误处理和导航:自定义错误页面可以提供更多的错误处理选项和导航链接,帮助用户解决问题。您可以提供返回首页、联系支持、查看常见问题等选项,以减轻用户的困惑和不便。
-
提高用户满意度:通过提供个性化和专业的错误页面,您可以增强用户对应用程序的信任感和满意度。一个令人印象深刻的错误页面可能会使用户对您的应用程序留下良好的印象,并增加他们继续使用的可能性。
需要注意的是,替换白色页面并非必需,这取决于您的应用程序需求和设计目标。默认的白色页面在很多情况下已经可以满足基本的错误处理需求。如果您决定进行自定义,请确保设计出简洁、易于理解和有用的错误页面,以提供更好的用户体验。
三、文件上传
1、yml配置
spring:
# JSON日期格式化
jackson:
date-format: yyyy-MM-dd HH:mm:ss
time-zone: GMT+8
servlet:
# 文件上传
multipart:
#启用文件上传功能
enabled: true
# 每个文件限制100MB
max-file-size: 10MB
#单次请求中所有文件的总大小
max-request-size: 1000MB
spring.jackson.date-format
:这是用于配置Jackson库的日期格式化的配置项。在示例中,日期格式被设置为"yyyy-MM-dd HH:mm:ss",这意味着日期会以这种格式进行序列化和反序列化操作。
spring.jackson.time-zone
:这是用于配置Jackson库的时区的配置项。在示例中,时区被设置为"GMT+8",这意味着日期的处理将基于东八区的时区设置。
spring.servlet.multipart.enabled
:这是用于启用或禁用Spring的文件上传功能的配置项。在示例中,该功能被启用,允许应用程序处理文件上传。
spring.servlet.multipart.max-file-size
:这是用于限制单个文件大小的配置项。在示例中,文件大小被限制为10MB,超过这个大小的文件将无法上传。
spring.servlet.multipart.max-request-size
:这是用于限制整个请求中所有文件总大小的配置项。在示例中,所有文件的总大小被限制为1000MB(1GB),超过这个大小的请求将无法处理。
2、controller实现,即可以上传单个也可以多个
@Slf4j
@RestController
public class FileUploadController {
/**
* 测试多文件上传
*/
@PostMapping("/upload2")
public String upload2 (@RequestParam("file") MultipartFile[] fileList){
try{
if (fileList.length > 0){
for (MultipartFile file:fileList){
// 打印文件基础信息
log.info("Name == >>{}",file.getName());
log.info("OriginalFilename == >>{}",file.getOriginalFilename());
log.info("ContentType == >>{}",file.getContentType());
log.info("Size == >>{}",file.getSize());
// 文件输出地址
String filePath = "d:/imag/" ;
new File(filePath).mkdirs();
File writeFile = new File(filePath, file.getOriginalFilename());
file.transferTo(writeFile);
}
}
return "success" ;
} catch (Exception e){
return "fail" ;
}
}
}
这段代码是一个使用Spring框架实现的文件上传的控制器类。下面是对代码的解释:
@Slf4j
注解:这是Lombok库提供的注解,用于自动生成日志记录器(Logger)。通过在类上添加@Slf4j
注解,你可以直接使用log
对象进行日志记录。
@RestController
注解:这表示这是一个RESTful风格的控制器类,它会直接返回数据而不是视图。
FileUploadController
类:这是文件上传的控制器类。
upload2
方法:这是一个处理文件上传的方法,使用@PostMapping
注解指定了请求路径为/upload2
,并接收一个名为file
的文件参数。该方法返回一个字符串作为响应结果。文件上传逻辑:在方法内部,首先检查传入的文件参数
fileList
是否为空,如果不为空,则遍历文件列表,对每个文件进行处理。打印文件信息:使用日志记录器
log
打印文件的基本信息,包括文件名、原始文件名、内容类型和文件大小。设置文件输出地址:将文件输出到指定的目录下,这里设置的目录为 "d:/imag/",并确保该目录存在。
创建文件对象并保存文件:通过
file.transferTo(writeFile)
将文件保存到指定的目录下。返回结果:如果文件上传成功,返回字符串 "success",否则返回字符串 "fail"。
3、创建一个uploadStatus.html
的文件
<!DOCTYPE html>
<html lang="en">
<head>
<meta charset="UTF-8">
<title>Title</title>
<script src="js/JQuery文件.txt.js"></script>
</head>
<body>
<form id="f1" enctype="multipart/form-data" >
Name:<input type="text" name="productName"/><br>
Image:<input type="file" name="file" multiple/><br>
<input type="button" value="提交"/><br>
</form>
<script>
$(function () {
$(':button').on('click',function () {
// 构建 formData 对象
let formData = new FormData($('#f1')[0]);
$.ajax({
url:'/upload2',
type:'post',
data:formData,
processData:false, // 告诉 jquery 不要处理发送的数据类型
contentType:false, // 告诉 jquery 不要设置请求头的 contentType
success:function ( result ) {
console.log(result + "saddsada");
if ( result === 'success' ){
alert("上传成功");
} else {
alert("上传失败");
}
},
error:function (error) {
alert(JSON.stringify(error));
}
})
})
})
</script>
</body>
</html>
这段代码是一个简单的HTML页面,包括一个表单用于上传文件,并使用JavaScript中的jQuery库来实现文件上传的逻辑。下面是对代码的解释:
enctype="multipart/form-data"
:在<form>
标签中设置了enctype
属性为 "multipart/form-data",表示表单数据会以 multipart/form-data 的形式进行编码,支持文件上传。表单元素:在表单中包含了两个输入框,一个用于输入产品名称(Name),另一个是用于选择文件(Image)。文件输入框设置了
multiple
属性,表示可以选择多个文件进行上传。JavaScript部分:使用了jQuery库,引入了名为 "js/JQuery文件.txt.js" 的JavaScript文件。
事件绑定:通过jQuery,在页面加载完成后绑定了一个按钮点击事件的处理函数。当按钮被点击时,会执行相应的文件上传逻辑。
文件上传逻辑:在按钮点击事件处理函数中,构建了一个 FormData 对象,将表单数据包括文件信息传递给后端。然后使用 jQuery 的 ajax 方法向 "/upload2" 发送 POST 请求,并传递 FormData 对象作为请求数据。
processData
和contentType
:这两个属性被设置为 false,告诉 jQuery 不要处理发送的数据类型和不要设置请求头的 contentType,因为我们已经使用了 FormData 对象来传递数据。请求成功和失败处理:根据后端返回的结果,在成功或失败时弹出相应的提示框。
需要注意的是,代码中有一个错误,即按钮的类型应该是 "submit" 而不是 "button",这样才能触发表单的提交事件。另外,引入的JavaScript文件名 "JQuery文件.txt.js" 可能存在错误,应当确认文件路径和文件名是否正确。
4、运行结果
四、自定义过滤器
1、写一个过滤器
@Slf4j
@WebServlet
public class TestFilter implements Filter {
@Override
public void init(FilterConfig filterConfig) throws ServletException {
Filter.super.init(filterConfig);
}
@Override
public void doFilter(ServletRequest servletRequest, ServletResponse servletResponse, FilterChain filterChain) throws IOException, ServletException {
log.info("请求经过 TestFilter.... ");
filterChain.doFilter(servletRequest, servletResponse);
}
@Override
public void destroy() {
Filter.super.destroy();
}
}
这是一个基于 Java Servlet API 的过滤器(Filter)示例代码。过滤器是一种可以在 Servlet 容器中对请求和响应进行预处理和后处理的组件。可以使用过滤器来实现许多功能,例如身份验证、日志记录、编码转换、性能监测等。
在这个示例代码中,TestFilter 实现了 Filter 接口并重写了其中的三个方法:init()、doFilter() 和 destroy()。init() 方法在过滤器初始化时被调用,可以在其中进行一些初始化操作;doFilter() 方法是过滤器的主要方法,用于处理请求和响应;destroy() 方法在过滤器销毁时被调用,可以在其中进行一些清理操作。
在这个具体的示例中,doFilter() 方法只是简单地输出了一条日志,表示请求经过了 TestFilter 这个过滤器。这个示例代码并没有做任何有用的处理,但它可以作为一个基础框架,用于实现更加复杂和实际的过滤器功能。
2、注册过滤器
@Configuration
public class MvcConfig implements WebMvcConfigurer {
/**
* FilterRegistrationBean 用于动态注册自定义的 Filter
* @return
*/
@Bean
public FilterRegistrationBean testFilter(){
FilterRegistrationBean filterFilterRegistrationBean = new FilterRegistrationBean();
// 装配自定义的过滤器
filterFilterRegistrationBean.setFilter(new TestFilter());
// 设置 filter 的 name
filterFilterRegistrationBean.setName("testFilter");
// 映射 filter 的请求 url
filterFilterRegistrationBean.addUrlPatterns("/*");
// 可以设置过滤器的 优先级别,数值越小,优先级别越高
filterFilterRegistrationBean.setOrder(1);
return filterFilterRegistrationBean;
}
}
这是一个用于注册过滤器的Spring MVC配置类。该类使用
FilterRegistrationBean
动态注册自定义的过滤器TestFilter
。在
testFilter()
方法中,首先创建了一个FilterRegistrationBean
对象filterFilterRegistrationBean
。然后,将自定义的过滤器TestFilter
装配到该对象中。接着,设置了过滤器的名称为"testFilter",并将过滤器映射到所有请求URL上。最后,通过setOrder()
方法设置了过滤器的优先级别为1。这样,当应用启动时,该过滤器就会被自动注册并生效,对所有请求进行过滤处理。
请注意,以上代码仅展示了过滤器的注册配置,并不包含过滤器的具体实现逻辑。
3、测试
把项目跑起来后,访问了两个地址都可以经过自定义过滤器,在做项目有特殊需求是需要用到过滤器就可以这么写。
五、open-api设置
1、配置 yml
# open-api设置
springdoc:
# 设置需要要扫描生成api的包
packages-to-scan: edu.nf.ch06.controller.api
api-docs:
# 是否禁用api文档,true是打开,false是禁用
# 如果是开发环境则设置为true,生产环境则禁用掉
enabled: true
这是一个用于配置Springdoc OpenAPI的配置文件。Springdoc是一个用于生成和展示API文档的库。
在该配置文件中,设置了需要扫描生成API文档的包路径为
edu.nf.ch06.controller.api
。这意味着只有该包下的控制器类会被扫描生成API文档。同时,
api-docs
部分设置了是否启用API文档的选项。在这里,将其设置为true
,即打开API文档的生成和展示功能。需要注意的是,根据注释中的说明,建议在开发环境中启用API文档生成,而在生产环境中禁用。这是为了避免将API文档暴露给未经授权的用户。
2、设置配置类
@Configuration
//使用注解配置OpenApi
@OpenAPIDefinition(info = @Info(
title = "项目接口文档",
version = "v1.0",
description = "基于springboot开发的API接口",
license = @License(name = "MIT", url = "http://springdoc.org")
),
externalDocs = @ExternalDocumentation(description = "参看文档", url = "https://gitee.com")
)
public class OpenApiConfig {
}
这是一个用于配置OpenAPI的Spring配置类。在该类上使用了注解
@OpenAPIDefinition
,用于定义OpenAPI规范中的信息、文档和许可证等相关内容。在
@OpenAPIDefinition
注解中,通过info
属性设置了API文档的基本信息,包括文档的标题、版本、描述和许可证信息。其中,@Info
注解用于设置文档的基本信息,@License
注解用于设置许可证信息。此外,还通过
externalDocs
属性设置了API文档的外部参考文档。其中,@ExternalDocumentation
注解用于设置外部参考文档的描述和URL。需要注意的是,
@OpenAPIDefinition
和@Info
、@License
、@ExternalDocumentation
等注解都属于Springdoc OpenAPI库中的注解,用于简化OpenAPI规范的配置和生成。
3、编写 controller
@RestController
@RequestMapping("/api/v1")
@Tag(name = "UserApiController", description = "用户API接口")
public class UserApiController extends BaseController {
@GetMapping("/users")
@Operation(method = "GET", summary = "用户查询",
description = "查询所有用户信息")
@ApiResponses({
@ApiResponse(responseCode = "200", description = "查询完成"),
@ApiResponse(responseCode = "500", description = "内部查询错误")
})
public ResultVo<List<User>> listUser() {
User u1 = new User("1001", "user1", 21);
User u2 = new User("1002", "user2", 20);
List<User> list = Arrays.asList(u1, u2);
return success(list);
}
@GetMapping("/user/{id}")
@Operation(method = "GET", summary = "用户查询",
description = "根据用户ID查询详细信息")
@Parameters({
@Parameter(name = "id", description = "用户ID",
required = true, in = ParameterIn.PATH)
})
@ApiResponses({
@ApiResponse(responseCode = "200", description = "查询完成"),
@ApiResponse(responseCode = "500", description = "内部查询错误")
})
public ResultVo<User> getUser(@PathVariable("id") String uid) {
User user = new User(uid, "user1", 19);
return success(user);
}
}
@RestController
:这个注解表示这是一个RESTful风格的控制器类,用于处理HTTP请求并返回RESTful风格的响应。它相当于将@Controller
和@ResponseBody
两个注解结合在一起使用,省去了在每个请求处理方法上都加上@ResponseBody
的麻烦。
@RequestMapping("/api/v1")
:这个注解用于指定整个控制器类的基本路径为"/api/v1",也就是说该控制器处理的URL都会以"/api/v1"开头。例如,如果有一个处理GET请求的方法映射了"/users"路径,那么实际的URL路径就是"/api/v1/users"。
@Tag(name = "UserApiController", description = "用户API接口")
:这个注解来自于Springdoc OpenAPI库,用于为该控制器类设置OpenAPI文档中的标签名称和描述信息。通过这个注解,你可以在生成的API文档中对该控制器进行分类和描述。
public class UserApiController extends BaseController
:这是控制器类的定义,继承自BaseController类。BaseController可能是一个自定义的基础控制器类,用于封装一些通用的功能和方法,让子类的控制器类继承并复用这些功能和方法。
@GetMapping("/users")
:这个注解表示处理HTTP的GET请求,并且指定了具体的路径为"/users"。它是@RequestMapping(method = RequestMethod.GET, value = "/users")
的简写形式。在Spring MVC中,这个注解通常用于标记处理GET请求的方法。
@Operation
:这个注解用于描述操作的信息,包括HTTP方法、摘要和描述等。它可以用在请求处理方法上,为方法提供一些额外的元数据,用于生成API文档。例如,你可以使用@Operation(summary = "获取所有用户", description = "用于查询系统中的所有用户信息")
来描述一个获取所有用户的方法。
@ApiResponses
:这个注解用于定义可能的响应信息,包括响应码和描述等。你可以在该注解内部使用@ApiResponse
注解来定义具体的响应信息。例如,你可以使用@ApiResponses(value = { @ApiResponse(responseCode = "200", description = "成功"), @ApiResponse(responseCode = "404", description = "未找到用户") })
来定义一个获取用户信息的方法可能返回的两种响应。
public ResultVo<List<User>> listUser()
:这是处理"/users"路径的GET请求的方法,返回一个ResultVo对象,其中包含了一个User对象列表。ResultVo可能是一个自定义的类,用于封装响应结果的数据和元数据,例如状态码、消息等。
@GetMapping("/user/{id}")
:这个注解表示处理HTTP的GET请求,并且指定了具体的路径为"/user/{id}",其中{id}是一个占位符,表示参数化的URL路径。例如,如果实际请求的URL路径为"/user/123",那么{id}的值就是"123"。
@Parameter
:这个注解用于描述方法的参数信息,包括参数名称、描述、是否必须等。它可以用在方法的参数上,为参数提供一些额外的元数据,用于生成API文档。例如,你可以使用@Parameter(name = "id", description = "用户ID", required = true)
来描述一个获取用户信息的方法的id参数。
public ResultVo<User> getUser(@PathVariable("id") String uid)
:这是处理"/user/{id}"路径的GET请求的方法,通过@PathVariable注解将路径中的{id}参数映射到方法的uid参数上,返回一个ResultVo对象,其中包含了一个User对象。@PathVariable注解用于将路径中的占位符参数映射到方法的参数上,例如将"/user/123"中的"123"映射到uid参数上。总的来说,这段代码使用了Spring MVC的注解来定义RESTful API控制器,同时利用了Springdoc OpenAPI库中的注解来简化OpenAPI规范的配置和生成,使得代码更加清晰和易于理解
4、测试
访问路径为:http://localhost:8080/上下文/swagger-ui/index.html
六、设置open-api的作用
OpenAPI是一种用于描述和定义RESTful API的规范。它提供了一种标准化的方式来描述API的各个方面,包括请求方法、路径、参数、响应等。通过使用OpenAPI规范,可以帮助开发者更好地理解和使用API,并且使得API的文档和代码保持同步。
设置OpenAPI的作用主要有以下几点:
-
文档生成:使用OpenAPI规范可以方便地生成API文档,包括接口的路径、请求方法、参数、响应等信息。这样,开发者可以通过查阅API文档了解每个接口的使用方法和预期的返回结果。
-
接口调试:OpenAPI规范可以作为接口的约定,开发人员可以根据规范来构造请求、处理响应,并进行接口的调试和测试。这样可以确保接口在开发阶段能够正确地运行并返回期望的结果。
-
代码生成:基于OpenAPI规范,可以生成客户端或服务器端的代码框架,减少手写代码的工作量。通过代码生成,可以快速搭建起与API对接的程序框架,提高开发效率。
-
接口管理和版本控制:OpenAPI规范可以帮助团队管理和维护大量的API接口。通过定义和维护OpenAPI规范文件,可以清晰地了解所有接口的定义和使用情况,并且能够进行版本控制和升级。
-
提供自动化工具支持:OpenAPI规范被广泛支持,有很多开源工具可以根据规范来进行接口测试、文档生成、代码生成等操作。这些工具可以提高开发效率和质量,并且保持与行业标准的一致性。
总的来说,设置OpenAPI规范可以帮助开发者更好地管理、使用和维护API,提高开发效率和代码质量,并且促进团队间的合作和沟通。