schemaCheck/docs/工程结构.md

序列化结构检测器 — 工程结构说明

工程：serialization-schema-checker（com.codechecker:serialization-schema-checker）
定位：基于 JavaParser 的 Redis 缓存 / MQ（RocketMQ、Kafka）value 序列化结构变更 静态检测工具
当前版本：1.1.0 · Java 11 · 可执行 Fat Jar（maven-shade）

---

1. 仓库顶层结构

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

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. 运行时数据流

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

---

5. 测试结构

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	配置项、合并规则、忽略/抑制
CI集成说明.md	流水线接入方式
v1.0/	Redis / MQ 检测实施方案（历史方案）
V1.1/	非结构写入收敛、新增写入点展示等整改方案

---

8. 模块依赖关系（简图）

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，便于单测与复用。