必须用 typing.TYPE_CHECKING 解决循环类型引用问题，即在 if TYPE_CHECKING: 块中进行仅用于类型提示的导入，避免运行时 ImportError，同时确保类型检查器能识别类型。
什么时候必须用 typing.TYPE_CHECKING
循环类型引用（circular type reference）时，TYPE_CHECKING 是唯一安全的解法。比如模块 A 定义了类 User，又在类型注解里用到了模块 B 的 Profile；而模块 B 同样在注解里引用了 User——直接导入会报 ImportError 或运行时报错，但类型检查器（如 mypy）又需要知道这些类型。
这时不能靠“把 import 写在函数里”硬扛，因为函数内 import 只解决运行时，对类型检查无效；也不能用字符串字面量（"Profile"）一劳永逸，它在泛型、方法签名、协议匹配等场景下会失效。
- 只在
if typing.TYPE_CHECKING:块里做from ... import ...，运行时不执行 - 确保所有仅用于类型提示的导入都放进去，包括
from __future__ import annotations无法覆盖的部分（如Protocol、TypedDict子类） - 别在
TYPE_CHECKING块里写运行逻辑，mypy 不检查它，但其他工具（如 pyright）可能误报
TYPE_CHECKING 和 from __future__ import annotations 能否共存
能，而且推荐共存——但作用完全不同，混用时容易误判效果。
from __future__ import annotations 把所有类型注解转成字符串，延迟到真正需要时再解析（比如调用 get_type_hints()），它解决的是「注解执行时机」问题；而 TYPE_CHECKING 解决的是「导入要不要发生」问题。前者不阻止导入语句执行，后者直接跳过整段代码块。
立即学习“Python免费学习笔记（深入）”；
- 加了
annotations后，仍需TYPE_CHECKING来避免循环导入引发的ImportError - 没加
annotations时，TYPE_CHECKING块里的类型名在运行时不可见，但 mypy 仍能识别——这是设计使然 - 如果用了
annotations还在TYPE_CHECKING外写def func(x: User) -> Profile:，且User未定义，运行时就炸（NameError），和类型检查无关
常见错误：在 TYPE_CHECKING 里写了实际依赖的代码
最典型的翻车是把数据库模型、配置加载、日志初始化塞进 if TYPE_CHECKING: 块里，以为“反正不运行”，结果上线后发现服务起不来——因为这些代码根本没执行。
这个块只对类型检查器可见，CPython 解释器在运行时完全跳过它。所以任何有副作用、有依赖、要被调用的代码，都不能放这儿。
- ❌
if TYPE_CHECKING: db = init_db()——db运行时是未定义的 - ❌
if TYPE_CHECKING: from myapp.models import User+ 后面直接用User当值（比如user = User()）——运行时报NameError - ✅ 正确姿势：所有运行时需要的对象，必须在
TYPE_CHECKING外定义或导入；类型注解中用到的，才放进去
mypy 和 pyright 对 TYPE_CHECKING 的处理差异
两者都支持，但行为细节不同，尤其在嵌套条件和未声明变量上。
mypy 更严格：如果 TYPE_CHECKING 块里定义了一个变量（比如 SomeType = Union[str, int]），它只在该块内有效，外面用会报错；pyright 则可能把它提升为模块级符号，导致意外通过检查但运行失败。
- myPy 默认把
TYPE_CHECKING当作纯类型上下文，不泄露名字；pyright 默认更宽松，可用"python.analysis.typeCheckingMode": "basic"收紧 - 别在
TYPE_CHECKING里定义别名并期望运行时可用——它只是给类型检查器看的临时符号 - 跨文件使用时，确保所有涉及循环引用的模块都一致启用
TYPE_CHECKING，否则某个文件类型检查通过，另一个却报错
真正难的不是写对 if TYPE_CHECKING:，而是判断哪一行代码是“只给类型检查器看”的、哪一行是“运行时真得存在”的——这两个边界一旦模糊，调试成本会指数上升。
