Spring AI Alibaba 项目源码学习（四）-Graph中的存储分析

Store 存储系统分析

请关注微信公众号：阿呆-bot
概述

本文档分析 spring-ai-alibaba-graph-core 模块中的 Store 存储系统，包括接口设计、实现模式、支持的存储类型和关键设计点。
入口类说明

Store - 存储接口

Store 是长期内存存储的接口，提供跨会话的持久化存储能力，与 CheckpointSaver（短期状态持久化）不同，Store 专注于长期数据管理。
核心职责：

• 提供层次化命名空间支持
  
• 支持结构化数据存储（Map 格式）
  
• 提供搜索和过滤功能
  
• 支持分页查询
  
• 跨会话数据持久化
  

关键代码：

1. public interface Store {
3.         /**
4.          * Store an item in the specified namespace with the given key. If an item with the
5.          * same namespace and key already exists, it will be updated.
6.          * @param item the item to store
7.          * @throws IllegalArgumentException if item is null or invalid
8.          */
9.         void putItem(StoreItem item);
11.         /**
12.          * Retrieve an item from the specified namespace with the given key.
13.          * @param namespace the hierarchical namespace path
14.          * @param key the item key
15.          * @return Optional containing the item if found, empty otherwise
16.          * @throws IllegalArgumentException if namespace or key is null/invalid
17.          */
18.         Optional<StoreItem> getItem(List<String> namespace, String key);
20.         /**
21.          * Delete an item from the specified namespace with the given key.
22.          * @param namespace the hierarchical namespace path
23.          * @param key the item key
24.          * @return true if the item was deleted, false if it didn't exist
25.          * @throws IllegalArgumentException if namespace or key is null/invalid
26.          */
27.         boolean deleteItem(List<String> namespace, String key);
29.         /**
30.          * Search for items based on the provided search criteria.
31.          * @param searchRequest the search parameters
32.          * @return search results with matching items
33.          * @throws IllegalArgumentException if searchRequest is null
34.          */
35.         StoreSearchResult searchItems(StoreSearchRequest searchRequest);
37.         /**
38.          * List available namespaces based on the provided criteria.
39.          * @param namespaceRequest the namespace listing parameters
40.          * @return list of namespace paths
41.          * @throws IllegalArgumentException if namespaceRequest is null
42.          */
43.         List<String> listNamespaces(NamespaceListRequest namespaceRequest);
45.         /**
46.          * Clear all items from the store.
47.          * <p>
48.          * <strong>WARNING:</strong> This operation is irreversible and will remove all stored
49.          * data.
50.          * </p>
51.          */
52.         void clear();
54.         /**
55.          * Get the total number of items in the store.
56.          * @return the number of items stored
57.          */
58.         long size();
60.         /**
61.          * Check if the store is empty.
62.          * @return true if the store contains no items, false otherwise
63.          */
64.         boolean isEmpty();
66. }

复制代码

BaseStore - 抽象基类

BaseStore 为所有 Store 实现提供通用的验证和工具方法，实现了模板方法模式。
核心职责：

• 提供参数验证方法
  
• 提供键编码/解码工具
  
• 提供搜索匹配逻辑
  
• 提供排序比较器
  

关键代码：

1. public abstract class BaseStore implements Store {
3.         /**
4.          * Validates the putItem parameters.
5.          * @param item the item to validate
6.          */
7.         protected void validatePutItem(StoreItem item) {
8.                 if (item == null) {
9.                         throw new IllegalArgumentException("item cannot be null");
10.                 }
11.                 if (item.getNamespace() == null) {
12.                         throw new IllegalArgumentException("namespace cannot be null");
13.                 }
14.                 if (item.getKey() == null || item.getKey().trim().isEmpty()) {
15.                         throw new IllegalArgumentException("key cannot be null or empty");
16.                 }
17.         }
19.         /**
20.          * Validates the getItem parameters.
21.          * @param namespace namespace
22.          * @param key key
23.          */
24.         protected void validateGetItem(List<String> namespace, String key) {
25.                 if (namespace == null) {
26.                         throw new IllegalArgumentException("namespace cannot be null");
27.                 }
28.                 if (key == null) {
29.                         throw new IllegalArgumentException("key cannot be null");
30.                 }
31.                 if (key.trim().isEmpty()) {
32.                         throw new IllegalArgumentException("key cannot be empty");
33.                 }
34.         }
36.         /**
37.          * Validates the deleteItem parameters.
38.          * @param namespace namespace
39.          * @param key key
40.          */
41.         protected void validateDeleteItem(List<String> namespace, String key) {
42.                 if (namespace == null) {
43.                         throw new IllegalArgumentException("namespace cannot be null");
44.                 }
45.                 if (key == null) {
46.                         throw new IllegalArgumentException("key cannot be null");
47.                 }
48.                 if (key.trim().isEmpty()) {
49.                         throw new IllegalArgumentException("key cannot be empty");
50.                 }
51.         }
53.         /**
54.          * Validates the searchItems parameters.
55.          * @param searchRequest search request
56.          */
57.         protected void validateSearchItems(StoreSearchRequest searchRequest) {
58.                 if (searchRequest == null) {
59.                         throw new IllegalArgumentException("searchRequest cannot be null");
60.                 }
61.         }
63.         /**
64.          * Validates the listNamespaces parameters.
65.          * @param namespaceRequest namespace request
66.          */
67.         protected void validateListNamespaces(NamespaceListRequest namespaceRequest) {
68.                 if (namespaceRequest == null) {
69.                         throw new IllegalArgumentException("namespaceRequest cannot be null");
70.                 }
71.         }
73.         /**
74.          * Create store key from namespace and key Uses safe encoding to avoid conflicts from
75.          * special characters.
76.          * @param namespace namespace
77.          * @param key key
78.          * @return store key
79.          */
80.         protected String createStoreKey(List<String> namespace, String key) {
81.                 try {
82.                         Map<String, Object> keyData = new HashMap<>();
83.                         keyData.put("namespace", namespace);
84.                         keyData.put("key", key);
85.                         return Base64.getEncoder().encodeToString(new ObjectMapper().writeValueAsBytes(keyData));
86.                 }
87.                 catch (Exception e) {
88.                         throw new RuntimeException("Failed to create store key", e);
89.                 }
90.         }
92.         /**
93.          * Parse store key to namespace and key.
94.          * @param storeKey store key
95.          * @return array containing [namespace, key]
96.          */
97.         @SuppressWarnings("unchecked")
98.         protected Object[] parseStoreKey(String storeKey) {
99.                 try {
100.                         byte[] decoded = Base64.getDecoder().decode(storeKey);
101.                         Map<String, Object> keyData = new ObjectMapper().readValue(decoded, Map.class);
102.                         List<String> namespace = (List<String>) keyData.get("namespace");
103.                         String key = (String) keyData.get("key");
104.                         return new Object[] { namespace, key };
105.                 }
106.                 catch (Exception e) {
107.                         throw new RuntimeException("Failed to parse store key: " + storeKey, e);
108.                 }
109.         }

复制代码

StoreItem - 存储项

StoreItem 表示存储中的单个数据项，包含命名空间、键、值和时间戳。
关键代码：

1. public class StoreItem implements Serializable {
3.         /**
4.          * The hierarchical namespace path for organizing items. For example: ["users",
5.          * "user123", "preferences"]
6.          */
7.         private List<String> namespace;
9.         /**
10.          * The unique key within the namespace.
11.          */
12.         private String key;
14.         /**
15.          * The item value as a structured Map.
16.          */
17.         private Map<String, Object> value;
19.         /**
20.          * Timestamp when the item was created (milliseconds since epoch).
21.          */
22.         private long createdAt;
24.         /**
25.          * Timestamp when the item was last updated (milliseconds since epoch).
26.          */
27.         private long updatedAt;
29.         /**
30.          * Default constructor for serialization frameworks.
31.          */
32.         public StoreItem() {
33.         }
35.         /**
36.          * Constructs a StoreItem with the specified namespace, key, and value. Timestamps are
37.          * set to the current time.
38.          * @param namespace the hierarchical namespace path
39.          * @param key the item key
40.          * @param value the item value
41.          */
42.         public StoreItem(List<String> namespace, String key, Map<String, Object> value) {
43.                 this.namespace = namespace;
44.                 this.key = key;
45.                 this.value = value;
46.                 long now = System.currentTimeMillis();
47.                 this.createdAt = now;
48.                 this.updatedAt = now;
49.         }
51.         /**
52.          * Constructs a StoreItem with full parameters including timestamps.
53.          * @param namespace the hierarchical namespace path
54.          * @param key the item key
55.          * @param value the item value
56.          * @param createdAt creation timestamp (milliseconds since epoch)
57.          * @param updatedAt last update timestamp (milliseconds since epoch)
58.          */
59.         public StoreItem(List<String> namespace, String key, Map<String, Object> value, long createdAt, long updatedAt) {
60.                 this.namespace = namespace;
61.                 this.key = key;
62.                 this.value = value;
63.                 this.createdAt = createdAt;
64.                 this.updatedAt = updatedAt;
65.         }
67.         /**
68.          * Static factory method to create a StoreItem.
69.          * @param namespace the hierarchical namespace path
70.          * @param key the item key
71.          * @param value the item value
72.          * @return a new StoreItem instance
73.          */
74.         public static StoreItem of(List<String> namespace, String key, Map<String, Object> value) {
75.                 return new StoreItem(namespace, key, value);
76.         }

复制代码

Store 实现类

MemoryStore - 内存存储

基于 ConcurrentHashMap 的内存实现，适用于测试和开发环境。
关键代码：

1. public class MemoryStore extends BaseStore {
3.         /**
4.          * Thread-safe storage for store items. Key format: "namespace1/namespace2/key"
5.          */
6.         private final Map<String, StoreItem> storage = new ConcurrentHashMap<>();
8.         /**
9.          * Read-write lock for thread safety during search operations.
10.          */
11.         private final ReadWriteLock lock = new ReentrantReadWriteLock();
13.         @Override
14.         public void putItem(StoreItem item) {
15.                 validatePutItem(item);
17.                 lock.writeLock().lock();
18.                 try {
19.                         String storeKey = createStoreKey(item.getNamespace(), item.getKey());
20.                         storage.put(storeKey, item);
21.                 }
22.                 finally {
23.                         lock.writeLock().unlock();
24.                 }
26.         }
28.         @Override
29.         public Optional<StoreItem> getItem(List<String> namespace, String key) {
30.                 validateGetItem(namespace, key);
32.                 lock.readLock().lock();
33.                 try {
34.                         String storeKey = createStoreKey(namespace, key);
35.                         return Optional.ofNullable(storage.get(storeKey));
36.                 }
37.                 finally {
38.                         lock.readLock().unlock();
39.                 }
40.         }

复制代码

特点：

• 线程安全（使用 ConcurrentHashMap 和 ReadWriteLock）
  
• 高性能（内存访问）
  
• 数据不持久化（应用重启后丢失）
  

FileSystemStore - 文件系统存储

基于文件系统的持久化存储实现。
特点：

• 数据持久化到本地文件系统
  
• 支持目录结构组织
  
• 适合单机部署
  

DatabaseStore - 数据库存储

基于关系型数据库（MySQL/PostgreSQL）的存储实现。
特点：

• 支持事务
  
• 支持复杂查询
  
• 适合生产环境
  

RedisStore - Redis 存储

基于 Redis 的存储实现。
特点：

• 高性能
  
• 支持分布式
  
• 支持过期策略
  

MongoStore - MongoDB 存储

基于 MongoDB 的存储实现。
特点：

• 支持文档存储
  
• 支持复杂查询
  
• 适合非结构化数据
  

关键类关系图

以下 PlantUML 类图展示了 Store 系统的类关系：

这种设计避免了特殊字符冲突，确保键的唯一性。
3. 搜索和过滤

StoreSearchRequest 支持多种搜索方式：

• 命名空间过滤：在指定命名空间下搜索
  
• 文本查询：在键和值中搜索文本
  
• 自定义过滤：基于值的键值对过滤
  
• 排序：支持多字段排序
  
• 分页：支持 offset 和 limit
  

关键代码：

1. protected boolean matchesSearchCriteria(StoreItem item, StoreSearchRequest searchRequest) {
2.                 // Namespace filter
3.                 List<String> namespaceFilter = searchRequest.getNamespace();
4.                 if (!namespaceFilter.isEmpty() && !startsWithPrefix(item.getNamespace(), namespaceFilter)) {
5.                         return false;
6.                 }
8.                 // Text query filter
9.                 String query = searchRequest.getQuery();
10.                 if (query != null && !query.trim().isEmpty()) {
11.                         String lowerQuery = query.toLowerCase();
12.                         // Search in key
13.                         if (!item.getKey().toLowerCase().contains(lowerQuery)) {
14.                                 // Search in value
15.                                 String valueStr = item.getValue().toString().toLowerCase();
16.                                 if (!valueStr.contains(lowerQuery)) {
17.                                         return false;
18.                                 }
19.                         }
20.                 }
22.                 // Custom filters
23.                 Map<String, Object> filters = searchRequest.getFilter();
24.                 if (!filters.isEmpty()) {
25.                         Map<String, Object> itemValue = item.getValue();
26.                         for (Map.Entry<String, Object> filter : filters.entrySet()) {
27.                                 Object itemVal = itemValue.get(filter.getKey());
28.                                 if (!Objects.equals(itemVal, filter.getValue())) {
29.                                         return false;
30.                                 }
31.                         }
32.                 }
34.                 return true;
35.         }

复制代码

实现关键点说明

1. 模板方法模式

BaseStore 实现了模板方法模式：

• 定义通用的验证和工具方法
  
• 子类实现具体的存储逻辑
  
• 确保所有实现的一致性
  

2. 策略模式

不同的 Store 实现代表不同的存储策略：

• MemoryStore：内存策略（快速但不持久）
  
• FileSystemStore：文件系统策略（持久但单机）
  
• DatabaseStore：数据库策略（事务支持）
  
• RedisStore：缓存策略（高性能）
  
• MongoStore：文档数据库策略（灵活）
  

3. 线程安全

• MemoryStore 使用 ConcurrentHashMap 和 ReadWriteLock 确保线程安全
  
• 其他实现依赖底层存储的线程安全机制
  

4. 键编码设计

使用 Base64 编码避免特殊字符问题：

• 支持任意命名空间和键名
  
• 确保键的唯一性
  
• 便于序列化和反序列化
  

5. 搜索优化

BaseStore 提供通用的搜索匹配逻辑：

• 命名空间前缀匹配
  
• 文本包含匹配
  
• 自定义过滤匹配
  
• 多字段排序支持
  

总结说明

核心设计理念

• 统一接口：Store 接口定义统一的存储操作，屏蔽底层实现差异
  
• 层次化组织：通过命名空间支持数据的层次化组织
  
• 灵活查询：支持多种搜索和过滤方式
  
• 可扩展性：通过接口和抽象类支持新的存储实现
  

支持的存储模式

• 内存模式（MemoryStore）：适合测试和开发
  
• 文件系统模式（FileSystemStore）：适合单机部署
  
• 数据库模式（DatabaseStore）：适合生产环境，支持事务
  
• 缓存模式（RedisStore）：适合高性能场景
  
• 文档数据库模式（MongoStore）：适合非结构化数据
  

关键优势

• 一致性：所有实现遵循相同的接口规范
  
• 可替换性：不同实现可以无缝替换
  
• 可扩展性：易于添加新的存储实现
  
• 类型安全：使用泛型和接口确保类型安全
  

使用场景

• 长期记忆：Agent 的长期记忆存储
  
• 知识库：存储结构化知识
  
• 用户数据：存储用户偏好和配置
  
• 会话数据：跨会话的数据持久化
  

来源：程序园用户自行投稿发布，如果侵权，请联系站长删除
免责声明：如果侵犯了您的权益，请联系站长，我们会及时删除侵权内容，谢谢合作！