Python Annotated

Python 中的 `Annotated` 主要用于`在不改变原有类型的情况下为类型提示添加额外的元数据`
让我详细解释它的主要用途：

### 1. 基本语法

```python
from typing import Annotated

# 基本格式：Annotated[类型, 元数据1, 元数据2, ...]
```

### 2. 主要用途

1. **添加文档说明**：

```python
from typing import Annotated

# 为参数添加详细说明
UserId = Annotated[int, "用户的唯一标识符"]

def get_user(user_id: UserId) -> dict:
    return {"id": user_id}
```

2. **添加单位信息**：

```python
from typing import Annotated
from dataclasses import dataclass

# 定义带单位的类型
Seconds = Annotated[float, "以秒为单位"]
Meters = Annotated[float, "以米为单位"]

@dataclass
class Movement:
    time: Seconds
    distance: Meters
    
    def speed(self) -> float:
        return self.distance / self.time
```

3. **添加验证规范**：

```python
from typing import Annotated
from dataclasses import dataclass

# 定义验证规则
Range = tuple[int, int]
ValidatedInt = Annotated[int, Range([0, 100])]

@dataclass
class Score:
    value: ValidatedInt  # 表示这个整数应该在0到100之间
```
需要注意的是：
> Annotated 本身只是提供类型提示和元数据，它不会自动执行任何验证
> 如果需要实际的验证，你需要自己实现验证逻辑或使用像 Pydantic 这样的验证框架

4. **框架集成**：

```python
from typing import Annotated
from enum import Enum

class SecurityLevel(Enum):
    PUBLIC = "public"
    PRIVATE = "private"

# 用于框架的权限控制
SecureEndpoint = Annotated[str, SecurityLevel.PRIVATE]

def api_endpoint(path: SecureEndpoint):
    # 框架可以读取注解来实现权限控制
    pass
```

5. **依赖注入**：

```
from typing import Annotated
from dataclasses import dataclass

@dataclass
class Database:
    url: str

@dataclass
class Cache:
    address: str

# 标记依赖
DbConnection = Annotated[Database, "primary"]
CacheConnection = Annotated[Cache, "redis"]

class Service:
    def __init__(
        self,
        db: DbConnection,
        cache: CacheConnection
    ):
        self.db = db
        self.cache = cache
```
> 这个例子只是展示了依赖注入的类型提示

6. **类型检查和IDE支持**

```python
from typing import Annotated, get_type_hints

# 定义带注解的类型
Age = Annotated[int, "人的年龄，必须是正整数"]

def process_age(age: Age) -> str:
    return f"年龄是 {age}"

# 获取类型提示
hints = get_type_hints(process_age, include_extras=True)
print(hints['age'])  # 输出: Annotated[int, '人的年龄，必须是正整数']

# 原始类型仍然保持不变
hints = get_type_hints(process_age, include_extras=False)
print(hints['age'])  # 输出: <class 'int'>
```

### 4. 主要优势
1. 不改变运行时行为：
- 添加元数据不会影响代码的实际执行
- 保持了类型的原始语义

2. 提供额外信息：
- 可以为类型添加任何形式的元数据
- 有助于文档生成和代码分析

3. 框架友好：
- 框架可以读取这些元数据来实现特定功能
- 支持更复杂的依赖注入和验证场景

4. 类型安全：
- 保持了类型检查的完整性
- IDE 可以正确识别原始类型

5. 可扩展性：
- 可以添加多个元数据
- 支持自定义元数据类型

### 5. 实际应用场景
1. API 框架：
- 参数验证
- 权限控制
- 依赖注入

2. 文档生成：
- 自动生成 API 文档
- 类型说明文档

3. 代码分析工具：
- 静态代码分析
- 代码质量检查

4. 测试框架：
- 测试用例生成
- 参数约束检查