# common-starter
**Repository Path**: javacodekit2010/common-starter
## Basic Information
- **Project Name**: common-starter
- **Description**: 易水公共组件是一个基于springboot的高度封装的零侵入式通用型组件，在对spring security和oauth2高度可定制化的功能封装外，还支持第三方登录和sso单点登录功能，使用户能够快速开启QQ登录和微信登录能力，搭建属于自己的认证/授权中心。此外，工具还提供各种常见的图形验证码、短信验证码和邮件验证码功能，并支持跨域设置和全局异常捕获功能，实现自定义异常信息提示。同时，组件还包含swagger接口文档功能，支持一键导出离线接口使用文档。最后，组件还提供了一个单表操作工具，对于单表操作用户可以直接使用，不用再进行简单重复性的CRUD操作
- **Primary Language**: Java
- **License**: Apache-2.0
- **Default Branch**: master
- **Homepage**: http://doc.yishuifengxiao.com/
- **GVP Project**: No
## Statistics
- **Stars**: 0
- **Forks**: 100
- **Created**: 2021-12-27
- **Last Updated**: 2021-12-27
## Categories & Tags
**Categories**: Uncategorized
**Tags**: None
## README
### 一 项目背景
在日常开发过程中，时常发现有一些简单的功能会被经常使用到，又没有一个比较好用的功能集合，因此在开发项目是需要反复配置，造成了大量不必要的重复性简单劳动，所以在从过往经验的基础上对日常使用到功能进行了一个通用封装，形成了 **易水公共组件** ，方便后期项目开发。 本着"一次开发,开箱即用"的原则，组件在开发时遵守以下几点：
- 开箱即用，可以选择性开启仅仅使用到的功能
- 基本配置, 在开启本组件功能后，无须二次配置即能使用组件的基本工功能。
- 个性配置，组件提供大量的配置属性，能通过预留的配置属性自定义组件功能。
- 高级配置，在系统默认配置和个性配置不能满足开发需要时，能通过自定义组件中的某些元件实现高级配置。
交流 QQ 群 :
(群号 624646260)
易水公共组件是基于springboot的高度封装的通用型组件，在对spring security和spring security oauth2高度可定制化的功能封装外，还支持第三方登录和sso单点登录功能，使用户能够快速开启QQ登录和微信登录能力，搭建属于自己的认证/授权中心。
此外，工具还提供各种常见的图形验证码、短信验证码和邮件验证码功能，并支持跨域设置和全局异常捕获功能，实现自定义异常信息提示。
另外，组件还包含swagger接口文档功能，支持一键导出离线接口使用文档。
最后，组件提供了大量丰富的配置属性，支持通过属性配置完成各项功能设置，真正实现零侵入、防止暴力破解的无缝接入功能。
在保证功能灵活可用的基础上，易水公共组件还针对国人的使用习惯进行了一些本地化配置，提供了详细完整的中文使用说明文档。总的来说，易水公共组件在保证单机应用的高效性能同时，还能支持分布式署环境，能自动识别单体应用还是集群应用，是目前主流的微服务开发过程中不可或缺的重要伙伴。
### 二 快速启动
在项目中加入以下依赖
```xml
com.yishuifengxiao.common
common-spring-boot-starter
5.3.0
```
易水组件已经发布到maven中央仓库，最新版本的依赖可参见 [https://mvnrepository.com/artifact/com.yishuifengxiao.common/common-spring-boot-starter](https://mvnrepository.com/artifact/com.yishuifengxiao.common/common-spring-boot-starter)。
在项目中引入上述依赖之后，就可以直接使用易水组件的相关功能了。
#### 2.1 数据库操作
例如操作数据库时再也不需要编写简单的CURD的操作代码，只需要在项目中加入以下代码即可操作数据库了：
```java
@Autowired
private JdbcHelper jdbcHelper;
```
也可以使用静态工具类`JdbcUtil `对数据进行操作。
下面是数据库操作工具`JdbcHelper `的一些典型接口
```java
/**
* 根据主键从指定表查询一条数据
*
* @param POJO类
* @param clazz POJO类
* @param primaryKey 主键
* @return 查询到的数据
*/
T findByPrimaryKey(Class clazz, Object primaryKey);
/**
* 查询所有符合条件的数据
*
* @param POJO类
* @param t 查询条件
* @return 符合条件的数据
*/
T findOne(T t);
/**
* 查询所有符合条件的数据
*
* @param POJO类
* @param t 查询条件
* @param order 排序条件
* @return 符合条件的数据
*/
List findAll(T t, Order order);
/**
* 根据主键全属性更新方式更新一条数据
*
* @param POJO类
* @param t 待更新的数据
* @return 受影响的记录的数量
*/
int updateByPrimaryKey(T t);
/**
* 根据主键可选属性更新方式更新一条数据
*
* @param POJO类
* @param t 待更新的数据
* @return 受影响的记录的数量
*/
int updateByPrimaryKeySelective(T t);
/**
* 根据主键删除一条数据
*
* @param POJO类
* @param clazz 操作的对象
* @param primaryKey 主键值
* @return 受影响的记录的数量
*/
int deleteByPrimaryKey(Class clazz, Object primaryKey);
/**
* 以全属性方式新增一条数据
*
* @param POJO类
* @param t 待新增的数据
* @return 受影响的记录的数量
*/
int insert(T t);
/**
* 以可选属性方式新增一条数据
*
* @param POJO类
* @param t 待新增的数据
* @return 受影响的记录的数量
*/
int insertSelective(T t);
```
#### 2.2 spring security使用
在使用组件的安全管理功能时，需要依赖于spring security的功能。
1 在项目中加入 spring security依赖
```
org.springframework.boot
spring-boot-starter-security
```
2 在项目中加入以下启动代码
下面的代码用户应该保证能被 `@ComponentScan`扫描到。
```
@Configuration
@EnableWebSecurity
public class SecurityConfig extends AbstractSecurityConfig {
@Override
protected void configure(HttpSecurity http) throws Exception {
super.configure(http);
}
}
```
该代码的示例代码可参见 `com.yishuifengxiao.common.security.SecurityConfig`
实现 `UserDetailsService` 接口，完成自己的授权逻辑，然后按照名字 `userDetailsService`将其注入到spring 之中。
【特别注意】
在用户未按照本步骤配置自己的授权逻辑时，组件会默认进行一个缺省实现。在缺省实现的情况下，用户能使用任意用户名配合密码(12345678)进行登录。
加入上述配置之后，只有组件中内置的默认路径能通过授权，访问其他的url都被重定向到 `/index`这个地址，具体的配置及原因请参照后续说明。
注入的`UserDetailsService`实例的名字必须为`userDetailsService`,否则组件会使用默认的缺省实现。
进行上述配置后，组件的安全管理功能是开启的。
#### 2.3 验证码使用
将验证码工具注入到需要使用到验证码的地方
注入代码如下：
```
@Autowired
private CodeProcessor codeProcessor;
```
在注入一个验证码工具后，通过以下代码即可快速生成一个图形验证码。 具体的示例代码如下：
```
@GetMapping("/code/image")
@ResponseBody
public Response image(HttpServletRequest request, HttpServletResponse response){
try {
codeProcessor.create(new ServletWebRequest(request, response),CodeType.IMAGE);
} catch (ValidateException e) {
return Response.error(e.getMessage());
}
return Response.suc();
}
```
在以上代码后，用户即可通过 `http://ip:port/code/image?image=唯一的随机值` 获取图形验证码了。
#### 2.4 swagger-ui
快速启动
在配置文件中加入以下配置即可快速开启swagger-ui功能。
```
yishuifengxiao.swagger.base-package= 需要扫描的控制器代码的路径
```
加入上述配置后即可通过`http://ip:port/doc.html`查看swagger-ui增强文档。
【特别鸣谢】
此项功能中的doc.html界面中功能使用到了刀哥的 swagger-bootstrap-ui 1.9.x 版本中的功能 ，在此特别感谢 刀哥 的大力支持，关于swagger-bootstrap-ui的详细说明请参见刀哥的 [swagger-bootstrap-ui文档](https://doc.xiaominfo.com/guide/),如需要更多强悍的swagger功能，使用刀哥的2.0.x以及以上的原生版本。
#### 2.5 全局异常处理
在默认情况下，全局异常处理功能已经开启，如果要关闭此功能，可以通过以下配置进行
```
yishuifengxiao.error.enable=false
```
再开启此功能的情况下，可以根据不同的异常配置不同的提示信息，配置格式下
```
yishuifengxiao.error.map.异常类=提示信息
```
示例如下
```
yishuifengxiao.error.map.ConstraintViolationException=已有重复数据
```
在上述配置中ConstraintViolationException是异常类的名字，例如ConstraintViolationException、DataIntegrityViolationException和DuplicateKeyException,对于多个需要提示的错误，配置成多行即可，例如
```
yishuifengxiao.error.map.ConstraintViolationException=全局异常捕获到异常信息了
yishuifengxiao.error.map.DataIntegrityViolationException=全局异常捕获到异常信息了
yishuifengxiao.error.map.DuplicateKeyException=全局异常捕获到异常信息了
```
#### 2.6 全局参数校验
全局参数校验主要是解决对于开启了参数校验的情况下需要每次手动判断是否存在异常信息导致产生重复代码的问题而创建了一个AOP切面，同意进行参数校验的结果判断的问题。
在默认情况下，全局参数校验结果判断功能是开启的，如果需要关闭此功能，可以通过以下配置进行
```
yishuifengxiao.aop.enable=false
```
在开启全局参数校验结果判断功能的前提下，要想此功能生效，还需要在Controller的方法里携带上`BindingResult`参数。一个简单的例子如下:
```
@AuthUser(required = true)
@ApiOperation(value = "更新用户信息", notes = "根据id更新用户基本信息")
@PostMapping("/updateUser")
@ResponseBody
public Response