Skip to content

Commit e5a67f0

Browse files
committed
docs: 补充 Groovy 脚本缓存多实例部署文档与 Redis 同步实现示例 (17.x/springboot-starter-script)
- 能力文档新增多实例部署章节:部署前提(共享仓储 + 跨实例失效同步) - 提供 Redis pub/sub 失效同步(GroovyScriptCacheSync)完整实现示例(推荐方案) - 提供 Redis 共享缓存容器(GroovyScriptCache)实现示例(可选方案) - 补充行为说明与注意事项(回环过滤、SHA256 编译缓存自愈、临时脚本进程内语义) Ref #214
1 parent 0355e56 commit e5a67f0

1 file changed

Lines changed: 170 additions & 2 deletions

File tree

‎docs/capabilities/springboot-starter-script/groovy-runtime.md‎

Lines changed: 170 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -10,6 +10,11 @@ symbols:
1010
- GroovyScriptRuntime
1111
- GroovyScript
1212
- GroovyScriptCacheContext
13+
- GroovyScriptCache
14+
- GroovyScriptCacheSync
15+
- GroovyScriptCacheSyncContext
16+
- GroovyScriptCacheEvent
17+
- LocalGroovyScriptCacheSync
1318
- GroovyScriptRuntimeContext
1419
- GroovyScriptController
1520
content_hash: deddb103b5a58509ca7c08ace4195760e618f5b07782cfcb857fc1326d4ae526
@@ -40,7 +45,10 @@ content_hash: deddb103b5a58509ca7c08ace4195760e618f5b07782cfcb857fc1326d4ae526
4045
| `GroovyScriptRuntime` | 底层执行引擎:GroovyShell 封装、LRU 编译缓存、invoke/run 方法、事务控制 |
4146
| `GroovyScriptRuntimeContext` | Runtime 的单例上下文,从配置读取 `shellMaxCacheSize` 初始化 |
4247
| `GroovyScript` | 脚本领域对象:封装 key/script/method/returnType/binds 等元信息,提供 compile/run/invoke 快捷方法 |
43-
| `GroovyScriptCacheContext` | 脚本对象的 LRU 缓存(最大 10240 条),三级查找:缓存 → 临时存储 → Repository |
48+
| `GroovyScriptCacheContext` | 脚本对象的 LRU 缓存(最大 10240 条),三级查找:缓存 → 临时存储 → Repository;缓存容器可通过 `setCache` 替换 |
49+
| `GroovyScriptCache` / `DefaultGroovyScriptCache` | 缓存容器接口与默认进程内 LRU 实现,多实例部署时可替换为 Redis 等共享缓存 |
50+
| `GroovyScriptCacheEvent` | 脚本缓存变更事件(SAVE / REMOVE),实现 `ISyncEvent`,可被进程内 `IHandler` 监听 |
51+
| `GroovyScriptCacheSync` / `GroovyScriptCacheSyncContext` | 缓存变更跨实例同步 SPI 与上下文:写路径发布事件,远端实例接收后失效本地缓存 |
4452
| `GroovyScriptController` | REST 端点 `/api/groovy-script/*`,提供 compile/getScript/getMetadata/save 接口 |
4553

4654
### 直接执行脚本
@@ -107,6 +115,166 @@ script.save();
107115
| GET | `/api/groovy-script/getMetadata?key=` | 获取脚本元数据 |
108116
| POST | `/api/groovy-script/save` | 保存脚本(编译+持久化) |
109117

118+
## 多实例部署(重要)
119+
120+
脚本对象缓存(`GroovyScriptCacheContext`)与临时脚本缓存都是**进程内**的。多实例部署(水平扩容、双端部署、多副本灰度)时,实例 A 修改脚本后,实例 B 的缓存不会自动感知——如果不做任何配置,B 将永久返回旧脚本(见 issue #214)。
121+
122+
### 部署前提
123+
124+
多实例部署**必须同时满足**以下两点,缺一不可:
125+
126+
1. **共享仓储**:通过 `GroovyScriptRepositoryContext.getInstance().setRepository(...)` 注入基于数据库(或 Redis)的仓储实现。模块默认的 `DefaultGroovyScriptRepository` 是进程内 HashMap,不提供跨实例数据共享;
127+
2. **跨实例失效同步**:实现 `GroovyScriptCacheSync` SPI 广播缓存变更事件,远端实例收到事件后自动失效本地缓存,下次读取回源仓储加载新版本。
128+
129+
单实例部署无需任何配置,默认 `LocalGroovyScriptCacheSync` 保持原有行为。
130+
131+
### Redis pub/sub 失效同步实现示例(推荐方案)
132+
133+
数据正文保存在共享数据库中,Redis 仅承担"失效通知"的广播通道,失效后各实例自动回源数据库加载新版本。该方案实现简单、无需处理脚本内容的序列化兼容问题。
134+
135+
依赖:`spring-boot-starter-data-redis`(版本由 Spring Boot BOM 管理)+ `com.alibaba.fastjson2:fastjson2`。
136+
137+
```java
138+
/**
139+
* 基于 Redis pub/sub 的脚本缓存跨实例同步实现
140+
* 广播通道:脚本保存/删除事件 -> 其他实例失效本地缓存并回源仓储
141+
*/
142+
@Component
143+
public class RedisGroovyScriptCacheSync implements GroovyScriptCacheSync {
144+
145+
public static final String CHANNEL = "groovy-script-cache-sync";
146+
147+
private final StringRedisTemplate redisTemplate;
148+
149+
public RedisGroovyScriptCacheSync(StringRedisTemplate redisTemplate) {
150+
this.redisTemplate = redisTemplate;
151+
}
152+
153+
@Override
154+
public void publish(GroovyScriptCacheEvent event) {
155+
// 事件包含 source(来源实例标识),远端实例 receive 时会自动过滤自身事件避免回环
156+
redisTemplate.convertAndSend(CHANNEL, JSON.toJSONString(event));
157+
}
158+
159+
/**
160+
* 订阅回调:收到远端事件后失效本地缓存
161+
* 由下方 RedisMessageListenerContainer 配置调用
162+
*/
163+
public void onMessage(String payload) {
164+
GroovyScriptCacheEvent event = JSON.parseObject(payload, GroovyScriptCacheEvent.class);
165+
// receive 内部:过滤本实例事件 -> 按事件类型 remove 本地缓存 key
166+
GroovyScriptCacheSyncContext.getInstance().receive(event);
167+
}
168+
}
169+
```
170+
171+
```java
172+
/**
173+
* 注册 Redis 频道订阅
174+
*/
175+
@Configuration
176+
public class GroovyScriptCacheSyncConfiguration {
177+
178+
@Bean
179+
public RedisMessageListenerContainer groovyScriptCacheSyncListenerContainer(
180+
RedisConnectionFactory connectionFactory,
181+
RedisGroovyScriptCacheSync sync) {
182+
RedisMessageListenerContainer container = new RedisMessageListenerContainer();
183+
container.setConnectionFactory(connectionFactory);
184+
container.addMessageListener((message, pattern) -> {
185+
String payload = new String(message.getBody(), StandardCharsets.UTF_8);
186+
sync.onMessage(payload);
187+
}, new ChannelTopic(RedisGroovyScriptCacheSync.CHANNEL));
188+
return container;
189+
}
190+
}
191+
```
192+
193+
> 说明:若事件序列化使用 JSON,`GroovyScriptCacheEvent` 的字段(type/key/source/updateTime)均为可序列化类型;`GroovyScriptCacheEvent` 同时实现了框架的 `ISyncEvent`,进程内业务可通过 `IHandler<GroovyScriptCacheEvent>` 监听脚本变更,与跨实例同步互不影响。
194+
195+
### Redis 共享缓存容器实现示例(可选)
196+
197+
如果希望连脚本对象的读取也走 Redis(例如仓储回源成本高的场景),可以实现 `GroovyScriptCache` 接口替换默认 LRU 容器:
198+
199+
```java
200+
/**
201+
* 基于 Redis 的脚本缓存容器
202+
* 注意:GroovyScript 含 Class<?> 类型字段(returnType/binds/requests),
203+
* 序列化时需记录类名、反序列化时按类名反射加载,此处仅示意骨架
204+
*/
205+
public class RedisGroovyScriptCache implements GroovyScriptCache {
206+
207+
private final StringRedisTemplate redisTemplate;
208+
private final Duration ttl = Duration.ofMinutes(30);
209+
210+
public RedisGroovyScriptCache(StringRedisTemplate redisTemplate) {
211+
this.redisTemplate = redisTemplate;
212+
}
213+
214+
private String cacheKey(String key) {
215+
return "groovy-script:cache:" + key;
216+
}
217+
218+
@Override
219+
public void save(GroovyScript script) {
220+
if (script != null) {
221+
redisTemplate.opsForValue().set(cacheKey(script.getKey()), serialize(script), ttl);
222+
}
223+
}
224+
225+
@Override
226+
public GroovyScript get(String key) {
227+
String payload = redisTemplate.opsForValue().get(cacheKey(key));
228+
return payload == null ? null : deserialize(payload);
229+
}
230+
231+
@Override
232+
public void remove(String key) {
233+
redisTemplate.delete(cacheKey(key));
234+
}
235+
236+
@Override
237+
public List<String> keys() {
238+
// 生产环境建议使用 SCAN 遍历,避免 KEYS 阻塞
239+
return redisTemplate.keys("groovy-script:cache:*").stream()
240+
.map(k -> k.substring("groovy-script:cache:".length()))
241+
.toList();
242+
}
243+
244+
@Override
245+
public int count() {
246+
return keys().size();
247+
}
248+
249+
@Override
250+
public void clear() {
251+
keys().forEach(redisTemplate::delete);
252+
}
253+
254+
// serialize/deserialize 需处理 Class<?> 字段(记录类名 -> 反射加载),此处从略
255+
}
256+
```
257+
258+
```java
259+
// 启用时替换默认缓存容器(通常在配置类中执行一次)
260+
GroovyScriptCacheContext.getInstance().setCache(new RedisGroovyScriptCache(redisTemplate));
261+
```
262+
263+
**方案选择建议**:
264+
265+
| 方案 | 适用场景 | 复杂度 |
266+
|------|---------|--------|
267+
| Redis pub/sub 失效通知(推荐) | 脚本正文在共享数据库中,改动频率低、读取频率高 | 低 |
268+
| Redis 共享缓存容器 + pub/sub | 仓储回源成本高,或数据库无法承载读取压力 | 中(需处理 `Class<?>` 字段序列化) |
269+
270+
### 行为说明与注意事项
271+
272+
- 收到远端 `SAVE`/`REMOVE` 事件后,本实例仅失效对应 key 的缓存,**下次读取自动回源仓储**,无需主动拉取脚本内容;
273+
- 已编译 Script 的运行时缓存(`GroovyScriptRuntime`)以脚本内容 SHA256 为 key,内容变化后自动使用新 key 编译,无需额外失效;
274+
- `GroovyScriptCacheEvent.source` 为各实例的 UUID 标识(`GroovyScriptCacheSyncContext.getId()`),`receive` 会忽略本实例的事件,避免广播回环;
275+
- 临时脚本(`temp()`)与默认临时仓储均为进程内设计,临时编辑结果对其他实例不可见,属于预期行为;
276+
- 默认 LRU 容器为进程内实现,容量上限 10240 条;多实例下即使不替换为 Redis 缓存容器,只要接入了失效同步,各实例也会在收到事件后回源加载最新脚本。
277+
110278
## 使用实例
111279

112280
以下示例展示一个完整的动态折扣计算场景:
@@ -160,4 +328,4 @@ cached.save();
160328
// 下次 invoke 自动使用新版本
161329
```
162330

163-
缓存机制说明:`GroovyScriptRuntime` 内部以脚本内容的 SHA256 作为缓存 key,相同内容的脚本不会重复编译。当脚本内容变更后,SHA256 值改变,自动触发重新编译。LRU 策略确保内存占用可控,默认上限可通过配置项调整。
331+
缓存机制说明:`GroovyScriptRuntime` 内部以脚本内容的 SHA256 作为缓存 key,相同内容的脚本不会重复编译。当脚本内容变更后,SHA256 值改变,自动触发重新编译。LRU 策略确保内存占用可控,默认上限可通过配置项调整。脚本对象缓存的跨实例失效机制见上文[多实例部署](#多实例部署重要)章节(issue #214)。

0 commit comments

Comments
 (0)