Cassandra 代码审查实战：Deep Boundary I/O 边界条件与输入输出检查清单-迪斯科星球

Cassandra 代码审查实战：Deep Boundary & I/O 边界条件与输入输出检查清单

【免费下载链接】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

本文以 Apache Cassandra 仓库内.claude/skills/deep-review/references/deep/deep-boundary.md中的「Deep Boundary & I/O」扩展检查清单为骨架，逐条展开讲解其背后的工程原理，并逐一对照 Cassandra 真实源码（压缩 I/O 路径、磁盘边界定位、二分搜索、NIO 读写等）给出可验证的实例。读完本文，你将掌握一套可复用的边界缺陷审查方法论：从 off-by-one、整数溢出、空值与越界、ByteBuffer 生命周期，到区间端点与算术陷阱，并能在 Cassandra 这类大型 Java 代码库中精准定位同类问题。

一、检查清单概览：为什么要做"边界深度"审查

代码审查中最隐蔽、后果最严重的缺陷，往往不是逻辑缺失，而是发生在**边界条件（boundary）与输入输出（I/O）**交汇处：多读一个 chunk、少算一个字节、提前一格截断、晚一秒超时。.claude/skills/deep-review/references/deep/deep-boundary.md这份清单把这类问题归纳为四大类，并为每类标注了权重（high / medium / low）与具体检查模式：

Off-by-One & Range Depth（越界一格的深层检查）
Null & Bounds Check Depth（空值与边界检查深度）
ByteBuffer & I/O Depth（缓冲区与输入输出深度）
Interval & Range Depth（区间与范围深度）

此外还有一组独立的Arithmetic Pitfalls（算术陷阱），并明确规定：应用清单前必须先做 Context Gathering（上下文收集）。审查不是对着 diff 看，而是先读目标文件全文，搞清楚数据范围、哨兵值、缓冲区生命周期、I/O 契约与算术单位这五件事。

下文将按清单原顺序展开，每一类都先给出检查要点，再结合 Cassandra 仓库中的真实代码给出对照实例与文件路径。

二、Context Gathering：动手前必须收集的五类上下文

清单把「读目标文件（而非仅读 diff）」列为REQUIRED前置步骤，具体要弄清五件事：

上下文项	要回答的问题	Cassandra 中的典型对象
Data ranges	索引、尺寸、位置在此代码中的合法取值范围是什么？	chunk 索引、SSTable 文件偏移、磁盘序号
Sentinel values	此上下文里`-1`、`0`、`null`、`MAX_VALUE`分别代表什么？	`binarySearch`的`-pos-1`插入点、`EOF = -1`、`retention = -1`表示无限
Buffer lifecycle	谁负责分配、定位、切片、释放缓冲区？	`CompressedSequentialWriter`的复用 buffer、`CompressionMetadata`的`Memory chunkOffsets`
I/O contracts	底层读写 API 保证了什么？是否可能部分读（partial read）？	NIO`Channel.read()`单次调用不保证填满缓冲区
Arithmetic units	尺寸、时间戳、位置各自用什么单位？	`compressedLength + 4`（checksum 的 int 长度）、`nanoTime()`与毫秒混用

以 Cassandra 的压缩写入路径为例：在 CompressedSequentialWriter.java 中，字段protected long chunkOffset = 0;（L54）是文件字节单位的 chunk 起始位置，而 buffer 的position()是未压缩字节单位的写入位置；metadataWriter.chunkOffsetBy(...)返回的则是索引文件中的偏移。三种单位混在同一方法里（如 L313 的chunkSize = (int) (chunkOffsetBy(nextChunkIndex) - chunkOffset - 4)），一旦把-4（checksum 占位）记错，读出的 chunk 就会整体错位。这正是清单强调"先弄清算术单位"的原因。

三、Off-by-One 与范围深度检查

3.1 时间单位在 API 边界上的错位（权重：high）

检查点：

时间戳是否以错误的单位跨过 API 边界？
返回值或展示值是否与调用方期望的单位不一致？
是否传错了TimeUnit枚举参数？

Cassandra 中大量接口以"纳秒"为内部单位（如超时、节流），但配置文件和 JMX 常以毫秒/微秒为单位。审查时应重点搜索nanoTime()、currentTimeMillis()、TimeUnit的混用点，并核对调用链两端的单位声明。

3.2 边界比较符：`<`与`<=`的语义核对（权重：high）

检查点：

用自然语言表述边界条件后，代码里的运算符是否与语义一致？
闭区间被当成开区间（或反之）？
恰好落在边界上的相等情形是否被漏掉？
块（chunk）边界对齐断言是否会误伤合法的部分块？

Cassandra 实例：chunk 必须为 2 的幂。在 CompressedChunkReader.java 中有一行硬性断言（L49）：

assert Integer.bitCount(metadata.chunkLength()) == 1; //must be a power of two

这条断言直接决定了后续chunkIndexBy(position)可以用移位替代除法（position >> log2(chunkLength)），从而把"整除是否精确"的问题变成位运算问题。但清单提醒的是另一面：当文件末尾的最后一个 chunk 不满 chunkLength 时，任何"chunk 必须完整对齐"的断言都会误报。因此读取路径在遇到末块时必须以文件长度（而非固定 chunk 大小）为界——CompressionMetadata.dataLength的字段注释正是为此设计："dataLength can represent either the true length of the file or some shorter value, in the case we want to impose a shorter limit on readers (when early opening, we want to ensure readers cannot read past fully written sections)"（CompressionMetadata.java L63-66）。边界对齐断言只应施加于"满块"假设成立的中间 chunk，绝不能施加于末块。

3.3 整数溢出：int 乘 1024 不提升为 long（权重：high）

检查点：

int配置值乘以 1024 或 1024*1024 时，是否因缺少 long 提升而溢出？
Comparator是否用整数相减（溢出风险）代替compare()？
大数值（文件位置、字节计数）上的收窄强转是否静默截断？

Cassandra 实例：chunkSize 的收窄强转。在 CompressedSequentialWriter.java L313：

int chunkSize = (int) (metadataWriter.chunkOffsetBy(realMark.nextChunkIndex) - chunkOffset - 4);

两个 long 相减后收窄为 int。在单 chunk 小于 2GB 的默认场景下安全，但一旦 chunk 上限被调大（chunk_length_in_kb配到极大值），这个强转会静默截断。审查这类代码时，应检查收窄前的差值是否有明确的上界证明，而不是依赖"默认配置不会超"。

3.4 比较器缺陷（权重：medium）

检查点：

比较器是否使用*.compare()方法而非减法？
相等元素是否被正确处理？
是否满足传递性契约？
多次比较的运算数顺序是否一致？

Java 的Comparator契约要求自反性、反对称性与传递性。用a - b实现比较在a、b异号时会溢出，导致排序结果错误且不可复现。Cassandra 中所有核心排序路径（如分区键、token 排序）均使用TypeAware的compareTo实现而非减法；审查新增比较器时，应专门构造Integer.MIN_VALUE与Integer.MAX_VALUE作为测试输入。

3.5 递归迭代器栈溢出（权重：medium）与递归包装链（权重：low）

递归迭代器：检查computeNext()、hasNext()或辅助方法是否自递归，输入规模大时是否爆栈。Cassandra 的AbstractIterator体系、流式迭代器（如范围扫描合并）应警惕链式filter → transform → concat的嵌套深度与输入规模成正比。
递归包装链：防御性包装（如unmodifiableCollection）在每次重建时不检查是否已包装，链深度随调用次数增长，遍历时溢出栈。审查时搜索"包装后再包装"的循环调用点。

3.6 MB/GB 转字节溢出（权重：medium）

检查点：

换算 MB/GB 为字节时，乘法前是否至少有一个操作数是long？
中间乘积是否在 2GB 处溢出？

Cassandra 实例：压缩参数解析。在 CompressionMetadata.java 的open(...)路径中，从索引文件头读取chunkLength（int）与maxCompressedSize（int）（L106-109），随后构造CompressionParams。任何"chunkLength * 1024"式的换算若仍以 int 完成，超过 2GB 即溢出；CompressionParams.validate的存在正是为了在配置阶段拦截这类问题，而非等到运行时。

3.7 循环停止条件（权重：medium）

检查点：

循环用> limit而非>= limit（或反之）？
是否多处理一个或少处理一个元素？

Cassandra 实例：扇出读（read-ahead）判断。CompressedChunkReader.java 中两次出现同一模式（L289、L376）：

scanReader = (readAheadBufferSize > 0 && readAheadBufferSize > metadata.chunkLength())

这里"是否启用预读"取决于预读缓冲区是否严格大于chunk 长度：恰好相等时禁用预读。这是一个刻意的开区间判断，但若后续维护者改成>=，预读缓冲区与 chunk 等长时的行为就会反转——审查时要把这类边界条件用注释固定下来，或抽出为带名字的方法。

3.8 缓冲区偏移调整（权重：medium）

检查点：

buffer.array()是否考虑了position()与arrayOffset()？
slice()之后是否考虑了非零偏移？

堆缓冲区array()返回的是整个后备数组，其有效数据从arrayOffset() + position()开始；slice()产生的视图arrayOffset()可能非零。审查搜索.array()与.position(、.slice(的组合，确保索引计算没有把 0 当成起点。Cassandra 中大量ByteBufferUtil辅助方法与Memory/SafeMemory直接内存路径，均绕过了array()以避免这类偏移陷阱。

3.9 二分搜索后的 +1 调整（权重：low）

检查点：在有序范围结构上二分后，对精确命中结果做 +1 调整，会破坏"元素应留在命中位置"的不变量。

Cassandra 实例：DiskBoundaries 的插入点转换。DiskBoundaries.java 用Collections.binarySearch定位 key 所属磁盘，且显式断言永远不会精确命中：

int pos = Collections.binarySearch(positions, sstable.getFirst()); assert pos < 0; // boundaries are .minkeybound and .maxkeybound so they should never be equal return -pos - 1; // L115-117

这里-pos - 1是二分"插入点"的标准逆运算（当pos < 0时插入点为-pos - 1）。清单提醒的是反例：若某实现把"未命中"与"命中"混在一起，在命中值上额外 +1，就会让元素落到错误区间。Cassandra 用assert pos < 0把"边界绝不与 key 相等"这个不变量显式固化，正是正确的防御姿势。同文件getDiskIndex(DecoratedKey key)（L155-160）也复用了同一模式。

3.10 非零 fromIndex 的二分返回值（权重：low）

binarySearch接受非零fromIndex时，自定义实现可能返回相对索引而调用方期望绝对索引。审查时确认二分函数的返回基准与调用处的使用基准一致，尤其当搜索范围是原数组的subList时。

3.11 正反向两半二分搜索的区间传反（权重：low）

当二分被拆成正序、逆序两半时，检查传给两半的 sublist 范围是否各自正确；传反会静默跳过有效匹配。此类代码常见于"从中间向两边扩散"的范围查询实现。

3.12 文件位置算术中的 int 中间量（权重：low）

多 GB 文件位置计算偏移时，过早的(int)强转会静默截断。与 3.3 同理，审查文件 I/O 代码时，所有位置/偏移量优先声明为long，仅在经过上界证明后才允许收窄。

3.13 for-each 循环体开头自增计数器（权重：low）

在 for-each 循环体顶部自增的手工计数器，用作数组索引时永远比当前元素领先一格。典型错误：遍历第 i 个元素却用i+1访问数组，末元素时越界。

3.14 恰好落在 chunk 倍数上的端点多读一个 chunk（权重：low）

端点恰好落在 chunk 边界上时，不需要再读下一个 chunk；未检查该情形会多发送一个 chunk。这与 3.2 的"末块合法不满块"互为镜像：边界上既不能少读，也不能多读。

3.15 恒定增量累加器漂移出合法输入域（权重：low）

以恒定增量累加的计数可能漂移出合法输入范围，破坏后续的范围检查逻辑。

3.16 "多检查一项"的扫描循环用错比较符（权重：low）

意在"检查区间外多一项"的扫描循环，若边界用<而非<=，会静默跳过那额外的一项。与 3.7 同族，审查时对照注释与代码的运算符。

四、空值与边界检查深度

4.1 Map/注册表查找为 null（权重：high）

检查点：

查找结果使用前是否判空？
后台任务是否与并发移除刚查到的条目产生竞态？
接受用户提供 key 的路径是否对查找结果判空？

Cassandra 中典型场景：CompressionMetadata的@Nullable CompressionDictionary compressionDictionary（CompressionMetadata.java L72-73，注释明确标注 "null when no dictionary"）——解压路径在无字典模式下不能解引用它。审查时搜索@Nullable注解字段的所有读取点，确认每条路径都处理了 null 分支。

4.2 集合/数组越界（权重：high）

检查点：

list.get(0)之前有没有isEmpty()？
array[idx]之前有没有长度检查？
Optional.get()之前有没有isPresent()？
平行列表长度是否一致？

4.3 indexOf/substring 未判 -1（权重：high）

检查点：

indexOf/lastIndexOf的返回值未加!= -1保护就被用作substring(...)的偏移？
split(...)在分隔符缺失时返回单元素数组，调用方却假设多元素结果？

这是 CQL 解析、配置解析路径上的高频缺陷：字符串里找不到分隔符时indexOf返回 -1，substring(-1)抛异常或取到错误位置。

4.4 可空生命周期字段（权重：high）

检查点：

字段在start()/setup()而非构造函数中初始化？
在关闭或启动竞态期间被解引用？
从错误的构造路径访问？

Cassandra 实例：writer 的 buffer 生命周期。CompressedSequentialWriter.java 中，压缩缓冲区的分配发生在 writer 打开/重建路径（L80-86 附近），而非构造函数；replay/truncate逻辑（L300-310）会重置buffer.position()与chunkOffset。若有一个后台 flush 线程在 buffer 尚未分配时被触发，就会命中 NPE——审查时关注"分配点"与"使用点"是否在同一生命周期边界内。

4.5 死循环（权重：high）

检查点：

while(true)/while(!done)是否有显式退出路径？
是否有超时、最大重试次数或中断检查？
上游停滞时条件是否永远不可能为真？

Cassandra 实例：带时限的等待循环。CompactionManager.java L2679 展示了正确的带退出条件写法：

while (nanoTime() - start < delay)

配合中断检查与退出条件，保证不会在极端情况下无限自旋。审查死循环时，清单给的启发式问题非常有效："你能证明这个条件终有一天为真吗？如果上游永远不推进呢？"

4.6 强转前缺少 instanceof（权重：high）

检查点：

每个强转前是否都有匹配的instanceof保护？
新增实现类时，它是否通过现有的类型检查？

4.7 空集合边界（权重：high）

检查点：

零元素时怎么办？是否防御了空输入？
空的凭据、配置或选项是否走了一条不同的（错误）代码路径？

4.8 空/不可能的范围未在执行前检测（权重：low）

逻辑上为空的范围（start > end，或边界永不相交）在执行前未被检测，导致空转或错误结果。Cassandra 的区间结构（如范围墓碑、压缩分片）在构造时即校验端点序，把"不可能范围"挡在入口。

4.9 无子类型检查访问可空子类型字段（权重：low）

只为某些子类型填充的字段，在未检查子类型时被访问，导致 NPE。对应 4.6：instanceof检查不仅保护强转，也保护"仅特定实现才有"的字段。

4.10 空累加器的"首次遇到"守卫跳过初始化（权重：low）

if (field != null && ...)形式的守卫，在字段初始为 null 时会把"首次遇到"的情形一并跳过，导致初始化永不发生。正确写法是区分"首次"与"已有值"两个分支。

4.11 claim/lock 方法返回 null 被直接解引用（权重：low）

"标记独占使用"的 claim 方法返回 null 表示无可用项，但调用方直接解引用。审查时对返回值带 null 语义的方法（可搜索返回类型上的@Nullable）逐一确认调用点。

4.12 构造函数把参数赋成 null（权重：low）

this.field = null;而非this.field = parameter;，静默丢弃配置。此类笔误审查时难以通过行为观察发现，只能靠逐行比对构造参数与字段赋值。

4.13 更新校验因缺少回填而拒绝无操作变更（权重：medium）

当更新强制不可变性时，必须把已有值复制进传入对象，否则"无变化更新"会触发虚假的"字段被修改"错误。这与 Cassandra 中不可变元数据（如表结构变更）的校验逻辑相关：先拷贝旧值再比较，而不是直接对旧值断言。

4.14 辅助方法在非法输入时静默返回空集合（权重：low）

辅助方法对非法输入仅打警告日志并返回空集合；调用方却阻塞等待从未提交的工作。审查时把"返回空"与"调用方预期非空"的契约显式化。

4.15 File.listFiles() 为 null（权重：medium）

检查点：

迭代前是否检查File.listFiles()结果非 null？
是否在非目录路径上调用？

listFiles()在路径不存在或 IO 错误时返回 null（而非空数组），直接 for-each 会 NPE。Cassandra 的快照/备份清理路径（find_snapshots.sh、nodetool clearsnapshot对应的 Java 实现）涉及大量目录枚举，这类防御必须到位。

4.16 File.length() 对目录返回 0（权重：low）

用file.length()求和计算磁盘占用时，目录返回 0 而非递归内容大小，导致占用被低估。需要Files.walkFileTree或显式递归。

4.17 处理前 poll() 导致异常时无法重试（权重：low）

清理循环里poll()在处理完成前移除了条目，任何异常都会让该条目永久未处理。应改为"处理成功后移除"。

4.18 除零（权重：low）

运行时派生的除数（如collection.size()）是否检查为零？尤其在计算平均值、进度百分比时。

五、ByteBuffer 与 I/O 深度检查

5.1 会推进 position 的 get()（特定模式）

无参ByteBuffer.get()会推进 position。若在比较器或共享视图内部调用，会产生带副作用的读取。审查时确认：缓冲区归本代码所有，还是共享/只读视图？

5.2 共享缓冲区未做快照就传给辅助方法（权重：medium）

检查点：

共享缓冲区传给辅助方法后，相对读是否作为副作用推进了 position？
同一缓冲区的后续读者是否从错误偏移读取？
rewind-恢复模式是否与并发读者竞态？

Cassandra 实例：hints 的压缩读写。CompressedHintsWriter.java L62-65 连续两次compressionBuffer.rewind()，配合flip()完成"写→读"交接。rewind()只重置 position 不调整 limit，若在写满后未先flip()，读者会读到超出已写区域的未初始化字节（对应清单 5.5）。hints 写入路径对同一 buffer 反复复用，任何 position/limit 错乱都会导致压缩流错位。

5.3 写入侧未检查容量就 put（权重：medium）

检查点：

定宽尾部/标记/段尾 token 的写入，是否在remaining() >= N检查之前？
编码循环是否以"输入消费完"而非"输出排空"退出——当输出超过输入时，尾部被静默截断？
不做输出边界校验的解压变体，是否被用于不可信网络数据？

Cassandra 实例：compressedLength 与 maxCompressedLength 的比较。CompressedSequentialWriter.java L219-239 展示了对"压缩后超过上限"的显式处理：

int uncompressedLength = buffer.position(); int compressedLength = compressed.position(); ... if (compressedLength >= maxCompressedLength) { toWrite = buffer; // 压缩无收益，直接写未压缩数据 if (uncompressedLength >= maxCompressedLength) compressedLength = uncompressedLength; else { ... buffer.limit(maxCompressedLength); 填充零 ... } }

这段代码保证写出的每块长度 ≤maxCompressedLength，且末块通过"填充零到上限"保持长度一致（注释说明：该路径只出现在文件末尾，读取时以文件长度限制缓冲区）。审查压缩类 I/O 时，应核对"压缩后长度检查"是否覆盖所有分支，尤其是compressedLength == maxCompressedLength的等号情形（清单 3.2 的边界比较）。

5.4 读长度前缀前未守卫 zero-remaining（权重：low）

从缓冲区读长度前缀（或定宽头部）前，是否检查remaining() >= headerSize？合法的空组件会因此抛出下溢异常，而不是被当作"无内容"。

5.5 rewind() 代替 flip()（权重：low）

写入填充缓冲区交给读者时，flip()会设置 limit = position 并复位 position 为 0；误用rewind()只复位 position，把已写区域之外的未初始化字节暴露给读者。对应 5.2 的 Cassandra hints 实例。

5.6 NIO 读取完整性（权重：low）

检查点：

Channel.read()是否假设一次调用就能填满整个缓冲区？
是否循环到remaining() == 0或 EOF？

NIO 契约是"尽力而为"：单次read()返回的字节数 ≤ 请求数。Cassandra 的FileInputStreamPlus、DataInputPlus等封装（CompressionMetadata.java L95 用newInputStream()读取索引头）内部实现了循环读取；审查裸 NIO 代码时必须要求有循环。

5.7 EOF 处理（特定模式）

检查点：

NIOread()是否区分 -1（EOF）与 0（空缓冲区）？
InputStream.read()在流结束时是否返回 -1 而非 0？

5.8 异常时留下部分文件（权重：low）

检查点：

写入路径异常时是否留下半写文件而没有 abort/delete？后续读取会把它当作完整文件。
写入已存在文件时是否先截断，否则新内容之外残留旧字节？

Cassandra 的 SSTable 写入采用"临时文件 + 提交时原子重命名"策略，正是为了规避这类问题；commitlog 段也有配套的完整性校验（如 checksum）。

5.9 无上限的重试/退避（权重：medium）

检查点：

指数退避是否有上限？
下界是否会增长超过上界？

典型的正确写法是backoff = Math.min(backoff * 2, maxBackoff)。

5.10 Sets.union 惰性视图链（权重：low）

循环中累积Sets.union会形成深度 = 迭代次数的视图链，遍历时性能退化甚至栈溢出；应物化为具体集合。

六、区间与范围深度检查

6.1 区间端点运算符（权重：low）

共享边界上< 0与<= 0是否与开/闭区间约定一致？文档约定是否与实现一致？

Cassandra 实例：DiskBoundaries 的断言。DiskBoundaries.java L116 用assert pos < 0声明"边界与 key 永不相等"，即区间采用左闭右开约定：getDiskIndex返回的插入点-pos - 1是 key 应归属的磁盘区间左端点。若某天边界生成逻辑允许相等，这个断言会在测试期立刻暴露——这就是"把约定变成可执行断言"的最佳实践。同文件的getDisksInBounds(first, last)（L162-169）用subList(firstIndex, lastIndex + 1)处理闭区间查询，两个端点语义必须一致。

6.2 半开区间转闭区间（权重：low）

用[a, b)API 包装[a, b]范围时，上界是否 +1？Cassandra 的区间结构（Range<T>、Bounds）大量使用[left, right)半开语义，包装层漏掉 +1 会导致末元素丢失。

6.3 范围边界部分强制（权重：low）

是否只强制了起始边界而忽略了结束边界（或反之）？

6.4 回绕范围导致无限线性扫描（权重：low）

反向或逆向迭代中，循环守卫对可能落在起点另一侧的端点使用严格<（或>），在回绕（wrap-around）范围内会死循环。审查 token ring / 环绕区间（Cassandra 的 token 范围是环形的）相关的迭代代码时，必须显式处理"跨过 0 点"的情形。

七、算术陷阱专项

7.1 缺括号（权重：low）

n + 1 / 2实际是n + (1/2)=n + 0。整数除法优先级陷阱在 chunk 大小换算、均值计算中常见。

7.2 浮点循环漂移（权重：low）

float/double 累加器从 0.0 循环到 1.0 时可能错过终值。应改用整数计数或<=容差比较。

7.3 向上取整除法（特定模式）

(n + d - 1) / d是否正确用于向上取整？
round-down-to-multiple在 value < N 时是否产生 0？

Cassandra 中 chunk 数计算、压缩块划分均涉及(n + chunkLength - 1) / chunkLength的向上取整，n = 0时结果应为 0。

7.4 容量与读边界混用（权重：low）

缓冲区 capacity 对读和 seek 是否都被当作排他边界？"seek 到末尾（≤ capacity）"应被允许，而"读末尾"不允许。

7.5 压缩与未压缩尺寸混用（权重：medium）

检查点：

文件切分决策用的是压缩还是未压缩尺寸？
进度条的分子分母是否使用同一尺寸口径？

Cassandra 实例：两类尺寸并存。CompressedSequentialWriter.java 同时维护uncompressedSize（L221）与compressedSize（L241）两个累加量，且 L250lastFlushOffset = uncompressedSize。任何进度报告、切分判断若混用两者，就会出现"分母是压缩字节、分子是未压缩字节"的失真。审查时对同方法内并存的多套尺寸单位保持高度警惕。

7.6 nanoTime 截止时间加法溢出（权重：low）

nanoTime() + duration在接近Long.MAX_VALUE时溢出；安全模式是nanoTime() - start < duration。Cassandra 实例：CompactionManager.java L2679 正是采用了安全模式while (nanoTime() - start < delay)，而非先加后比。

7.7 Integer.MAX_VALUE 哨兵上的算术溢出（权重：low）

limit + 1在 limit 为Integer.MAX_VALUE时静默回绕为负数。凡是可能取到 MAX_VALUE 的"上限 + 1"模式都必须先判等。

7.8 概率门控不短路边界值（权重：low）

概率检查在配置为 0.0 或 1.0 时仍调用 RNG。优化方式是对 0.0/1.0 短路。

7.9 由原始哨兵计算的过期/截止时间（权重：low）

检查点：

配置值如retention = -1（表示无限）是否被直接用于now + duration，产生"已过期"的瞬间？
定义为负数的 epoch 偏移常量是否被减（双重否定）而非加？

Cassandra 中"保留期 -1 = 永不过期"类语义（如 hint 过期、TTL 相关配置）必须在进入算术前先替换哨兵。

7.10 序列化尺寸与真实写入不符（权重：medium）

检查点：

尺寸计算是否加了字段的长度前缀却忘了载荷字节？
条件字段是否被无条件计数、又在分支内再次计数——声明尺寸 > 实际写入字节？
尺寸计算与写入路径的字段顺序是否发散，重构改了一处漏了另一处？

Cassandra 实例：chunk 偏移的记账。CompressedSequentialWriter.java L244 写入偏移metadataWriter.addOffset(chunkOffset)后，L256 推进chunkOffset += compressedLength + 4;——这里的+4是每块末尾 checksum（int）的占位。若"偏移记账"与"实际写入"（writeChunk写入压缩数据 + 4 字节校验和）两处不一致，读侧按偏移定位就会错位。L313 的chunkSize = ... - chunkOffset - 4又需要把这块 checksum 扣回来。"写偏移的地方、推进偏移的地方、扣 checksum 的地方"三者必须永远保持同步——这正是清单第 7.10 条"尺寸计算与写入路径发散"的典型形态。

八、把清单落地为审查动作

综合以上全部检查项，可以把.claude/skills/deep-review/references/deep/deep-boundary.md提炼为一组可执行的审查动作：

先收集上下文，再读 diff：明确数据范围、哨兵值、缓冲区归属、I/O 契约、算术单位，见本文第二节；
对每个边界写一句自然语言不变量：如"边界 key 绝不等于分界点（DiskBoundaries.java L116 的assert pos < 0）""chunk 长度必须为 2 的幂（CompressedChunkReader.java L49）"；
把不变量变成断言或注释：Cassandra 的压缩路径正是这样做的——Integer.bitCount(...) == 1、assert pos < 0，让越界在测试期而非生产期暴露；
对 high 权重项做系统性扫描：时间单位跨界、</<=、int 溢出、查找判空、死循环、instanceof、空集合、EOF 处理；
对 I/O 代码逐字节对账：写入字节、偏移推进、checksum 占位、尺寸统计四个数字必须自洽（CompressedSequentialWriter.java L219-256 是极佳的对账样例）；
对 low 权重项采用模式搜索：rewind()与flip()混用、nanoTime() + duration、indexOf后直接substring、listFiles()未判空等，均可通过正则批量定位后再人工确认。

边界缺陷之所以危险，是因为它们在常规输入下完全正常，只在恰好越界的那一刻爆发。本文给出的每一类检查项，都在 Cassandra 仓库中能找到对应的真实代码或防御范例——把它们作为审查时的"边界语义标尺"，就能在代码合入前拦截这一类最隐蔽的缺陷。

创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考

企业官网建设流程全解析