From c780b269d604178e28ffdaeb87420ccb988e9131 Mon Sep 17 00:00:00 2001 From: dongzi Date: Tue, 14 Jul 2026 17:47:11 +0800 Subject: [PATCH] =?UTF-8?q?feat:=20=E6=96=87=E6=A1=A3=E6=9B=B4=E6=96=B0?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit --- docs/实施方案.md | 49 ++++++++++++++++++++++++------------------------ docs/配置说明.md | 11 +++-------- 2 files changed, 28 insertions(+), 32 deletions(-) diff --git a/docs/实施方案.md b/docs/实施方案.md index 1c4237b..d20a472 100644 --- a/docs/实施方案.md +++ b/docs/实施方案.md @@ -143,7 +143,7 @@ flowchart TB 1. **纯静态分析**：基于 Java 源码 AST + 符号解析，不启动 Spring 容器 2. **Diff 驱动**：只分析本次 push 变更涉及的文件及其关联类型 3. **本仓限定**：类型解析仅在业务仓库 `src/main/java` 范围内 -4. **可配置**：忽略规则、严重级别、通知开关、阻断开关均可 YAML 配置 +4. **可配置**：忽略规则、通知开关、阻断开关均可 YAML 配置 5. **可演进**：已覆盖 JSON 字符串写入与 Template 直写 / Hash；后续可扩展读路径反向确认、报告落盘等 --- @@ -163,7 +163,7 @@ flowchart TB **不采用** Spoon / Eclipse JDT 的原因：JavaParser 足够覆盖第一版需求，依赖更轻，CLI 启动更快。 -**Lombok 处理策略**：第一版基于源码字段 + `@Data` 等注解推断序列化字段；对 `@Builder`、`@SuperBuilder` 等复杂场景标记为「低置信度」并降级为 P2 提示。后续可选集成 `lombok.ast` 或 delombok 预处理。 +**Lombok 处理策略**：基于源码字段 + `@Data` 等注解推断序列化字段；对 `@Builder`、`@SuperBuilder` 等复杂场景标记为低置信度提示。后续可选集成 `lombok.ast` 或 delombok 预处理。 --- @@ -353,19 +353,19 @@ redisUtil.insert(buildCacheKey(encode), JSON.toJSONString(envelope), ttl); 对比同一写入点在 old/new 两个版本的 `TypeSchema`，输出 `SchemaChange` 列表。 -**变更类型与严重级别**： +**变更类型**（有结构差异即告警；`block` 下任意变更均阻断）： -| 变更类型 | 示例 | 默认级别 | -|----------|------|----------| -| `FIELD_REMOVED` | 删除 `dbName` | P0 | -| `TYPE_CHANGED` | `linkList` 从数组变对象 | P0 | -| `WRAPPER_ADDED` | 顶层增加 `vo` 包装 | P0 | -| `FIELD_PATH_MOVED` | `dbName` → `vo.dbName` | P0 | -| `FIELD_ADDED` | 新增 `expiresAtMs` | P1 | -| `KEY_PATTERN_CHANGED` | key 常量变更 | P1 | -| `WRITE_POINT_REMOVED` | 删除缓存写入 | P1 | -| `WRITE_POINT_ADDED` | 新增缓存写入 | P2 | -| `LOW_CONFIDENCE` | 类型推断失败 | P2 | +| 变更类型 | 示例 | +|----------|------| +| `FIELD_REMOVED` | 删除 `dbName` | +| `TYPE_CHANGED` | `linkList` 从数组变对象 | +| `WRAPPER_ADDED` | 顶层增加 `vo` 包装 | +| `FIELD_PATH_MOVED` | `dbName` → `vo.dbName` | +| `FIELD_ADDED` | 新增 `expiresAtMs` | +| `KEY_PATTERN_CHANGED` | key 常量变更 | +| `WRITE_POINT_REMOVED` | 删除缓存写入 | +| `WRITE_POINT_ADDED` | 新增缓存写入 | +| `LOW_CONFIDENCE` | 类型推断失败（仍提示，置信度较低） | #### Step 8：报告与通知 @@ -377,13 +377,13 @@ redisUtil.insert(buildCacheKey(encode), JSON.toJSONString(envelope), ttl); 企微 Markdown 规则： -- 抬头不含 mode / P0~P2 汇总；正文按 Key 展示骨架 +- 抬头不含 mode 汇总；正文按 Key 展示骨架 - **删除字段**：旧骨架中橙色 `` - **新增字段**：新骨架中绿色 `` - key 未解析时展示源码表达式 + 灰色「（key 未解析）」 - 单条超 4096 UTF-8 字节时按 Key 拆成多条依次发送 -CI 控制台额外输出字段明细（含严重级别），再打印与企微一致的 Markdown。 +CI 控制台额外输出字段级变更明细（变更类型 + 位置 + 摘要），再打印与企微一致的 Markdown。 调用企微 Webhook 发送 Markdown（支持 `--dry-run` 仅本地输出）。 @@ -430,7 +430,7 @@ manual_mappings: | 层级 | 位置 | 职责 | |------|------|------| -| 默认配置 | 工具 jar 内 `default-config.yaml` | 检测模式、忽略规则、严重级别默认值 | +| 默认配置 | 工具 jar 内 `default-config.yaml` | 检测模式、忽略规则等默认值 | | 业务覆盖 | `jnpf-java-cloud/.gitea/config/cache-schema-check-config.yaml` | mode、notify、include_modules、manual_mappings | 合并规则：**业务配置覆盖默认配置**，未声明的项沿用默认值。 @@ -491,10 +491,10 @@ notify: | Git diff 扫描 | 变更文件列表 | ✅ | | W01~W03 写入点检测 | 覆盖 JSON 字符串写入 | ✅ | | 基础 Schema 提取 | 支持普通类、内部类、List、嵌套 | ✅ | -| Schema Diff | 字段增删、包装、路径迁移 | ✅ | +| Schema Diff | 字段增删、包装、路径迁移 | ✅ | | 企微通知 | 按 Key 骨架 Markdown | ✅ | | notify/block / enabled | 配置驱动 | ✅ | -| 夹具测试 | TenantVO/CacheEnvelope 样本 | ✅ | +| 样本夹具测试 | TenantVO/CacheEnvelope 等 | ✅ | **验收标准**： @@ -532,12 +532,14 @@ notify: - `RedisWritePointDetectorTest`：各种写入 AST 模式匹配 - `RedisKeyResolverTest`：常量、format、拼接推断 -### 11.2 夹具集成测试 +### 11.2 样本夹具测试（fixtures） -在 `src/test/resources/fixtures/` 放置真实业务代码片段（从 `jnpf-java-cloud` 提取并脱敏），模拟 old/new 两个版本： +「夹具」= 放在测试资源里的**脱敏源码样本**（不是连真实 Redis / 不是起 Gitea 流水线）。 -| 夹具 | 验证点 | -|------|--------| +路径：`src/test/resources/fixtures/`。测试代码加载这些 `.txt`/Java 片段，在内存中跑检测器 / Schema 对比，用来验证典型业务场景是否被正确识别。 + +| 夹具目录 | 验证点 | +|----------|--------| | `fixtures/tenant/` | 包装结构变更（TenantVO → CacheEnvelope） | | `fixtures/lock/` | 锁/计数器/token 应被忽略 | | `fixtures/template/` | W04 Template 直写 | @@ -598,7 +600,6 @@ public class WritePoint { ```java public class SchemaChange { - Severity severity; // P0, P1, P2 ChangeType changeType; // FIELD_REMOVED, WRAPPER_ADDED, ... String keyPattern; String writeLocation; // class#method:line diff --git a/docs/配置说明.md b/docs/配置说明.md index 872603f..919d316 100644 --- a/docs/配置说明.md +++ b/docs/配置说明.md @@ -106,17 +106,12 @@ detection: - W04 # redisTemplate 直写对象 - W05 # opsForHash().put - # 类型推断最低置信度，低于此值仅输出 P2 提示 + # 类型推断最低置信度，低于此值标记为低置信度提示 min_confidence: 0.6 # 字段展开最大深度（防止循环引用死循环） max_field_depth: 8 -# 严重级别覆盖（可选） -severity_overrides: - FIELD_ADDED: P1 - WRITE_POINT_ADDED: P2 - # 人工补充映射（自动推断失败或需精确指定时使用） manual_mappings: - id: tenant-db-content @@ -266,10 +261,10 @@ suppressions: ### 5.1 结构说明 -- 抬头：仓库、分支、提交、提交人、时间（**不再**展示 mode / P0P1P2 汇总） +- 抬头：仓库、分支、提交、提交人、时间（不展示 mode） - 正文：按 **一个 Redis Key 一块**，展示位置、类型与前后序列化骨架 - 超长（UTF-8 > 4096 字节）时按 key **拆成多条**消息依次发送 -- CI 控制台另打「字段明细」（含 P0/P1/P2），企微侧不分级别 +- CI 控制台另打「字段明细」（变更类型 / 位置 / 摘要），企微侧按骨架展示 ### 5.2 字段高亮颜色