npm - @alanwang-merit/meritdata-platform-skill-package - Versions diffs - 1.0.10 → 1.0.12 - Mend

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

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.

Files changed (631) hide show

package/skills/meritdata-platform-cache/references/distributed-lock.md DELETED Viewed

@@ -1,199 +0,0 @@
-# 分布式锁（cache）
-> 基于 Redis 的分布式锁实现。防重复提交、防并发修改、防超卖。
----
-## 1. 平台封装
-平台已封装 `DistributedLock` 接口，二开直接注入即可，不需要自己实现 SETNX。
-```java
-@Resource
-private DistributedLock distributedLock;
-```
-接口：
-```java
-public interface DistributedLock {
-    /**
-     * 尝试加锁
-     * @param key 锁 key
-     * @param waitSeconds 最长等待秒数
-     * @param leaseSeconds 锁自动释放秒数（防死锁）
-     * @return LockHandle（解锁用）
-     */
-    LockHandle tryLock(String key, long waitSeconds, long leaseSeconds);
-    /**
-     * 释放锁（必须在 finally 中调用）
-     */
-    void unlock(LockHandle handle);
-}
-```
-## 2. 基本用法
-### 2.1 防止重复提交
-```java
-@PostMapping("/order/submit")
-public Result submit(@RequestBody OrderRequest req) {
-    String userId = SecurityUtils.getCurrentUserId();
-    String lockKey = "lock:order:submit:" + userId;
-    LockHandle lock = distributedLock.tryLock(lockKey, 0, 30);
-    if (lock == null) {
-        return Result.error("操作过于频繁，请稍后再试");
-    }
-    try {
-        orderService.submit(req);
-        return Result.success();
-    } finally {
-        distributedLock.unlock(lock);
-    }
-}
-```
-### 2.2 防止超卖
-```java
-public void deductStock(String skuId, int quantity) {
-    String lockKey = "lock:stock:" + skuId;
-    LockHandle lock = distributedLock.tryLock(lockKey, 5, 10);
-    if (lock == null) {
-        throw new BizException("系统繁忙，请重试");
-    }
-    try {
-        int current = stockRepository.getStock(skuId);
-        if (current < quantity) {
-            throw new BizException("库存不足");
-        }
-        stockRepository.deduct(skuId, quantity);
-    } finally {
-        distributedLock.unlock(lock);
-    }
-}
-```
-### 2.3 定时任务防并发（多实例部署）
-```java
-@Scheduled(cron = "0 0 2 * * ?")
-public void dailyJob() {
-    String lockKey = "lock:job:dailyReport";
-    // waitSeconds=0: 不等待，拿不到锁就跳过
-    LockHandle lock = distributedLock.tryLock(lockKey, 0, 3600);
-    if (lock == null) {
-        log.info("另一个实例正在执行 dailyJob，跳过");
-        return;
-    }
-    try {
-        reportService.generate();
-    } finally {
-        distributedLock.unlock(lock);
-    }
-}
-```
-## 3. 关键参数
-### 3.1 waitSeconds（等待时间）
-| 值 | 场景 |
-|----|------|
-| 0 | 不等待，拿不到锁立即失败（防止重复提交） |
-| 1 ~ 5 | 短暂等待（库存扣减） |
-| 30+ | 长时间等待（一般不建议，业务应快速失败） |
-### 3.2 leaseSeconds（锁持有时间）
-**必须**设置且**必须** < 实际业务执行时间。防宕机导致死锁。
-```java
-// ❌ 错：leaseSeconds 不设或太长
-distributedLock.tryLock("key", 0, 99999);  // 30 小时后才会自动释放
-// ✅ 正确：根据业务最长执行时间
-distributedLock.tryLock("key", 0, 30);  // 30 秒后自动释放
-```
-### 3.3 锁粒度
-```java
-// ❌ 错：锁粒度太粗（全部用户一把锁）
-String lockKey = "lock:submit";
-// ✅ 正确：按用户隔离
-String lockKey = "lock:submit:" + userId;
-// ✅ 正确：按资源隔离
-String lockKey = "lock:stock:" + skuId;
-```
-## 4. ❌ 反模式
-### 4.1 ❌ 不释放锁
-```java
-// ❌ 错：忘记 unlock
-LockHandle lock = distributedLock.tryLock("key", 0, 30);
-if (lock != null) {
-    doSomething();
-    // 漏掉 unlock！
-}
-```
-✅ **必须**用 try-finally。
-### 4.2 ❌ 在锁内做 HTTP 调用
-```java
-// ❌ 错：锁内做远程调用（锁持有时间过长）
-LockHandle lock = distributedLock.tryLock("key", 0, 30);
-try {
-    String data = httpClient.get("https://slow-api.com");  // 慢调用！
-    process(data);
-} finally {
-    distributedLock.unlock(lock);
-}
-```
-✅ 锁内**只**做必要的临界区操作。
-### 4.3 ❌ 锁粒度过粗导致性能瓶颈
-```java
-// ❌ 错：所有订单一把锁
-String lockKey = "lock:order";
-// ✅ 正确：按订单 ID 隔离
-String lockKey = "lock:order:" + orderId;
-```
-### 4.4 ❌ 自己实现 SETNX
-```java
-// ❌ 错：自实现，没有 lease 机制 → 死锁风险
-if (redis.setnx(key, "1")) {
-    // 没有 expire → 如果进程崩溃 → 死锁
-}
-```
-✅ 用平台 DistributedLock（内部已用 Lua 脚本保证原子性）。
-## 5. Redlock（高级）
-需要更高可靠性（如金融场景）时，可考虑 Redlock 算法（多个独立 Redis 实例）。
-平台暂未集成，二开需要时使用 [Redisson](https://redisson.org/)。
-## 6. 关联阅读
-- [guide.md](guide.md) — 缓存基础
-- [resilience.md](resilience.md) — 防穿透/击穿/雪崩
-- [key-design.md](key-design.md) — 缓存 key 设计
-- [SKILL.md](../SKILL.md)

package/skills/meritdata-platform-cache/references/guide.md DELETED Viewed

@@ -1,141 +0,0 @@
-# 平台缓存指南（cache）
-> **核心约束**：缓存 key **必须包含用户/租户标识**；敏感数据禁止缓存；必须有 TTL。
----
-## 1. 引入依赖
-```xml
-<dependency>
-    <groupId>org.springframework.boot</groupId>
-    <artifactId>spring-boot-starter-data-redis</artifactId>
-</dependency>
-<dependency>
-    <groupId>org.springframework.boot</groupId>
-    <artifactId>spring-boot-starter-cache</artifactId>
-</dependency>
-```
-## 2. application.yml
-```yaml
-spring:
-  redis:
-    host: ${REDIS_HOST:localhost}
-    port: ${REDIS_PORT:6379}
-    password: ${REDIS_PASSWORD:}
-    database: 0
-    timeout: 3000
-    lettuce:
-      pool:
-        max-active: 20
-        max-idle: 10
-        min-idle: 5
-        max-wait: 2000
-  cache:
-    type: redis
-    redis:
-      time-to-live: 600000      # 默认 TTL 10 分钟
-      cache-null-values: false   # 不缓存 null
-```
-## 3. @Cacheable 用法
-### 3.1 基本用法
-```java
-@Cacheable(value = "user", key = "#userId")
-public UserDTO getById(String userId) {
-    return userRepository.findById(userId).orElse(null);
-}
-```
-### 3.2 ✅ 正确：缓存 key 带用户/租户标识
-```java
-// ✅ 正确：缓存 key 包含 userId 和 tenantId 实现隔离
-@Cacheable(value = "user", key = "#userId + ':' + T(SecurityUtils).getCurrentTenantId()")
-public UserDTO getById(String userId) { ... }
-// ✅ 正确：缓存 key 包含 orgId 实现组织隔离
-@Cacheable(value = "orderList", key = "T(SecurityUtils).getCurrentOrgId() + ':' + #status")
-public List<Order> listByStatus(String status) { ... }
-```
-### 3.3 ❌ 反例：缓存 key 全局共享
-```java
-// ❌ 错：key 只有 userId → 不同租户的数据混淆
-@Cacheable(value = "user", key = "#userId")
-public UserDTO getById(String userId) { ... }
-// ❌ 错：常量 key → 所有人都共享同一份
-@Cacheable(value = "globalConfig", key = "'config'")
-public Config getConfig() { ... }
-```
-## 4. 缓存注解
-| 注解 | 用途 |
-|------|------|
-| `@Cacheable` | 查：先查缓存，没有再调方法 |
-| `@CachePut` | 改：每次都执行方法，并更新缓存 |
-| `@CacheEvict` | 删：清除缓存 |
-| `@Caching` | 组合多个缓存操作 |
-```java
-@Caching(
-    put = @CachePut(value = "user", key = "#user.id"),
-    evict = @CacheEvict(value = "userList", allEntries = true)
-)
-public UserDTO update(UserDTO user) { ... }
-```
-## 5. RedisTemplate 用法（精细控制）
-```java
-@Autowired
-private StringRedisTemplate redisTemplate;
-public void demo() {
-    // 设置（带 TTL）
-    redisTemplate.opsForValue().set("key", "value", Duration.ofMinutes(10));
-    // 获取
-    String value = redisTemplate.opsForValue().get("key");
-    // 删除
-    redisTemplate.delete("key");
-    // 批量删除（按前缀）
-    Set<String> keys = redisTemplate.keys("user:10001:*");
-    redisTemplate.delete(keys);
-}
-```
-## 6. 缓存穿透 / 击穿 / 雪崩
-详见 [resilience.md](resilience.md)。
-## 7. 分布式锁
-详见 [distributed-lock.md](distributed-lock.md)。
-## 8. ❌ 反模式汇总
-| 反模式 | 后果 |
-|--------|------|
-| 缓存 key 无用户标识 | 数据泄露 / 跨租户串数据 |
-| 缓存无 TTL | 内存泄漏 |
-| 缓存敏感数据（密码/token）| 安全风险 |
-| 用 @Cacheable 缓存 null | 缓存穿透 |
-| 缓存更新不及时 | 数据不一致 |
-## 9. 关联阅读
-- [key-design.md](key-design.md) — 缓存 key 设计
-- [resilience.md](resilience.md) — 防穿透 / 击穿 / 雪崩
-- [distributed-lock.md](distributed-lock.md) — 分布式锁
-- [SKILL.md](../SKILL.md)

package/skills/meritdata-platform-cache/references/key-design.md DELETED Viewed

@@ -1,167 +0,0 @@
-# 缓存 key 设计规范（cache）
-> 缓存 key 是缓存的"身份证"。设计不当 → 数据泄露 / 跨租户串数据 / 缓存失效。
----
-## 1. key 命名格式
-### 1.1 三段式命名
-```
-{业务域}:{资源名}:{业务标识[:扩展标识]}
-```
-| 段 | 含义 | 示例 |
-|----|------|------|
-| 业务域 | 模块名（防止不同模块 key 冲突）| `order`、`user`、`config` |
-| 资源名 | 缓存的对象类型 | `info`、`list`、`count` |
-| 业务标识 | 缓存对象的唯一 ID | `userId`、`orderNo` |
-| 扩展标识 | 可选，用于二级隔离 | `tenantId`、`orgId` |
-### 1.2 ✅ 正确示例
-```java
-// 用户信息（单对象）
-"user:info:" + userId + ":" + tenantId
-// 订单列表（按用户 + 状态）
-"order:list:user:" + userId + ":status:" + status + ":" + tenantId
-// 字典项（全局但按租户）
-"dict:items:type:" + dictType + ":tenant:" + tenantId
-// 配置项（全局共享）
-"config:global:feature_flags"
-```
-### 1.3 ❌ 反例
-```java
-// ❌ 无业务域前缀（key 冲突风险）
-userId + "_info"
-// ❌ 无租户标识（跨租户串数据）
-"user:info:" + userId
-// ❌ 把敏感数据放 key
-"user:info:" + userId + ":" + phone  // phone 进 key 可能被日志泄露
-// ❌ key 太长（>200 字符）
-"order:list:" + a + ":" + b + ":" + c + ":" + d + ":" + e + ":" + f + ...
-```
-## 2. 必须包含的标识
-### 2.1 用户级隔离（个人数据）
-```java
-// ✅ 正确：key 包含 userId
-"user:info:" + userId
-```
-### 2.2 租户/组织级隔离（多租户系统）
-```java
-// ✅ 正确：key 包含 tenantId
-"order:list:tenant:" + tenantId + ":user:" + userId
-```
-### 2.3 全局共享（无隔离需求）
-```java
-// ✅ 正确：配置项等全局数据
-"config:global:datasource"
-```
-## 3. TTL 设计
-| 数据类型 | 推荐 TTL | 理由 |
-|----------|---------|------|
-| 用户信息 | 10 ~ 30 分钟 | 中等频次更新 |
-| 配置项 | 5 ~ 30 分钟 | 配合 @NacosValue 自动刷新 |
-| 字典项 | 1 ~ 24 小时 | 很少变 |
-| 会话/token | 跟随 token 过期 | 严格匹配 |
-| 临时计算结果 | 1 ~ 5 分钟 | 高频过期 |
-| 列表查询 | 30 秒 ~ 5 分钟 | 频繁变更 |
-```java
-// RedisTemplate 设置 TTL
-redisTemplate.opsForValue().set(key, value, Duration.ofMinutes(10));
-// @Cacheable 设置 TTL
-@Cacheable(value = "user", key = "#userId", cacheManager = "tenMinutesCacheManager")
-```
-## 4. 删除策略
-### 4.1 精确删除
-```java
-// 删除单个 key
-redisTemplate.delete("user:info:" + userId);
-// 删除同前缀的多个 key（慎用 KEYS，性能差）
-Set<String> keys = redisTemplate.keys("user:info:10001:*");
-redisTemplate.delete(keys);
-// 推荐：用 SCAN 代替 KEYS
-ScanOptions options = ScanOptions.scanOptions().match("user:info:10001:*").count(100);
-Cursor<byte[]> cursor = redisTemplate.executeWithStickyConnection(
-    connection -> connection.scan(options)
-);
-```
-### 4.2 模糊删除（按模式）
-```java
-public void evictByPrefix(String prefix) {
-    Set<String> keys = redisTemplate.keys(prefix + "*");
-    if (keys != null && !keys.isEmpty()) {
-        redisTemplate.delete(keys);
-    }
-}
-```
-## 5. 序列化
-### 5.1 JSON 序列化（推荐）
-```java
-@Bean
-public RedisTemplate<String, Object> redisTemplate(RedisConnectionFactory factory) {
-    RedisTemplate<String, Object> template = new RedisTemplate<>();
-    template.setConnectionFactory(factory);
-    ObjectMapper mapper = new ObjectMapper();
-    mapper.activateDefaultTyping(
-        mapper.getPolymorphicTypeValidator(),
-        ObjectMapper.DefaultTyping.NON_FINAL,
-        JsonTypeInfo.As.PROPERTY
-    );
-    Jackson2JsonRedisSerializer<Object> serializer =
-        new Jackson2JsonRedisSerializer<>(mapper, Object.class);
-    template.setKeySerializer(new StringRedisSerializer());
-    template.setValueSerializer(serializer);
-    return template;
-}
-```
-### 5.2 序列化选型
-| 序列化方式 | 优点 | 缺点 |
-|-----------|------|------|
-| JSON | 可读、跨语言、通用 | 体积较大、性能一般 |
-| Protobuf | 高性能、小体积 | 不可读、需 schema |
-| JDK | 默认 | 体积大、不可读、版本敏感 |
-**推荐**：调试阶段用 JSON；性能敏感用 Protobuf。
-## 6. 关联阅读
-- [guide.md](guide.md) — 缓存基础用法
-- [resilience.md](resilience.md) — 防穿透/击穿/雪崩
-- [distributed-lock.md](distributed-lock.md) — 分布式锁
-- [SKILL.md](../SKILL.md)

package/skills/meritdata-platform-cache/references/resilience.md DELETED Viewed

@@ -1,181 +0,0 @@
-# 缓存防穿透 / 击穿 / 雪崩（cache）
-> 三大经典缓存异常场景及平台标准解法。
----
-## 1. 概念速查
-| 问题 | 触发条件 | 后果 |
-|------|---------|------|
-| **穿透** | 查询不存在的 key（DB 也没有）| 每次都打到 DB，DB 压力大 |
-| **击穿** | 热点 key 过期瞬间 + 大量并发 | 同一瞬间全部打到 DB |
-| **雪崩** | 大量 key 同时过期 | DB 被瞬时大量请求打挂 |
-## 2. 防穿透（Cache Penetration）
-### 2.1 场景
-```java
-// 攻击者/爬虫查询不存在的 userId
-getUserById("1000000000000");  // DB 中不存在
-```
-每次都打到 DB。
-### 2.2 解法 1：缓存空值
-```java
-@Cacheable(value = "user", key = "#userId", unless = "#result == null")
-public UserDTO getById(String userId) {
-    return userRepository.findById(userId).orElse(null);
-}
-```
-注意：`unless` 让 null 也缓存；但需设置较短 TTL 防止内存泄漏。
-### 2.3 解法 2：布隆过滤器（数据量大时）
-```java
-@Resource
-private BloomFilter<String> userBloomFilter;
-public UserDTO getById(String userId) {
-    // 1. 先查布隆过滤器（不存在 → 直接返回）
-    if (!userBloomFilter.mightContain(userId)) {
-        return null;
-    }
-    // 2. 查缓存
-    UserDTO user = redis.get("user:info:" + userId);
-    if (user != null) return user;
-    // 3. 查 DB
-    user = userRepository.findById(userId).orElse(null);
-    if (user != null) {
-        redis.setex("user:info:" + userId, 600, JSON.toJSONString(user));
-    }
-    return user;
-}
-```
-## 3. 防击穿（Cache Breakdown）
-### 3.1 场景
-热点 key（如明星产品 SKU）过期瞬间 + 1 万并发 → 全部打到 DB。
-### 3.2 解法：分布式锁 + 单线程回源
-```java
-public UserDTO getById(String userId) {
-    String key = "user:info:" + userId;
-    UserDTO user = redis.get(key);
-    if (user != null) return user;
-    // 加分布式锁，只让一个线程回源
-    String lockKey = "lock:user:" + userId;
-    if (redisLock.tryLock(lockKey, 5, 30)) {  // 等待 5s，锁 30s 自动释放
-        try {
-            // 双重检查（已上锁后再查一次）
-            user = redis.get(key);
-            if (user != null) return user;
-            user = userRepository.findById(userId).orElse(null);
-            if (user != null) {
-                redis.setex(key, 600, JSON.toJSONString(user));
-            }
-            return user;
-        } finally {
-            redisLock.unlock(lockKey);
-        }
-    } else {
-        // 没拿到锁 → 等一会再查缓存
-        try { Thread.sleep(50); } catch (InterruptedException e) {}
-        return redis.get(key);
-    }
-}
-```
-详见 [distributed-lock.md](distributed-lock.md)。
-### 3.3 解法：逻辑过期（异步刷新，不阻塞）
-```java
-@Data
-public class CacheWrapper<T> {
-    private T data;
-    private long expireTime;   // 逻辑过期时间
-}
-// 读缓存
-public UserDTO getById(String userId) {
-    String key = "user:info:" + userId;
-    CacheWrapper<UserDTO> wrapper = redis.get(key);
-    if (wrapper == null) {
-        // 缓存中没有 → 同步回源
-        return loadFromDb(userId);
-    }
-    if (wrapper.getExpireTime() < System.currentTimeMillis()) {
-        // 逻辑过期 → 异步刷新（不等）
-        asyncExecutor.execute(() -> refreshCache(userId));
-    }
-    return wrapper.getData();
-}
-```
-## 4. 防雪崩（Cache Avalanche）
-### 4.1 场景
-某天 0 点批量缓存统一过期（如 100 万 key），0:00:00 → 0:00:01 全部打到 DB。
-### 4.2 解法 1：TTL 加随机值
-```java
-int baseTtl = 600;  // 10 分钟
-int jitter = RandomUtils.nextInt(0, 60);  // 0 ~ 60 秒随机
-int actualTtl = baseTtl + jitter;
-redisTemplate.opsForValue().set(key, value, Duration.ofSeconds(actualTtl));
-```
-### 4.3 解法 2：多级缓存
-```
-L1: Caffeine（本地，1s ~ 10s TTL）
-   ↓ 未命中
-L2: Redis（远程，10 分钟 TTL）
-   ↓ 未命中
-L3: DB
-```
-详见 [Caffeine 集成](https://github.com/ben-manes/caffeine)。
-### 4.4 解法 3：熔断降级
-```java
-public UserDTO getById(String userId) {
-    try {
-        return queryWithCache(userId);
-    } catch (RedisConnectionFailureException e) {
-        log.warn("Redis 不可用，降级到 DB 直查", e);
-        // 熔断：直接走 DB
-        return userRepository.findById(userId).orElse(null);
-    }
-}
-```
-详见 Sentinel/Hystrix 集成。
-## 5. 三种问题速查
-| 问题 | 关键点 | 关键解法 |
-|------|--------|---------|
-| 穿透 | key 不存在 | 空值缓存 / 布隆过滤器 |
-| 击穿 | 单 key 热点过期 | 分布式锁 / 逻辑过期 |
-| 雪崩 | 批量 key 同时过期 | TTL 抖动 / 多级缓存 |
-## 6. 关联阅读
-- [guide.md](guide.md) — 缓存基础
-- [key-design.md](key-design.md) — 缓存 key 设计
-- [distributed-lock.md](distributed-lock.md) — 分布式锁
-- [SKILL.md](../SKILL.md)