缓存

LuckReport 支持自定义缓存扩展，实现 ReportCache 接口，即可快速接入自定义缓存方案。

针对分布式、集群部署的业务系统，为保证多服务节点间的报表缓存数据一致性，需统一采用分布式缓存方案。LuckReport 提供了 luck-report-redis 扩展包，开箱即用，只需引入依赖并配置 Redis 连接信息即可快速接入 Redis 分布式缓存。

接口方法说明

ReportCache 接口核心方法：

方法名	返回类型	说明
disabled()	boolean	返回是否禁用该缓存（Redis 不可用时返回 true）
get(String key)	T	根据键获取缓存值
get(String key, Class<T> clazz)	T	根据键获取缓存值并转换为指定类型
put(String key, T value)	void	存入缓存（不设置过期时间）
put(String key, T value, long time)	void	存入缓存并设置过期时间（单位：秒）
exists(String key)	boolean	判断缓存键是否存在
remove(String key)	void	删除指定缓存键
keys(String keyPatten)	Set<String>	根据前缀查询匹配的所有缓存键
setExpire(String key, long time)	boolean	设置缓存键的过期时间（单位：秒）

接入 Redis 缓存

1. 添加 luck-report-redis 依赖

在 pom.xml 中引入 luck-report-redis 扩展包，该包已内置 Redis 缓存实现，无需再手动添加 spring-boot-starter-data-redis 依赖：

<!-- Luck Report Redis 缓存扩展 -->
<dependency>
    <groupId>com.luck.cloud</groupId>
    <artifactId>luck-report-redis</artifactId>
    <version>1.0.2</version>
</dependency>

2. 添加 Redis 配置

在 application.yml（或 application-dev.yml 等环境配置文件）中添加 Redis 连接配置，并禁用本地缓存：

spring:
  redis:
    host: 127.0.0.1        # Redis 地址
    port: 6379             # Redis 端口
    password:              # 有密码就填，无密码删除此行
    database: 0            # 使用的库编号
    timeout: 3000
    lettuce:
      pool:
        max-active: 8
        max-idle: 8
        min-idle: 0

luck-report:
  # ...
  # 采用 Redis 缓存，禁用本地缓存（分布式/集群环境必须配置）
  disableLocalReportCache: true

配置说明：

配置项	说明
disableLocalReportCache	设置为 true 禁用本地缓存，分布式环境必须配置

缓存键生成策略

Luck-Report 使用 ReportCacheKeyResolver 接口来生成缓存键前缀，用于区分不同用户的缓存数据。默认实现基于 Session ID，适用于传统 Session 认证场景。

接口方法说明

ReportCacheKeyResolver 接口核心方法：

方法名	返回类型	说明
disabled()	boolean	返回是否禁用该缓存键生成器
getPrefix()	String	返回缓存键前缀，用于区分不同用户

使用场景

当业务系统使用 JWT Token 等无状态认证方式时，由于没有 Session ID，需要自定义缓存键生成策略。常见的做法是基于用户 ID 生成缓存键前缀。

配置说明

如果实现了自定义的 ReportCacheKeyResolver，需要在配置文件中禁用默认的 Session 缓存键生成器：

luck-report:
  # 禁用 Session 缓存键生成器（使用 JWT Token 认证时需要配置）
  disableSessionCacheKeyResolver: true

示例：基于用户 ID 的缓存键生成器

从 SecurityContext 获取当前用户 ID 作为缓存键前缀：

package com.luck.product.boot;

import com.luck.report.infra.modules.cache.service.ReportCacheKeyResolver;
import org.springframework.stereotype.Component;

/**
 * 基于用户 ID 的缓存键解析器
 * 替代默认的 Session 方式，解决 JWT Token 认证中无 Session ID 的问题
 */
@Component
public class UserCacheKeyResolver implements ReportCacheKeyResolver {

    private boolean disabled = false;

    @Override
    public boolean disabled() {
        return disabled;
    }

    public void setDisabled(boolean disabled) {
        this.disabled = disabled;
    }

    /**
     * 获取缓存前缀（基于用户 ID）
     * 同一用户的所有请求使用相同的缓存前缀，确保缓存数据可跨请求访问
     */
    @Override
    public String getPrefix() {
        try {
            // 从业务系统的 SecurityContext 获取当前用户 ID
            Long userId = SecurityUtils.getUserId();
            if (userId != null) {
                return String.valueOf(userId);
            }
        } catch (Exception e) {
            // 未登录或获取失败，返回默认值
        }
        return "anonymous";
    }
}

对应配置文件：

luck-report:
  # 禁用本地缓存
  disableLocalReportCache: true
  # 禁用 Session 缓存键生成器（使用 JWT Token 认证时必须配置）
  disableSessionCacheKeyResolver: true