Skip to content

项目基本配置和使用相关技术栈文档【必读】

Jump to bottom
Exrick edited this page May 5, 2020 · 22 revisions

Lombok插件安装

  • 项目使用 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与配置日志记录位置

  • 启用Elasticsearch，操作日志使用ES或数据库记录配置
spring:
    # Elasticsearch
    data:
      elasticsearch:
        # 暂未使用ES 关闭其持久化存储
        repositories:
          enabled: true

xboot:
  # 日志记录方式 true使用Elasticsearch记录(需启动并配置ES) false记录至数据库中(默认)
  logRecord:
    es: false

操作日志注解使用

  • 日志注解使用@SystemLog(description="操作日志名称", type=日志类型)
    • 日志类型type枚举类相关候选值：OPERATION（默认，用户操作相关）、LOGIN（用户登录），可自定义添加修改

接口相关

  • 为方便前端配置代理，所有接口建议以统一路径例如“/xboot”开头（当然后端也可配置context-path）
  • 登录成功后前端在返回的result字段中保存token（因登录接口已需要图片验证码验证，需带上验证码参数，详见文档 验证码过滤器使用 或 Swagger接口文档统一认证 部分）
  • 之后的请求中请在header或参数中添加该token参数即可，默认KEY为accessToken（SecurityConstant中可修改）

无状态风格Token令牌交互相关配置

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方法即可生成相关代码，别忘了在实体类中添加相关字段，运行项目后将自动生成数据库表，详见后面代码生成章节文档

Spring缓存注解

  • 配置失效过期时间
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

Quartz定时任务使用

  • 在cn.exrick.xboot.modules.quartz.jobs包下写好好你的定时任务类，参考代码中已有2个定时任务Job示例
  • 启动应用在后台页面“定时任务”菜单添加配置你写的的定时任务类保存成功后将开始执行

Spring Security官方推荐权限管理

  • Spring Security官方推荐注解表达式权限管理，当然你可以在XBoot权限菜单中动态配置，更佳灵活
    • @PreAuthorize("authenticated")
    • @PreAuthorize("hasAuthority('SCOPE_add')")
    • @PreAuthorize("hasRole('ADMIN')")
    • @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=) 必须符合指定的正则表达式
  • 更多及使用方法详见开发经验章节文档

MySQL数据库存储emoji

  • 当然可修改数据库所有编码默认为utf8mb4，为了节省空间，建议请修改具体需要的字符型字段的编码及排序规则为utf8mb4即可，如：
ALTER TABLE 表名 MODIFY COLUMN 列名 varchar(256) CHARACTER SET utf8mb4 COLLATE utf8_general_ci;
Clone this wiki locally