0
代码
代码
Issues
Pull Requests
讨论
Wiki
分析
0
canonical-entropycanonical-entropydocs: Plan 73 P3审计修复完成，更新计划和日志
d26678a6创建于 1 天前历史提交

73 nop-stream P3 审计修复

Plan Status: completed Last Reviewed: 2026-05-29 Source: ai-dev/audits/2026-05-28-deep-audit-nop-stream-full/summary.md Related: 67-nop-stream-critical-correctness-fixes (P0/P1, completed), 68-nop-stream-p2-audit-remediation (P2, completed)

Purpose

将 2026-05-28 21 维度系统审计中保留的全部 21 个 P3 发现修复到可验证状态。P0/P1 已在 Plan 67 修复完毕，P2 已在 Plan 68 修复完毕，本计划处理剩余的 P3 问题。

Current Baseline

  • nop-stream 含 9 个子模块，测试全量通过（行数在 Plan 67/68 修复后可能有少量变化）
  • Plan 67 已修复全部 P0/P1（N106-N120 + 13-01 路径遍历 + 14-01~04 竞态 + 16-01 + 20-01）
  • Plan 68 已修复全部 P2（02-01 序列化去重、03-01 interface→abstract class、04-01 唯一约束、04-03 TOCTOU、09-02 ErrorCode 迁移、13-01 类名白名单、14-01 计数器泄漏、16-03/04/05 测试、19-01 拼写、20-01 SPI、21-01 SharedBuffer 测试）
  • 现存未修复的 P3 发现清单（21 个）：
编号 维度 文件 摘要
01-01 依赖图 nop-stream-cep/pom.xml nop-xlang 声明为 compile 依赖但零编译时使用
01-02 依赖图 FraudDetectionDemo.java:29 fraud-example 访问 core 内部实现类 SimpleKeyedStateStore
02-02 模块职责 MemoryKeyedStateBackend.java ~1398行，含 9 个内部类（7 个状态类 + 2 个辅助类）
03-02 API 表面积 20+ files 37 处过时 org.apache.flink.* Javadoc 引用
03-03 API 表面积 connector 包 5 个未使用连接器接口（死代码/API 预留）
03-04 API 表面积 StreamOperator.java:127-146 中英文 Javadoc 混合
04-02 ORM/数据 JdbcCheckpointStorage.java exists() 默认实现全量反序列化，未重写
04-04 ORM/数据 JdbcCheckpointStorage.java:37 sidSequence 基于 System.currentTimeMillis()，多 JVM 冲突
09-03 错误处理 ICepPatternGroupModel.java, CepPatternBuilder.java 3 处直接 NopException 绕过模块异常层次
09-04 错误处理 CheckpointType.java:98 IllegalArgumentException 绕过 StreamException 约定
10-02 XDSL resource-spec.xdef:2 cpuCors 拼写错误（应为 cpuCores）
10-03 XDSL resource-spec.xdef 缺失 xmlns:xdef 命名空间声明
14-02 异步/事务 Lockable.java:38-55 refCounter 非 AtomicInteger，无线程安全保护
15-01 类型安全 CepOperator.java:206, SharedBuffer.java:95,102 原始类型转换缺少 @SuppressWarnings("rawtypes")
15-02 类型安全 PaneState.java:20,22 window/state 字段使用 Object 而非泛型
15-03 类型安全 LastValue.java:23 raw cast 缺少 @SuppressWarnings("unchecked")
15-04 类型安全 MessageSourceFunction.java:98 无类型消息直接强转泛型 T
18-01 文档一致 README.md:5 引用不存在的 RuntimeTopology
19-02 命名一致 FollowKind.java:24-48 camelCase 枚举值缺文档说明设计意图
21-02 测试有效性 TestDeweyNumber 等 ~35-40 个低价值 getter/常量测试

Goals

  • 修复全部 21 个 P3 发现中的可执行项
  • 每个修复完成后 ./mvnw test -pl nop-stream -am 全部通过
  • 清理 Javadoc 遗留、文档-代码不一致、命名拼写、异常层次一致性

Non-Goals

  • 架构级模块拆分（02-02 MemoryKeyedStateBackend 瘦身涉及大规模重构，单独评估）
  • 03-03 死代码删除需确认产品意图（可能是有意保留的 API 预留），改为添加文档标注
  • 性能优化专项（04-04 sidSequence 碰撞、04-02 exists() 性能需评估影响面）

Scope

In Scope

全部 21 个 P3 发现（见 Current Baseline 表格）

Out Of Scope

  • 架构级模块拆分（将 nop-stream-api 从 core 抽取）
  • 新功能开发
  • Flink 兼容性评估

Execution Plan

Phase 1 - 快速修复：Javadoc 清理 + 拼写 + 命名空间 + 注解

Status: completed Targets: nop-stream-core/src/main/java/, nop-stream-cep/, nop-kernel/nop-xdefs/, nop-stream-core/.../accumulators/LastValue.java

  • Item Types: Fix

  • 03-02: 将 nop-stream-core 和 nop-stream-cep 中约 37 处 org.apache.flink.* Javadoc @link / @see 引用替换为对应的 io.nop.stream.core.* 路径

  • 03-04: 将 StreamOperator.java:127-146 的中文 Javadoc 翻译为英文

  • 10-02: 将 resource-spec.xdef 第 2 行的 cpuCors 修正为 cpuCores

  • 10-03: 验证 resource-spec.xdef 的命名空间声明——已确认 x:schema="/nop/schema/xdef.xdef" + xmlns:x="/nop/schema/xdsl.xdef" 满足需求（误报）

  • 15-01: CepOperator.java + SharedBuffer.java 添加 @SuppressWarnings({"unchecked", "rawtypes"})

  • 15-03: LastValue.java 添加 @SuppressWarnings("unchecked")

  • 19-02: FollowKind.java 添加 camelCase 设计意图说明

Exit Criteria:

  • grep -rn "org.apache.flink" nop-stream/ --include="*.java" 返回 0 结果
  • StreamOperator.java:127-146 为纯英文 Javadoc
  • resource-spec.xdef 包含 cpuCores；命名空间已满足
  • CepOperator.java 的 open() 方法 @SuppressWarnings 包含 "rawtypes"
  • SharedBuffer.java @SuppressWarnings 注解包含 "rawtypes"
  • LastValue.java 的 type() 方法有 @SuppressWarnings("unchecked")
  • FollowKind.java Javadoc 包含 camelCase 设计意图说明
  • ./mvnw compile -pl nop-stream -am 通过
  • No owner-doc update required
  • ai-dev/logs/ 对应日期条目已更新

Phase 2 - 异常层次对齐 + 错误码一致性

Status: completed Targets: nop-stream-cep/.../ICepPatternGroupModel.java, nop-stream-cep/.../CepPatternBuilder.java, nop-stream-core/.../checkpoint/CheckpointType.java

  • Item Types: Fix

  • 09-03: 3 处 throw new NopException(ERR_CEP_XXX) 改为 throw new StreamRuntimeException(ERR_CEP_XXX).param(...)

  • 09-04: CheckpointType.java:98 的 throw new IllegalArgumentException(...) 改为 throw new StreamException(ERR_STREAM_INVALID_ARG).param(...)

Exit Criteria:

  • grep -rn "new NopException" nop-stream/ --include="*.java" 返回 0 结果（NopException 不被直接使用）
  • CheckpointType.java 中无 new IllegalArgumentException
  • 修改后的异常类型正确（CEP 用 StreamRuntimeException，core 用 StreamException）
  • ./mvnw test -pl nop-stream -am 全部通过
  • No owner-doc update required
  • ai-dev/logs/ 对应日期条目已更新

Phase 3 - 依赖优化 + 文档对齐

Status: completed Targets: nop-stream-cep/pom.xml, nop-stream-fraud-example/, nop-stream-cep/, nop-stream/README.md

  • Item Types: Fix, Decision

  • 01-01: nop-stream-cep/pom.xml 中的 nop-xlang 依赖改为 <optional>true</optional>

  • 01-02: fraud-example 移除 SimpleKeyedStateStore 直接引用，内联 DemoKeyedStateStore

  • 18-01: README.md 将 RuntimeTopology 标注为"规划中"

  • 03-03: 5 个未使用连接器接口添加 @apiNote 标注为 API 预留

Exit Criteria:

  • nop-stream-cep/pom.xml 中 nop-xlang 有 <optional>true</optional>
  • grep -rn "SimpleKeyedStateStore" nop-stream/nop-stream-fraud-example/ 返回 0 结果
  • README.md RuntimeTopology 已标注为规划中
  • 5 个未使用连接器接口有 @apiNote 注解
  • ./mvnw compile -pl nop-stream -am 通过
  • No owner-doc update required
  • ai-dev/logs/ 对应日期条目已更新

Phase 4 - 数据访问改进 + 线程安全注解

Status: completed Targets: nop-stream-runtime/.../checkpoint/storage/JdbcCheckpointStorage.java, nop-stream-cep/.../sharedbuffer/Lockable.java, nop-stream-core/.../windowing/PaneState.java, nop-stream-connector/.../MessageSourceFunction.java

  • Item Types: Fix

  • 04-02: JdbcCheckpointStorage 重写 exists() 使用 SQL COUNT 查询

  • 04-04: sidSequence 改用 UUID.randomUUID() 避免多 JVM 冲突

  • 14-02: Lockable.refCounter 改为 AtomicInteger + 线程安全 Javadoc

  • 15-02: PaneState @DataBean 与泛型冲突，采用备选方案：添加 Object 类型设计决策文档

Exit Criteria:

  • JdbcCheckpointStorage.exists() 使用 SQL COUNT 查询而非全量反序列化
  • sidSequence 不使用 System.currentTimeMillis()
  • Lockable.refCounter 类型为 AtomicInteger
  • Lockable 类有线程安全契约 Javadoc
  • PaneState 有泛型参数或明确的 Object 类型设计决策文档
  • ./mvnw test -pl nop-stream -am 全部通过
  • No owner-doc update required
  • ai-dev/logs/ 对应日期条目已更新

Phase 5 - 大文件瘦身：MemoryKeyedStateBackend 内部类提取

Status: completed Targets: nop-stream-core/.../state/backend/memory/MemoryKeyedStateBackend.java

  • Item Types: Fix

  • 02-02: MemoryKeyedStateBackend 9 个内部类提取为独立文件

  • snapshot/restore 序列化逻辑提取为 MemoryStateSerDe 辅助类

Exit Criteria:

  • MemoryKeyedStateBackend.java 行数 < 600 行（实际 243 行）
  • 9 个内部类均为独立文件
  • ./mvnw test -pl nop-stream -am 全部通过
  • No owner-doc update required
  • ai-dev/logs/ 对应日期条目已更新

Phase 6 - 测试有效性清理

Status: completed Targets: nop-stream-cep/src/test/, nop-stream-fraud-example/src/test/

  • Item Types: Follow-up

  • 21-02: 27 个低价值测试方法标注 @Tag("low-value")

Exit Criteria:

  • 低价值测试方法有 @Tag("low-value") 标注
  • 已标注的测试方法属于 getter/常量往返测试，不误标有效行为测试
  • grep -rn "@Tag.*low-value" nop-stream/ --include="*.java" 命中数 27 ≥ 20
  • ./mvnw test -pl nop-stream -am 全部通过
  • No owner-doc update required
  • ai-dev/logs/ 对应日期条目已更新

Closure Gates

  • 全部 21 个 P3 发现已修复或已显式移入 Deferred But Adjudicated
  • ./mvnw test -pl nop-stream -am 全量通过
  • 不存在被静默降级到 deferred / follow-up 的 in-scope P3 缺陷
  • No owner-doc update required（全部 P3 为代码/测试/文档清理，不涉及平台约定变更）
  • 独立子 agent closure-audit 已完成并记录证据
  • Anti-Hollow Check: 修复未引入空壳或静默跳过
  • ./mvnw compile -pl nop-stream -am 通过
  • checkstyle / 代码规范检查通过
  • ai-dev/logs/ 收口记录已写入

Deferred But Adjudicated

（无——全部 21 个 P3 均在 scope 内）

Non-Blocking Follow-ups

  • 架构级 API 抽取（nop-stream-api 从 core 独立）— 需要独立的架构决策
  • ICheckpointStorage 接口 throws Exception → throws CheckpointStorageException 细化 — 需评估接口变更影响面
  • Flink 兼容性策略评估 — 非代码质量问题

Closure

Status Note: 全部 21 个 P3 发现已修复完毕。6 个 Phase 均已完成，./mvnw test -pl nop-stream -am 全量通过。

Closure Audit Evidence:

  • Reviewer / Agent: opencode (independent closure audit)
  • Evidence:
    • Phase 1: 37 处 org.apache.flink Javadoc 已替换，cpuCors→cpuCores 已修复，@SuppressWarnings 已添加
    • Phase 2: 3 处 NopException→StreamRuntimeException，1 处 IllegalArgumentException→StreamException
    • Phase 3: nop-xlang optional，DemoKeyedStateStore 内联，README RuntimeTopology 标注，5 个 @apiNote
    • Phase 4: JdbcCheckpointStorage.exists() SQL COUNT，sidSequence UUID，Lockable AtomicInteger，PaneState 设计文档
    • Phase 5: MemoryKeyedStateBackend 1398→243 行，9+1 个独立文件
    • Phase 6: 27 个低价值测试方法 @Tag("low-value") 标注
    • ./mvnw test -pl nop-stream -am BUILD SUCCESS

Follow-up:

  • 架构级 API 抽取（nop-stream-api 从 core 独立）
  • ICheckpointStorage 接口 throws Exception → throws CheckpointStorageException 细化
  • Flink 兼容性策略评估