如何用 Spring Boot 整合 Spring Data KeyValue 快速实现键值存储

Spring Data KeyValue 是 Spring Data 家族中面向键值存储的抽象模块，它允许开发者使用统一的 Repository 编程模型来操作基于键值结构的数据源。与 JPA 或 MongoDB 模块不同，Spring Data KeyValue 的默认实现运行在 JVM 内存中，底层使用 ConcurrentHashMap 保存实体，因此不需要额外部署数据库或缓存中间件。这种特性让它非常适合小型工具、测试代码、临时数据缓存以及某些对持久化要求不高的业务场景。本文将围绕 Spring Boot 与 Spring Data KeyValue 的整合展开，从依赖配置、实体映射、Repository 编写、高级操作和选型对比等角度给出完整示例。

严格来说，Spring Data KeyValue 并不是一个独立的存储引擎，而是一套抽象的 SPI 和默认实现。它把每个实体对象序列化为一个键值对，键通常是实体 ID，值则是整个实体。因为存储介质是内存 Map，所以它的性能非常高，但数据在应用重启后会丢失。如果你需要持久化，可以自定义 KeyValueAdapter 对接外部存储，或者直接选择 Spring Data Redis、Spring Data JDBC 等模块。下面先理解它的核心机制。

一、理解 Spring Data KeyValue 的核心机制

Spring Data KeyValue 的核心接口是 KeyValueAdapter 和 KeyValueTemplate。KeyValueTemplate 负责与底层存储交互，提供增删改查、分页、排序和流式查询等能力；KeyValueAdapter 则是存储适配层，默认实现 MapKeyValueAdapter 将数据放入 ConcurrentHashMap。当你在 Spring Boot 启动类上标注 @EnableMapRepositories 注解时，框架会自动配置这些组件，并扫描标记了 @KeySpace 的实体类。

实体类使用 @KeySpace 注解声明命名空间，使用 @Id 标注主键。命名空间类似传统数据库中的表名，但底层的 Map 结构是全局共享的，@KeySpace 只是帮助框架在生成键时添加前缀，避免不同实体类型之间的 ID 冲突。例如一个订单实体和一个用户实体都使用字符串 ID 时，订单实体的键可能是 order:1001，用户实体的键可能是 user:1001。这个设计让多个实体类型可以安全地共存于同一个存储实例中。

键值存储是一种以键为唯一标识、值可以是任意对象的数据模型。Spring Data KeyValue 将实体序列化为对象后直接放入 Map，并不涉及 JSON 序列化，因此对象引用是原始的，修改实体后需要手动保存才能同步到 Map。这一点与 JPA 的持久化上下文不同，开发者需要留意对象状态与存储之间的一致性。

二、Spring Boot 项目依赖与基础配置

首先在 pom.xml 中引入 spring-data-keyvalue 依赖。Spring Boot 并没有为这个模块提供单独的 starter，通常需要手动添加该依赖，并保持与 Spring Boot 版本一致。下面是一个 Maven 配置示例。

<dependency>
    <groupId>org.springframework.data</groupId>
    <artifactId>spring-data-keyvalue</artifactId>
</dependency>
<dependency>
    <groupId>org.springframework.boot</groupId>
    <artifactId>spring-boot-starter</artifactId>
</dependency>

如果你的项目使用 Spring Boot 的 dependencyManagement 管理版本，可以省略版本号；否则需要手动指定与 Spring Boot 匹配的版本，例如 3.2.x 对应 Spring Data 2023.1.x。引入依赖后，启动类需要添加 @EnableMapRepositories 注解。这个注解告诉 Spring Data KeyValue 使用基于内存 Map 的仓库实现。示例代码如下。

import org.springframework.boot.SpringApplication;
import org.springframework.boot.autoconfigure.SpringBootApplication;
import org.springframework.data.map.repository.config.EnableMapRepositories;

@SpringBootApplication
@EnableMapRepositories
public class KeyValueApplication {
    public static void main(String[] args) {
        SpringApplication.run(KeyValueApplication.class, args);
    }
}

注意，如果你在 Spring Boot 3 中使用，Java 版本需要 17 以上，包结构保持不变。配置完成后，框架会自动创建 KeyValueTemplate 和 MapKeyValueAdapter，并扫描带有 @KeySpace 注解的实体，无需额外配置数据源。

三、定义实体与 Repository 接口

假设我们要实现一个简单的用户会话存储，实体类如下所示。@KeySpace 的值为 sessions，表示所有会话数据共享一个命名空间；@Id 标注 sessionId 作为键。字段可以包含任意类型，框架会直接存储整个对象引用。

import org.springframework.data.annotation.Id;
import org.springframework.data.keyvalue.annotation.KeySpace;
import java.io.Serializable;

@KeySpace("sessions")
public class UserSession implements Serializable {
    @Id
    private String sessionId;
    private String username;
    private long createdAt;
    private int expireSeconds;

    public UserSession() {}

    public UserSession(String sessionId, String username, long createdAt, int expireSeconds) {
        this.sessionId = sessionId;
        this.username = username;
        this.createdAt = createdAt;
        this.expireSeconds = expireSeconds;
    }

    // 省略 getter 和 setter
}

接下来创建 Repository 接口。Spring Data KeyValue 支持 CrudRepository、PagingAndSortingRepository 以及自定义派生查询方法。对于键值存储，最基本的接口可以这样定义。

import org.springframework.data.repository.CrudRepository;
import java.util.List;

public interface UserSessionRepository extends CrudRepository<UserSession, String> {
    List<UserSession> findByUsername(String username);
    void deleteByUsername(String username);
}

这里的 findByUsername 是 Spring Data 的派生查询，框架会从方法名解析出查询条件，但底层并不是 SQL，而是遍历 Map 进行过滤。对于内存数据来说性能可以接受，但如果数据量较大需要考虑性能。也可以使用 @Query 注解手动指定查询表达式，不过 Spring Data KeyValue 的查询语言是 SpEL，主要用于过滤。

在业务类中注入 Repository 即可直接调用 save、findById、findAll、delete 等方法。例如保存一个会话：

UserSession session = new UserSession("abc123", "zhangsan", System.currentTimeMillis(), 1800);
userSessionRepository.save(session);
UserSession loaded = userSessionRepository.findById("abc123").orElse(null);

四、使用 KeyValueTemplate 完成高级操作

Repository 接口适合固定的 CRUD 模式，但当你需要动态构造查询、批量操作或访问底层存储结构时，KeyValueTemplate 是更好的选择。它可以直接注入使用，提供了 insert、update、delete、findById、findAll 以及流式查询等方法。下面是一个注入 KeyValueTemplate 并进行条件查询的例子。

import org.springframework.data.keyvalue.core.KeyValueTemplate;
import org.springframework.stereotype.Service;
import java.util.List;
import java.util.stream.Collectors;
import java.util.stream.StreamSupport;

@Service
public class SessionService {
    private final KeyValueTemplate keyValueTemplate;

    public SessionService(KeyValueTemplate keyValueTemplate) {
        this.keyValueTemplate = keyValueTemplate;
    }

    public List<UserSession> findExpiredSessions(long now) {
        Iterable<UserSession> all = keyValueTemplate.findAll(UserSession.class);
        return StreamSupport.stream(all.spliterator(), false)
                .filter(s -> now - s.getCreatedAt() > s.getExpireSeconds() * 1000L)
                .collect(Collectors.toList());
    }
}

KeyValueTemplate 还提供了排序与分页的 API，例如 findAll(Pageable) 或 find(KeyValueQuery)。如果 Repository 的派生查询不够灵活，可以直接使用 template 构建查询。另一个常见需求是清空某个命名空间下的所有数据，可以使用 template.delete(UserSession.class) 删除该类型的所有实体。

需要特别注意的是，KeyValueTemplate 的操作不会自动触发 TTL 或过期检查。默认 Map 实现里的数据会一直存在，除非手动删除。如果要实现过期，需要自己维护过期字段并定时清理，或者使用支持 TTL 的 KeyValueAdapter。Spring Data KeyValue 本身并不提供开箱即用的过期机制，这也是它与 Redis 模块的重要区别。

五、与 Spring Data Redis 的对比与选型建议

Spring Data KeyValue 和 Spring Data Redis 都提供了对键值数据的 Repository 抽象，但二者定位完全不同。KeyValue 默认基于内存 Map，进程内操作，零网络开销，性能极高；Redis 是独立的中间件，支持持久化、主从复制、集群和丰富的数据结构。对于需要跨实例共享数据或持久化存储的场景，KeyValue 无法满足，必须选择 Redis 或其他数据库。

从使用成本看，KeyValue 不需要安装任何服务，依赖少，适合单元测试、小型工具和临时缓存。它的查询能力也有限，派生查询本质是全量扫描，数据量超过几万条时性能会明显下降。Redis 模块提供了 RedisTemplate 和专门的查询能力，并且可以通过 @RedisHash 实体实现 TTL，使用起来更加成熟。

如果你的项目只是需要一个内存键值存储来快速验证业务逻辑，或者数据生命周期与应用进程一致，Spring Data KeyValue 是值得考虑的轻量方案。反之，如果涉及多实例部署、数据长期保存或高并发读写，建议从一开始就使用 Spring Data Redis。理解二者的边界，可以避免后期迁移带来的成本。

Spring BootSpring Data KeyValue键值存储修改时间：2026-10-04 01:34:55