@alanwang-merit/meritdata-platform-skill-package 1.0.9 → 1.0.10

package/skills/meritdata-platform-core/references/assets/02_/344/270/200/345/237/272/347/241/200/350/256/276/346/226/275-1.1/347/274/223/345/255/230/346/223/215/344/275/234-SysCacheServiceFacade.md

@@ -0,0 +1,423 @@
+---
+name: 一基础设施-1.1缓存操作-SysCacheServiceFacade
+source-file: 公共资产清单
+source-section: 一、基础设施类 → 1.1 缓存操作 → SysCacheServiceFacade L70-L464
+keywords: [Redis缓存, SysCacheServiceFacade, put, get, hset, hget, enqueue, publish, Redis统一门面]
+use-cases: [缓存用户会话, 计数器, 任务队列, 跨服务通知, 分布式锁, 库存扣减, 限流计数器]
+related: [03_一基础设施-1.1缓存操作-StringCacheFacade.md, 04_一基础设施-1.2配置中心-NacosUtils.md, 11_三平台服务-3.3会话信息获取-SessionUtils.md]
+---
+
+# 1.1 缓存操作 — SysCacheServiceFacade
+
+> **原文章节**：`公共资产清单 → 一、基础设施类 → 1.1 缓存操作 → SysCacheServiceFacade`
+> **行号范围**：L70-L464
+
+## 🎯 一句话
+`SysCacheServiceFacade` 是平台统一的 Redis 缓存门面，对外暴露 23 个静态方法，覆盖 KV、Hash、List（消息队列）、Pub/Sub 四大类操作。
+
+## 📋 接口/方法清单
+
+### 1.1 缓存操作
+
+#### SysCacheServiceFacade
+
+##### 1.1.1 新增缓存
+
+完整包路径：`com.meritdata.tempo.syscache.service.SysCacheServiceFacade`
+
+方法：`put(key, value)`
+
+入参：String key, Object value
+
+返回：void
+
+使用场景：系统存在高频访问且不刷新的变量时，将信息存入redis，无固定期限（永不失效）
+
+示例：
+```java
+SysCacheServiceFacade.put("EXECPTION_EVENT_SESSION" + username, allSessions);
+SysCacheServiceFacade.put("user:session:" + userId, userSession);
+```
+
+##### 1.1.2 添加缓存并设置生存时间
+
+方法：`putExpire(key, value, seconds)`
+
+入参：String key, Object value, int seconds
+
+返回：void
+
+使用场景：需要设置缓存过期时间的场景，如token缓存，seconds为过期秒数
+
+示例：
+```java
+SysCacheServiceFacade.putExpire("nacosToken", accessToken, 14400);
+SysCacheServiceFacade.putExpire("temp:data:" + id, value, 3600);
+```
+
+##### 1.1.3 添加缓存并设置到期时间
+
+方法：`putExpireAt(key, value, unixTime)`
+
+入参：String key, Object value, long unixTime
+
+返回：void
+
+使用场景：需要在指定时间点过期的缓存，unixTime为Unix时间戳（毫秒）
+
+**注意**：实际实现内部会自动给unixTime加3000
+
+示例：
+```java
+// unixTime为毫秒时间戳
+SysCacheServiceFacade.putExpireAt("event:expire", value, System.currentTimeMillis() + 3600000);
+```
+
+##### 1.1.4 读取缓存
+
+方法：`get(key)`
+
+入参：String key
+
+返回：Object
+
+使用场景：获取已存储的缓存值
+
+示例：
+```java
+String token = SysCacheServiceFacade.get("nacosToken").toString();
+Object session = SysCacheServiceFacade.get("user:session:" + userId);
+```
+
+##### 1.1.5 判断key是否存在
+
+方法：`isExist(key)`
+
+入参：String key
+
+返回：Boolean
+
+使用场景：判断某个缓存是否已存在
+
+示例：
+```java
+boolean exists = SysCacheServiceFacade.isExist("nacosToken");
+if (exists) {
+    // token存在，刷新或使用
+}
+```
+
+##### 1.1.6 清除缓存
+
+方法：`remove(key)`
+
+入参：String key
+
+返回：void
+
+使用场景：主动清除某个缓存
+
+示例：
+```java
+SysCacheServiceFacade.remove("nacosToken");
+SysCacheServiceFacade.remove("user:session:" + userId);
+```
+
+##### 1.1.7 读取Hash缓存
+
+方法：`hget(h, hkey)`
+
+入参：String h, String hkey
+
+返回：Object
+
+使用场景：从Hash结构中获取单个字段值
+
+示例：
+```java
+User user = (User) SysCacheServiceFacade.hget(CACHE_SESSION_LIST_KEY, loginName);
+Object value = SysCacheServiceFacade.hget("user:hash", "username");
+```
+
+##### 1.1.8 写入Hash缓存
+
+方法：`hset(h, hkey, hvalue)`
+
+入参：String h, String hkey, Object hvalue
+
+返回：void
+
+使用场景：将数据以Hash结构存储，常用于存储用户会话信息
+
+示例：
+```java
+SysCacheServiceFacade.hset(CACHE_SESSION_LIST_KEY, user.getUsername(), user);
+SysCacheServiceFacade.hset("user:profile", userId, userProfile);
+```
+
+##### 1.1.9 获取Hash所有数据
+
+方法：`hgetAll(key)`
+
+入参：String key
+
+返回：Map<String, Object>
+
+使用场景：获取Hash结构中的所有键值对
+
+示例：
+```java
+Map<String, Object> allUsers = SysCacheServiceFacade.hgetAll(CACHE_SESSION_LIST_KEY);
+```
+
+##### 1.1.10 删除Hash字段
+
+方法：`hdel(h, hkey)`
+
+入参：String h, String hkey
+
+返回：Long
+
+使用场景：删除Hash中的指定字段
+
+示例：
+```java
+SysCacheServiceFacade.hdel(CACHE_SESSION_LIST_KEY, loginName);
+SysCacheServiceFacade.hdel("user:profile", userId);
+```
+
+##### 1.1.11 获取Hash所有字段
+
+方法：`hkeys(h)`
+
+入参：String h
+
+返回：Set<String>
+
+使用场景：获取Hash结构中的所有字段名
+
+示例：
+```java
+Set<String> fields = SysCacheServiceFacade.hkeys(CACHE_SESSION_LIST_KEY);
+for (String key : fields) {
+    // 遍历所有缓存的用户名
+}
+```
+
+##### 1.1.12 获取Hash所有值
+
+方法：`hvalues(h)`
+
+入参：String h
+
+返回：List<Object>
+
+使用场景：获取Hash结构中的所有值
+
+示例：
+```java
+List<Object> allUsers = SysCacheServiceFacade.hvalues(CACHE_SESSION_LIST_KEY);
+```
+
+##### 1.1.13 批量读取
+
+方法：`multiGet(keys)`
+
+入参：List keys
+
+返回：List<Object>
+
+使用场景：一次性获取多个缓存值，减少网络开销
+
+示例：
+```java
+List<String> keys = Arrays.asList("key1", "key2", "key3");
+List<Object> values = SysCacheServiceFacade.multiGet(keys);
+```
+
+##### 1.1.14 队列入队
+
+方法：`enqueue(key, value)`
+
+入参：String key, T value
+
+返回：Long
+
+使用场景：实现消息队列的入队操作
+
+示例：
+```java
+SysCacheServiceFacade.enqueue("task_queue", taskData);
+SysCacheServiceFacade.enqueue("async:job:queue", jobMessage);
+```
+
+##### 1.1.15 队列出队
+
+方法：`dequeue(key)`
+
+入参：String key
+
+返回：Object
+
+使用场景：实现消息队列的出队操作
+
+示例：
+```java
+Object data = SysCacheServiceFacade.dequeue("task_queue");
+while ((data = SysCacheServiceFacade.dequeue("task_queue")) != null) {
+    // 处理队列数据
+}
+```
+
+##### 1.1.16 批量出队
+
+方法：`dequeueList(key)`
+
+入参：String key
+
+返回：List<Object>
+
+使用场景：一次性出队多个数据
+
+示例：
+```java
+List<Object> batchData = SysCacheServiceFacade.dequeueList("task_queue");
+```
+
+##### 1.1.17 获取队列长度
+
+方法：`queueSize(key)`
+
+入参：String key
+
+返回：Long
+
+使用场景：查看队列中等待处理的任务数量
+
+示例：
+```java
+Long size = SysCacheServiceFacade.queueSize("task_queue");
+if (size > 100) {
+    // 队列积压告警
+}
+```
+
+##### 1.1.18 递增
+
+方法：`increment(k)` / `increment(k, delta)`
+
+入参：String k, long delta(可选)
+
+返回：Long
+
+使用场景：计数器实现，如访问次数统计、序列号生成
+
+示例：
+```java
+SysCacheServiceFacade.increment("page:views");
+SysCacheServiceFacade.increment("request:count", 1);
+Long newValue = SysCacheServiceFacade.increment("order:seq");
+```
+
+##### 1.1.19 递减
+
+方法：`decrement(k)` / `decrement(k, delta)`
+
+入参：String k, long delta(可选)
+
+返回：Long
+
+使用场景：计数器递减，如库存扣减
+
+示例：
+```java
+SysCacheServiceFacade.decrement("stock:count");
+Long remaining = SysCacheServiceFacade.decrement("inventory:qty", quantity);
+```
+
+##### 1.1.20 不存在则设置
+
+方法：`setIfAbsent(k, v)`
+
+入参：String k, Object v
+
+返回：boolean
+
+使用场景：分布式锁、幂等性控制、新用户标识
+
+示例：
+```java
+boolean locked = SysCacheServiceFacade.setIfAbsent("lock:order:" + orderId, "locked");
+if (locked) {
+    // 获取锁成功，处理订单
+}
+```
+
+##### 1.1.21 获取旧值并设置新值
+
+方法：`getAndSet(k, v)`
+
+入参：String k, Object v
+
+返回：Object
+
+使用场景：原子性获取旧值并设置新值，如token刷新
+
+示例：
+```java
+Object oldToken = SysCacheServiceFacade.getAndSet("user:token:" + userId, newToken);
+```
+
+##### 1.1.22 发布消息
+
+方法：`publish(channel, message)`
+
+入参：String channel, String message
+
+返回：void
+
+使用场景：Redis发布订阅模式的消息发布
+
+示例：
+```java
+SysCacheServiceFacade.publish("channel:notify", "有新消息通知");
+SysCacheServiceFacade.publish("event:update", JSON.toJSONString(event));
+```
+
+##### 1.1.23 订阅消息
+
+方法：`subscribe(channel, ICacheSubscribeListener)`
+
+入参：String channel, ICacheSubscribeListener listener
+
+返回：void
+
+使用场景：Redis发布订阅模式的消息订阅
+
+**调用链**：
+- `SysCacheServiceFacade.subscribe(channel, listener)` - 公开API，参数顺序 `(channel, listener)`
+- 内部调用 `SysCacheServiceContext.subscribe(listener, channel)` - 参数顺序被调换
+- 底层 `ICacheService.subscribe(listener, channel)` - Redis标准顺序
+
+**注意**：`ICacheSubscribeListener.onMessage(msg)`回调接口**只接收一个参数msg**
+
+示例：
+```java
+// subscribe方法接收(channel, listener)，回调onMessage只接收(msg)
+SysCacheServiceFacade.subscribe("channel:notify", (msg) -> {
+    // 处理接收到的消息
+    System.out.println("收到消息: " + msg);
+});
+```
+
+---
+
+## 💡 使用建议
+- **优先使用 SysCacheServiceFacade 而非直接使用 RedisTemplate**：平台已封装序列化策略和多租户隔离，二开项目直接调用静态方法即可，避免重复造轮子。
+- **缓存 key 命名**：参考示例使用 `业务:实体:{id}` 的三层结构（如 `user:session:123`），方便全局检索和按前缀批量失效。
+- **分布式锁模式**：`setIfAbsent` + `remove` 是常见组合；如需自动过期防止死锁，可结合 `putExpire` 二次包装。
+
+## 🔗 相关章节
+- 03_一基础设施-1.1缓存操作-StringCacheFacade.md
+- 04_一基础设施-1.2配置中心-NacosUtils.md
+- 11_三平台服务-3.3会话信息获取-SessionUtils.md

package/skills/meritdata-platform-core/references/assets/03_/344/270/200/345/237/272/347/241/200/350/256/276/346/226/275-1.1/347/274/223/345/255/230/346/223/215/344/275/234-StringCacheFacade.md

@@ -0,0 +1,78 @@
+---
+name: 一基础设施-1.1缓存操作-StringCacheFacade
+source-file: 公共资产清单
+source-section: 一、基础设施类 → 1.1 缓存操作 → StringCacheFacade L465-L517
+keywords: [String缓存, StringCacheFacade, put, get, multiGet]
+use-cases: [字符串缓存, 配置版本号缓存, 用户名缓存]
+related: [02_一基础设施-1.1缓存操作-SysCacheServiceFacade.md]
+---
+
+# 1.1 缓存操作 — StringCacheFacade
+
+> **原文章节**：`公共资产清单 → 一、基础设施类 → 1.1 缓存操作 → StringCacheFacade`
+> **行号范围**：L465-L517
+
+## 🎯 一句话
+`StringCacheFacade` 是专用于 String 类型缓存的轻量门面，仅提供 3 个方法（put / get / multiGet），相比 `SysCacheServiceFacade` 拥有更强的类型安全和返回类型约束。
+
+## 📋 接口/方法清单
+
+#### StringCacheFacade
+
+##### 1.1.24 String类型缓存-新增
+
+完整包路径：`com.meritdata.tempo.syscache.service.StringCacheFacade`
+
+方法：`put(key, value)`
+
+入参：String key, String value
+
+返回：void
+
+使用场景：存储字符串类型的缓存数据
+
+示例：
+```java
+StringCacheFacade.put("config:version", "1.0.0");
+StringCacheFacade.put("user:name:" + userId, username);
+```
+
+##### 1.1.25 String类型缓存-读取
+
+方法：`get(key)`
+
+入参：String key
+
+返回：String
+
+使用场景：获取字符串类型的缓存值
+
+示例：
+```java
+String version = StringCacheFacade.get("config:version");
+```
+
+##### 1.1.26 String类型缓存-批量读取
+
+方法：`multiGet(keys)`
+
+入参：List keys
+
+返回：List<String>
+
+使用场景：批量获取字符串缓存
+
+示例：
+```java
+List<String> keys = Arrays.asList("key1", "key2");
+List<String> values = StringCacheFacade.multiGet(keys);
+```
+
+---
+
+## 💡 使用建议
+- **值确为 String 时优先使用 `StringCacheFacade`**：`get()` 直接返回 `String`，避免 `SysCacheServiceFacade.get(...).toString()` 的强制转换和空指针风险。
+- **不适合存储复杂对象**：StringCacheFacade 仅支持 String 类型，复杂对象请回退到 `SysCacheServiceFacade` 的 KV 存储。
+
+## 🔗 相关章节
+- 02_一基础设施-1.1缓存操作-SysCacheServiceFacade.md

package/skills/meritdata-platform-core/references/assets/04_/344/270/200/345/237/272/347/241/200/350/256/276/346/226/275-1.2/351/205/215/347/275/256/344/270/255/345/277/203-NacosUtils.md

@@ -0,0 +1,193 @@
+---
+name: 一基础设施-1.2配置中心-NacosUtils
+source-file: 公共资产清单
+source-section: 一、基础设施类 → 1.2 配置中心 → NacosUtils L518-L684
+keywords: [Nacos配置中心, NacosUtils, getConfigList, publishConfig, MeritdataCloudProperties, Spring Bean]
+use-cases: [动态读取Nacos配置, 修改Nacos配置, 配置文件批量更新, Nacos鉴权Token获取]
+related: [02_一基础设施-1.1缓存操作-SysCacheServiceFacade.md]
+---
+
+# 1.2 配置中心 — NacosUtils
+
+> **原文章节**：`公共资产清单 → 一、基础设施类 → 1.2 配置中心 → NacosUtils`
+> **行号范围**：L518-L684
+
+## 🎯 一句话
+`NacosUtils` 提供 Nacos 配置的读写能力，对外暴露 10 个方法（基于 Spring Bean 注入），常用于运行时动态获取/修改配置。
+
+## 📋 接口/方法清单
+
+### 1.2 配置中心
+
+#### NacosUtils
+
+**注意**：`NacosUtils` **不是静态工具类**，它是一个Spring Bean，需要通过依赖注入获取实例。类上有`@DisableEncrypt`注解，但方法使用`@Autowired`注入`MeritdataCloudProperties`和`Environment`。
+
+**正确用法**（通过Spring注入）：
+```java
+@Autowired
+private NacosUtils nacosUtils;
+```
+
+##### 1.2.1 获取配置列表
+
+完整包路径：`com.meritdata.cloud.utils.NacosUtils`
+
+方法：`getConfigList(dataId)`
+
+入参：String dataId
+
+返回：Map
+
+使用场景：获取Nacos上某个配置分组的所有配置项
+
+示例：
+```java
+Map configMap = nacosUtils.getConfigList("common-cloud-system-manage.properties");
+```
+
+##### 1.2.2 获取配置文件
+
+方法：`getConfigFile(dataId)`
+
+入参：String dataId
+
+返回：String
+
+使用场景：获取Nacos上某个配置文件的完整内容
+
+示例：
+```java
+String content = nacosUtils.getConfigFile("application.properties");
+```
+
+##### 1.2.3 获取配置值
+
+方法：`getConfigValue(dataId, configKey)`
+
+入参：String dataId, String configKey
+
+返回：String
+
+使用场景：获取Nacos上指定配置项的值
+
+示例：
+```java
+String value = nacosUtils.getConfigValue("common-cloud-system-manage.properties", "meritdata.cloud.security-label-show");
+```
+
+##### 1.2.4 获取所有配置文件
+
+方法：`getAllConfigFile()`
+
+入参：无
+
+返回：Map<String, String>
+
+使用场景：获取Nacos上所有配置文件的键值对
+
+示例：
+```java
+Map<String, String> allConfigs = nacosUtils.getAllConfigFile();
+```
+
+##### 1.2.5 修改配置
+
+方法：`updateConfig(dataId, configKey, configValue)`
+
+入参：String dataId, String configKey, String configValue
+
+返回：boolean
+
+使用场景：修改Nacos上的配置值
+
+示例：
+```java
+boolean success = nacosUtils.updateConfig("common-cloud-system-manage.properties",
+    "meritdata.cloud.security-label-show", "true");
+```
+
+##### 1.2.6 更新配置文件
+
+方法：`updateConfigFile(dataId, quote)`
+
+入参：String dataId, String quote
+
+返回：boolean
+
+使用场景：更新整个配置文件内容
+
+示例：
+```java
+boolean success = nacosUtils.updateConfigFile("application.properties", newConfigContent);
+```
+
+##### 1.2.7 新增配置
+
+方法：`addConfig(dataId, configKey, configValue)`
+
+入参：String dataId, String configKey, String configValue
+
+返回：boolean
+
+使用场景：在Nacos上新增配置项
+
+示例：
+```java
+boolean added = nacosUtils.addConfig("custom.properties", "custom.key", "customValue");
+```
+
+##### 1.2.8 重置配置文件
+
+方法：`reSetConfigFile(dataId, quote)`
+
+入参：String dataId, String quote
+
+返回：boolean
+
+使用场景：重置配置文件内容
+
+示例：
+```java
+nacosUtils.reSetConfigFile("reset.properties", defaultContent);
+```
+
+##### 1.2.9 清除配置文件
+
+方法：`clearConfigFile(dataId)`
+
+入参：String dataId
+
+返回：boolean
+
+使用场景：清除Nacos上某个配置文件的所有内容
+
+示例：
+```java
+nacosUtils.clearConfigFile(dataId);
+```
+
+##### 1.2.10 获取Nacos Token
+
+方法：`getNacosToken()`
+
+入参：无
+
+返回：String
+
+使用场景：获取Nacos访问令牌
+
+示例：
+```java
+String token = nacosUtils.getNacosToken();
+```
+
+---
+
+## 💡 使用建议
+- **`NacosUtils` 是 Spring Bean**：`@Autowired private NacosUtils nacosUtils;` 注入，**不要**用 `NacosUtils.xxx` 静态调用。
+- **配置 dataId 命名规范**：使用 `common-{模块}.properties`（如 `common-cloud-system-manage.properties`），保持与 bootstrap.properties 中声明的 profile 一致。
+- **运行时动态变更**：对于需要"不重启服务切换功能开关"的场景，可调用 `updateConfig` 后结合 `@RefreshScope` 实现热刷新。
+
+## 🔗 相关章节
+- 02_一基础设施-1.1缓存操作-SysCacheServiceFacade.md