springboot中swagger、異步/定時/郵件任務的問題

1、SpringBoot:集成Swagger終極版

在這裡插入圖片描述

學習目標:

  • 瞭解Swagger的概念及作用
  • 掌握在項目中集成Swagger自動生成API文檔

1.1、Swagger簡介

前後端分離

  • 前端 -> 前端控制層、視圖層
  • 後端 -> 後端控制層、服務層、數據訪問層
  • 前後端通過API進行交互
  • 前後端相對獨立且松耦合

產生的問題

  • 前後端集成,前端或者後端無法做到“及時協商,盡早解決”,最終導致問題集中爆發

解決方案

  • 首先定義schema [ 計劃的提綱 ],並實時跟蹤最新的API,降低集成風險

Swagger

  • 號稱世界上最流行的API框架
  • Restful Api 文檔在線自動生成器 => API 文檔 與API 定義同步更新
  • 直接運行,在線測試API
  • 支持多種語言 (如:Java,PHP等)
  • 官網:https://swagger.io/

1.2、SpringBoot集成Swagger

SpringBoot集成Swagger => springfox,兩個jar包

  • Springfox-swagger2
  • swagger-springmvc

使用Swagger

要求:jdk 1.8 + 否則swagger2無法運行

步驟:

1、新建一個SpringBoot-web項目

2、添加Maven依賴

   <!-- https://mvnrepository.com/artifact/io.springfox/springfox-swagger-ui -->
        <dependency>
            <groupId>io.springfox</groupId>
            <artifactId>springfox-swagger-ui</artifactId>
            <version>3.0.0</version>
        </dependency>
        <!-- https://mvnrepository.com/artifact/io.springfox/springfox-swagger2 -->
        <dependency>
            <groupId>io.springfox</groupId>
            <artifactId>springfox-swagger2</artifactId>
            <version>3.0.0</version>
        </dependency>

3、編寫HelloController,測試確保運行成功!

4、要使用Swagger,我們需要編寫一個配置類-SwaggerConfig來配置 Swagger

@Configuration //配置類
@EnableSwagger2// 開啟Swagger2的自動配置
public class SwaggerConfig {  
}

5、訪問測試 :http://localhost:8080/swagger-ui.html ,可以看到swagger的界面;

在這裡插入圖片描述

重要在於寫 文檔名和描述,即ApiInfo有參構造的前2個參數。

1.3、配置Swagger

1、Swagger實例Bean是Docket,所以通過配置Docket實例來配置Swaggger。

  //配置瞭swagger的docket的bean實例
    @Bean
    public Docket getDocket(){
        return new Docket(DocumentationType.SWAGGER_2);
    }

2、可以通過apiInfo()屬性配置文檔信息

//配置文檔信息
private ApiInfo apiInfo() {
   Contact contact = new Contact("聯系人名字", "http://xxx.xxx.com/聯系人訪問鏈接", "聯系人郵箱");
   return new ApiInfo(
           "Swagger學習", // 標題
           "學習演示如何配置Swagger", // 描述
           "v1.0", // 版本
           "http://terms.service.url/組織鏈接", // 組織鏈接
           contact, // 聯系人信息
           "Apach 2.0 許可", // 許可
           "許可鏈接", // 許可連接
           new ArrayList<>()// 擴展
  );
}

3、Docket 實例關聯上 apiInfo()

@Bean
public Docket docket() {
   return new Docket(DocumentationType.SWAGGER_2).apiInfo(apiInfo());
}

4、重啟項目,訪問測試 http://localhost:8080/swagger-ui.html 看下效果;

在這裡插入圖片描述


1.4、配置掃描接口

1、構建Docket時通過select()方法配置怎麼掃描接口。

@Bean
public Docket docket() {
    return new Docket(DocumentationType.SWAGGER_2)
        .apiInfo(apiInfo())
        .select()// 通過.select()方法,去配置掃描接口,RequestHandlerSelectors配置如何掃描接口
        .apis(RequestHandlerSelectors.basePackage("com.wei.swagger.controller"))
        .build();
}

2、重啟項目測試,由於我們配置根據包的路徑掃描接口,所以我們隻能看到一個類

3、除瞭通過包路徑配置掃描接口外,還可以通過配置其他方式掃描接口,這裡註釋一下所有的配置方式:

any() // 掃描所有,項目中的所有接口都會被掃描到
none() // 不掃描接口
// 通過方法上的註解掃描,如withMethodAnnotation(GetMapping.class)隻掃描get請求
withMethodAnnotation(final Class<? extends Annotation> annotation)
// 通過類上的註解掃描,如.withClassAnnotation(Controller.class)隻掃描有controller註解的類中的接口
withClassAnnotation(final Class<? extends Annotation> annotation)
basePackage(final String basePackage) // 根據包路徑掃描接口

4、除此之外,我們還可以配置接口掃描過濾 paths :

 //配置瞭swagger的docket的bean實例
    @Bean
    public Docket getDocket(Environment environment){
        return new Docket(DocumentationType.SWAGGER_2)
                .apiInfo(getApiInfo())
                .select()
                //RequestHandlerSelectors配置要掃描接口的方式、
                //basePackage 指定要讓swagger掃描的包
                //RequestHandlerSelectors 還有any 和none方法
                //withClassAnnotation 隻掃描類上有XX註解
                //withMethodAnnotation 隻掃描方法上有XX註解
                .apis(RequestHandlerSelectors.basePackage("com.wei.swagger.controller"))
                //paths 過濾路徑
                .paths(PathSelectors.ant("/wei/**"))
                .build();
    }

5、這裡的可選值還有

any() // 任何請求都掃描
none() // 任何請求都不掃描
regex(final String pathRegex) // 通過正則表達式控制
ant(final String antPattern) // 通過ant()控制

1.5、配置Swagger開關

1、通過enable()方法配置是否啟用swagger,如果是false,swagger將不能在瀏覽器中訪問瞭

enable 鏈式編程

@Bean
    public Docket getDocket(Environment environment){
        return new Docket(DocumentationType.SWAGGER_2)
                .enable(false)// 關閉swagger : false。 默認ture 開啟
                .apiInfo(getApiInfo())
                .select()
                //RequestHandlerSelectors配置要掃描接口的方式、
                //basePackage 指定要讓swagger掃描的包
                //RequestHandlerSelectors 還有any 和none方法
                //withClassAnnotation 隻掃描類上有XX註解
                //withMethodAnnotation 隻掃描方法上有XX註解
                .apis(RequestHandlerSelectors.basePackage("com.wei.swagger.controller"))
                //paths 過濾路徑
                .paths(PathSelectors.ant("/wei/**"))
                .build();
    }

2、如何動態配置當項目處於test、dev環境時顯示swagger,處於prod時不顯示?

 @Bean
    public Docket getDocket(Environment environment){
        Profiles profiles = Profiles.of("dev","test"); //dev or test
        System.out.println(profiles);
        //通過environment.acceptsProfiles(profiles) 判斷是否處在自己設定的環境當中
        boolean b = environment.acceptsProfiles(profiles);
        return new Docket(DocumentationType.SWAGGER_2)
                .enable(b)// 關閉swagger : false。 默認ture 開啟
                .apiInfo(getApiInfo())
                .select()
                //RequestHandlerSelectors配置要掃描接口的方式、
                //basePackage 指定要讓swagger掃描的包
                //RequestHandlerSelectors 還有any 和none方法
                //withClassAnnotation 隻掃描類上有XX註解
                //withMethodAnnotation 隻掃描方法上有XX註解
                .apis(RequestHandlerSelectors.basePackage("com.wei.swagger.controller"))
                //paths 過濾路徑
                .paths(PathSelectors.ant("/wei/**"))
                .build();
    }

3、可以在項目中增加一個dev的配置文件查看效果!

在這裡插入圖片描述

4、也可以通過配置文件實現,隻是界面顯示不友好。
application.properties

spring.profiles.active=prod

application-dev.properties

springfox.documentation.swagger-ui.enabled=true

application-prod.properties

springfox.documentation.swagger-ui.enabled=false

在這裡插入圖片描述


1.6、配置API分組

在這裡插入圖片描述

1、如果沒有配置分組,默認是default。通過groupName()方法即可配置分組:

@Bean
public Docket docket(Environment environment) {
   return new Docket(DocumentationType.SWAGGER_2).apiInfo(apiInfo())
      .groupName("group1") // 配置分組
       // 省略配置....
}

2、重啟項目查看分組

3、如何配置多個分組?配置多個分組隻需要配置多個docket即可:

@Bean
    public Docket getDocket2(){
        return new Docket(DocumentationType.SWAGGER_2).groupName("group2");
    }
    @Bean
    public Docket getDocket3(){
        return new Docket(DocumentationType.SWAGGER_2).groupName("group3");
    }

4、重啟項目查看即可

1.7、實體配置

1、新建一個實體類

package com.wei.swagger.pojo;

import io.swagger.annotations.ApiModel;
import io.swagger.annotations.ApiModelProperty;
import lombok.Data;

@ApiModel("user實體類")
@Data
public class User {
    @ApiModelProperty("用戶名")
    private String username;
    @ApiModelProperty("密碼")
    private String password;
}

2、隻要這個實體在請求接口的返回值上(即使是泛型),都能映射到實體項中:

 @RequestMapping(value = "/user" , method = RequestMethod.POST)
    public User user(){
        return new User();
    }

3、重啟查看測試

在這裡插入圖片描述

註:並不是因為@ApiModel這個註解讓實體顯示在這裡瞭,而是隻要出現在接口方法的返回值上的實體都會顯示在這裡,而@ApiModel和@ApiModelProperty這兩個註解隻是為實體添加註釋的。

@ApiModel為類添加註釋

@ApiModelProperty為類屬性添加註釋

1.8、常用註解

Swagger的所有註解定義在io.swagger.annotations包下

下面列一些經常用到的,未列舉出來的可以另行查閱說明:

Swagger註解 簡單說明
@Api(tags = “xxx模塊說明”) 作用在模塊類上
@ApiOperation(“xxx接口說明”) 作用在接口方法上
@ApiModel(“xxxPOJO說明”) 作用在模型類上:如VO、BO
@ApiModelProperty(value = “xxx屬性說明”,hidden = true) 作用在類方法和屬性上,hidden設置為true可以隱藏該屬性
@ApiParam(“xxx參數說明”) 作用在參數、方法和字段上,類似@ApiModelProperty

我們也可以給請求的接口配置一些註釋

 @ApiOperation("test請求")
    @RequestMapping(value = "/test" , method = RequestMethod.GET)
    public String test(@ApiParam("名字") String name){
        return "test "+name;
    }

測試結果如下

在這裡插入圖片描述

給controller添加註釋

@Api(tags = "hello 控制器")
public class HelloController {
}

這樣的話,可以給一些比較難理解的屬性或者接口,增加一些配置信息,讓人更容易閱讀!

相較於傳統的Postman或Curl方式測試接口,使用swagger簡直就是傻瓜式操作,不需要額外說明文檔(寫得好本身就是文檔)而且更不容易出錯,隻需要錄入數據然後點擊Execute,如果再配合自動化框架,可以說基本就不需要人為操作瞭。

Swagger是個優秀的工具,現在國內已經有很多的中小型互聯網公司都在使用它,相較於傳統的要先出Word接口文檔再測試的方式,顯然這樣也更符合現在的快速迭代開發行情。當然瞭,提醒下大傢在正式環境要記得關閉Swagger,一來出於安全考慮二來也可以節省運行時內存。

總結:
1、我們可以通過swagger給一些比較難理解的屬性或者接口,增加註釋信息
2、接口文檔實時更新
3、可以在線測試


1.9、拓展:其他皮膚

我們可以導入不同的包實現不同的皮膚定義:

1、默認的 訪問 http://localhost:8080/swagger-ui/

<dependency> 
   <groupId>io.springfox</groupId>
   <artifactId>springfox-swagger-ui</artifactId>
   <version>2.9.2</version>
</dependency>

在這裡插入圖片描述

2、bootstrap-ui 訪問 http://localhost:8080/doc.html

<!-- 引入swagger-bootstrap-ui包 /doc.html-->
<dependency>
    <groupId>com.github.xiaoymin</groupId>
    <artifactId>swagger-bootstrap-ui</artifactId>
    <version>1.9.1</version>
</dependency>

在這裡插入圖片描述

3、Layui-ui 訪問 http://localhost:8080/docs.html

<!-- 引入swagger-ui-layer包 /docs.html-->
<dependency>
    <groupId>com.github.caspar-chen</groupId>
    <artifactId>swagger-ui-layer</artifactId>
    <version>1.1.3</version>
</dependency>

在這裡插入圖片描述

4、mg-ui 訪問 http://localhost:8080/document.html

<!-- 引入swagger-ui-layer包 /document.html-->
<dependency>
    <groupId>com.zyplayer</groupId>
    <artifactId>swagger-mg-ui</artifactId>
    <version>1.0.6</version>
</dependency>

在這裡插入圖片描述


2、SpringBoot:異步、定時、郵件任務

2.1、異步任務

編寫方法,假裝正在處理數據,使用線程設置一些延時,模擬同步等待的情況;

@Service
public class AsyncService {

   public void hello(){
       try {
           Thread.sleep(3000);
      } catch (InterruptedException e) {
           e.printStackTrace();
      }
       System.out.println("業務進行中....");
  }
}

3、編寫controller包

4、編寫AsyncController類

我們去寫一個Controller測試一下

@RestController
public class AsyncController {

   @Autowired
   AsyncService asyncService;

   @GetMapping("/hello")
   public String hello(){
       asyncService.hello();
       return "hello!!!ok!!!";
  }

}

5、訪問http://localhost:8080/hello進行測試,3秒後出現hello!!!ok!!!,這是同步等待的情況。

問題:我們如果想讓用戶直接得到消息,就在後臺使用多線程的方式進行處理即可,但是每次都需要自己手動去編寫多線程的實現的話,太麻煩瞭,我們隻需要用一個簡單的辦法,在我們的方法上加一個簡單的註解即可,如下:

6、給hello方法添加@Async註解;

//告訴Spring這是一個異步方法
@Async
public void hello(){
   try {
       Thread.sleep(3000);
  } catch (InterruptedException e) {
       e.printStackTrace();
  }
   System.out.println("業務進行中....");
}

SpringBoot就會自己開一個線程池,進行調用!但是要讓這個註解生效,我們還需要在主程序上添加一個註解@EnableAsync ,開啟異步註解功能;

@EnableAsync //開啟異步註解功能
@SpringBootApplication
public class SpringbootTaskApplication {

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

}

7、重啟測試,網頁瞬間響應,後臺代碼依舊執行!
無需等待AsyncService 的hello 方法走完,可以繼續執行下面的語句。

2.2、郵件任務

郵件發送,在我們的日常開發中,也非常的多,Springboot也幫我們做瞭支持郵件發送需要引入spring-boot-start-mail
SpringBoot 自動配置MailSenderAutoConfiguration
定義MailProperties內容,配置在application.yml中
自動裝配JavaMailSender(實現類:JavaMailSenderImpl 來寫代碼)
測試郵件發送

測試:

1、引入pom依賴

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

2、查看自動配置類:MailSenderAutoConfiguration

在這裡插入圖片描述

這個類中存在bean,JavaMailSenderImpl

在這裡插入圖片描述

然後我們去看下配置文件

@ConfigurationProperties(
   prefix = "spring.mail"
)
public class MailProperties {
   private static final Charset DEFAULT_CHARSET;
   private String host;
   private Integer port;
   private String username;
   private String password;
   private String protocol = "smtp";
   private Charset defaultEncoding;
   private Map<String, String> properties;
   private String jndiName;
}

3、配置文件:

[email protected]
spring.mail.password=你的163授權碼
spring.mail.host=smtp.163.com

# 如果使用qq,需要配置ssl
spring.mail.properties.mail.smtp.ssl.enable=true

4、Spring單元測試

package com.wei;

import org.junit.jupiter.api.Test;
import org.springframework.beans.factory.annotation.Autowired;
import org.springframework.boot.test.context.SpringBootTest;
import org.springframework.mail.SimpleMailMessage;
import org.springframework.mail.javamail.JavaMailSenderImpl;
import org.springframework.mail.javamail.MimeMessageHelper;

import javax.mail.MessagingException;
import javax.mail.internet.MimeMessage;
import java.io.File;
import java.io.IOException;

@SpringBootTest
class Springboot09TestApplicationTests {
    @Autowired
    JavaMailSenderImpl javaMailSender;

    @Test
    void contextLoads() {
        // 發送郵件
        SimpleMailMessage mailMessage = new SimpleMailMessage();
        mailMessage.setFrom("[email protected]");
        mailMessage.setTo("[email protected]");
        mailMessage.setSubject("subject2..");
        mailMessage.setText("text2...");
        javaMailSender.send(mailMessage);
    }
    @Test
    void contextLoads2() throws MessagingException, IOException {
        // 發送復雜的郵件
        MimeMessage mimeMessage  = javaMailSender.createMimeMessage();
        // 組裝
        MimeMessageHelper helper = new MimeMessageHelper(mimeMessage,true);    // true ,支持多組件 multipart
        helper.setSubject("subject");
        helper.setText("<h1 style='color:red'>test 復雜郵件</h1>",true);     // true ,支持html
        //附件
        String fileName = this.getClass().getClassLoader().getResource("1.jpg").getPath();   // 獲取resources下的絕對路徑
        helper.addAttachment("1.jpg", new File(fileName));
        helper.addAttachment("2.jpg", new File(fileName));

        helper.setFrom("[email protected]");     //發送
        helper.setTo("[email protected]");       //接收
        javaMailSender.send(mimeMessage);
    }

}

contextLoads 結果

在這裡插入圖片描述

contextLoads2 結果

在這裡插入圖片描述

查看郵箱,郵件接收成功!

我們隻需要使用Thymeleaf進行前後端結合即可開發自己網站郵件收發功能瞭!

2.3、定時任務

項目開發中經常需要執行一些定時任務,比如需要在每天凌晨的時候,分析一次前一天的日志信息,Spring為我們提供瞭異步執行任務調度的方式,提供瞭兩個接口。

  • TaskExecutor接口
  • TaskScheduler接口

兩個註解:

  • @EnableScheduling
  • @Scheduled

cron表達式參考:https://www.cnblogs.com/javahr/p/8318728.html

測試步驟:

1、創建一個ScheduledService

我們裡面存在一個hello方法,他需要定時執行,怎麼處理呢?

import org.springframework.scheduling.annotation.Scheduled;
import org.springframework.stereotype.Service;
@Service
public class ScheduledService {
    //在一個特定的時間執行這個方法
    @Scheduled(cron = "秒 分 時 * * ?")
    public void hello(){
        System.out.println("hello 執行瞭");
    }

}

2、這裡寫完定時任務之後,我們需要在主程序上增加@EnableScheduling 開啟定時任務功能

@EnableAsync //開啟異步註解功能
@EnableScheduling //開啟基於註解的定時任務
@SpringBootApplication
public class SpringbootTaskApplication {

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

}

3、表達式生成器

http://www.bejson.com/othertools/cron/

4、常用的表達式

(1)0/2 * * * * ?   表示每2秒 執行任務
(1)0 0/2 * * * ?   表示每2分鐘 執行任務
(1)0 0 2 1 * ?   表示在每月的1日的凌晨2點調整任務
(2)0 15 10 ? * MON-FRI   表示周一到周五每天上午10:15執行作業
(3)0 15 10 ? 6L 2002-2006   表示2002-2006年的每個月的最後一個星期五上午10:15執行作
(4)0 0 10,14,16 * * ?   每天上午10點,下午2點,4點
(5)0 0/30 9-17 * * ?   朝九晚五工作時間內每半小時
(6)0 0 12 ? * WED   表示每個星期三中午12點
(7)0 0 12 * * ?   每天中午12點觸發
(8)0 15 10 ? * *   每天上午10:15觸發
(9)0 15 10 * * ?     每天上午10:15觸發
(10)0 15 10 * * ?   每天上午10:15觸發
(11)0 15 10 * * ? 2005   2005年的每天上午10:15觸發
(12)0 * 14 * * ?     在每天下午2點到下午2:59期間的每1分鐘觸發
(13)0 0/5 14 * * ?   在每天下午2點到下午2:55期間的每5分鐘觸發
(14)0 0/5 14,18 * * ?     在每天下午2點到2:55期間和下午6點到6:55期間的每5分鐘觸發
(15)0 0-5 14 * * ?   在每天下午2點到下午2:05期間的每1分鐘觸發
(16)0 10,44 14 ? 3 WED   每年三月的星期三的下午2:10和2:44觸發
(17)0 15 10 ? * MON-FRI   周一至周五的上午10:15觸發
(18)0 15 10 15 * ?   每月15日上午10:15觸發
(19)0 15 10 L * ?   每月最後一日的上午10:15觸發
(20)0 15 10 ? * 6L   每月的最後一個星期五上午10:15觸發
(21)0 15 10 ? * 6L 2002-2005   2002年至2005年的每月的最後一個星期五上午10:15觸發
(22)0 15 10 ? * 6#3   每月的第三個星期五上午10:15觸發

到此這篇關於springboot中swagger、異步/定時/郵件任務的問題的文章就介紹到這瞭,更多相關springboot swagger內容請搜索WalkonNet以前的文章或繼續瀏覽下面的相關文章希望大傢以後多多支持WalkonNet!

推薦閱讀: