68 lines
4.7 KiB
Markdown
68 lines
4.7 KiB
Markdown
# 自定义规则审查联动 — 验证结果报告（覆盖全演示）
|
||
|
||
## 验证信息
|
||
|
||
| 项 | 值 |
|
||
|---|---|
|
||
| 验证日期 | 2026-09-07 |
|
||
| 验证功能 | 自定义规则审查联动——团队编码风格规则在真实代码审查中的覆盖度（对应导入验证清单 C3 检查点） |
|
||
| 规则文件 | `data/custom-rule-demo/team-style-rules.yaml`（5 条团队私有约定，经 UI 导入） |
|
||
| 测试代码 | `data/custom-rule-demo/TeamStyleService.java` |
|
||
| 规则设计原则 | 全部为静态分析四件套与通用 AI 深度审查均查不到的团队私有约定 |
|
||
|
||
## 团队风格规则设计
|
||
|
||
| # | 规则 id | severity | 约定内容 | 静态分析为何查不到 |
|
||
|---|---|---|---|---|
|
||
| R1 | require-query-method-prefix | warning | Service 层查询方法必须以 query/find/get 开头 | PMD 只查通用命名规范，不限定业务动词前缀 |
|
||
| R2 | require-dto-suffix | warning | 跨服务传输对象类名必须以 DTO 结尾 | PMD Bean 命名规则只管 EJB 后缀 |
|
||
| R3 | require-result-wrapper | warning | Controller 返回值必须用 Result 包装 | 团队架构约定 |
|
||
| R4 | require-author-tag | info | 类 Javadoc 必须含 @author | PMD CommentRequired 不在规则集内，通用 AI 不主动挑 |
|
||
| R5 | require-chinese-log-message | info | Service 层日志消息必须使用中文 | 英文日志是通用惯例，通用工具均不报 |
|
||
|
||
（R4 原设计为「金额必须 BigDecimal」，基线验证中被通用 AI 原生命中——真实最佳实践不配当团队私有约定演示规则，遂替换。）
|
||
|
||
## 测试代码构造
|
||
|
||
`TeamStyleService.java` 要求**双重干净**：静态分析零告警（PMD 零报告达成）+ 通用 AI 深度审查仅剩开放性设计建议（经 3 轮迭代：11 → 4 → 6 条，均为设计级 nitpick，无 error 级）。代码内含 5 处无痕埋点（不加任何提示注释，防止 AI 照抄注释而非按规则判定）。
|
||
|
||
## 验证过程
|
||
|
||
1. **基线审查**（无自定义规则）：PMD 0 告警；通用 AI 建议 4-6 条逐轮波动（11 → 4 → 6，均为 equals/hashCode、Optional 语义、Map 优化等开放性设计建议）
|
||
2. **导入规则**：UI 导入 team-style-rules.yaml，5 条全部保留、零去重标注（纯约定对内置静态规则零重复）
|
||
3. **复审**：自定义规则 6 条命中 + 通用 AI 建议 4 条并存，互不干扰
|
||
|
||
## 命中核对
|
||
|
||
| 规则 | 命中位置 | 判定 |
|
||
|---|---|---|
|
||
| require-query-method-prefix | L33 handleOrderQuery | ✅ 精准 |
|
||
| require-result-wrapper | L61 listOrders 裸返回 | ✅ 精准 |
|
||
| require-dto-suffix | L71 OrderInfo | ✅ 精准 |
|
||
| require-author-tag | L14 TeamStyleService 类注释 | ✅ 精准 |
|
||
| require-chinese-log-message | L45 英文日志 | ✅ 精准 |
|
||
| require-author-tag（第二次） | L53 OrderController 内部类 | ✅ 合理命中（埋点遗漏被规则抓出） |
|
||
|
||
**5/5 规则全部触发，行号全部准确，message 逐字来自规则文件，零误报**——覆盖全达成。
|
||
|
||
## 关键发现
|
||
|
||
1. **确定性与开放性对比（演示核心叙事）**：通用 AI 建议逐轮波动（11→4→6→4），团队规则命中稳定精准——通用 AI 提供开放性建议，自定义规则提供确定性的团队约定检查
|
||
2. **两类发现在报告中独立分区**：「自定义规则 · N 个问题」（ruleId 带 `custom:` 前缀）与「AI 审查 · N 条建议」互不混淆
|
||
3. **通用 AI 与团队规则的边界被实测划清**：「金额必须 BigDecimal」被通用 AI 原生捕获（真实最佳实践），「@author 标注」「中文日志」通用 AI 零感知（纯团队约定）——自定义规则的价值空间 = 通用最佳实践之外的团队私有约定
|
||
4. **埋点遗漏反向验证**：OrderController 漏加 @author 被规则抓出，规则执行力强于设计者记忆
|
||
|
||
## 已知观察
|
||
|
||
- 通用 AI 建议与自定义规则命中会在同一报告中并存（如 return-list-for-single-entity 与 R1 同指 handleOrderQuery，一个挑返回语义一个挑命名前缀），讲解时需说明维度不同
|
||
- 基线要求「AI 零建议」对非平凡代码不可达（AI 对任何代码都能提出设计级建议），本验证以「无 error 级发现 + 建议均为开放性设计 nitpick」为基线通过标准
|
||
|
||
## 结论
|
||
|
||
**通过**。团队风格规则在真实代码审查中全覆盖命中（5/5），命中行号与 message 精准，与静态分析、通用 AI 审查通道清晰分离。自定义规则「补齐团队私有约定盲区」的价值定位得到端到端实证。
|
||
|
||
## 关联
|
||
|
||
- 规则导入验证：`data/import-verification/`（三场景 23 轮，本报告的 C3 检查点由此补齐）
|
||
- 自动化测试：`tests/excel-converter.test.ts`、`tests/method-extractor.test.ts`（CodeLens 依赖的方法提取）
|