你在看 xxx.py 时会看到很多“看起来像注解”的东西：@property、@dataclass(frozen=True)、@overload，以及函数/变量后面跟着的 : int、-> Decimal。
如果你来自 Java，很容易把它们统称为“注解”，然后问：底层原理是什么？和 Java 注解一样吗？

这篇文章把概念一次分清：Python 里至少有两类完全不同的东西，长得像，但机制和用途不一样。

1. 要解决什么问题

你想搞清楚三件事：

• @property / @dataclass / @overload 这些 @xxx 到底做了什么？什么时候执行？
• x: int、def f(x: int) -> str 这种类型“注解”会影响运行吗？
• 它们和 Java 的 @Override、@Transactional 这种注解是同一种东西吗？

2. 核心思路是什么

把“Python 的注解”拆成两类，你就不迷糊了：

1. 装饰器（decorator）：以 @xxx 形式出现，本质是“可执行的函数调用”，在定义时运行，直接改变函数/类对象。
2. 类型注解（type annotations）：以 : T、-> T 形式出现，本质是“元数据”，默认不改变运行时行为，主要给工具（mypy/IDE/ruff）使用。

Java 的注解更接近“元数据”，但 Java 生态里常见的“注解驱动功能”通常来自框架在运行时/编译期扫描并处理这些元数据；而 Python 的装饰器是“直接执行代码”。

3. 关键机制怎么工作

3.1 装饰器：定义时执行的“对象变换器”

例如：给函数自动加日志（不改业务代码，只改“定义方式”）：

def log_call(func: Callable[..., T]) -> Callable[..., T]:
    @wraps(func)
    def wrapper(*args: object, **kwargs: object) -> T:
        print(f"[log] calling {func.__name__} args={args} kwargs={kwargs}")
        result = func(*args, **kwargs)
        print(f"[log] done {func.__name__} result={result!r}")
        return result
    return wrapper


@log_call
def total(price: float, quantity: int) -> float:
    return price * quantity


total(10.5, 2)

上面的 @log_call 在导入模块时就会执行，等价于：

def total(price: float, quantity: int) -> float:
    return price * quantity

total = log_call(total)

将total作为参数传递到这个注解@log_call中，包裹total这个方法

这句话非常关键：装饰器在函数定义完成后立即执行（模块导入时/类体执行时），并把 f 替换成装饰器返回的对象。

这就是为什么它和 Java 注解不一样：Java 注解本身不会“执行”，它只是写进 class 元数据；Python 装饰器是“真函数调用”。

3.2 @property：用描述符协议把方法变成属性访问

一句话结论：@property 会把“方法”变成“描述符对象”，从而支持 obj.attr 这种属性语法。

你写：

class Order:
    @property
    def amount(self):
        return self.price * self.quantity

解释器背后做了 3 步：

1. 先定义普通函数 amount(self)。
2. 执行 property(amount)，得到一个 property 对象。
3. 把这个对象绑定到类属性 Order.amount 上。

所以它大致等价于：

def amount(self):
    return self.price * self.quantity

Order.amount = property(amount)

关键区别（这点最容易混）：

• 访问 Order.amount（类访问）：拿到的是 property 对象本身。
• 访问 order.amount（实例访问）：触发描述符 __get__，最终执行 amount(order)，返回计算结果。

所以你“看起来在读属性”，其实在执行函数逻辑。

你可以用这个最小示意理解它的底层形状：

class property:
    def __init__(self, fget):
        self.fget = fget
    def __get__(self, obj, objtype=None):
        # obj 是实例（如 order）；类访问时 obj 可能是 None
        return self.fget(obj)

一个可运行验证（看清“类上是 property，实例上是值”）：

class Order:
    def __init__(self, price, quantity):
        self.price = price
        self.quantity = quantity

    @property
    def amount(self):
        return self.price * self.quantity

print(type(Order.amount))         # <class 'property'>
o = Order(10.5, 2)
print(o.amount)                   # 21.0

真实实现还支持 setter/deleter/doc，但底层核心就是 描述符协议（descriptor protocol）。

3.3 @dataclass(frozen=True)：类装饰器在定义后“批量生成方法”

@dataclass 是“装饰器作用于类”的例子：它拿到 class Order: ... 这个类对象，然后根据字段生成/注入方法，如 __init__、__repr__、比较方法等。

frozen=True 的含义：

• 让实例字段不可修改（通过重写 __setattr__ 等机制实现）
• 让对象更像“值对象”（value object），更利于维护不变量

重要点：这不是“编译期魔法”，而是 类创建完成后，装饰器对类对象做了改造。

3.4 @overload：主要服务于类型检查器，运行时几乎不起作用

typing.overload 的核心用途：给类型检查器提供“同名函数的多种签名”，让它在不同入参下推导出不同返回类型。

先看写法：

from typing import overload

@overload
def get(x: int) -> int: ...

@overload
def get(x: str) -> str: ...

def get(x):
    return x

把它理解成一句话：前面两段是“类型声明”，最后一段才是“运行时代码”。

可以这样读：

• 类型检查器看到：
  • get(1) 的返回值按 int 推导
  • get("a") 的返回值按 str 推导
• Python 运行时只看到最后这个实现：
  • def get(x): return x

也就是说，@overload 不会在运行时做分发；真正的分发逻辑（如果需要）要你自己在最后的实现里写。

一个更贴地的心智模型：

• @overload 解决“编辑器和 mypy 能不能准确理解 API”
• 最后实现解决“程序实际怎么运行”

这就是为什么你看到 OrderBook.__getitem__ 里用 @overload：为了让 book[0] 推导为 Order、book[:2] 推导为 list[Order]，从而让 mypy --strict 通过。

3.5 类型注解：默认不改变运行，只写进 __annotations__

先给结论：类型注解默认是“说明书”，不是“运行时拦截器”。

当你写：

def total_amount(self) -> Decimal:
    ...

Python 默认不会在运行时强制检查“返回值一定是 Decimal”。
它会把这段类型信息记录到 __annotations__，供静态分析工具和框架读取。

一个快速验证（故意返回错类型，程序仍能跑）：

def bad_total() -> int:
    return "not int"  # 故意写错类型

print(bad_total())               # 运行时不会报类型错误
print(bad_total.__annotations__) # {'return': <class 'int'>}

这段输出能说明两件事：

• 运行时按“真实代码”执行，不会因为注解和返回值不一致而自动抛错。
• 注解信息仍然存在，并可通过反射读取（__annotations__）。

因此，类型注解更接近“元数据 + 开发期约束”：

• 开发期：mypy/IDE 用它做静态检查和自动提示。
• 运行时：只有你接入额外机制（如 pydantic、beartype、手写校验）才会变成“强约束”。

3.6 from __future__ import annotations：把注解延迟成字符串（避免前向引用问题）

先给结论：它改变的是“注解在运行时怎么保存”，不是“类型检查力度”。

你在文件顶部会看到：

from __future__ import annotations

最重要的行为变化：

• 不加它：注解通常会尽早求值，前向引用更容易触发 NameError
• 加了它：注解先按字符串保存，等你需要时再解析

一个最小对照示例：

# 没有 future（旧行为示意）
class Node:
    def __init__(self, next: Node | None = None):  # Node 这里可能尚未可用
        self.next = next

from __future__ import annotations

class Node:
    def __init__(self, next: Node | None = None):
        self.next = next

print(Node.__init__.__annotations__)
# {'next': 'Node | None'}  # 以字符串形式保存

工程收益：

• 更稳地处理前向引用（即“先引用、后定义”的类型名，尤其在互相引用的类型中）。
• 减少导入时类型依赖带来的循环引用问题。

注意边界：

• 它不会自动做运行时类型校验。
• 它不会让 mypy“更严格”，只是让注解在运行时更可控。

4. 怎么实际使用（工程建议）

你可以用一个简单决策表来选：

• 你要“改变函数/类的运行时行为”（缓存、重试、注册、把方法变成属性）

  • 用装饰器（@property、@dataclass、自定义 @retry）

• 你要“表达接口契约/让工具帮你发现误用”（参数类型、返回类型、重载签名）

  • 用类型注解（: T、-> T）+ mypy
  • 需要多个调用形态时用 @overload

5. 思考题

1. @property 让属性访问变成“执行代码”。你会如何避免它在日志/调试时造成昂贵计算或副作用？
2. @dataclass(frozen=True) 让对象不可变很好，但哪些场景下你反而需要可变对象？你会如何把“不变量”保持在边界层？
3. Python 类型注解默认不强制检查。你更偏向“靠 mypy 静态检查”还是“运行时校验”（例如 pydantic）？为什么？
4. Java 注解是元数据，Python 装饰器是可执行变换。你觉得哪一种更容易被滥用？你的团队会如何定规范？

5.1 参考解答

1. 关于 @property 的副作用与性能

• 原则：@property 应保持轻量、无副作用、无 I/O。
• 重计算逻辑不要放在 property 里，改成显式方法（如 compute_xxx()）或使用 @cached_property。
• 日志/调试时避免无脑打印整个对象，防止间接触发大量 property 计算。

2. 关于 @dataclass(frozen=True) 的适用边界

• 适合：订单、事件、配置快照这类“值对象”。
• 不适合：状态频繁变化的对象（会话状态、实时缓存、状态机）。
• 实践：核心领域对象尽量不可变，边界层/组装层允许可变，用分层保证不变量。

3. 关于 mypy 与运行时校验

• 推荐“组合拳”：
• 内部代码协作靠 mypy（开发期尽早发现接口误用）。
• 系统边界（HTTP/MQ/文件输入）加运行时校验（如 pydantic）。
• 一句话：内部偏静态，边界偏动态。

4. 关于 Java 注解 vs Python 装饰器的滥用风险

• 两者都可能被滥用：Java 常见“框架魔法过深”，Python 常见“装饰器叠太多导致调用链不透明”。
• 团队规范建议：
• 每个装饰器只做一件事（日志/重试/鉴权不要混在一个装饰器里）。
• 强制使用 functools.wraps 保留函数元信息。
• 多装饰器叠加时，文档明确执行顺序与副作用。