基本开发指南 · XBoot前后端分离开发平台文档

### 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; ```