项目基本配置和使用相关技术栈文档【必读】
-
项目使用 Lombok 插件简化开发，请自行在编译器中安装，不安装会报错但不影响运行，常用注解说明：
-
@Data：自动生成get、set等方法 -
@Slf4j：日志打印可直接使用log.info()等 - 更多详见开发经验章节文档
-
- 配置文件可使用Jasypt加密，可到
cn.exrick.xboot.common包中找到 JasyptUtil 工具类生成加解密结果，当检测到格式为ENC(xxx)时会自动解密，当然也可直接明文（生产环境中可通过环境变量、命令行等形式进行设置）
# 配置文件加密key 生产环境中可通过环境变量、命令行等形式进行设置
jasypt:
encryptor:
password: xboot
spring:
# 数据源
datasource:
# Jasypt加密 可到common-utils中找到JasyptUtil加解密工具类生成加密结果 格式为ENC(加密结果)
password: ENC(F4B0s6u9xcDw3V+P0qC4CA==)- 启用Elasticsearch，操作日志使用ES或数据库记录配置
spring:
# Elasticsearch
data:
elasticsearch:
# 暂未使用ES 关闭其持久化存储
repositories:
enabled: true
xboot:
# 日志记录方式 true使用Elasticsearch记录(需启动并配置ES) false记录至数据库中(默认)
logRecord:
es: false- 日志注解使用
@SystemLog(description="操作日志名称", type=日志类型)- 日志类型type枚举类相关候选值：
OPERATION（默认，用户操作相关）、LOGIN（用户登录），可自定义添加修改
- 日志类型type枚举类相关候选值：
- 为方便前端配置代理，所有接口建议以统一路径例如“/xboot”开头（当然后端也可配置
context-path） - 登录成功后前端在返回的
result字段中保存token（因登录接口已需要图片验证码验证，需带上验证码参数，详见文档 验证码过滤器使用 或 Swagger接口文档统一认证 部分）
- 之后的请求中请在header或参数中添加该token参数即可，默认KEY为
accessToken（SecurityConstant中可修改）
xboot:
token:
# 默认为true，token将存入redis，并具有单点登录功能 设为false使用JWT交互
redis: true
# 是否开启单设备登陆 仅当token交互方式为redis时生效（默认60分钟内无请求自动失效，下方可配置）
sdl: true
# token中存储用户权限数据 设为true开启后可避免每次请求再获取用户权限，但有可能导致编辑权限菜单后无法读取到最新权限数据（需用户重新登录）
storePerms: true
# token过期时间（分钟）
tokenExpireTime: 60
# 用户选择保存登录状态对应token过期时间（天）
saveLoginTime: 7
# 限制用户登陆错误次数（次）
loginTimeLimit: 10
# 错误超过次数后多少分钟后才能继续登录（分钟）
loginAfterTime: 10- 忽略鉴权url配置（不需要登录认证 开放的接口 支持通配符）
# 忽略鉴权url
ignored:
urls:
- /xboot/user/regist
- 分布式限流(基于Redis令牌桶算法)
- 全局限流
xboot: # 全局限流 ratelimit: enable: true # 每1秒内 timeout: 1000 # 总限制100个请求 limit: 100 # IP限流 iplimit: enable: true # 每1秒内 timeout: 1000 # 每个ip限制15个请求 limit: 15
- 指定方法限流注解
@RateLimiter(limit = 1, timeout = 5000)
- 自定义多维度IP、uid限流示例
@Autowired private RedisRaterLimiter redisRaterLimiter; // IP限流 1秒限1个请求 String token = redisRaterLimiter.acquireToken(ip, 1, 1000); if (StrUtil.isBlank(token)) { throw new XbootException("你手速怎么这么快，请点慢一点"); }
- 配置无需限流的资源或接口
# 忽略url
ignored:
# 限流及黑名单不拦截的路径
limitUrls:
- /**/*.js
- /**/*.css
- /**/*.png
- /**/*.ico- 分布式同步锁(基于Spring集成实现的Redis同步锁简单封装)
@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方法即可生成相关代码，别忘了在实体类中添加相关字段，运行项目后将自动生成数据库表，详见后面代码生成章节文档
- 配置失效过期时间
xboot:
# 使用Spring @Cacheable注解失效时间
cache:
# 过期时间单位 支持day、hour、minute对应天、小时、分钟
unit: day
# 过期时间 永久不过期设为-1
time: 15- 使用示例
@CacheConfig(cacheNames = "user")
public interface UserService extends XbootBaseService<User,String> {
@Cacheable(key = "#username")
User findByUsername(String username);
}- 删除刷新注解
@CacheEvict(key = "#u.username") - 注意手动删除刷新缓存时key为：
user::username
- 在
cn.exrick.xboot.modules.quartz.jobs包下写好好你的定时任务类，参考代码中已有2个定时任务Job示例 - 启动应用在后台页面“定时任务”菜单添加配置你写的的定时任务类保存成功后将开始执行
- Spring Security官方推荐注解表达式权限管理，当然你可以在XBoot权限菜单中动态配置，更佳灵活
- @PreAuthorize("authenticated")
- @PreAuthorize("hasAuthority('SCOPE_add')")
- @PreAuthorize("hasRole('ADMIN')")
- @PreAuthorize("hasRole('ADMIN') AND hasRole('USER')")
- @PreAuthorize("hasRole('ADMIN') OR hasRole('USER')")
- 需要校验的实体类字段或Controller请求参数加上JSR校验注解后，Controller请求参数前加上
@Valid注解。注意对于@PathVariable或@RequestParam参数的校验，记得在Controller类上添加@Validated注解。已全局封装参数、@ResponseBody参数校验异常处理 - 常用JSR/Jakarta Bean Validation提供的校验注解:
- @NotNull(message=) 必须不能为 null
- @Email(message=) 必须为邮箱格式
- @Size(max=, min=)` 大小必须在指定的范围内
- @Pattern(regex=, message=) 必须符合指定的正则表达式
- 更多及使用方法详见开发经验章节文档
- 当然可修改数据库所有编码默认为
utf8mb4，为了节省空间，建议请修改具体需要的字符型字段的编码及排序规则为utf8mb4即可，如：
ALTER TABLE 表名 MODIFY COLUMN 列名 varchar(256) CHARACTER SET utf8mb4 COLLATE utf8_general_ci;