feat: 文档更新
This commit is contained in:
49
docs/实施方案.md
49
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 展示骨架
|
||||
- **删除字段**：旧骨架中橙色 `<font color="warning">`
|
||||
- **新增字段**：新骨架中绿色 `<font color="info">`
|
||||
- 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
|
||||
|
||||
11
docs/配置说明.md
11
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 字段高亮颜色
|
||||
|
||||
|
||||
Reference in New Issue
Block a user