深入解析 ty 的 no-matching-overload 诊断：Python 重载函数调用失败的静态检测机制

ty 是 ruff 仓库中内置的 Python 类型检查器，no-matching-overload（无匹配重载）是它在类型推断阶段对重载函数（@overload）调用进行检查时报告的一类核心错误诊断。本文以仓库中的测试文档 crates/ty_python_semantic/resources/mdtest/diagnostics/no_matching_overload.md 为骨架，结合 bind.rs 中调用绑定与诊断报告的实现，以及 diagnostic.rs 中该 lint 的声明与规则文档 no-matching-overload.md，系统讲解该诊断的触发场景、诊断输出结构、源码实现原理与运行方式。读完本文，你将理解 ty 如何对重载函数调用逐一对齐参数、聚合所有失败签名，并能在自己的代码中快速定位与修复这类 TypeError 隐患。

一、诊断是什么：规则语义与默认级别

no-matching-overload 对应 ty 类型检查器中的 NO_MATCHING_OVERLOAD lint，其含义是：对重载函数的调用未能匹配上任何一个 @overload 签名。该 lint 的声明位于 diagnostic.rs：

declare_lint! {
    #[doc = include_str!("../../resources/lint_docs/no-matching-overload.md")]
    pub(crate) static NO_MATCHING_OVERLOAD = {
        summary: "detects calls that do not match any overload",
        status: LintStatus::stable("0.0.1-alpha.1"),
        default_level: Level::Error,
    }
}

其公开规则文档 crates/ty_python_semantic/resources/lint_docs/no-matching-overload.md 明确说明了两点：

• 做什么（What it does）：检查对重载函数的调用中，没有任何一个重载与调用参数匹配的情况；
• 为什么是坏味道（Why is this bad）：如果没有向任何一个重载提供正确参数，程序在运行时将抛出 TypeError。

该 lint 的默认级别是 Level::Error（错误），状态为稳定（stable）。在 mdtest 中，触发该错误的调用点用行内注释标记，形式统一为：

f(b"foo")  # error: [no-matching-overload]

二、基础触发场景：最简单的重载失配

文档第一个用例演示了最典型、最基础的触发方式——调用参数类型不在任何重载签名覆盖范围内：

from typing import overload

@overload
def f(x: int) -> int: ...
@overload
def f(x: str) -> str: ...
def f(x: int | str) -> int | str:
    return x

f(b"foo")  # error: [no-matching-overload]

这里 f 声明了两个重载：一个接受 int 返回 int，一个接受 str 返回 str，实现函数则接收并返回 int | str 的联合类型。调用 f(b"foo") 传入的是 bytes，它既不能赋值给 int，也不能赋值给 str，因此所有重载都匹配失败，ty 报告 no-matching-overload。

注意实现函数体中的 ... 与真实实现并存的情况：在 typing.overload 的约定中，@overload 装饰的函数体必须用 ... 占位，紧随其后需要一个不含 @overload 的实现函数，其参数类型应为所有重载的并集（这里是 int | str）。这正是 crates/ty_python_semantic/resources/mdtest/overloads.md 中“Overloads”相关用例反复验证的语义。

三、诊断输出结构：错误定位与四级信息

通过查看该测试对应的快照文件（位于 crates/ty_python_semantic/resources/mdtest/snapshots/ 目录，例如 no_matching_overload…_-_…Calls_to_overloaded_…_(36814b28492c01d2).snap 与 no_matching_overload…_-_…Call_to_function_wit…_(f66e3a8a3977c472).snap），可以看到一个完整的 no-matching-overload 诊断由以下几部分组成：

error[no-matching-overload]: No overload of function `f` matches arguments
  --> src/mdtest_snippet.py:61:1
   |
61 | f(b"foo")  # error: [no-matching-overload]
   | ^^^^^^^^^
info: First overload defined here
  --> src/mdtest_snippet.py:3:1
info: Possible overloads for function `f`:
info:   (lion: int, turtle: int, ...) -> int
info:   (lion: str, turtle: str, ...) -> str
info: Overload implementation defined here
  --> src/mdtest_snippet.py:41:5

• 主错误信息：No overload of function f matches arguments，定位到整个调用表达式（快照中以 ^^^^^^^^^ 标注整个调用）；
• info 1：指向第一个重载声明的定义位置（First overload defined here），帮助用户快速跳到源码中的重载列表；
• info 2：逐行列出所有可能的重载签名（Possible overloads for function f:）；
• info 3：指向实现函数的定义位置（Overload implementation defined here）。

该诊断的生成逻辑在 bind.rs 的 report_diagnostics 分支中：当 overloads 数量大于 1、且既没有“只有一个重载通过 arity 检查”也没有“只有一个重载类型匹配”这两种可以精确上报的情形时，就退化为输出这条通用的“无匹配重载”消息，并依次附加上述子诊断与 info 信息。

四、参数展开与 __get__ 绑定场景

文档还覆盖了两个容易忽略但实现上有特殊处理的场景。

4.1 对重载函数显式调用 __get__

from typing import overload

@overload
def f(x: int) -> int: ...
@overload
def f(x: str) -> str: ...
@overload
def f(x: bytes) -> bytes: ...
def f(x: int | str | bytes) -> int | str | bytes:
    return x

f.__get__()  # error: [no-matching-overload]

文档特别指出：用于绑定 __get__ 的重载是独立于 f 的声明而合成的，但诊断仍然应该展示 f 的每一个重载声明。在 bind.rs 中可以找到对 KnownBoundMethodType::FunctionTypeDunderGet(function) 的专门匹配分支，说明 ty 把 f.__get__ 这类描述符绑定调用作为 FunctionKind::MethodWrapper 处理，从而仍能回溯到原始函数 f 的重载列表并逐一展示。

4.2 方法调用与构造器调用

方法上的重载同样会被检查：

class Foo:
    @overload
    def bar(self, x: int) -> int: ...
    @overload
    def bar(self, x: str) -> str: ...
    def bar(self, x: int | str) -> int | str:
        return x

foo = Foo()
foo.bar(b"wat")  # error: [no-matching-overload]

这里 b"wat" 同样是 bytes，无法匹配 int 或 str 两个重载。从快照文件看，ty 会为绑定方法（BoundMethod）展开签名时自动绑定 self（对应 bind.rs 中 overload.signature.bind_self(db, env, None) 的逻辑），保证诊断中展示的签名不含 self 参数。

构造器场景在文档中以 type() 作为示例（type() # error: [no-matching-overload]），并带有 TODO 说明：截至 2025-05-15，构造器的诊断存在不理想之处——不会展示未匹配的重载列表，且输出可能受 debug_assertions 开启与否影响（涉及 Todo 类型的处理差异）。

五、重载数量上限与省略机制

文档用一个“过多未匹配重载”的用例专门验证了诊断输出列表存在数量上限。该用例为 foo 声明了数十个 int/str/float/list[...]/bool 组合的三参数重载（见 no_matching_overload.md），然后调用 foo(Foo(), Foo()) 触发诊断。快照显示：ty 只展示前 50 个签名，然后输出一行省略信息：

info: Possible overloads for function `foo`:
info:   (a: int, b: int, c: int) -> Unknown
info:   ...
info:   (a: int, b: int, c: int) -> Unknown
info: ... omitted 11 overloads

这个上限在 bind.rs 中以常量定义：

const MAXIMUM_OVERLOADS: usize = 50;

对应的输出逻辑在 bind.rs：先统计 possible_overload_count，用 .take(MAXIMUM_OVERLOADS) 只迭代前 50 个，当总数超过上限时补一行 "... omitted {remaining} overloads"，其中 remaining = possible_overload_count - MAXIMUM_OVERLOADS。

同时可以注意快照中展示的签名返回类型均为 Unknown——因为这些 @overload 声明没有标注返回类型，ty 以未知类型呈现，但这不影响参数匹配与诊断触发。

六、多参数函数：长签名的展示与可读性

文档最后一个完整用例使用 16 个动物命名的参数构造了两个长签名重载：

@overload
def f(
    lion: int,
    turtle: int,
    tortoise: int,
    goat: int,
    capybara: int,
    chicken: int,
    ostrich: int,
    gorilla: int,
    giraffe: int,
    condor: int,
    kangaroo: int,
    anaconda: int,
    tarantula: int,
    millipede: int,
    leopard: int,
    hyena: int,
) -> int: ...
@overload
def f(
    lion: str,
    turtle: str,
    tortoise: str,
    goat: str,
    capybara: str,
    chicken: str,
    ostrich: str,
    gorilla: str,
    giraffe: str,
    condor: str,
    kangaroo: str,
    anaconda: str,
    tarantula: str,
    millipede: str,
    leopard: str,
    hyena: str,
) -> str: ...
def f(
    lion: int | str,
    turtle: int | str,
    ...
) -> int | str:
    return 0

f(b"foo")  # error: [no-matching-overload]

对应的快照（…_-_Calls_to_overloaded_…_(36814b28492c01d2).snap）展示了 ty 如何将两个长签名完整写入 Possible overloads 列表，并附上“第一个重载定义处”与“实现定义处”的精确源码区间标注。这说明即使参数很多，诊断依然保持签名完整、可读，方便开发者逐项对照。

七、运行与验证方式

这些用例是 mdtest 快照测试的一部分。mdtest 框架的入口位于 crates/mdtest/src/lib.rs，测试文件放置在 resources/mdtest 目录下，运行后会与 resources/mdtest/snapshots/ 下的快照文件比对，以校验诊断输出是否与预期一致。除本文档外，同目录的 crates/ty_python_semantic/resources/mdtest/diagnostics/union_call.md 也包含对该诊断的关联用例，crates/ty_python_semantic/resources/mdtest/overloads.md 则系统覆盖了 @overload 的合法/非法声明与调用语义。

ty 是 ruff 仓库中的类型检查器，其规则列表生成在 crates/ty/docs/rules.md 中。若要在本地复现本文所有示例的诊断输出，可在此仓库工作区构建并运行 ty 类型检查相关命令，输入任意一节中的 Python 代码即可看到与快照一致的 error[no-matching-overload] 报告。

八、小结：诊断触发条件与修复要点

综合本文档与源码实现，no-matching-overload 的触发与报告机制可归纳为：

1. 触发条件：调用目标具有多个 @overload 声明（overloads 数量 > 1），且所有重载均匹配失败——既无重载通过 arity（参数个数）检查，也没有唯一一个重载通过类型检查；
2. 判定依据：ty 为每个重载逐一进行参数绑定（bind），收集各自的绑定错误，通过 has_binding_errors 判断是否“无匹配重载”（bind.rs）；
3. 报告内容：错误信息、第一个重载定义位置、最多 50 个可能的重载签名（超出部分以省略计数提示）、实现函数定义位置；
4. 修复思路：检查调用实参类型是否与某个重载的参数类型可赋值，必要时为缺失的类型组合补充新的 @overload 声明，或将调用参数修正为已有重载可接受的类型，从而避免运行时 TypeError。