Cassandra 代码评审指南API 完整性与契约专项检查22 个高信号问题清单【免费下载链接】cassandraOpen source transactional distributed database. Linear scalability and proven fault-tolerance on commodity hardware or cloud infrastructure without compromising performance.项目地址: https://gitcode.com/GitHub_Trending/cassa/cassandra导读在 Cassandra 这样一个拥有数千个类、遍布 src/java/org/apache/cassandra 的分布式数据库代码库中新增类、字段或枚举常量时最容易引入的缺陷并非写错了逻辑而是漏了某个本该成对出现的行为实现了接口却没覆写默认值为 false 的谓词方法、给类加了字段却忘记同步到 equals/hashCode/序列化、注册了监听器却没有对应的注销路径。本指南以仓库.claude/skills/shallow-review/references/general/specialists/completeness.md中收录的 22 个最高信号审查问题为核心骨架逐条结合 Cassandra 源码中的真实实现如 LivenessInfo、RowCacheKey、AuthCacheService 等展开讲解帮助你建立一套可复制、可执行的完整性审查清单在合并请求PR评审阶段系统性地拦截完整性缺陷。一、接口与覆写完整性默认实现往往是错误的答案当一个新类实现接口或继承抽象类时接口/父类中提供的default方法或空实现方法通常是为多数情况准备的占位答案对新实现而言很可能是错误的。审查时要逐一列出所有 abstract/default 方法逐条判断默认行为是否适用于新实现。1. 行为谓词方法isX / hasX / canX是否全部覆写审查点新类实现接口或继承抽象类时是否覆写了每一个行为谓词方法isX()、hasX()、canX()尤其是那些默认返回false或空操作的实现例如一个带 TTL 的类必须覆写isExpired()。Cassandra 中的典型例证是 LivenessInfo它定义了isExpiring()、isExpired()、isLive(long nowInSec)等谓词。接口内部维护了三种实现——ImmutableLivenessInfo无 TTL、ExpiringLivenessInfo带 TTL、ExpiredLivenessInfo已过期作为主键墓碑使用。其中 ExpiredLivenessInfo 覆写了 isExpired() 返回 true并覆写 isLive() 恒返回 false从而实现对整个主键的影子删除。如果新增一个实现类却漏掉isExpired()默认实现会把它当成永不过期的数据参与合并直接导致 TTL 语义失效。2. 生命周期方法close / release / abort是否覆写审查点当新类持有父类不知道的资源时是否覆写了所有生命周期方法close()、release()、abort()父类默认的close()往往只释放自己已知的资源子类新增的缓冲区、文件句柄或线程池若不在覆写中释放就会造成资源泄漏。3. 类型族新增子类型时是否覆盖所有分发点审查点当类型族type family中新增子类型/变体时它是否被每一个类型分发点处理——不仅仅是 enum switch还包括instanceof链、visitor 的visitXxx方法、类型转换器映射表type-converter map以及模式匹配分支静默 fallthrough 到默认分支通常会返回null或错误的值。在 Cassandra 中例如 DeletionInfo 接口族包含MutableDeletionInfo、ImmutableDeletionInfo等实现MutableDeletionInfo.add(DeletionInfo) 中就有assert newInfo instanceof MutableDeletionInfo这样的类型判断——一旦新增第三种实现而忘记在此处处理就可能触发断言失败或行为不一致。4. 子类新增实例字段时是否覆写内存测量方法审查点子类新增了实例字段是否覆写了内存测量方法unsharedHeapSize、estimateSize等装饰器/包装类是否覆写了每个默认抛UnsupportedOperationException的接口方法Cassandra 通过 IMeasurableMemory 接口要求所有可测量的对象实现unsharedHeapSize()用于行缓存/键缓存的容量核算。RowCacheKey 覆写该方法时用EMPTY_SIZE ObjectSizes.sizeOfArray(key)精确计算堆外数组开销LivenessInfo 的 default 实现则区分EMPTY返回 0与其他实例返回预测量常量。如果子类新增字段却不更新测量方法缓存容量会被低估最终导致内存超限。二、字段完整性新增字段必须全家桶同步5. 新字段是否出现在所有镜像方法中审查点类中新增字段后它是否出现在序列化/反序列化/serializedSize、equals/hashCode、toString、拷贝构造函数、builder 的build()、describe/toMap漏掉任意一处都会造成看似相同实则不同的隐蔽 bug。6. 描述符/序列化器方法是否包含兄弟方法拥有的全部字段审查点描述符/序列化器方法是否包含其兄弟方法如equals、hashCode、toString、serialize所包含的全部字段应逐字段比对而不是凭记忆。7. equals/hashCode 是否覆盖全部身份字段且能防御类型不匹配审查点equals/hashCode是否包含每一个决定身份的字段不仅是显示名或主键equals是否防御操作数类型不匹配getClass() ! o.getClass()或委托给带类型守卫的比较器Serializable类的声明字段类型本身是否可序列化transient字段在缺少自定义readObject时能否被正确重建RowCacheKey 给出了教科书式实现equals先做getClass() ! o.getClass()守卫再逐字段比较tableId、indexName、keyhashCode同步覆盖同一组字段toString也输出全部字段。三者字段集合完全一致这正是清单第 5、6、7 条要求的落点。三、注册对称性每一个 register 都必须有匹配的 remove8. 每次注册是否有对应的注销路径成功与失败路径都要覆盖审查点对每一次注册addListener、register、subscribe、put进 registry、addMetric是否存在匹配的移除动作并且同时覆盖 shutdown/close/destroy 路径上的成功与失败分支如果多次注册按顺序发生其中一次抛异常时清理逻辑是否仍能移除全部注册Cassandra 的 AuthCacheService 是注册/注销成对设计的实例register(AuthCache?,?)与unregister(AuthCache?,?)一一对应并用HashSet保证去重。审查新增缓存时就要确认其销毁路径是否调用了unregister否则热更新后旧缓存会残留在集合中。9. 自注册类是否真的会被加载审查点自注册类如static final INSTANCE new Foo()在构造函数中把自己注册进全局 registry是否真的从启动路径被加载如果没有任何代码引用该类静态初始化永远不会执行注册会静默缺失。AuthCacheService.instance 正是这种单例自注册模式的实例——审查时必须回溯调用链确认initializeAndRegisterCaches()确实在 CassandraDaemon 的启动流程中被调用否则认证缓存永远不会被预热。四、可见性private 不等于没人需要10. private / 包私有成员是否真的没有外部访问需求审查点字段/方法声明为private或包私有后包外类或子类是否仍然需要访问它VisibleForTesting注解只把可见性放宽到包私有不会更宽。同时要检查该成员此前是否为protected而被本次改动收窄收窄后要复查所有子类。RowCacheKey 中有一个VisibleForTesting的构造器包私有专门给测试使用——这正是为了测试而放宽可见性的标准做法而生产代码仍保持不可见。五、累积Accumulation与只差一个字符11. 循环累加是否误用了赋值代替累加审查点对于field expression形式的代码如果field在迭代中追踪运行总数是否应该写成field expression重点检查循环中的指标累加器metric accumulators、计数器counters和聚合统计aggregated stats。这类 bug 的典型症状是统计值总是等于最后一次迭代的值。六、事件与分发完整性新增事件类型必须全链路处理12. 新增 enum 常量/事件类型是否处理了所有 switch 与分发表审查点新增 enum 常量或事件类型时是否在所有switch 语句、分发 map 和处理器注册处被处理尤其警惕静默的default: break——它可能把本应报错的事件悄悄吞掉。13. 状态机处理器是否排入后续动作而不是只打日志返回审查点状态机处理器onTimeout、onError、onRetry是否排入了合适的后续动作还是仅 log 后返回、让状态机卡死Cassandra 的网络消息处理器如 InboundMessageHandler对超时/错误的处理必须显式推进状态否则连接会永久悬挂。14. 新增错误码/异常类/响应状态是否加入了错误映射表审查点引入新的错误码/异常类/响应状态时是否加入了错误映射表区别于分发 switch未映射的错误码通常会把可重试错误变成致命错误或把致命错误变成被静默吞掉的假成功。七、方法绑定与重构过载、提取与包装的隐形陷阱15. 新增带默认值的重载后所有需要新行为的调用方是否改用了新签名审查点方法新增参数并提供带默认值的重载后所有需要新行为的调用方是否都调用了新签名旧调用方会静默绑定到旧重载行为保持不变但意图已过时。16. 提取方法后调用点是否保留了重复操作审查点把代码提取为 helper 之后调用点是否仍执行了 helper 也执行的操作提取方法重构导致的重复写、重复关double-write、double-close。17. 包装器/委托转发调用时是否透传了全部参数审查点包装器/委托把调用转发给内部实现时是否透传了全部参数——包括辅助性参数如追踪上下文tracing context、一致性级别consistency level、认证凭据auth credentials、客户端选项——而不仅仅是主值只要有一层 fallthrough 到无参重载调用方意图就被静默丢弃。这在高一致性的分布式系统中尤为致命一致性级别丢失意味着写操作可能在不满足仲裁条件时就被确认。18. 跨版本子目录复制的代码bug 修复是否传播到了所有副本审查点当代码块在版本化子目录间重复格式变体、协议版本门控副本、legacy 与当前实现并存时对其中一份副本的 bug 修复是否已传播到所有兄弟副本应跨同级目录 grep 被修复的符号找出过期副本。Cassandra 中 SStable 格式演进如 test/data/legacy-sstables 下的 da/ma/mb/mc/md/me/na/nb/oa 各版本目录就是此类重复的典型场景序列化修复必须逐版本验证。八、工厂路由每个鉴别值都必须产出正确的类型19. 工厂按类型参数分发时每个鉴别值的返回类型是否正确审查点工厂按类型参数分发创建具体对象时对每个鉴别值discriminator value返回的类是否正确合并多个工厂后要逐一验证每个值产出的类型与合并前一致。20. 多条构造/工厂路径是否都执行了必需的注册/校验/后置构造步骤审查点类存在多个构造器或工厂路径主路径 vs 次路径、from-bytes vs from-memory、copy-of vs fresh时每条路径是否都执行了必需的注册/校验/后置构造步骤次路径是否跳过了某一步LivenessInfo 提供了多工厂路径的对照create(long)、create(long, int, long)、withExpirationTime(...)、以及仅供 scrub 场景绕过溢出策略的私有expiring(...)变体——每条路径都要保证ExpiringLivenessInfo的ttl ! EXPIRED_LIVENESS_TTL断言成立任何一条新路径忘记该前置条件都会产生非法状态。九、常量与构造器无声丢弃的参数21. 常量与方法调用是否用混审查点代码调用Foo.bar()时是否本应使用常量Foo.BAR或反之当更具体的重载能强制校验必需值时是否错误地调用了宽泛的重载22. 构造器参数是否被静默丢弃内联初始化是否覆盖了构造器赋值审查点构造器接受的参数是否从未赋给字段被静默丢弃字段的内联初始化器是否赋了一个常量而构造器从未覆盖它导致调用方传入的值凭空消失这两个问题在 Cassandra 的不可变值类如各类 Key、LivenessInfo 实现中尤其常见——新增构造参数却忘记赋值equals/toString/序列化全部随之失真且编译器不会给出任何警告。十、把清单落进日常评审一个可复用的检查顺序上面 22 个问题可以在一次评审中按信息流动的顺序执行避免遗漏接口层问题 1–4新类实现了哪些接口/父类逐一列出 abstract/default 方法逐个判断默认行为是否适用于新实现字段层问题 5–7列出类中全部字段与equals/hashCode/toString/serialize/serializedSize/builder 逐字段比对生命周期层问题 8–9、2register 与 unregister 成对出现close/release 是否释放了父类不知道的资源自注册单例是否真的被加载分发层问题 12–14、3新枚举常量/事件类型/错误码是否在全部 switch、分发 map、错误映射表中被处理路由层问题 19–20、15、17工厂每个鉴别值产出类型正确吗每条构造路径都完成全部后置步骤吗重载/包装转发是否丢失参数或意图细节层问题 10、11、16、18、21、22可见性、累加、提取重构残留、跨版本副本传播、常量误用、参数丢弃。这套顺序正好与.claude/skills/shallow-review/references/general/specialists/completeness.md清单的分组结构接口与覆写 → 字段 → 注册对称性 → 可见性 → 累积 → 事件与分发 → 方法绑定与重构 → 工厂路由 → 常量对应评审者可以按序打勾把完整性审查从凭经验变成可执行的流程。同时仓库中.claude/skills/shallow-review目录下的其他专项清单如并发、性能等方向可以与本文互补构成一套覆盖不同维度的评审工具箱。【免费下载链接】cassandraOpen source transactional distributed database. Linear scalability and proven fault-tolerance on commodity hardware or cloud infrastructure without compromising performance.项目地址: https://gitcode.com/GitHub_Trending/cassa/cassandra创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考