Python 类的类型标注有哪些最佳实践方案？

对于Python类的类型标注，我通常遵循这几个核心原则：

1. 类属性标注 直接在类体中标注，使用ClassVar区分实例属性和类属性：

from typing import ClassVar, Optional

class User:
    # 类属性
    default_role: ClassVar[str] = "guest"
    user_count: ClassVar[int] = 0
    
    # 实例属性
    def __init__(self, name: str, age: int):
        self.name: str = name
        self.age: int = age
        self.email: Optional[str] = None

2. 方法返回类型 特别是__init__返回None，其他方法明确标注返回类型：

class Calculator:
    def __init__(self) -> None:
        self.value: float = 0.0
    
    def add(self, x: float) -> "Calculator":
        self.value += x
        return self
    
    @classmethod
    def create(cls) -> "Calculator":
        return cls()

3. 处理前向引用 类内部相互引用时用字符串，或者from __future__ import annotations：

from __future__ import annotations

class Node:
    def __init__(self, value: int):
        self.value = value
        self.next: Node | None = None  # 直接使用Node，不需要字符串

4. 泛型类 使用TypeVar和Generic定义泛型类：

from typing import TypeVar, Generic

T = TypeVar('T')

class Container(Generic[T]):
    def __init__(self, item: T):
        self.item: T = item
    
    def get(self) -> T:
        return self.item

5. 特殊方法标注 @property和@staticmethod也需要标注：

class Rectangle:
    def __init__(self, width: float, height: float):
        self._width = width
        self._height = height
    
    @property
    def area(self) -> float:
        return self._width * self._height
    
    @staticmethod
    def is_square(width: float, height: float) -> bool:
        return width == height

6. 使用@dataclass简化 Python 3.7+推荐用@dataclass自动生成__init__：

from dataclasses import dataclass
from typing import Optional

@dataclass
class Product:
    id: int
    name: str
    price: float
    description: Optional[str] = None

关键点总结：

• 类属性用ClassVar，实例属性在__init__中标注
• 所有方法都标注返回类型，__init__返回None
• 用字符串或from __future__ import annotations处理循环引用
• 泛型类用TypeVar和Generic
• 特殊方法如@property也要标注
• 考虑用@dataclass减少样板代码

一句话建议： 保持类型标注一致且完整，优先用@dataclass简化代码。