宁缺毋滥(重精确轻召回):只报告可能导致错误行为、内存不安全、安全漏洞或实质性性能问题的内容。不要报告由zig fmt处理的格式问题;在提出兼容性问题前,先考虑项目的 Zig 版本、构建模式(Debug、ReleaseSafe、ReleaseFast、ReleaseSmall)及生效的comptime配置。
内存安全与非法行为
5 项- 切片、指针或
[]const u8视图比其指向的存储存活更久,尤其是派生自栈局部变量、临时对象或被复用/释放的缓冲区的地址内置来源与改动说明
- 可检测的非法行为——越界索引、整数溢出、丢失值的
@intCast/@truncate收窄、对可选类型的空解包、非法的@ptrCast/@alignCast——在ReleaseFast或ReleaseSmall中可达;这些模式禁用了安全检查,同样的代码会变成静默的未定义行为内置来源与改动说明
- 读取
undefined内存,或在值完全初始化之前使用它内置来源与改动说明
@ptrCast、@alignCast、@bitCast或指针运算未在局部建立类型、对齐、来源(provenance)及生命周期不变量内置来源与改动说明
- 在
Debug/ReleaseSafe中,若无真实生命周期或别名缺陷的证据,不要报告普通的值拷贝或经边界检查的访问内置来源与改动说明
分配器与资源清理
5 项- 从
Allocator获取的内存没有与之匹配的free/destroy,或用与分配时不同的分配器释放内置来源与改动说明
- 获取资源却没有相应的
defer或errdefer,使提前return或错误路径发生泄漏或留下残缺状态内置来源与改动说明
- 仅在成功路径清理的值缺少
errdefer,导致同函数后续步骤失败时发生泄漏内置来源与改动说明
- 对已释放或已别名的对象执行
deinit造成双重释放或释放后使用内置来源与改动说明
- 在失败会改变正确性的边界处忽略分配或可失败调用的结果内置
来源与改动说明
错误、可选类型与控制流
5 项- 用
catch unreachable、catch undefined或_ =丢弃错误联合,而该错误在运行时实际可达内置来源与改动说明
- 对不可信输入或运行时输入下合法可为 null 的可选类型使用
orelse unreachable或.?内置来源与改动说明
- 在可复用的库或服务器代码中对普通非法输入使用
unreachable或@panic,尤其是在 release-unsafe 模式下会变成非法行为的场合内置来源与改动说明
- 对错误集或带标签联合做
switch,用else静默处理无关分支,从而掩盖新增的变体内置来源与改动说明
- 用断言(
std.debug.assert)校验不可信输入,因为它们在 release-unsafe 构建中会被编译剔除内置来源与改动说明
comptime、泛型与构建代码
4 项comptime代码或基于@This()的泛型读取可变外部状态,在无明确要求的情况下使构建不可复现内置来源与改动说明
- 类型参数函数假定调用方的类型具备某些能力(字段、方法、布局),而该类型可能并不具备,产生费解的编译错误而非受检约束内置
来源与改动说明
build.zig步骤获取、执行或信任不可信输入;或硬编码绝对路径与平台假设内置来源与改动说明
- 当生成行为清晰且输入经过校验时,不要报告普通的
comptime用法内置来源与改动说明
并发与 C 互操作
5 项- 共享可变状态被多线程访问,却没有
std.Thread.Mutex、原子操作或既定的单属主设计内置来源与改动说明
- 跨阻塞操作或回调持有锁,造成死锁或饥饿风险内置
来源与改动说明
extern/export声明或callconv注解相对 C 侧存在类型、结构体布局、可空性或所有权不兼容内置来源与改动说明
- 消费 C 字符串或缓冲区前未校验长度、空终止、编码与生命周期内置
来源与改动说明
- 用户可控数据未经验证即传给进程派生、路径访问、SQL 构造或反序列化;秘密嵌入源码、日志或错误消息内置
来源与改动说明