feat: 文档更新

2026-07-14 17:11:58 +08:00
parent 6e06cbf5b5
commit 1f119edb7c
3 changed files with 190 additions and 122 deletions
--- a/docs/配置说明.md
+++ b/docs/配置说明.md
@@ -1,6 +1,8 @@
 # 缓存序列化结构检测 — 配置说明

-> **双层配置**：工具 jar 内置 `default-config.yaml`（默认） + 业务仓库 `.gitea/config/cache-schema-check-config.yaml`（覆盖）
+> **双层配置**：工具 jar 内置 `default-config.yaml`（默认） + 业务仓库 `.gitea/config/cache-schema-check-config.yaml`（覆盖）  
+> 工具坐标：`com.codechecker:cache-schema-checker:1.0.0`  
+> 主类：`com.codechecker.cache.cli.CacheSchemaCheckerMain`

 ---

@@ -22,23 +24,28 @@ jar 内 default-config.yaml（工具仓维护）

 ```yaml
 # jnpf-java-cloud/.gitea/config/cache-schema-check-config.yaml
+enabled: true
 mode: notify

 notify:
  enabled: true
-  webhook_env: WECOM_ROBOT_WEBHOOK
+  # 推荐直接写完整 Webhook；也可用环境变量在流水线注入
+  webhook_url: ""

 include_modules:
  - jnpf-tenant
 ```

+流水线通常把 Secret 注入环境或配置文件中的 `webhook_url`。兼容旧字段：`webhook_env`（值为 `http` 开头时当作 URL 使用）。
+
 ### 1.2 工具内置默认配置（jar 内 default-config.yaml）

-由 `redisCheck` 仓库维护，随 jar 发布，包含：
+由 `redisCheck` 仓库维护，随 jar 发布，默认包含：

- `detection.patterns`（W01~W03）
- `ignore.key_patterns`（锁/计数器/token）
- `detection.min_confidence`、`max_field_depth` 等
+- `detection.patterns`：**W01~W05**（JSON 字符串写入 + Template 直写 + Hash）
+- `ignore.key_patterns`（锁 / 计数器 / token）
+- `detection.min_confidence`、`max_field_depth`
+- `mode: notify`、`enabled: true`

 ---

@@ -63,8 +70,10 @@ source_roots:
 # 通知配置
 notify:
  enabled: true
-  # 从环境变量读取 Webhook URL
-  webhook_env: WECOM_ROBOT_WEBHOOK
+  # Webhook 完整 URL（优先）
+  webhook_url: ""
+  # 兼容旧字段：值为 http 开头时视为 URL
+  # webhook_env: WECOM_ROBOT_WEBHOOK
  # 无变更时是否也发通知（一般 false）
  notify_on_clean: false
  # 消息标题前缀
@@ -76,9 +85,9 @@ ignore:
  key_patterns:
    - "*:lock"
    - "*:lock:*"
+    - "*lock*"
    - "loginCount:*"
    - "Authorization:*"
-    - "Authorization:login:session:*"

  # 忽略的文件路径模式
  file_patterns:
@@ -89,7 +98,7 @@ ignore:

 # 检测规则
 detection:
-  # 启用的写入模式
+  # 启用的写入模式（默认已全部开启）
  patterns:
    - W01   # redisUtil.insert + JSON.toJSONString
    - W02   # redisTemplate.opsForValue().set + JSON.toJSONString
@@ -171,7 +180,8 @@ mode: block
 | 字段 | 类型 | 默认值 | 说明 |
 |------|------|--------|------|
 | `enabled` | boolean | true | 是否发企微 |
-| `webhook_env` | string | WECOM_ROBOT_WEBHOOK | 环境变量名 |
+| `webhook_url` | string | `""` | 企微机器人 Webhook 完整 URL（优先） |
+| `webhook_env` | string | — | 兼容旧字段；值为 `http` 开头时当作 URL |
 | `notify_on_clean` | boolean | false | 无变更时是否通知 |
 | `title_prefix` | string | [缓存结构变更] | 消息标题前缀 |

@@ -182,25 +192,33 @@ mode: block
 - `*` 匹配单层
 - `**` 匹配多层

-常见内置忽略（代码层也有硬编码兜底）：
+内置/代码层常见过滤：

- 分布式锁 key
- 登录计数
- session/token
+- 分布式锁 key（配置 glob + 方法名忽略）
+- 登录计数、session/token
+- 琐碎 value：字面量、`"1"`、`UUID.randomUUID()` 等
+- 方法：`setIfAbsent` / `increment` / `delete` / `expire` 等

 ### 3.5 detection.patterns

-| 模式 | 说明 | 阶段 |
+| 模式 | 说明 | 状态 |
 |------|------|------|
-| W01 | `redisUtil.insert(key, JSON.toJSONString(x), ttl)` | Phase 1 |
-| W02 | `redisTemplate.opsForValue().set(key, JSON.toJSONString(x), ...)` | Phase 1 |
-| W03 | `stringRedisTemplate.opsForValue().set(key, JsonUtil.getObjectToString(x), ...)` | Phase 1 |
-| W04 | `redisTemplate.opsForValue().set(key, obj, ...)` | Phase 2（已启用） |
-| W05 | `redisTemplate.opsForHash().put(key, field, obj)` | Phase 2（已启用） |
+| W01 | `redisUtil.insert(key, JSON.toJSONString(x), ttl)` | 已启用 |
+| W02 | `redisTemplate.opsForValue().set(key, JSON.toJSONString(x), ...)` | 已启用 |
+| W03 | `stringRedisTemplate.opsForValue().set(key, JsonUtil.getObjectToString(x), ...)` | 已启用 |
+| W04 | `redisTemplate.opsForValue().set(key, obj, ...)` 直写对象 | 已启用（Phase 2） |
+| W05 | `redisTemplate.opsForHash().put(key, field, obj)` | 已启用（Phase 2） |
+
+业务仓可通过只声明子集暂时关闭某些模式，例如仅保留 JSON 写入：
+
+```yaml
+detection:
+  patterns: [W01, W02, W03]
+```

 ### 3.6 manual_mappings

-当自动推断不准确时使用。匹配优先级 **高于** 自动推断。
+当自动推断不准确时使用。匹配优先级 **高于** 自动推断（按 `类全名#方法名` 覆盖 key 模式与 value 类型）。

 | 字段 | 必填 | 说明 |
 |------|------|------|
@@ -217,59 +235,97 @@ mode: block
 ```yaml
 suppressions:
  - id: my-suppression
-    writer_method: "com.example.FooService#cacheBar"
+    key_pattern: "file:download:user:progress:*"
    change_types:
      - FIELD_ADDED
    reason: "新增字段向后兼容"
 ```

+### 3.8 include_modules / exclude_modules
+
+| 字段 | 说明 |
+|------|------|
+| `include_modules` | 非空时仅扫描列出的顶层模块；空表示全仓 |
+| `exclude_modules` | 始终排除的顶层模块 |
+
+顶层模块取路径第一段，例如 `jnpf-tenant/jnpf-tenant-biz/src/main/java/...` → `jnpf-tenant`。
+
 ---

-## 4. 环境变量
+## 4. 环境变量 / Secret

 | 变量 | 必填 | 说明 |
 |------|------|------|
-| `WECOM_ROBOT_WEBHOOK` | notify.enabled=true 时必填 | 企微机器人 Webhook 完整 URL |
+| `WECOM_ROBOT_WEBHOOK` | 视流水线写法 | 可将 Secret 写入配置中的 `webhook_url`，或在启动前注入 |

 在 Gitea 仓库 Settings → Secrets 中配置。

 ---

-## 5. 企微消息格式示例
+## 5. 企微消息格式
+
+### 5.1 结构说明
+
+- 抬头：仓库、分支、提交、提交人、时间（**不再**展示 mode / P0P1P2 汇总）
+- 正文：按 **一个 Redis Key 一块**，展示位置、类型与前后序列化骨架
+- 超长（UTF-8 > 4096 字节）时按 key **拆成多条**消息依次发送
+- CI 控制台另打「字段明细」（含 P0/P1/P2），企微侧不分级别
+
+### 5.2 字段高亮颜色
+
+| 变更 | 企微颜色 | Markdown |
+|------|----------|----------|
+| 字段删除（标在旧骨架） | 橙色 | `<font color="warning">…</font>` |
+| 字段新增 / 包装层（标在新骨架） | 绿色 | `<font color="info">…</font>` |
+| 路径迁移 | 旧橙 / 新绿 | 同上 |
+| key 未解析提示 | 灰色 | `<font color="comment">（key 未解析）</font>` |
+
+### 5.3 示例（已解析 key）

 ```markdown
 ## [缓存结构变更] jnpf-java-cloud

-> 分支: feature/tenant-cache
-> 提交: a1b2c3d → e4f5g6h
-> 提交人: zhangsan
-> 时间: 2026-07-13 14:00:00
-> 模式: notify
+> **分支**: code/redis_change_detection_v1.0
+> **提交**: cedd161c → 67c8a6eb
+> **提交人**: dongzi
+> **时间**: 2026-07-13 16:54:17

-### P0 - 顶层结构包装变更
- **Key**: `tenant:db:content:*`
- **位置**: `TenantDbContentCacheHelper#cacheSuccess:92`
- **变更**:
-  - `dbName` → `vo.dbName`（字段路径迁移）
-  - `linkList` → `vo.linkList`（字段路径迁移）
-  - 新增顶层字段 `expiresAtMs`
- **影响**: 旧缓存反序列化可能失败，需评估缓存刷新策略
+- Key --> `tenant:db:content:*`
+  > **位置**: `TenantDbContentCacheHelper#cacheSuccess:92`
+  > **类型**: `CacheEnvelope`
+  > **value值由：** “{"dbName":"","linkList":[{"id":""}]}”
+  > **变更为：** “…（仅新增/迁移字段片段带 <font color="info">绿色</font>）…”
 ```

+实际发送时仅对改动属性片段染色：新增 → `info`（绿），删除 → `warning`（橙）。
+
+### 5.4 示例（key 未解析）
+
+```markdown
+- Key --> `req.getKey()` <font color="comment">（key 未解析）</font>
+  > **位置**: `ClockInXxxService#export:128`
+  > **类型**: `List<ClockInExportVo>`
+  > **value值由：** “{"a":""}”
+  > **变更为：** “…新增字段带绿色高亮…”
+```
+
+未解析时按「写入位置 + key 表达式」拆分聚合，避免多个未知 key 串在一起。
+
 ---

 ## 6. 推荐上线配置

-### 6.1 观察期（第 1 周，已确认策略）
+### 6.1 观察期（第 1 周）

 业务仓默认配置：

 ```yaml
+enabled: true
 mode: notify

 notify:
  enabled: true
-  webhook_env: WECOM_ROBOT_WEBHOOK
+  webhook_url: ""   # 由流水线写入真实 Webhook

 include_modules:
  - jnpf-tenant
@@ -285,6 +341,7 @@ include_modules: []  # 扩至全仓
 ### 6.2 全量启用（观察期结束后）

 ```yaml
+enabled: true
 mode: block
 include_modules: []  # 空表示全部模块
 detection: