云尚办公系统学习笔记（1.基础设置）
目录
- 一.项目介绍
-
- 1.介绍
- 2.核心技术
- 3.项目模块
- 4.数据库
- 二.搭建环境
-
- 1.搭建项目模块
- 2.导入依赖
- 三.MyBatis-Plus
-
- 1.简介
- 2.主要特点
- 3.依赖
- 四.MyBatis-Plus入门
-
- 1.配置文件
- 2.启动类
- 3.实体类
- 4.Mapper类
- 5.Service类
- 6.Service实现类Impl
- 7.Controller类
- 五.定义统一返回结果对象
-
- 1.定义统一返回结果对象
- 2.改造controller方法
- 六.knife4j
-
- 1.Swagger介绍
- 2.集成knife4j
- 七.分页查询
-
- 1.分页插件
- 2.分页controller
- 3.其他controller
- 八.配置日期时间格式
- 九.统一异常处理
一.项目介绍
1.介绍
云尚办公系统是一套自动办公系统（OA系统），系统主要包含：管理端和员工端。
管理端包含：权限管理、审批管理、公众号菜单管理。
员工端采用微信公众号操作，包含：办公审批、微信授权登录、消息推送等功能。
主要参照尚硅谷OA系统设计，记录如下学习笔记。
2.核心技术
| 基础框架 | SpringBoot |
|---|---|
| 数据缓存 | Redis |
| 数据库 | MySQL |
| 权限控制 | SpringSecurity |
| 工作流引擎 | Activiti |
| 前端技术 | vue-admin-template + Node.js + Npm + Vue + ElementUI + Axios |
| 微信公众号 | 公众号菜单 + 微信授权登录 + 消息推送 |
3.项目模块
最终服务器端架构模块
- oa-parent：根目录，管理子模块：
- common：公共类父模块
- common-util：核心工具类
- service-util：service模块工具类
- spring-security：spring-security业务模块
- model：实体类模块
- service-oa：系统服务模块
- common：公共类父模块
4.数据库
导入数据库，Activiti表后续自动导入，数据库表如下：
二.搭建环境
1.搭建项目模块
按照上面结构，在idea中建立如下项目模块
2.导入依赖
oa-parent模块pom.xml文件
<?xml version="1.0" encoding="UTF-8"?>
<project xmlns="http://maven.apache.org/POM/4.0.0"
xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
xsi:schemaLocation="http://maven.apache.org/POM/4.0.0 http://maven.apache.org/xsd/maven-4.0.0.xsd">
<modelVersion>4.0.0</modelVersion>
<!--指定springboot版本-->
<parent>
<groupId>org.springframework.boot</groupId>
<artifactId>spring-boot-starter-parent</artifactId>
<version>2.3.6.RELEASE</version>
</parent>
<groupId>org.example</groupId>
<artifactId>oa-parent</artifactId>
<packaging>pom</packaging>
<version>1.0-SNAPSHOT</version>
<modules>
<module>common</module>
<module>model</module>
<module>service-oa</module>
</modules>
<!--依赖版本-->
<properties>
<maven.compiler.source>8</maven.compiler.source>
<maven.compiler.target>8</maven.compiler.target>
<java.version>1.8</java.version>
<mybatis-plus.version>3.4.1</mybatis-plus.version>
<mysql.version>8.0.30</mysql.version>
<knife4j.version>3.0.3</knife4j.version>
<jwt.version>0.9.1</jwt.version>
<fastjson.version>2.0.21</fastjson.version>
</properties>
<!--配置dependencyManagement锁定依赖的版本-->
<dependencyManagement>
<dependencies>
<!--mybatis-plus 持久层-->
<dependency>
<groupId>com.baomidou</groupId>
<artifactId>mybatis-plus-boot-starter</artifactId>
<version>${mybatis-plus.version}</version>
</dependency>
<!--mysql-->
<dependency>
<groupId>mysql</groupId>
<artifactId>mysql-connector-java</artifactId>
<version>${mysql.version}</version>
</dependency>
<!--knife4j 接口测试-->
<dependency>
<groupId>com.github.xiaoymin</groupId>
<artifactId>knife4j-spring-boot-starter</artifactId>
<version>${knife4j.version}</version>
</dependency>
<!--jjwt 做jwp-->
<dependency>
<groupId>io.jsonwebtoken</groupId>
<artifactId>jjwt</artifactId>
<version>${jwt.version}</version>
</dependency>
<!--fastjson-->
<dependency>
<groupId>com.alibaba</groupId>
<artifactId>fastjson</artifactId>
<version>${fastjson.version}</version>
</dependency>
</dependencies>
</dependencyManagement>
<build>
<plugins>
<plugin>
<groupId>org.apache.maven.plugins</groupId>
<artifactId>maven-compiler-plugin</artifactId>
<version>3.1</version>
<configuration>
<source>1.8</source>
<target>1.8</target>
</configuration>
</plugin>
</plugins>
</build>
</project>
common模块：
<?xml version="1.0" encoding="UTF-8"?>
<project xmlns="http://maven.apache.org/POM/4.0.0"
xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
xsi:schemaLocation="http://maven.apache.org/POM/4.0.0 http://maven.apache.org/xsd/maven-4.0.0.xsd">
<parent>
<artifactId>oa-parent</artifactId>
<groupId>org.example</groupId>
<version>1.0-SNAPSHOT</version>
</parent>
<modelVersion>4.0.0</modelVersion>
<artifactId>common</artifactId>
<packaging>pom</packaging>
<modules>
<module>common-util</module>
<module>service-util</module>
<module>spring-security</module>
</modules>
<properties>
<maven.compiler.source>8</maven.compiler.source>
<maven.compiler.target>8</maven.compiler.target>
</properties>
</project>
common-util:
<?xml version="1.0" encoding="UTF-8"?>
<project xmlns="http://maven.apache.org/POM/4.0.0"
xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
xsi:schemaLocation="http://maven.apache.org/POM/4.0.0 http://maven.apache.org/xsd/maven-4.0.0.xsd">
<parent>
<artifactId>common</artifactId>
<groupId>org.example</groupId>
<version>1.0-SNAPSHOT</version>
</parent>
<modelVersion>4.0.0</modelVersion>
<artifactId>common-util</artifactId>
<properties>
<maven.compiler.source>8</maven.compiler.source>
<maven.compiler.target>8</maven.compiler.target>
</properties>
<dependencies>
<dependency>
<groupId>org.springframework.boot</groupId>
<artifactId>spring-boot-starter-web</artifactId>
<scope>provided </scope>
</dependency>
<dependency>
<groupId>io.jsonwebtoken</groupId>
<artifactId>jjwt</artifactId>
</dependency>
<dependency>
<groupId>org.projectlombok</groupId>
<artifactId>lombok</artifactId>
</dependency>
<dependency>
<groupId>com.alibaba</groupId>
<artifactId>fastjson</artifactId>
</dependency>
</dependencies>
</project>
service-util:
<?xml version="1.0" encoding="UTF-8"?>
<project xmlns="http://maven.apache.org/POM/4.0.0"
xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
xsi:schemaLocation="http://maven.apache.org/POM/4.0.0 http://maven.apache.org/xsd/maven-4.0.0.xsd">
<parent>
<artifactId>common</artifactId>
<groupId>org.example</groupId>
<version>1.0-SNAPSHOT</version>
</parent>
<modelVersion>4.0.0</modelVersion>
<artifactId>service-util</artifactId>
<properties>
<maven.compiler.source>8</maven.compiler.source>
<maven.compiler.target>8</maven.compiler.target>
</properties>
<dependencies>
<dependency>
<groupId>org.example</groupId>
<artifactId>common-util</artifactId>
<version>1.0-SNAPSHOT</version>
</dependency>
<dependency>
<groupId>org.springframework.boot</groupId>
<artifactId>spring-boot-starter-web</artifactId>
</dependency>
<dependency>
<groupId>com.baomidou</groupId>
<artifactId>mybatis-plus-boot-starter</artifactId>
</dependency>
<!--mysql-->
<dependency>
<groupId>mysql</groupId>
<artifactId>mysql-connector-java</artifactId>
</dependency>
<dependency>
<groupId>com.github.xiaoymin</groupId>
<artifactId>knife4j-spring-boot-starter</artifactId>
</dependency>
</dependencies>
</project>
spring-security:
<?xml version="1.0" encoding="UTF-8"?>
<project xmlns="http://maven.apache.org/POM/4.0.0"
xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
xsi:schemaLocation="http://maven.apache.org/POM/4.0.0 http://maven.apache.org/xsd/maven-4.0.0.xsd">
<parent>
<artifactId>common</artifactId>
<groupId>org.example</groupId>
<version>1.0-SNAPSHOT</version>
</parent>
<modelVersion>4.0.0</modelVersion>
<artifactId>spring-security</artifactId>
<properties>
<maven.compiler.source>8</maven.compiler.source>
<maven.compiler.target>8</maven.compiler.target>
</properties>
<dependencies>
<dependency>
<groupId>org.example</groupId>
<artifactId>common-util</artifactId>
<version>1.0-SNAPSHOT</version>
</dependency>
<!-- Spring Security依赖 -->
<dependency>
<groupId>org.springframework.boot</groupId>
<artifactId>spring-boot-starter-security</artifactId>
</dependency>
<dependency>
<groupId>org.springframework.boot</groupId>
<artifactId>spring-boot-starter-web</artifactId>
<scope>provided </scope>
</dependency>
<dependency>
<groupId>org.example</groupId>
<artifactId>model</artifactId>
<version>1.0-SNAPSHOT</version>
<scope>compile</scope>
</dependency>
<dependency>
<groupId>org.springframework.boot</groupId>
<artifactId>spring-boot-starter-data-redis</artifactId>
</dependency>
</dependencies>
</project>
model模块：
<?xml version="1.0" encoding="UTF-8"?>
<project xmlns="http://maven.apache.org/POM/4.0.0"
xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
xsi:schemaLocation="http://maven.apache.org/POM/4.0.0 http://maven.apache.org/xsd/maven-4.0.0.xsd">
<parent>
<artifactId>oa-parent</artifactId>
<groupId>org.example</groupId>
<version>1.0-SNAPSHOT</version>
</parent>
<modelVersion>4.0.0</modelVersion>
<artifactId>model</artifactId>
<properties>
<maven.compiler.source>8</maven.compiler.source>
<maven.compiler.target>8</maven.compiler.target>
</properties>
<dependencies>
<!--lombok用来简化实体类-->
<dependency>
<groupId>org.projectlombok</groupId>
<artifactId>lombok</artifactId>
</dependency>
<!--JavaMVC框架集成Swagger生成Api文档-->
<dependency>
<groupId>com.github.xiaoymin</groupId>
<artifactId>knife4j-spring-boot-starter</artifactId>
<scope>provided </scope>
</dependency>
<dependency>
<groupId>com.baomidou</groupId>
<artifactId>mybatis-plus-boot-starter</artifactId>
<scope>provided </scope>
</dependency>
</dependencies>
</project>
serive-oa模块：
<?xml version="1.0" encoding="UTF-8"?>
<project xmlns="http://maven.apache.org/POM/4.0.0"
xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
xsi:schemaLocation="http://maven.apache.org/POM/4.0.0 http://maven.apache.org/xsd/maven-4.0.0.xsd">
<parent>
<artifactId>oa-parent</artifactId>
<groupId>org.example</groupId>
<version>1.0-SNAPSHOT</version>
</parent>
<modelVersion>4.0.0</modelVersion>
<artifactId>service-oa</artifactId>
<properties>
<maven.compiler.source>8</maven.compiler.source>
<maven.compiler.target>8</maven.compiler.target>
</properties>
<dependencies>
<dependency>
<groupId>org.example</groupId>
<artifactId>model</artifactId>
<version>1.0-SNAPSHOT</version>
</dependency>
<dependency>
<groupId>org.example</groupId>
<artifactId>service-util</artifactId>
<version>1.0-SNAPSHOT</version>
</dependency>
<dependency>
<groupId>org.springframework.boot</groupId>
<artifactId>spring-boot-starter-test</artifactId>
<scope>test</scope>
</dependency>
<!--代码生成-->
<dependency>
<groupId>com.baomidou</groupId>
<artifactId>mybatis-plus-generator</artifactId>
<version>3.4.1</version>
</dependency>
<!--代码生成-->
<dependency>
<groupId>org.apache.velocity</groupId>
<artifactId>velocity-engine-core</artifactId>
<version>2.0</version>
</dependency>
<dependency>
<groupId>org.example</groupId>
<artifactId>spring-security</artifactId>
<version>1.0-SNAPSHOT</version>
</dependency>
<!--引入activiti的springboot启动器 -->
<dependency>
<groupId>org.activiti</groupId>
<artifactId>activiti-spring-boot-starter</artifactId>
<version>7.1.0.M6</version>
<exclusions>
<exclusion>
<artifactId>mybatis</artifactId>
<groupId>org.mybatis</groupId>
</exclusion>
</exclusions>
</dependency>
<!--引入vx公众号-->
<dependency>
<groupId>com.github.binarywang</groupId>
<artifactId>weixin-java-mp</artifactId>
<version>4.1.0</version>
</dependency>
</dependencies>
<build>
<finalName>${project.artifactId}</finalName>
<plugins>
<plugin>
<groupId>org.springframework.boot</groupId>
<artifactId>spring-boot-maven-plugin</artifactId>
</plugin>
</plugins>
<resources>
<resource>
<directory>src/main/java</directory>
<includes>
<include>**/*.yml
**/ *.properties</include>
<include>**/*.xml
false
src/main/resources
**/ *.yml</include>
<include>**/*.properties
**/ *.xml</include>
<include>**/*.png
false
三.MyBatis-Plus
官网：https://baomidou.com/
1.简介
MyBatis-Plus（简称 MP）是一个MyBatis的增强工具，在 MyBatis 的基础上只做增强不做改变，为简化开发、提高效率而生。
2.主要特点
- 无侵入：只做增强不做改变，引入它不会对现有工程产生影响，如丝般顺滑
- 强大的 CRUD 操作：内置通用 Mapper、通用 Service，仅仅通过少量配置即可实现单表大部分 CRUD 操作，更有强大的条件构造器，满足各类使用需求
- 支持 Lambda 形式调用：通过 Lambda 表达式，方便的编写各类查询条件，无需再担心字段写错
- 支持主键自动生成：支持多达 4 种主键策略（内含分布式唯一 ID 生成器 - Sequence），可自由配置，完美解决主键问题
- 内置代码生成器：采用代码或者 Maven 插件可快速生成 Mapper 、 Model 、 Service 、 Controller 层代码，支持模板引擎，更有超多自定义配置等您来使用
- 内置分页插件：基于 MyBatis 物理分页，开发者无需关心具体操作，配置好插件之后，写分页等同于普通 List 查询
- 分页插件支持多种数据库：支持 MySQL、MariaDB、Oracle、DB2、H2、HSQL、SQLite、Postgre、SQLServer 等多种数据库
3.依赖
com.baomidou
mybatis-plus-boot-starter
3.4.1
四.MyBatis-Plus入门
一般项目都是如下结构：
1.配置文件
配置 MySQL 数据库的相关配置及Mybatis-Plus日志（service-oa模块下）
application.yml：
spring:
application:
name: service-oa
profiles:
active: dev
application-dev.yml：
注意localtions扫描文件的路径（*表示当前目录下所有）
2.启动类
package com.example;
import org.mybatis.spring.annotation.MapperScan;
import org.springframework.boot.SpringApplication;
import org.springframework.boot.autoconfigure.SpringBootApplication;
@SpringBootApplication
@ComponentScan("com.example")
@MapperScan("com.example.*.mapper")
public class ServiceAuthApplication {
public static void main(String[] args) {
SpringApplication.run(ServiceAuthApplication.class, args);
}
}
3.实体类
这里先随便拿下个实体类出来介绍，用哪个创建哪个，也可以通过代码生成软件生成所有表对应的实体类。
已引入，实体类说明：
实体类注解详细文档：https://baomidou.com/pages/223848/
@TableName ：表名注解，标识实体类对应的表
@TableId：主键注解，type = IdType.AUTO（数据库 ID 自增）
@TableField：字段注解（非主键）
@TableLogic：逻辑删除
@ApiModel/ApiModelProperty：在实体类上边使用，标记类时swagger的解析类，方便
接口测试
@Data：自动生成get set方法！
package com.example.model.system;
import com.baomidou.mybatisplus.annotation.TableField;
import com.baomidou.mybatisplus.annotation.TableName;
import com.example.model.base.BaseEntity;
import io.swagger.annotations.ApiModel;
import io.swagger.annotations.ApiModelProperty;
import lombok.Data;
import java.util.List;
//data生成get set方法
@Data
@ApiModel(description = "用户")
@TableName("sys_user")
public class SysUser extends BaseEntity {
private static final long serialVersionUID = 1L;
@ApiModelProperty(value = "用户名")
@TableField("username")
private String username;
@ApiModelProperty(value = "密码")
@TableField("password")
private String password;
@ApiModelProperty(value = "姓名")
@TableField("name")
private String name;
@ApiModelProperty(value = "手机")
@TableField("phone")
private String phone;
@ApiModelProperty(value = "头像地址")
@TableField("head_url")
private String headUrl;
@ApiModelProperty(value = "部门id")
@TableField("dept_id")
private Long deptId;
@ApiModelProperty(value = "岗位id")
@TableField("post_id")
private Long postId;
@ApiModelProperty(value = "描述")
@TableField("description")
private String description;
@ApiModelProperty(value = "openId")
@TableField("open_id")
private String openId;
@ApiModelProperty(value = "状态（1：正常 0：停用）")
@TableField("status")
private Integer status;
@TableField(exist = false)
private List<SysRole> roleList;
//岗位
@TableField(exist = false)
private String postName;
//部门
@TableField(exist = false)
private String deptName;
}
4.Mapper类
com.baomidou.mybatisplus.core.mapper.BaseMapper这是Mybatis-Plus提供的默认Mapper接口。（注意@Mapper注解）
package com.example.auth.mapper;
import com.baomidou.mybatisplus.core.mapper.BaseMapper;
import com.example.model.system.SysRole;
import org.apache.ibatis.annotations.Mapper;
@Mapper
public interface SysRoleMapper extends BaseMapper<SysRole>{
}
当mapper文件继承basemapper类后，就已经默认封装了简单的查询，添加，删除接口，无需再自己编写。Mapper对应的xml文件也可以不用，除非要自己自定义一些高级功能：
5.Service类
package com.example.auth.service;
import com.example.model.auth.SysRole;
import com.baomidou.mybatisplus.extension.service.IService;
import java.util.List;
public interface SysRoleService extends IService<SysRole> {
}
com.baomidou.mybatisplus.extension.service.IService这是Mybatis-Plus提供的默认Service接口。
6.Service实现类Impl
implement实现对应的service接口（注意加上注解@Serivce）
@Service
public class SysRoleServiceImpl extends ServiceImpl<SysRoleMapper, SysRole> implements SysRoleService {
}
com.baomidou.mybatisplus.extension.service.impl.ServiceImpl这是Mybatis-Plus提供的默认Service接口实现。对应Mapper接口，以及实体类。
7.Controller类
@ResponseBody：告诉控制器返回对象会被自动序列化成JSON，并且传回HttpResponse这个对象。
@Controller的作用：声明该类是Controller层的Bean，将该类声明进入Spring容器中进行管理
@RestController：相当于Controller加ResponseBody共同作用的结果，但采用Restful风格的形式。
@RequestMapping注解是一个用来处理请求地址映射的注解，可用于映射一个请求或一个方法，可以用在类或方法上。
@Autowired：自动装配
@GetMapping
@PostMapping
@PutMapping
@DeleteMapping
@PatchMapping
从命名约定我们可以看到每个注释都是为了处理各自的传入请求方法类型，即*@GetMapping用于处理请求方法的GET类型，@ PostMapping用于处理请求方法的POST*类型等。
package com.example.auth.controller;
import com.example.auth.service.SysRoleService;
import com.example.model.auth.SysRole;
import org.springframework.beans.factory.annotation.Autowired;
import org.springframework.web.bind.annotation.GetMapping;
import org.springframework.web.bind.annotation.RequestMapping;
import org.springframework.web.bind.annotation.RestController;
import java.util.List;
@RestController
@RequestMapping("/admin/system/sysRole")
public class SysRoleController {
@Autowired
private SysRoleService sysRoleService;
@GetMapping("findAll")
public List<SysRole> findAll() {
List<SysRole> roleList = sysRoleService.list();
return roleList;
}
}
五.定义统一返回结果对象
项目中我们会将响应封装成json返回，一般我们会将所有接口的数据格式统一， 使前端(iOS Android, Web)对数据的操作更一致、轻松。
一般情况下，统一返回数据格式没有固定的格式，只要能描述清楚返回的数据状态以及要返回的具体数据就可以。但是一般会包含状态码（code）、返回消息（message）、数据（data）这几部分内容
例如，我们的系统要求返回的基本数据格式如下：
列表：
{
“code”: 200,
“message”: “成功”,
“data”: [
{
“id”: 2,
“roleName”: “系统管理员”
}
],
“ok”: true
}
分页：
{
“code”: 200,
“message”: “成功”,
“data”: {
“records”: [
{
“id”: 2,
“roleName”: “系统管理员”
},
{
“id”: 3,
“name”: “普通管理员”
}
],
“total”: 10,
“size”: 3,
“current”: 1,
“orders”: [],
“hitCount”: false,
“searchCount”: true,
“pages”: 2
},
“ok”: true
}
没有返回数据：
{
“code”: 200,
“message”: “成功”,
“data”: null,
“ok”: true
}
失败：
{
“code”: 201,
“message”: “失败”,
“data”: null,
“ok”: false
}
1.定义统一返回结果对象
操作模块：common-util
后续其他模块也会用到，故抽取到common-util模块
package com.example.common.result;
import lombok.Data;
/**
* 统一返回结果状态信息类
*
*/
@Data
public class Result<T> {
//返回码
private Integer code;
//返回消息
private String message;
//返回数据
private T data;
public Result(){}
// 返回数据
protected static <T> Result<T> build(T data) {
Result<T> result = new Result<T>();
if (data != null)
result.setData(data);
return result;
}
//封装具体返回数据
public static <T> Result<T> build(T body, Integer code, String message) {
Result<T> result = build(body);
result.setCode(code);
result.setMessage(message);
return result;
}
//封装返回数据
public static <T> Result<T> build(T body, ResultCodeEnum resultCodeEnum) {
Result<T> result = build(body);
//状态码
result.setCode(resultCodeEnum.getCode());
//信息
result.setMessage(resultCodeEnum.getMessage());
return result;
}
public static<T> Result<T> ok(){
return Result.ok(null);
}
/**
* 操作成功
* @param data baseCategory1List
* @param
* @return
*/
public static<T> Result<T> ok(T data){
Result<T> result = build(data);
return build(data, ResultCodeEnum.SUCCESS);
}
public static<T> Result<T> fail(){
return Result.fail(null);
}
/**
* 操作失败
* @param data
* @param
* @return
*/
public static<T> Result<T> fail(T data){
Result<T> result = build(data);
return build(data, ResultCodeEnum.FAIL);
}
public Result<T> message(String msg){
this.setMessage(msg);
return this;
}
public Result<T> code(Integer code){
this.setCode(code);
return this;
}
}
package com.example.common.result;
import lombok.Getter;
/**
* 统一返回结果状态信息类
*
*/
@Getter
public enum ResultCodeEnum {
SUCCESS(200,"成功"),
FAIL(201, "失败"),
LOGIN_ERROR(208,"认证失败")
;
private Integer code;
private String message;
private ResultCodeEnum(Integer code,String message) {
this.code = code;
this.message = message;
}
}
2.改造controller方法
对比之前：现在所有的返回值都能设置成一个固定的Result结构
@GetMapping("findAll")
public List<SysRole> findAll() {
List<SysRole> roleList = sysRoleService.list();
return roleList;
}
@GetMapping("findAll")
public Result<List<SysRole>> findAll() {
List<SysRole> roleList = sysRoleService.list();
return Result.ok(roleList);
}
六.knife4j
文档地址： https://doc.xiaominfo.com/
knife4j是为Java MVC框架集成Swagger生成Api文档的增强解决方案。
1.Swagger介绍
前后端分离开发模式中，api文档是最好的沟通方式。
Swagger 是一个规范和完整的框架，用于生成、描述、调用和可视化 RESTful 风格的 Web 服务。
1、及时性 (接口变更后，能够及时准确地通知相关前后端开发人员)
2、规范性 (并且保证接口的规范性，如接口的地址，请求方式，参数及响应格式和错误信息)
3、一致性 (接口信息一致，不会出现因开发人员拿到的文档版本不一致，而出现分歧)
4、可测性 (直接在接口文档上进行测试，以方便理解业务)
2.集成knife4j
knife4j属于service模块公共资源，因此我们集成到service-uitl模块
1 添加依赖
操作模块：service-uitl
<dependency>
<groupId>com.github.xiaoymin</groupId>
<artifactId>knife4j-spring-boot-starter</artifactId>
</dependency>
2 添加knife4j配置类
操作模块：service-uitl
package com.example.common.config.knife4j;
import org.springframework.context.annotation.Bean;
import org.springframework.context.annotation.Configuration;
import springfox.documentation.builders.ApiInfoBuilder;
import springfox.documentation.builders.ParameterBuilder;
import springfox.documentation.builders.PathSelectors;
import springfox.documentation.builders.RequestHandlerSelectors;
import springfox.documentation.schema.ModelRef;
import springfox.documentation.service.ApiInfo;
import springfox.documentation.service.Contact;
import springfox.documentation.service.Parameter;
import springfox.documentation.spi.DocumentationType;
import springfox.documentation.spring.web.plugins.Docket;
import springfox.documentation.swagger2.annotations.EnableSwagger2WebMvc;
import java.util.ArrayList;
import java.util.List;
/**
* knife4j配置信息 网页接口测试
*/
@Configuration
@EnableSwagger2WebMvc
public class Knife4jConfig {
@Bean
public Docket adminApiConfig(){
List<Parameter> pars = new ArrayList<>();
ParameterBuilder tokenPar = new ParameterBuilder();
tokenPar.name("token")
.description("用户token")
.defaultValue("")
.modelRef(new ModelRef("string"))
.parameterType("header")
.required(false)
.build();
pars.add(tokenPar.build());
//添加head参数end
Docket adminApi = new Docket(DocumentationType.SWAGGER_2)
.groupName("adminApi")
.apiInfo(adminApiInfo())
.select()
//只显示admin路径下的页面
.apis(RequestHandlerSelectors.basePackage("com.example"))
.paths(PathSelectors.regex("/admin/.*"))
.build()
.globalOperationParameters(pars);
return adminApi;
}
private ApiInfo adminApiInfo(){
return new ApiInfoBuilder()
.title("后台管理系统-API文档")
.description("本文档描述了后台管理系统微服务接口定义")
.version("1.0")
.contact(new Contact("example", "http://example.com", "[email protected]"))
.build();
}
}
3 Controller层添加注解
如上介绍的类上加@Api（tags = “”） 方法上加ApiOperation (value = “”)
4 测试
七.分页查询
1.分页插件
操作模块：service-uitl，service公共资源
说明：我们将@MapperScan(“com.example.auth.mapper”)提取到该配置类上面，统一
管理，启动类就不需要了。不止是auth 以及以后的service-oa下的所有功能如：process
wechat都需要在里面配置扫描。
package com.example.common.config.mp;
import com.baomidou.mybatisplus.annotation.DbType;
import com.baomidou.mybatisplus.autoconfigure.ConfigurationCustomizer;
import com.baomidou.mybatisplus.extension.plugins.MybatisPlusInterceptor;
import com.baomidou.mybatisplus.extension.plugins.inner.PaginationInnerInterceptor;
import org.mybatis.spring.annotation.MapperScan;
import org.springframework.context.annotation.Bean;
import org.springframework.context.annotation.Configuration;
/**
* 分页插件
*/
@Configuration
@MapperScan(basePackages = {"com.example.auth.mapper","com.example.process.mapper","com.example.wechat.mapper"})
public class MybatisPlusConfig {
/**
* 新的分页插件,一缓和二缓遵循mybatis的规则,需要设置 MybatisConfiguration#useDeprecatedExecutor = false 避免缓存出现问题(该属性会在旧插件移除后一同移除)
*/
@Bean
public MybatisPlusInterceptor mybatisPlusInterceptor() {
MybatisPlusInterceptor interceptor = new MybatisPlusInterceptor();
interceptor.addInnerInterceptor(new PaginationInnerInterceptor(DbType.MYSQL));
return interceptor;
}
@Bean
public ConfigurationCustomizer configurationCustomizer() {
return configuration -> configuration.setUseDeprecatedExecutor(false);
}
}
2.分页controller
//条件分页查询
//page 当前页 limit 每页显示记录数
//SysRoleQueryVo 条件对象
@ApiOperation("条件分页查询")
@GetMapping("{page}/{limit}")
public Result pageQueryRole(@PathVariable Long page,
@PathVariable Long limit,
SysRoleQueryVo sysRoleQueryVo) {
//调用service的方法实现
//1 创建Page对象，传递分页相关参数
//page 当前页 limit 每页显示记录数
Page<SysRole> pageParam = new Page<>(page,limit);
//2 封装条件，判断条件是否为空，不为空进行封装
LambdaQueryWrapper<SysRole> wrapper = new LambdaQueryWrapper<>();
String roleName = sysRoleQueryVo.getRoleName();
if(!StringUtils.isEmpty(roleName)) {
//封装 like模糊查询
wrapper.like(SysRole::getRoleName,roleName);
}
//3 调用方法实现
IPage<SysRole> pageModel = sysRoleService.page(pageParam, wrapper);
return Result.ok(pageModel);
}
3.其他controller
@ApiOperation(value = "获取")
@GetMapping("get/{id}")
public Result get(@PathVariable Long id) {
SysRole role = sysRoleService.getById(id);
return Result.ok(role);
}
@ApiOperation(value = "新增角色")
@PostMapping("save")
public Result save(@RequestBody @Validated SysRole role) {
sysRoleService.save(role);
return Result.ok();
}
@ApiOperation(value = "修改角色")
@PutMapping("update")
public Result updateById(@RequestBody SysRole role) {
sysRoleService.updateById(role);
return Result.ok();
}
@ApiOperation(value = "删除角色")
@DeleteMapping("remove/{id}")
public Result remove(@PathVariable Long id) {
sysRoleService.removeById(id);
return Result.ok();
}
@ApiOperation(value = "根据id列表删除")
@DeleteMapping("batchRemove")
public Result batchRemove(@RequestBody List<Long> idList) {
sysRoleService.removeByIds(idList);
return Result.ok();
}
八.配置日期时间格式
application-dev.yml添加以下内容
jackson:
date-format: yyyy-MM-dd HH:mm:ss
time-zone: GMT+8
九.统一异常处理
我们想让异常结果也显示为统一的返回结果对象，并且统一处理系统的异常信息，那么需要统一异常处理。
创建统一异常处理器
操作模块：service-util
package com.example.common.config.exception;
import com.example.common.result.Result;
import org.springframework.web.bind.annotation.ControllerAdvice;
import org.springframework.web.bind.annotation.ExceptionHandler;
import org.springframework.web.bind.annotation.ResponseBody;
@ControllerAdvice
public class GlobalExceptionHandler {
//全局异常处理，执行方法
@ExceptionHandler(Exception.class)
//返回json数据
@ResponseBody
public Result error(Exception e){
e.printStackTrace();
return Result.fail();
}
//特定异常处理
@ExceptionHandler(ArithmeticException.class)
@ResponseBody
public Result error(ArithmeticException e){
e.printStackTrace();
return Result.fail().message("执行了特定异常处理");
}
//执行自定义异常
@ExceptionHandler(GuiguException.class)
@ResponseBody
public Result error(GuiguException e){
e.printStackTrace();
return Result.fail().message(e.getMessage()).code(e.getCode());
}
}
自定义异常
package com.example.common.config.exception;
import com.example.common.result.ResultCodeEnum;
import lombok.Data;
/**
* 自定义全局异常类
*
*/
@Data
public class GuiguException extends RuntimeException {
//异常状态码
private Integer code;
//描述信息
private String message;
/**
* 通过状态码和错误消息创建异常对象
* @param code
* @param message
*/
public GuiguException(Integer code, String message) {
super(message);
this.code = code;
this.message = message;
}
/**
* 接收枚举类型对象
* @param resultCodeEnum
*/
public GuiguException(ResultCodeEnum resultCodeEnum) {
super(resultCodeEnum.getMessage());
this.code = resultCodeEnum.getCode();
this.message = resultCodeEnum.getMessage();
}
@Override
public String toString() {
return "GuliException{" +
"code=" + code +
", message=" + this.getMessage() +
'}';
}
}