CodeQL C 查询精度改进:cs/call-to-object-tostring 对值元组的识别逻辑解析
CodeQL C# 查询精度改进:cs/call-to-object-tostring 对值元组的识别逻辑解析
导读
本文围绕 CodeQL C# 查询 cs/call-to-object-tostring(“Use of default ToString()”)在 1.0.18 版本中的一次 Minor Analysis Improvements 展开:该版本针对 C# 值元组(ValueTuple)场景优化了查询判定逻辑,显著降低了元组类型上的误报。读完本文,你将掌握该查询的检测目标、默认 ToString() 判定的底层原理,以及元组特判在 DefaultToStringQuery.qll 中的具体实现,并了解如何运行查询与阅读对应测试用例加以验证。
版本变更背景
C# 1.0.18 变更记录 位于仓库 csharp/ql/src/change-notes/released/ 目录下,与其余上百个按版本号组织的变更记录并列。该版本在 Minor Analysis Improvements 分类下仅记录了一条针对 C# 的改动:
C#: Improve precision of the query
cs/call-to-object-tostringfor value tuples.
即:提升查询 cs/call-to-object-tostring 在值元组上的精度。“提高精度”在 CodeQL 语境下通常意味着两类效果:一是消除原本会误报(false positive)的元组场景,二是让应报的元组场景(如元组内部元素本身未覆写 ToString())继续被准确捕获。两条路径在 1.0.18 的实现中同时存在,下文结合源码逐一说明。
查询是什么:检测默认 ToString() 的调用
查询 cs/call-to-object-tostring 的正式名称为 Use of default ToString(),声明位于 DefaultToString.ql:
@kind problem,@problem.severity warning,@precision very-high;@id cs/call-to-object-tostring;- 标签
quality、reliability、correctness; - 描述为:调用
ToString的默认实现会返回一个“几乎不可能是你期望值”的字符串。
其语义在 DefaultToString.qhelp 中有权威说明:调用 System.Object 或 System.ValueType 上的 ToString 方法,返回的是该值的类型的完全限定名(fully qualified name),绝大多数情况下既没有用,也不是开发者本意。该规则同时查找对默认 ToString 的显式调用与隐式调用(例如字符串拼接、Console.WriteLine 自动装箱格式化等场景)。
典型误用与正确写法
仓库在 Useless code 目录 下提供了成对的示例代码。错误示例 DefaultToStringBad.cs 中,Person 类未覆写 ToString(),Console.WriteLine("p: " + p) 实际输出类型名 p: Bad+Person;int<a href="https://link.gitcode.com/i/6fef3fc056dcc11c27fb62a36c03b823" target="_blank">] 数组直接拼接同样输出 ints: System.Int32[]。修正示例 [DefaultToStringGood.cs 则通过覆写 ToString()(public override string ToString() => Name;)和使用 string.Join(", ", ints) 得到 p: Eric Arthur Blair 与 ints: 1, 2, 3。
这两份样例同时说明了一个重要的边界:数组无法通过覆写 ToString() 修正,只能改用显式拼接/序列化手段;而这正是元组场景的相似性所在——元组的“默认 ToString()”同样无法被用户直接覆写,必须按元素递归判断。
1.0.18 改进的核心:值元组的递归判定
查询的 QL 逻辑主体位于 DefaultToStringQuery.qll。与 1.0.18 改动直接相关的谓词是 alwaysDefaultToString,其完整语义为:
t自身或t的任何子类型继承了来自System.Object或System.ValueType的默认ToString()方法。
predicate alwaysDefaultToString(ValueOrRefType t) {
not t instanceof TupleType and
not t instanceof Enum and
exists(ToStringMethod m | t.hasMethod(m) |
m.getDeclaringType() instanceof SystemObjectClass or
m.getDeclaringType() instanceof SystemValueTypeClass
) and
not exists(RefType overriding |
overriding.getAMethod() instanceof ToStringMethod and
overriding.getABaseType+() = t
) and
((t.isAbstract() or t instanceof Interface) implies not t.isEffectivelyPublic())
or
exists(ValueOrRefType elem |
elem = t.(TupleType).getElementType(_) and
alwaysDefaultToString(elem)
)
}
从源码结构可以读出该版本针对元组的两个关键改动:
其一,主分支显式排除 TupleType。 主判定分支开头新增 not t instanceof TupleType。这是因为 C# 编译器为元组生成的底层类型是 System.ValueTuple,它确实继承自 System.ValueType,若不做排除,任何元组都会被直接命中“继承默认 ToString()”的主分支而一律报出——这恰恰是 1.0.18 之前元组场景精度不佳的根源。
其二,新增元组递归分支。 最后一个 or 分支处理元组:取元组的每一个元素类型(t.(TupleType).getElementType(_)),递归调用 alwaysDefaultToString。因此元组整体是否命中,取决于其元素类型是否递归地命中。这是 1.0.18 的核心改进逻辑。
TupleType 的类型抽象
递归中用到的 TupleType 定义于 Type.qll:
class TupleType extends ValueType, @tuple_type,注释明确其为元组类型,例如(int, bool, string);getUnderlyingType()返回底层类型System.ValueTuple;getElement(int n)返回第 n 个元素字段(如(int, string)的第 0 个元素是字段Item1 int)。
可见元组在数据库模式中被建模为独立实体(@tuple_type),并记录每个元素的类型,这正是 QL 侧能对元素逐一递归判定的数据基础。
结合测试用例理解改进效果
仓库测试目录 DefaultToString 查询测试 恰好覆盖了 1.0.18 新增的元组场景(该测试文件与变更记录同时期演进):
Console.WriteLine(new ValueTuple<int, int>(1, 2)); // GOOD
Console.WriteLine((1, 2)); // GOOD
var t1 = new ValueTuple<int, DefaultToString>(1, new DefaultToString());
Console.WriteLine(t1); // BAD
var t2 = new ValueTuple<A, D>(new A(), new D());
Console.WriteLine(t2); // GOOD
逐条对照递归分支的判定:
| 测试行 | 元素类型 | 递归判定结果 | 期望 |
|---|---|---|---|
new ValueTuple<int, int>(1, 2) |
int |
int 本身不命中默认 ToString 主分支 |
GOOD(1.0.18 消除的误报) |
(1, 2)(语法糖) |
int |
同上 | GOOD |
new ValueTuple<int, DefaultToString>(...) |
int + DefaultToString |
元素 DefaultToString 未覆写 ToString(),命中主分支 |
BAD(元组内部隐患仍被捕获) |
new ValueTuple<A, D>(...) |
A + D |
子类型 D 覆写了 ToString(),A 覆写后子类 B 继承覆写,均不命中 |
GOOD |
同时注意测试中的边界组合:Console.WriteLine(new ValueTuple<int, DefaultToString>(...)) 被判为 BAD,说明 1.0.18 的元组特判不是简单地对所有元组放行,而是把“默认 ToString() 风险”下沉到元素级别递归判断,既修掉了 (int, int) 这类纯值元组的误报,又保住了包含未覆写引用类型的元组告警。
相邻版本的协同演进
值得说明的是,元组分支与同文件中的其他排除条件共同构成完整判定:
not t instanceof Enum与 1.4.0 的改动对应——1.4.0 变更记录 记载该版本“移除了枚举类型上的误报”;- 主分支中
(t.isAbstract() or t instanceof Interface) implies not t.isEffectivelyPublic()处理内部接口/抽象类型的可见性边界(测试中IPrivate报 BAD、IPublic报 GOOD 即为此规则的验证); - 子类型覆写检查(
overriding.getABaseType+() = t)保证子类覆写了ToString()时不再命中(测试中B : A、D : C均归为 GOOD)。
底层原理:invokesToString 如何捕获显式与隐式调用
元组判定只解决“哪些类型算默认 ToString()”,而“哪些表达式算调用了 ToString()”由 invokesToString 谓词负责,它定义了三种捕获途径:
- 显式调用:
MethodCall的限定符(qualifier)是表达式e,且调用目标mc.getTarget()是ToStringMethod; - 隐式调用:
e是ImplicitToStringExpr(即编译器在字符串拼接、格式化插值等场景自动插入的ToString()调用节点); - 转发调用:通过可赋值参数定义(
AssignableDefinitions::ImplicitParameterDefinition)判定某参数的所有读取路径必然触发ToString(),从而把“传入该参数的实参”也视为触发了默认ToString()。
这三类途径确保查询能覆盖 p.ToString() 显式写法、"hello " + p 拼接写法,以及 Console.WriteLine(p) 这类经框架方法转发的隐式写法。查询最终通过 problems 谓词输出结果,消息模板为:
Default 'ToString()': $@ inherits 'ToString()' from 'Object', and so is not suitable for printing.
如何运行查询并验证精度
定位查询与套件
该查询在仓库中的完整路径为 csharp/ql/src/Useless code/DefaultToString.ql,并被收录进默认套件 csharp-security-and-quality.qls,因此普通 codeql database analyze 的默认配置即可触发。
命令行运行方式
在已提取好的 C# 数据库上运行该查询的典型命令为:
codeql database analyze <database> \
csharp/ql/src/Useless\ code/DefaultToString.ql \
--format=sarif-latest \
--output=default-tostring.sarif
也可按规则 ID 从套件中筛选:
codeql database analyze <database> \
--suite=csharp/ql/src/codeql-suites/csharp-security-and-quality.qls \
--format=sarif-latest \
--output=results.sarif
前提是本地具备可用的 CodeQL CLI 与对应版本的 C# 查询包(qpack);命令中的路径需替换为仓库实际检出位置。
用测试验证精度行为
仓库自带回归测试可直接验证 1.0.18 的行为变化:
- 测试源文件:DefaultToString.cs;
- 期望输出:DefaultToString.expected;
- 测试入口:DefaultToString.ql。
运行方式为 CodeQL 标准查询测试(codeql test run 指向该测试目录),.expected 文件即“预期结果快照”——任何判定变化都会导致测试失败,从而防止未来改动意外回退 1.0.18 的精度改进。
变更记录体系与阅读指引
本次改动记录在 1.0.18.md,该文件遵循仓库统一的 change-notes 规范:每个版本一个 Markdown 文件,按 Major/Minor Analysis Improvements、Deprecated Queries、Bug Fixes 等分类组织。C# 相关的全部历史变更汇总于 csharp/ql/src/CHANGELOG.md。若想追踪该查询的后续演进,可对比 1.4.0 变更记录(枚举误报移除)及 1.0.19.md 等相邻版本记录。
小结
1.0.18 对 cs/call-to-object-tostring 的改进可概括为一句话:将值元组的默认 ToString() 判定从“类型级一刀切”改为“元素级递归判定”。实现上通过 alwaysDefaultToString 中 not t instanceof TupleType 排除元组直判、再以 TupleType.getElementType 逐元素递归两条规则完成;测试用例验证了 (int, int) 误报被消除、而 (int, DefaultToString) 隐患仍被捕获的精度行为。这一改动体现了 CodeQL 查询精度工程的一般方法:识别编译器自动生成/框架继承导致的宽泛类型匹配,下钻到可被用户行为影响的粒度重新判定,并同步补充回归测试锁定行为。