199 lines
7.6 KiB
Markdown
199 lines
7.6 KiB
Markdown
# 序列化结构检测器 — 工程结构说明
|
||
|
||
> 工程：`serialization-schema-checker`（`com.codechecker:serialization-schema-checker`）
|
||
> 定位：基于 JavaParser 的 **Redis 缓存 / MQ（RocketMQ、Kafka）value 序列化结构变更** 静态检测工具
|
||
> 当前版本：`1.1.0` · Java 11 · 可执行 Fat Jar（maven-shade）
|
||
|
||
---
|
||
|
||
## 1. 仓库顶层结构
|
||
|
||
```text
|
||
redisCheck/
|
||
├── pom.xml # Maven 单模块工程
|
||
├── .gitea/ # Gitea Actions 与示例/自检配置
|
||
│ ├── workflows/
|
||
│ │ └── serialization-schema-check.yaml
|
||
│ └── config/
|
||
│ └── serialization-schema-check-config.yaml
|
||
├── docs/ # 方案、配置与集成文档（本目录）
|
||
├── src/
|
||
│ ├── main/
|
||
│ │ ├── java/com/codechecker/cache/ # 主代码（按职责分包）
|
||
│ │ └── resources/
|
||
│ │ └── default-config.yaml # jar 内置默认配置
|
||
│ └── test/
|
||
│ ├── java/com/codechecker/cache/ # 单测 / 场景测
|
||
│ └── resources/fixtures/ # 源码片段夹具
|
||
└── target/ # 构建产物（不入库）
|
||
```
|
||
|
||
---
|
||
|
||
## 2. 主代码包结构
|
||
|
||
根包：`com.codechecker.cache`
|
||
|
||
```text
|
||
com.codechecker.cache
|
||
├── cli/ # 命令行入口
|
||
├── config/ # 配置模型与加载
|
||
├── git/ # Git diff / show 封装
|
||
├── analyze/ # 扫描编排与主分析流程
|
||
├── detector/ # 写入点 / 读侧提示检测
|
||
├── key/ # Redis key 表达式解析
|
||
├── schema/ # 类型索引、字段 Schema、骨架 JSON
|
||
├── diff/ # Schema Diff 与变更类型
|
||
├── report/ # 报告模型与渲染
|
||
└── notify/ # 企微机器人通知
|
||
```
|
||
|
||
### 2.1 包职责与主要类
|
||
|
||
| 包 | 职责 | 主要类 |
|
||
|----|------|--------|
|
||
| **cli** | picocli 入口；加载配置 → 分析 → 控制台报告 → 可选通知 | `SerializationSchemaCheckerMain` |
|
||
| **config** | 默认配置与业务配置深度合并；运行时配置模型 | `ConfigLoader`、`CheckerConfig` |
|
||
| **git** | 变更 Java 文件列表、按 SHA 取文件内容 | `GitDiffScanner`、`GitException` |
|
||
| **analyze** | 端到端编排：候选文件 → 写点检测 → Schema 提取 → Diff → 报告 | `SchemaCheckAnalyzer`、`FileScanner`、`GlobMatcher` |
|
||
| **detector** | 识别 Redis/MQ 写入（投递）点与读侧类型提示 | `RedisWritePointDetector`、`MqWritePointDetector`、`CacheReadHintDetector`、`MqReadHintDetector`、`BareValueTypes`、`WritePoint`、`CacheReadHint` |
|
||
| **key** | 将 key 表达式解析为模式（如 `demo:foo:*`） | `RedisKeyResolver` |
|
||
| **schema** | 源码类型索引、字段展开、骨架 JSON 渲染 | `SourceIndex`、`JavaSchemaExtractor`、`TypeSchema`、`FieldSchema`、`SkeletonJsonRenderer`、`AnnotationSupport`、`JsonType` |
|
||
| **diff** | 新旧 Schema 对比，产出变更明细 | `SchemaDiffer`、`SchemaChange`、`ChangeType`、`Severity` |
|
||
| **report** | 按 Key/Topic 聚合、企微 Markdown / 控制台文本 | `CheckReport`、`KeyStructureChange`、`ReportBuilder`、`SkeletonAnnotator` |
|
||
| **notify** | 企微机器人 Webhook 发送 | `WeComNotifier` |
|
||
|
||
### 2.2 核心数据模型（实体）
|
||
|
||
| 类 | 含义 |
|
||
|----|------|
|
||
| `WritePoint` | 一处 Redis 写入或 MQ 投递点（通道、key/topic、value 类型、位置） |
|
||
| `CacheReadHint` | 读侧反序列化推断出的类型提示（补强写入点，不单独告警） |
|
||
| `TypeSchema` / `FieldSchema` | value 类型展开后的扁平 Schema |
|
||
| `SchemaChange` | 单条结构变更（类型、路径、严重级别、说明） |
|
||
| `KeyStructureChange` | 按 Key/Topic 聚合的摘要（含前后骨架 JSON） |
|
||
| `CheckReport` | 一次检测的完整结果 |
|
||
| `CheckerConfig` | 运行配置（含 Notify / Ignore / Detection 等嵌套结构） |
|
||
|
||
---
|
||
|
||
## 3. 运行时数据流
|
||
|
||
```text
|
||
SerializationSchemaCheckerMain
|
||
│
|
||
▼
|
||
ConfigLoader.load(--config)
|
||
│ jar 内 default-config.yaml ⊕ 业务配置
|
||
▼
|
||
SchemaCheckAnalyzer.analyze(oldSha, newSha)
|
||
│
|
||
├─ GitDiffScanner → 变更 .java 文件
|
||
├─ FileScanner → 读新旧源码内容
|
||
├─ SourceIndex → 建类型索引
|
||
├─ Redis/Mq WritePointDetector → 写入/投递点
|
||
├─ Cache/Mq ReadHintDetector → 读侧类型补强
|
||
├─ JavaSchemaExtractor → 展开 TypeSchema
|
||
├─ SchemaDiffer → SchemaChange 列表
|
||
└─ 聚合 KeyStructureChange → CheckReport
|
||
│
|
||
▼
|
||
ReportBuilder （控制台 + 企微 Markdown）
|
||
│
|
||
▼
|
||
WeComNotifier （可选，--dry-run 时跳过）
|
||
```
|
||
|
||
**退出码约定**
|
||
|
||
| 码 | 含义 |
|
||
|----|------|
|
||
| `0` | 通过、跳过（`enabled=false` / 无基准 SHA）或 notify 模式有变更 |
|
||
| `1` | `mode=block` 且检测到结构变更 |
|
||
| `2` | 执行异常 |
|
||
|
||
---
|
||
|
||
## 4. 资源与配置
|
||
|
||
| 路径 | 说明 |
|
||
|------|------|
|
||
| `src/main/resources/default-config.yaml` | 工具内置默认：检测模式、忽略规则、严重级别等 |
|
||
| 业务仓 `.gitea/config/serialization-schema-check-config.yaml` | 业务覆盖配置（流水线 `--config` 指向） |
|
||
| 本仓 `.gitea/config/serialization-schema-check-config.yaml` | 工具仓自用/示例配置 |
|
||
|
||
配置合并与字段说明见：[配置说明.md](./配置说明.md)
|
||
|
||
---
|
||
|
||
## 5. 测试结构
|
||
|
||
```text
|
||
src/test/java/com/codechecker/cache/
|
||
├── TestSupport.java # 夹具加载等公共方法
|
||
├── *ScenarioTest.java # 端到端场景（tenant / mq / recording-todo）
|
||
├── analyze/ / config/ / detector/
|
||
├── diff/ / key/ / report/ / schema/ # 与主包对应的单测
|
||
└── ...
|
||
|
||
src/test/resources/fixtures/
|
||
├── lock/ # 分布式锁等非结构写入样例
|
||
├── template/ # 模板写入样例
|
||
├── tenant/ # 包装层 / 字段迁移场景
|
||
├── recording-todo/ # Redis 写入场景
|
||
└── mq/
|
||
├── kafka-patrol/ # Kafka 巡检相关
|
||
├── kafka-record/ # Kafka Record 投递/消费
|
||
├── rocket-im/ # RocketMQ IM 通知
|
||
└── rocket-wallet/ # RocketMQ 钱包扣款
|
||
```
|
||
|
||
夹具多为 `.txt` 形式的 Java 源码片段，由场景测试拼装为新旧版本对比输入。
|
||
|
||
---
|
||
|
||
## 6. 构建与产物
|
||
|
||
| 项 | 说明 |
|
||
|----|------|
|
||
| 构建 | `mvn clean package` |
|
||
| 主类 | `com.codechecker.cache.cli.SerializationSchemaCheckerMain` |
|
||
| 产物 | `target/serialization-schema-checker-1.1.0.jar`（shade 可执行包） |
|
||
| 主要依赖 | JavaParser、SnakeYAML、Jackson、picocli、Lombok（provided）、JUnit 5（test） |
|
||
|
||
---
|
||
|
||
## 7. 文档索引
|
||
|
||
| 文档 | 内容 |
|
||
|------|------|
|
||
| [工程结构.md](./工程结构.md) | 本文：目录与模块职责 |
|
||
| [配置说明.md](./配置说明.md) | 配置项、合并规则、忽略/抑制 |
|
||
| [CI集成说明.md](./CI集成说明.md) | 流水线接入方式 |
|
||
| [v1.0/](./v1.0/) | Redis / MQ 检测实施方案（历史方案） |
|
||
| [V1.1/](./V1.1/) | 非结构写入收敛、新增写入点展示等整改方案 |
|
||
|
||
---
|
||
|
||
## 8. 模块依赖关系（简图）
|
||
|
||
```mermaid
|
||
flowchart TB
|
||
CLI[cli] --> CFG[config]
|
||
CLI --> AN[analyze]
|
||
CLI --> RPT[report]
|
||
CLI --> NT[notify]
|
||
AN --> GIT[git]
|
||
AN --> DET[detector]
|
||
AN --> SCH[schema]
|
||
AN --> DIFF[diff]
|
||
AN --> RPT
|
||
DET --> KEY[key]
|
||
DET --> SCH
|
||
DIFF --> SCH
|
||
RPT --> DIFF
|
||
NT --> RPT
|
||
```
|
||
|
||
上层调用下层；`detector` / `schema` / `diff` 不依赖 `cli` 与 `notify`，便于单测与复用。
|