### Lombok插件安装 - 项目使用 [Lombok](https://projectlombok.org/) 插件简化开发,请自行在编译器中安装,不安装会报错但不影响运行,常用注解说明: - `@Data`:自动生成get、set等方法 - `@Slf4j`:日志打印可直接使用`log.info()`等 - 更多详见文档 [开发经验章节](https://www.kancloud.cn/exrick/xboot/1684587) 部分 ### 配置文件加密 - 配置文件可使用Jasypt加密,可到 `cn.exrick.xboot.common` 包中找到 JasyptUtil 工具类生成加解密结果,当检测到格式为`ENC(xxx)`时会自动解密,当然也可直接明文(生产环境中可通过环境变量、命令行等形式进行设置) ```yaml # 配置文件加密key 生产环境中可通过环境变量、命令行等形式进行设置 jasypt: encryptor: password: xboot spring: # 数据源 datasource: # Jasypt加密 可到common-utils中找到JasyptUtil加解密工具类生成加密结果 格式为ENC(加密结果) password: ENC(F4B0s6u9xcDw3V+P0qC4CA==) ``` ### 启用Elasticsearch与配置日志记录位置 - 启用Elasticsearch,操作日志使用ES或数据库记录配置 ```yaml spring: # Elasticsearch data: elasticsearch: # 启用 repositories: enabled: true autoconfigure: exclude: # 取消排除 # - org.springframework.boot.autoconfigure.data.elasticsearch.ReactiveElasticsearchRestClientAutoConfiguration xboot: # 日志记录方式 设置为true logRecord: es: true ``` ### 操作日志注解使用 - 日志注解使用`@SystemLog(description="操作日志名称", type=日志类型)` - 日志类型type枚举类相关候选值:`OPERATION`(默认,用户操作相关)、`LOGIN`(用户登录),可自定义添加修改 ### 接口相关 - 为方便前端配置代理,所有接口建议以统一路径例如“/xboot”开头(当然后端也可配置`context-path`) - 登录成功后前端在返回的`result`字段中保存token令牌集合(因登录接口已添加图片验证码验证,需带上图片验证码所需参数,具体使用详见文档 [验证码开发使用](https://www.kancloud.cn/exrick/xboot/1136968) 或 [接口文档使用及认证](https://www.kancloud.cn/exrick/xboot/1027473) 部分) <img src="https://ooo.0o0.ooo/2019/02/04/5c581d77f2cfc.png" width="600px"/> - 之后的请求中请在header或参数中添加该token参数即可,默认KEY为`accessToken`(`SecurityConstant`中可修改) <img src="https://ooo.0o0.ooo/2019/02/04/5c581d78061b4.png" width="600px"/> ### 无状态风格Token令牌交互相关配置 ```yaml xboot: token: # 默认为true,token将存入redis,并具有单设备登录、自动刷新token过期时间功能 设为false使用JWT交互 redis: true # 是否开启单设备登陆 一个账号仅支持同时一台设备登录 仅当token交互方式为redis时生效 sdl: false # token中存储用户权限数据 开启后可避免每次请求再获取用户权限,但有可能导致编辑权限菜单后无法读取到最新权限数据(需用户重新登录) storePerms: true # token过期时间 redis模式有请求自动刷新过期时间(分钟) tokenExpireTime: 60 # 用户选择 保存登录状态/记住我 对应token过期时间 不会自动刷新过期时间(天) saveLoginTime: 7 # 限制用户登陆错误次数(次) loginTimeLimit: 10 # 错误超过次数后多少分钟后才能继续登录(分钟) loginAfterTime: 10 ``` ### 无需登录认证接口配置 - 忽略鉴权url配置(不需要登录认证 开放的接口 支持通配符) ``` # 忽略鉴权url ignored: urls: - /xboot/auth/login ``` ### 限流配置 - 分布式限流(基于Redis令牌桶算法) - 全局限流 ```yaml xboot: # 全局限流 ratelimit: enable: true # 每1秒内 timeout: 1000 # 总限制100个请求 limit: 100 # IP限流 iplimit: enable: true # 每1秒内 timeout: 1000 # 每个ip限制15个请求 limit: 15 ``` - 指定方法限流注解(详见注解源码注释) ```java /** * name 自定义限流切入点名称 类型long 默认类的引用路径+方法名 * rate 限流速率(时间间隔内最大请求个数) 类型long 默认5 * rateInterval 速率间隔 单位毫秒 类型long 默认1000 * ipLimit 是否启用IP限流(加上IP作为name标识)类型boolean 默认false */ @RateLimiter(rate = 1, rateInterval = 5000) ``` - 自定义多维度IP、uid限流示例(可选基于内存的令牌桶算法) ```java @Autowired private RedisRaterLimiter redisRaterLimiter; // IP限流 1秒限1个请求 基于Redis的令牌桶算法 String token = redisRaterLimiter.acquireByRedis(ip, 1, 1000); // 基于内存的令牌桶算法 每秒限1个请求 String token = redisRaterLimiter.acquireByGuava(1); if (StrUtil.isBlank(token)) { throw new XbootException("你手速怎么这么快,请点慢一点"); } ``` - 配置无需限流的资源或接口 ```yml # 忽略url ignored: # 限流及黑名单不拦截的路径 limitUrls: - /**/*.js - /**/*.css - /**/*.png - /**/*.ico ``` ### 文件上传大小限制 ```yml xboot: # 文件大小上传配置 单位MB maxUploadFile: 5 ``` ### 同步锁使用 - 分布式同步锁 ```java @Autowired private RedisLockTemplate redisLockTemplate; redisLockTemplate.execute("订单流水号", 3, TimeUnit.SECONDS, new Callback() { @Override public Object onGetLock() throws InterruptedException { // TODO 获得锁后要做的事 log.info("生成订单流水号"); return null; } @Override public Object onTimeout() throws InterruptedException { // TODO 未获取到锁(获取锁超时)后要做的事 log.info("oops 没拿到锁"); return null; } }); ``` ### 后端代码生成 - 后端代码生成方法在 `cn.exrick.xboot.generator` 包中的 `XbootGenerator.java` 或`XbootMPGenerator.java` 工具类,支持JPA或Mybatis-Plus代码生成,修改好生成类配置后运行主函数main方法即可生成相关代码,别忘了在实体类中添加相关字段,运行项目后将自动生成数据库表,详见文档[代码生成部分](https://www.kancloud.cn/exrick/xboot/1021397) ### Spring缓存注解 - 配置失效过期时间 ```yml xboot: # 使用Spring @Cacheable注解失效时间 cache: # 缓存过期时间 Duration类型 D–天 H小时 M–分钟 S–秒 永久不过期设为非正值 timeToLive: 15D ``` - 使用示例 ```java @CacheConfig(cacheNames = "user") public interface UserService extends XbootBaseService<User,String> { @Cacheable(key = "#username") User findByUsername(String username); } ``` - 删除刷新注解 `@CacheEvict(key = "#u.username")` - 注意手动删除刷新缓存时key为:`user::username` ### Quartz定时任务使用 - 在`cn.exrick.xboot.modules.quartz.jobs`包下编写好你的定时任务类,参考代码中已有2个定时任务Job示例 - 启动应用在后台页面“定时任务”菜单添加配置你写的的定时任务类保存成功后将开始执行 - 注意在Quartz中注入Bean需使用构造setter注入方式或使用`SpringUtil.getBean("你的类名")`工具类 ### Spring Security官方推荐权限管理 - Spring Security官方推荐[注解表达式权限管理](https://docs.spring.io/spring-security/site/docs/5.4.1/reference/html5/#el-common-built-in)(当然你可以在XBoot权限菜单中动态配置,更佳灵活) * @PreAuthorize("isAuthenticated()") * @PreAuthorize("hasAuthority('read')") * @PreAuthorize("hasAnyAuthority('read', 'write')") * @PreAuthorize("hasRole('ADMIN')") * @PreAuthorize("hasAnyRole('ADMIN', 'USER')") * @PreAuthorize("hasRole('ADMIN') and hasRole('USER')") * @PreAuthorize("hasRole('ADMIN') or hasRole('USER')") ### Spring自带定时:`@Scheduled(cron="cron表达式")` ### Spring异步:`@Async` ### 参数校验注解 - 需要校验的实体类字段或Controller请求参数加上JSR校验注解后,Controller请求参数前加上`@Valid`注解。注意对于`@PathVariable`或`@RequestParam`参数的校验,记得在Controller类上添加`@Validated`注解。已全局封装`参数、@ResponseBody`参数校验异常处理 - 常用JSR/Jakarta Bean Validation提供的校验注解: - @NotNull(message=) 必须不能为 null - @Email(message=) 必须为邮箱格式 - @Size(max=, min=) 大小必须在指定的范围内 - @Pattern(regex=, message=) 必须符合指定的正则表达式 - 更多及使用方法详见文档[告别996-参数校验部分](https://www.kancloud.cn/exrick/xboot/1684588) ### MySQL数据库存储Emoji - 如果需要存储Emoji表情、不常用的汉字,以及任何新增的Unicode字符,需要兼容四字节Unicode的字符集`utf8mb4`。当然可修改数据库所有编码默认为`utf8mb4`,为了节省空间,建议请修改具体需要的字符型字段的编码及排序规则为`utf8mb4`即可,如: ```sql ALTER TABLE 表名 MODIFY COLUMN 列名 varchar(256) CHARACTER SET utf8mb4 COLLATE utf8mb4_general_ci; ```