293 lines
7.2 KiB
Markdown
293 lines
7.2 KiB
Markdown
# 缓存序列化结构检测 — 配置说明
|
||
|
||
> **双层配置**：工具 jar 内置 `default-config.yaml`（默认） + 业务仓库 `.gitea/config/cache-schema-check-config.yaml`（覆盖）
|
||
|
||
---
|
||
|
||
## 1. 配置合并机制
|
||
|
||
```text
|
||
jar 内 default-config.yaml（工具仓维护）
|
||
↓ 深度合并
|
||
业务仓 cache-schema-check-config.yaml（业务仓维护）
|
||
↓
|
||
最终生效配置
|
||
```
|
||
|
||
- 业务配置**仅需写差异项**，不必复制全部默认规则
|
||
- 升级 jar 时，默认忽略规则/检测模式自动跟随工具版本演进
|
||
- 业务仓必须存在 `--config` 指定的配置文件（可为仅含 `mode` 的最小文件）
|
||
|
||
### 1.1 业务仓最小配置示例
|
||
|
||
```yaml
|
||
# jnpf-java-cloud/.gitea/config/cache-schema-check-config.yaml
|
||
mode: notify
|
||
|
||
notify:
|
||
enabled: true
|
||
webhook_env: WECOM_ROBOT_WEBHOOK
|
||
|
||
include_modules:
|
||
- jnpf-tenant
|
||
```
|
||
|
||
### 1.2 工具内置默认配置（jar 内 default-config.yaml）
|
||
|
||
由 `redisCheck` 仓库维护，随 jar 发布，包含：
|
||
|
||
- `detection.patterns`（W01~W03）
|
||
- `ignore.key_patterns`（锁/计数器/token）
|
||
- `detection.min_confidence`、`max_field_depth` 等
|
||
|
||
---
|
||
|
||
## 2. 业务仓完整配置示例
|
||
|
||
```yaml
|
||
# 总开关：false 时不执行检测、不发通知、流水线直接通过
|
||
enabled: true
|
||
|
||
# 运行模式
|
||
# notify - 仅通知，不阻断流水线
|
||
# block - 检测到结构变更即阻断流水线（exit 1）
|
||
mode: notify
|
||
|
||
# 是否扫描测试代码（已确认：不扫描）
|
||
scan_test_sources: false
|
||
|
||
# 源码扫描根目录（仅 main，不含 test）
|
||
source_roots:
|
||
- "src/main/java"
|
||
|
||
# 通知配置
|
||
notify:
|
||
enabled: true
|
||
# 从环境变量读取 Webhook URL
|
||
webhook_env: WECOM_ROBOT_WEBHOOK
|
||
# 无变更时是否也发通知（一般 false）
|
||
notify_on_clean: false
|
||
# 消息标题前缀
|
||
title_prefix: "[缓存结构变更]"
|
||
|
||
# 忽略规则
|
||
ignore:
|
||
# 忽略的 key 模式（glob）
|
||
key_patterns:
|
||
- "*:lock"
|
||
- "*:lock:*"
|
||
- "loginCount:*"
|
||
- "Authorization:*"
|
||
- "Authorization:login:session:*"
|
||
|
||
# 忽略的文件路径模式
|
||
file_patterns:
|
||
- "**/test/**"
|
||
|
||
# 忽略的写入方法（类全名#方法名）
|
||
writer_methods: []
|
||
|
||
# 检测规则
|
||
detection:
|
||
# 启用的写入模式
|
||
patterns:
|
||
- W01 # redisUtil.insert + JSON.toJSONString
|
||
- W02 # redisTemplate.opsForValue().set + JSON.toJSONString
|
||
- W03 # stringRedisTemplate + JsonUtil.getObjectToString
|
||
- 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
|
||
writer_method: "jnpf.util.TenantDbContentCacheHelper#cacheSuccess"
|
||
key_pattern: "tenant:db:content:*"
|
||
value_type: "jnpf.util.TenantDbContentCacheHelper.CacheEnvelope"
|
||
description: "租户库信息缓存"
|
||
|
||
- id: attendance-base-setting
|
||
writer_method: "jnpf.attendance.service.impl.AttendanceBaseSettingServiceImpl#getStringAttendanceBaseSettingMap"
|
||
key_pattern: "fbt:attendance:base_setting:cache:*"
|
||
value_type: "java.util.Map"
|
||
description: "考勤基础设置缓存（Map<String, AttendanceBaseSetting>）"
|
||
|
||
# 抑制规则（已知误报）
|
||
suppressions:
|
||
- id: ignore-export-progress
|
||
key_pattern: "file:download:user:progress:*"
|
||
reason: "导出进度缓存，结构变更不影响业务读取"
|
||
|
||
# 模块过滤（可选，默认扫描全部模块）
|
||
include_modules:
|
||
- jnpf-tenant
|
||
- jnpf-ftb
|
||
- jnpf-file
|
||
- fantaibao-data-analysis
|
||
|
||
# exclude_modules: []
|
||
```
|
||
|
||
---
|
||
|
||
## 3. 配置项说明
|
||
|
||
### 3.1 enabled
|
||
|
||
总开关。默认 `true`。
|
||
|
||
| 值 | 行为 |
|
||
|----|------|
|
||
| `true` | 正常执行检测（再按 `mode` / `notify` 行为） |
|
||
| `false` | 跳过检测与通知，流水线 `exit 0`（与 `notify.enabled` 无关） |
|
||
|
||
临时关闭时可仅改此项，无需删除 workflow。
|
||
|
||
### 3.2 mode
|
||
|
||
| 值 | 行为 |
|
||
|----|------|
|
||
| `notify` | 检测到变更 → 发企微 → `exit 0` |
|
||
| `block` | 检测到任意结构变更 → 发企微 → `exit 1` |
|
||
|
||
建议上线初期仍使用 `mode: notify` 观察误报情况，确认稳定后再切换：
|
||
|
||
```yaml
|
||
mode: block
|
||
```
|
||
|
||
### 3.3 notify
|
||
|
||
| 字段 | 类型 | 默认值 | 说明 |
|
||
|------|------|--------|------|
|
||
| `enabled` | boolean | true | 是否发企微 |
|
||
| `webhook_env` | string | WECOM_ROBOT_WEBHOOK | 环境变量名 |
|
||
| `notify_on_clean` | boolean | false | 无变更时是否通知 |
|
||
| `title_prefix` | string | [缓存结构变更] | 消息标题前缀 |
|
||
|
||
### 3.4 ignore.key_patterns
|
||
|
||
支持 glob：
|
||
|
||
- `*` 匹配单层
|
||
- `**` 匹配多层
|
||
|
||
常见内置忽略（代码层也有硬编码兜底）：
|
||
|
||
- 分布式锁 key
|
||
- 登录计数
|
||
- session/token
|
||
|
||
### 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（已启用） |
|
||
|
||
### 3.6 manual_mappings
|
||
|
||
当自动推断不准确时使用。匹配优先级 **高于** 自动推断。
|
||
|
||
| 字段 | 必填 | 说明 |
|
||
|------|------|------|
|
||
| `id` | 是 | 唯一标识 |
|
||
| `writer_method` | 否 | `类全名#方法名`，精确匹配写入点 |
|
||
| `key_pattern` | 否 | 精确 key 模式 |
|
||
| `value_type` | 否 | 强制指定 value 类型 |
|
||
| `description` | 否 | 备注 |
|
||
|
||
### 3.7 suppressions
|
||
|
||
用于屏蔽已知可接受的变更：
|
||
|
||
```yaml
|
||
suppressions:
|
||
- id: my-suppression
|
||
writer_method: "com.example.FooService#cacheBar"
|
||
change_types:
|
||
- FIELD_ADDED
|
||
reason: "新增字段向后兼容"
|
||
```
|
||
|
||
---
|
||
|
||
## 4. 环境变量
|
||
|
||
| 变量 | 必填 | 说明 |
|
||
|------|------|------|
|
||
| `WECOM_ROBOT_WEBHOOK` | notify.enabled=true 时必填 | 企微机器人 Webhook 完整 URL |
|
||
|
||
在 Gitea 仓库 Settings → Secrets 中配置。
|
||
|
||
---
|
||
|
||
## 5. 企微消息格式示例
|
||
|
||
```markdown
|
||
## [缓存结构变更] jnpf-java-cloud
|
||
|
||
> 分支: feature/tenant-cache
|
||
> 提交: a1b2c3d → e4f5g6h
|
||
> 提交人: zhangsan
|
||
> 时间: 2026-07-13 14:00:00
|
||
> 模式: notify
|
||
|
||
### P0 - 顶层结构包装变更
|
||
- **Key**: `tenant:db:content:*`
|
||
- **位置**: `TenantDbContentCacheHelper#cacheSuccess:92`
|
||
- **变更**:
|
||
- `dbName` → `vo.dbName`（字段路径迁移）
|
||
- `linkList` → `vo.linkList`（字段路径迁移）
|
||
- 新增顶层字段 `expiresAtMs`
|
||
- **影响**: 旧缓存反序列化可能失败，需评估缓存刷新策略
|
||
```
|
||
|
||
---
|
||
|
||
## 6. 推荐上线配置
|
||
|
||
### 6.1 观察期（第 1 周，已确认策略）
|
||
|
||
业务仓默认配置：
|
||
|
||
```yaml
|
||
mode: notify
|
||
|
||
notify:
|
||
enabled: true
|
||
webhook_env: WECOM_ROBOT_WEBHOOK
|
||
|
||
include_modules:
|
||
- jnpf-tenant
|
||
```
|
||
|
||
观察满 1 周、确认误报可接受后，手动切换：
|
||
|
||
```yaml
|
||
mode: block
|
||
include_modules: [] # 扩至全仓
|
||
```
|
||
|
||
### 6.2 全量启用（观察期结束后）
|
||
|
||
```yaml
|
||
mode: block
|
||
include_modules: [] # 空表示全部模块
|
||
detection:
|
||
patterns: [W01, W02, W03, W04, W05]
|
||
```
|