Python 后端开发技术博客专栏 | 第 08 篇 上下文管理器与类型系统 -- 资源管理与代码健壮性

难度等级： 中级-高级
适合读者： 有 Python 基础的开发者，准备面试的中高级工程师
前置知识： 第 02 篇《函数式编程与 Python 魔法》、第 05 篇《Python 数据模型与标准库精选》

---

导读

后端开发中有两类问题反复出现：资源泄漏 和类型错误。

数据库连接忘记关闭、文件句柄没有释放、锁没有解除 -- 这些资源泄漏问题在小规模测试中可能不会暴露，但在高并发生产环境中就是定时炸弹。Python 的上下文管理器（Context Manager）通过 with 语句提供了优雅且可靠的资源管理方案，确保资源在任何情况下（包括异常）都能被正确释放。

另一方面，Python 作为动态类型语言，类型错误往往在运行时才暴露。user["name"] 拿到的到底是 str 还是 None？process(data) 的 data 参数到底该传什么类型？Python 3.5 引入的类型标注（Type Hints）配合 mypy 等静态检查工具，让你在编写阶段就能发现这些问题。

本文将系统讲解上下文管理器的协议机制与实战模式，以及 Python 类型系统从基础到高级的完整体系。

---

学习目标

读完本文后，你将能够：

1. 完整理解 with 语句的执行流程，包括 __enter__、__exit__ 的调用时机和异常处理语义
2. 熟练使用 contextlib 模块中的 @contextmanager、suppress、ExitStack 等工具
3. 实现生产级的自定义上下文管理器：数据库连接池、计时器、临时环境、分布式锁
4. 掌握 Python 类型标注体系：基础类型、泛型、Protocol、TypeGuard、ParamSpec
5. 理解 mypy 的配置与渐进式类型标注策略
6. 在面试中准确回答上下文管理器和类型系统相关的高频问题

---

一、上下文管理器协议

1.1 with 语句的执行流程

当你写 with expr as var: 时，Python 的执行流程如下：

# with 语句的等价伪代码
manager = expr                    # 求值表达式，得到上下文管理器对象
value = manager.__enter__()       # 调用 __enter__，返回值绑定到 as 后的变量
exc = True
try:
    # with 块的代码体
    TARGET = value                # 如果有 as 子句
    BODY
except:
    exc = False
    # __exit__ 返回 True 表示"吞掉异常"，False/None 表示"继续传播"
    if not manager.__exit__(*sys.exc_info()):
        raise
finally:
    if exc:
        manager.__exit__(None, None, None)

关键点：

• __enter__ 的返回值绑定到 as 变量，不是管理器对象本身
• __exit__ 总是被调用，无论是否发生异常
• __exit__ 返回 True 可以"吞掉"异常，但这很少使用

1.2 __enter__ 和 __exit__ 的完整语义

from typing import Optional, Type
from types import TracebackType


class ManagedResource:
    """演示上下文管理器协议的完整语义"""

    def __init__(self, name: str):
        self.name = name
        self.is_open = False

    def __enter__(self) -> "ManagedResource":
        """
        进入上下文时调用。
        返回值绑定到 as 变量（通常返回 self，但不是必须的）。
        """
        print(f"  [{self.name}] __enter__: Acquiring resource")
        self.is_open = True
        return self

    def __exit__(
        self,
        exc_type: Optional[Type[BaseException]],
        exc_val: Optional[BaseException],
        exc_tb: Optional[TracebackType],
    ) -> bool:
        """
        退出上下文时调用。参数：
        - exc_type: 异常类型（无异常时为 None）
        - exc_val: 异常实例（无异常时为 None）
        - exc_tb: 回溯对象（无异常时为 None）
        返回值：True 吞掉异常，False/None 继续传播
        """
        print(f"  [{self.name}] __exit__: Releasing resource (exc={exc_type})")
        self.is_open = False
        return False  # 不吞掉异常


# 正常退出
print("--- 正常退出 ---")
with ManagedResource("conn") as res:
    print(f"  Using resource: {res.name}, is_open={res.is_open}")
print(f"  After with: is_open={res.is_open}")
# __enter__: Acquiring resource
# Using resource: conn, is_open=True
# __exit__: Releasing resource (exc=None)
# After with: is_open=False


# 异常退出：__exit__ 仍然被调用
print("\n--- 异常退出 ---")
try:
    with ManagedResource("conn2") as res2:
        raise ValueError("Something went wrong")
except ValueError:
    print(f"  Exception caught, is_open={res2.is_open}")
# __enter__: Acquiring resource
# __exit__: Releasing resource (exc=<class 'ValueError'>)
# Exception caught, is_open=False

1.3 异常吞没：exit 返回 True

class SuppressErrors:
    """演示 __exit__ 返回 True 吞掉异常"""

    def __init__(self, *exceptions):
        self._exceptions = exceptions

    def __enter__(self):
        return self

    def __exit__(self, exc_type, exc_val, exc_tb):
        if exc_type is not None and issubclass(exc_type, self._exceptions):
            print(f"  Suppressed: {exc_type.__name__}: {exc_val}")
            return True  # 吞掉异常！
        return False


# ValueError 被吞掉
with SuppressErrors(ValueError, TypeError):
    int("not_a_number")
print("  Execution continues normally!")
# Suppressed: ValueError: invalid literal for int() with base 10: 'not_a_number'
# Execution continues normally!

# KeyError 不在列表中，继续传播
try:
    with SuppressErrors(ValueError):
        d = {}
        _ = d["missing"]
except KeyError:
    print("  KeyError propagated as expected")

---

二、contextlib 工具箱

2.1 @contextmanager：用生成器实现上下文管理器

手动实现 __enter__ 和 __exit__ 对于简单场景略显繁琐。contextlib.contextmanager 允许你用一个包含 yield 的生成器函数来定义上下文管理器：

import contextlib
import time
import os
import tempfile
import shutil
from typing import Generator


@contextlib.contextmanager
def timer(label: str) -> Generator[dict, None, None]:
    """计时上下文管理器，yield 一个可以事后读取结果的字典"""
    result: dict = {"label": label, "elapsed": 0.0}
    start = time.perf_counter()
    try:
        yield result  # yield 的值绑定到 as 变量
    finally:
        result["elapsed"] = time.perf_counter() - start
        print(f"  [{label}] {result['elapsed']:.4f}s")


with timer("list comprehension") as t:
    _ = [i ** 2 for i in range(100000)]
print(f"  Elapsed: {t['elapsed']:.4f}s")


@contextlib.contextmanager
def temporary_directory(prefix: str = "tmp_") -> Generator[str, None, None]:
    """创建临时目录，退出时自动清理"""
    dirpath = tempfile.mkdtemp(prefix=prefix)
    try:
        yield dirpath
    finally:
        shutil.rmtree(dirpath, ignore_errors=True)


with temporary_directory("test_") as tmpdir:
    # 在临时目录中工作
    filepath = os.path.join(tmpdir, "data.txt")
    with open(filepath, "w") as f:
        f.write("temp data")
    print(f"  Temp dir exists: {os.path.exists(tmpdir)}")
# 退出后自动清理
print(f"  Temp dir exists after with: {os.path.exists(tmpdir)}")

@contextmanager 的工作原理：

# 简化版 @contextmanager 的实现原理
class _GeneratorContextManager:
    def __init__(self, gen):
        self.gen = gen

    def __enter__(self):
        return next(self.gen)  # 执行到 yield，返回 yield 的值

    def __exit__(self, exc_type, exc_val, exc_tb):
        if exc_type is None:
            # 正常退出：继续执行 yield 之后的代码
            try:
                next(self.gen)
            except StopIteration:
                return False
        else:
            # 异常退出：将异常注入生成器
            try:
                self.gen.throw(exc_type, exc_val, exc_tb)
            except StopIteration:
                return True  # 生成器处理了异常
            except:
                raise  # 生成器没有处理异常
        return False

2.2 suppress：静默指定异常

import contextlib
import os

# 传统写法
try:
    os.remove("nonexistent_file.txt")
except FileNotFoundError:
    pass

# 使用 suppress 更简洁
with contextlib.suppress(FileNotFoundError):
    os.remove("nonexistent_file.txt")

# 多个异常类型
with contextlib.suppress(FileNotFoundError, PermissionError):
    os.remove("nonexistent_file.txt")

# suppress 的返回值无法获取异常信息
# 如果你需要检查是否发生了异常，用 try/except

2.3 ExitStack：管理多个上下文

ExitStack 在需要动态管理多个上下文管理器时非常有用：

import contextlib
from typing import List


@contextlib.contextmanager
def open_resource(name: str):
    print(f"  Opening {name}")
    yield name
    print(f"  Closing {name}")


# 场景 1：动态数量的资源
resource_names = ["db_primary", "db_replica", "cache"]

with contextlib.ExitStack() as stack:
    resources: List[str] = []
    for name in resource_names:
        r = stack.enter_context(open_resource(name))
        resources.append(r)
    print(f"  Working with: {resources}")
# 退出时按 LIFO（后进先出）顺序关闭所有资源


# 场景 2：注册回调函数
print("\n--- ExitStack callbacks ---")
with contextlib.ExitStack() as stack:
    stack.callback(print, "  Callback 3 (first registered, last executed)")
    stack.callback(print, "  Callback 2")
    stack.callback(print, "  Callback 1 (last registered, first executed)")
    print("  Inside with block")
# LIFO 顺序执行回调


# 场景 3：条件性资源管理
@contextlib.contextmanager
def optional_lock(use_lock: bool):
    """有条件地获取锁"""
    if use_lock:
        print("  Acquiring lock")
        yield "locked"
        print("  Releasing lock")
    else:
        yield "unlocked"

with optional_lock(True) as status:
    print(f"  Status: {status}")

with optional_lock(False) as status:
    print(f"  Status: {status}")

2.4 asynccontextmanager：异步上下文管理器

import contextlib

# asynccontextmanager 用于异步上下文管理器
# 基本模式（需要在 async 函数中使用）：

"""
import aiohttp

@contextlib.asynccontextmanager
async def http_session():
    session = aiohttp.ClientSession()
    try:
        yield session
    finally:
        await session.close()

async def fetch_data():
    async with http_session() as session:
        async with session.get('https://api.example.com/data') as resp:
            return await resp.json()
"""

# 同步演示：asynccontextmanager 的模式
@contextlib.asynccontextmanager
async def async_timer(label: str):
    import time
    start = time.perf_counter()
    try:
        yield
    finally:
        elapsed = time.perf_counter() - start
        print(f"  [async {label}] {elapsed:.4f}s")

# 使用方式（需要在 async 函数中）：
# async with async_timer("fetch"):
#     await some_async_operation()

---

三、实战：自定义上下文管理器

3.1 数据库连接池的上下文管理

import contextlib
import threading
from typing import Optional
from collections import deque


class Connection:
    """模拟数据库连接"""

    _id_counter = 0

    def __init__(self, host: str, port: int):
        Connection._id_counter += 1
        self.id = Connection._id_counter
        self.host = host
        self.port = port
        self.is_closed = False
        self._in_transaction = False

    def execute(self, sql: str) -> str:
        if self.is_closed:
            raise RuntimeError("Connection is closed")
        return f"[Conn-{self.id}] Executed: {sql}"

    def begin(self) -> None:
        self._in_transaction = True

    def commit(self) -> None:
        self._in_transaction = False

    def rollback(self) -> None:
        self._in_transaction = False

    def close(self) -> None:
        self.is_closed = True

    def __repr__(self) -> str:
        status = "closed" if self.is_closed else "open"
        return f"Connection(id={self.id}, {self.host}:{self.port}, {status})"


class ConnectionPool:
    """数据库连接池，支持上下文管理器"""

    def __init__(self, host: str, port: int, max_size: int = 5):
        self._host = host
        self._port = port
        self._max_size = max_size
        self._pool: deque = deque()
        self._size = 0
        self._lock = threading.Lock()

    def _create_connection(self) -> Connection:
        self._size += 1
        return Connection(self._host, self._port)

    def acquire(self) -> Connection:
        with self._lock:
            if self._pool:
                return self._pool.popleft()
            if self._size < self._max_size:
                return self._create_connection()
            raise RuntimeError("Connection pool exhausted")

    def release(self, conn: Connection) -> None:
        with self._lock:
            if not conn.is_closed:
                self._pool.append(conn)
            else:
                self._size -= 1

    @contextlib.contextmanager
    def connection(self):
        """获取连接的上下文管理器"""
        conn = self.acquire()
        try:
            yield conn
        finally:
            self.release(conn)

    @contextlib.contextmanager
    def transaction(self):
        """事务上下文管理器：自动 commit/rollback"""
        conn = self.acquire()
        conn.begin()
        try:
            yield conn
            conn.commit()
        except Exception:
            conn.rollback()
            raise
        finally:
            self.release(conn)


# 使用
pool = ConnectionPool("localhost", 5432, max_size=3)

# 简单连接
with pool.connection() as conn:
    result = conn.execute("SELECT * FROM users")
    print(result)

# 事务
with pool.transaction() as conn:
    conn.execute("INSERT INTO users VALUES (1, 'Alice')")
    conn.execute("INSERT INTO users VALUES (2, 'Bob')")
    # 正常退出 -> 自动 commit
    print(conn.execute("COMMIT will happen"))

# 事务回滚
try:
    with pool.transaction() as conn:
        conn.execute("INSERT INTO users VALUES (3, 'Charlie')")
        raise ValueError("Business logic error")
except ValueError:
    print("  Transaction rolled back due to error")

# 连接复用
with pool.connection() as c1:
    id1 = c1.id
with pool.connection() as c2:
    id2 = c2.id
print(f"  Connection reused: {id1 == id2}")  # True（同一个连接被复用）

3.2 计时器与性能分析上下文管理器

import contextlib
import time
from typing import Optional


class Timer:
    """支持嵌套的计时器上下文管理器"""

    _stack: list = []

    def __init__(self, name: str = ""):
        self.name = name
        self.elapsed: float = 0.0
        self._start: float = 0.0

    def __enter__(self) -> "Timer":
        self._start = time.perf_counter()
        Timer._stack.append(self)
        return self

    def __exit__(self, *args) -> None:
        self.elapsed = time.perf_counter() - self._start
        Timer._stack.pop()
        indent = "  " * (len(Timer._stack) + 1)
        print(f"{indent}[{self.name}] {self.elapsed:.4f}s")

    @staticmethod
    def current() -> Optional["Timer"]:
        return Timer._stack[-1] if Timer._stack else None


# 嵌套计时
with Timer("total"):
    with Timer("phase_1"):
        _ = [i ** 2 for i in range(50000)]
    with Timer("phase_2"):
        _ = sum(range(100000))
# 输出：
#   [phase_1] 0.XXXXs
#   [phase_2] 0.XXXXs
# [total] 0.XXXXs

3.3 临时环境变量上下文管理器

import contextlib
import os
from typing import Dict, Optional


@contextlib.contextmanager
def temp_env(**env_vars: Optional[str]):
    """临时设置环境变量，退出时恢复"""
    old_values: Dict[str, Optional[str]] = {}
    try:
        for key, value in env_vars.items():
            old_values[key] = os.environ.get(key)
            if value is None:
                os.environ.pop(key, None)
            else:
                os.environ[key] = value
        yield
    finally:
        for key, old_value in old_values.items():
            if old_value is None:
                os.environ.pop(key, None)
            else:
                os.environ[key] = old_value


# 使用
os.environ["APP_MODE"] = "production"
print(f"  Before: APP_MODE={os.environ.get('APP_MODE')}")

with temp_env(APP_MODE="testing", DEBUG="1"):
    print(f"  Inside: APP_MODE={os.environ.get('APP_MODE')}")
    print(f"  Inside: DEBUG={os.environ.get('DEBUG')}")

print(f"  After: APP_MODE={os.environ.get('APP_MODE')}")
print(f"  After: DEBUG={os.environ.get('DEBUG')}")
# Before: APP_MODE=production
# Inside: APP_MODE=testing
# Inside: DEBUG=1
# After: APP_MODE=production
# After: DEBUG=None

3.4 重试上下文管理器

import contextlib
import time
import random
from typing import Tuple, Type


@contextlib.contextmanager
def retry(
    max_attempts: int = 3,
    exceptions: Tuple[Type[Exception], ...] = (Exception,),
    delay: float = 0.0,
    backoff: float = 1.0,
):
    """重试上下文管理器"""
    attempt = 0
    current_delay = delay
    while True:
        attempt += 1
        try:
            yield attempt
            break  # 成功则退出
        except exceptions as e:
            if attempt >= max_attempts:
                raise  # 超过最大次数，抛出异常
            print(f"  Attempt {attempt} failed: {e}. Retrying in {current_delay:.1f}s...")
            time.sleep(current_delay)
            current_delay *= backoff


# 注意：retry 上下文管理器实际上不能直接这样实现，
# 因为 with 语句只会执行一次 __enter__。
# 正确的重试模式需要用循环包裹。下面是可行的实现：

class RetryContext:
    """可重试的上下文管理器"""

    def __init__(
        self,
        max_attempts: int = 3,
        exceptions: Tuple[Type[Exception], ...] = (Exception,),
        delay: float = 0.1,
    ):
        self.max_attempts = max_attempts
        self.exceptions = exceptions
        self.delay = delay
        self.attempts = 0
        self.succeeded = False

    def __iter__(self):
        """通过迭代器协议实现重试循环"""
        for attempt in range(1, self.max_attempts + 1):
            self.attempts = attempt
            yield attempt

    @contextlib.contextmanager
    def attempt(self):
        """每次尝试的上下文管理器"""
        try:
            yield self.attempts
            self.succeeded = True
        except self.exceptions as e:
            if self.attempts >= self.max_attempts:
                raise
            print(f"  Attempt {self.attempts} failed: {e}")
            time.sleep(self.delay)


# 使用模式
retrier = RetryContext(max_attempts=3, exceptions=(ValueError,), delay=0.01)
for attempt in retrier:
    with retrier.attempt():
        if attempt < 3:
            raise ValueError(f"Simulated failure on attempt {attempt}")
        print(f"  Succeeded on attempt {attempt}")
    if retrier.succeeded:
        break

---

四、Python 类型系统（Type Hints）

4.1 基础类型标注

Python 3.5 引入了类型标注，3.9+ 支持内置类型的泛型语法（list[int] 代替 List[int]）：

from typing import Any, Dict, List, Optional, Tuple, Union, Set


# ========== 基础类型 ==========
name: str = "Alice"
age: int = 30
score: float = 95.5
is_active: bool = True


# ========== 容器类型 ==========
# Python 3.9+ 可以直接用内置类型
# Python 3.8 需要从 typing 导入大写版本
names: List[str] = ["Alice", "Bob"]
scores: Dict[str, float] = {"Alice": 95.5, "Bob": 87.3}
coordinates: Tuple[float, float] = (1.0, 2.0)
tags: Set[str] = {"python", "backend"}

# 嵌套容器
user_groups: Dict[str, List[str]] = {
    "admin": ["Alice", "Bob"],
    "user": ["Charlie", "David"],
}


# ========== Optional 和 Union ==========
def find_user(user_id: int) -> Optional[Dict[str, Any]]:
    """返回用户字典或 None。Optional[X] 等价于 Union[X, None]"""
    users = {1: {"name": "Alice", "age": 30}}
    return users.get(user_id)

def process_input(value: Union[str, int, float]) -> str:
    """接受多种类型"""
    return str(value)


# ========== 函数签名 ==========
def create_user(
    name: str,
    email: str,
    age: int = 0,
    *,
    is_admin: bool = False,
) -> Dict[str, Any]:
    """完整的函数类型标注"""
    return {
        "name": name,
        "email": email,
        "age": age,
        "is_admin": is_admin,
    }


# 验证
user = create_user("Alice", "alice@example.com", 30, is_admin=True)
print(user)  # {'name': 'Alice', 'email': 'alice@example.com', 'age': 30, 'is_admin': True}
result = find_user(1)
print(result)  # {'name': 'Alice', 'age': 30}

4.2 泛型（Generic）

泛型允许你创建参数化的类型，让同一段代码安全地处理不同类型的数据：

from typing import TypeVar, Generic, Optional, List, Iterator

T = TypeVar("T")
K = TypeVar("K")
V = TypeVar("V")


class Stack(Generic[T]):
    """类型安全的泛型栈"""

    def __init__(self) -> None:
        self._items: List[T] = []

    def push(self, item: T) -> None:
        self._items.append(item)

    def pop(self) -> T:
        if not self._items:
            raise IndexError("Stack is empty")
        return self._items.pop()

    def peek(self) -> T:
        if not self._items:
            raise IndexError("Stack is empty")
        return self._items[-1]

    def __len__(self) -> int:
        return len(self._items)

    def __iter__(self) -> Iterator[T]:
        return iter(reversed(self._items))


# 使用时指定类型参数
int_stack: Stack[int] = Stack()
int_stack.push(1)
int_stack.push(2)
print(int_stack.pop())  # 2

str_stack: Stack[str] = Stack()
str_stack.push("hello")
str_stack.push("world")
print(str_stack.peek())  # world


class LRUCache(Generic[K, V]):
    """多类型参数的泛型类"""

    def __init__(self, capacity: int) -> None:
        self._capacity = capacity
        self._cache: dict = {}
        self._order: list = []

    def get(self, key: K) -> Optional[V]:
        if key in self._cache:
            self._order.remove(key)
            self._order.append(key)
            return self._cache[key]
        return None

    def put(self, key: K, value: V) -> None:
        if key in self._cache:
            self._order.remove(key)
        elif len(self._cache) >= self._capacity:
            oldest = self._order.pop(0)
            del self._cache[oldest]
        self._cache[key] = value
        self._order.append(key)

    def __len__(self) -> int:
        return len(self._cache)


cache: LRUCache[str, int] = LRUCache(capacity=2)
cache.put("a", 1)
cache.put("b", 2)
cache.put("c", 3)  # "a" 被淘汰
print(cache.get("a"))  # None
print(cache.get("b"))  # 2
print(cache.get("c"))  # 3


# ========== 受约束的 TypeVar ==========
from typing import TypeVar

# T 只能是 int 或 float
Number = TypeVar("Number", int, float)

def add(a: Number, b: Number) -> Number:
    return a + b

print(add(1, 2))      # 3
print(add(1.5, 2.5))  # 4.0


# T 必须是 str 的子类型
StrLike = TypeVar("StrLike", bound=str)

def to_upper(s: StrLike) -> StrLike:
    return s.upper()  # type: ignore[return-value]

print(to_upper("hello"))  # HELLO

4.3 Literal 与 TypeAlias

from typing import Literal

# Literal：限制值的范围
LogLevel = Literal["DEBUG", "INFO", "WARNING", "ERROR", "CRITICAL"]

def set_log_level(level: LogLevel) -> None:
    print(f"Log level: {level}")

set_log_level("INFO")    # OK
# set_log_level("VERBOSE")  # mypy 报错


# TypeAlias（Python 3.10+ 正式语法，3.8 用注释或赋值）
# Python 3.10+: type UserId = int
# Python 3.8:
from typing import Dict, List, Any

UserId = int
UserRecord = Dict[str, Any]
UserList = List[UserRecord]

def get_users() -> UserList:
    return [
        {"id": 1, "name": "Alice"},
        {"id": 2, "name": "Bob"},
    ]

users: UserList = get_users()
print(f"Users: {len(users)}")  # Users: 2

4.4 Protocol：结构化子类型

Protocol（Python 3.8+）让你无需继承就能定义接口约束，这在第 07 篇中已有介绍。这里展示它在类型系统中的高级用法：

from typing import Protocol, runtime_checkable, TypeVar, List


@runtime_checkable
class Comparable(Protocol):
    """任何支持比较的对象"""
    def __lt__(self, other: Any) -> bool: ...
    def __eq__(self, other: object) -> bool: ...


CT = TypeVar("CT", bound=Comparable)

def find_min(items: List[CT]) -> CT:
    """泛型 + Protocol：类型安全的通用最小值查找"""
    if not items:
        raise ValueError("Empty list")
    result = items[0]
    for item in items[1:]:
        if item < result:
            result = item
    return result


# int 和 str 都满足 Comparable 协议
print(find_min([3, 1, 4, 1, 5]))      # 1
print(find_min(["cherry", "apple", "banana"]))  # apple


@runtime_checkable
class HasLength(Protocol):
    def __len__(self) -> int: ...


def print_length(obj: HasLength) -> None:
    print(f"Length: {len(obj)}")

print_length([1, 2, 3])      # Length: 3
print_length("hello")        # Length: 5
print_length({"a": 1})       # Length: 1

4.5 TypeGuard：类型收窄

TypeGuard（Python 3.10+，3.8 可从 typing_extensions 导入）让你在自定义类型判断函数中告诉类型检查器"如果这个函数返回 True，参数就是某个更具体的类型"：

from typing import Any, List, Union

# Python 3.10+ 可以直接从 typing 导入 TypeGuard
# 这里演示概念，不依赖 typing_extensions

def is_str_list(val: List[Any]) -> bool:
    """检查列表是否全部是字符串"""
    return all(isinstance(x, str) for x in val)

# 使用场景
def process_items(items: List[Union[str, int]]) -> str:
    str_items = [x for x in items if isinstance(x, str)]
    int_items = [x for x in items if isinstance(x, int)]
    return f"strings={len(str_items)}, ints={len(int_items)}"

result = process_items(["hello", 1, "world", 2])
print(result)  # strings=2, ints=2

# TypeGuard 的真正价值在静态分析阶段：
"""
from typing import TypeGuard

def is_str_list(val: list[Any]) -> TypeGuard[list[str]]:
    return all(isinstance(x, str) for x in val)

def process(data: list[Any]) -> None:
    if is_str_list(data):
        # mypy 现在知道 data 是 list[str]
        print(data[0].upper())  # 不会报错
    else:
        print("Not a string list")
"""

4.6 ParamSpec 与 Concatenate：装饰器类型标注

ParamSpec（Python 3.10+）解决了装饰器类型标注中最棘手的问题 -- 如何保留被装饰函数的参数类型：

from typing import TypeVar, Callable, Any
import functools
import time

# Python 3.10+ 可以从 typing 导入 ParamSpec
# 这里使用传统方式演示装饰器类型标注

RT = TypeVar("RT")

def timing_decorator(func: Callable[..., RT]) -> Callable[..., RT]:
    """计时装饰器（简化版类型标注）"""
    @functools.wraps(func)
    def wrapper(*args: Any, **kwargs: Any) -> RT:
        start = time.perf_counter()
        result = func(*args, **kwargs)
        elapsed = time.perf_counter() - start
        print(f"  {func.__name__}: {elapsed:.4f}s")
        return result
    return wrapper


@timing_decorator
def compute(n: int) -> int:
    return sum(range(n))


result = compute(100000)
print(f"  Result: {result}")


# ParamSpec 的完整类型标注（Python 3.10+）：
"""
from typing import ParamSpec, TypeVar, Callable
import functools

P = ParamSpec("P")
R = TypeVar("R")

def timing(func: Callable[P, R]) -> Callable[P, R]:
    @functools.wraps(func)
    def wrapper(*args: P.args, **kwargs: P.kwargs) -> R:
        start = time.perf_counter()
        result = func(*args, **kwargs)
        elapsed = time.perf_counter() - start
        print(f"{func.__name__}: {elapsed:.4f}s")
        return result
    return wrapper
"""

---

五、mypy 与静态类型检查

5.1 mypy 配置与使用

mypy 是 Python 最流行的静态类型检查器。它在不运行代码的情况下分析类型标注，找出类型不匹配的错误：

# ========== mypy 基本配置（mypy.ini 或 pyproject.toml） ==========
"""
# mypy.ini
[mypy]
python_version = 3.8
warn_return_any = True
warn_unused_configs = True
disallow_untyped_defs = True
check_untyped_defs = True
no_implicit_optional = True
strict_equality = True

# 对第三方库的配置
[mypy-requests.*]
ignore_missing_imports = True

[mypy-sqlalchemy.*]
ignore_missing_imports = True
"""

# ========== pyproject.toml 格式 ==========
"""
[tool.mypy]
python_version = "3.8"
warn_return_any = true
warn_unused_configs = true
disallow_untyped_defs = true
check_untyped_defs = true
no_implicit_optional = true
strict_equality = true

[[tool.mypy.overrides]]
module = "requests.*"
ignore_missing_imports = true
"""

5.2 渐进式类型标注策略

大型项目不可能一次性添加所有类型标注。推荐的渐进式策略：

# ========== 阶段 1：基本标注 ==========
# 只标注函数签名，不标注局部变量

def calculate_price(base: float, tax_rate: float, discount: float = 0) -> float:
    subtotal = base * (1 + tax_rate)  # 局部变量自动推导
    return subtotal * (1 - discount)


# ========== 阶段 2：严格模式 ==========
# 添加所有类型标注，处理 None 安全

from typing import Optional, Dict, Any, List

def process_response(response: Dict[str, Any]) -> Optional[str]:
    data = response.get("data")
    if data is None:
        return None
    if not isinstance(data, str):
        return None
    return data.strip()


# ========== 阶段 3：高级类型 ==========
# 使用泛型、Protocol、TypeGuard 等

from typing import TypeVar, Generic, Protocol, runtime_checkable

T_co = TypeVar("T_co", covariant=True)

class ReadableStream(Protocol[T_co]):
    def read(self, size: int = -1) -> T_co: ...

def read_all(stream: ReadableStream[str]) -> str:
    return stream.read()

5.3 常见类型错误与修复

from typing import Optional, Dict, List, Any, Union


# ========== 错误 1：Optional 未处理 None ==========
def get_name_bad(user: Optional[Dict[str, str]]) -> str:
    # mypy error: Item "None" of "Optional[Dict[str, str]]" has no attribute "get"
    # return user.get("name", "unknown")
    pass

def get_name_good(user: Optional[Dict[str, str]]) -> str:
    if user is None:
        return "unknown"
    return user.get("name", "unknown")

print(get_name_good(None))             # unknown
print(get_name_good({"name": "Alice"})) # Alice


# ========== 错误 2：Union 类型没有收窄 ==========
def process_value_bad(value: Union[str, int]) -> str:
    # mypy error: "int" has no attribute "upper"
    # return value.upper()
    pass

def process_value_good(value: Union[str, int]) -> str:
    if isinstance(value, str):
        return value.upper()  # mypy 知道这里 value 是 str
    return str(value)         # mypy 知道这里 value 是 int

print(process_value_good("hello"))  # HELLO
print(process_value_good(42))       # 42


# ========== 错误 3：可变默认参数的类型 ==========
def add_tag_bad(item: Dict[str, Any], tags: List[str] = []) -> Dict[str, Any]:
    # 经典陷阱：可变默认参数
    tags.append("new")
    item["tags"] = tags
    return item

def add_tag_good(
    item: Dict[str, Any],
    tags: Optional[List[str]] = None,
) -> Dict[str, Any]:
    if tags is None:
        tags = []
    tags.append("new")
    item["tags"] = tags
    return item

print(add_tag_good({"name": "test"}))  # {'name': 'test', 'tags': ['new']}


# ========== 错误 4：忽略返回值类型 ==========
def find_item(items: List[str], target: str) -> Optional[int]:
    """返回索引或 None"""
    try:
        return items.index(target)
    except ValueError:
        return None

# 正确处理返回值
index = find_item(["a", "b", "c"], "b")
if index is not None:
    print(f"Found at index {index}")  # Found at index 1
else:
    print("Not found")

5.4 面试高频题：类型系统

Q1：Python 的类型标注是强制的吗？有什么实际价值？

A：Python 的类型标注不是强制的，运行时不做类型检查（除非使用 Pydantic 等工具）。它的价值在于：

1. 静态分析：mypy 等工具可以在编写阶段发现类型错误，减少线上 bug
2. 代码文档：类型标注就是最好的文档，比注释更准确（因为可以被工具验证）
3. IDE 支持：类型标注让 IDE 提供更精确的自动补全、跳转和重构
4. 团队协作：大型项目中，类型标注让接口契约更明确

推荐的策略是渐进式标注：先标注公共 API 和关键函数，逐步扩展到整个代码库。

Q2：Protocol 和 ABC 的区别是什么？

A：ABC（Abstract Base Class）是名义子类型 ，要求显式继承。Protocol 是结构化子类型，只要对象的结构匹配就被视为该类型。

• 用 ABC：框架内部接口定义，需要强制实现检查和默认方法
• 用 Protocol：跨库兼容，不想强制继承，更符合鸭子类型风格

Protocol 加上 @runtime_checkable 后支持 isinstance 检查，但只检查方法/属性的存在性，不检查签名和返回类型。

---

六、面试高频题汇总

Q1：上下文管理器的典型应用场景有哪些？

A：上下文管理器的核心价值是确保资源在任何情况下（包括异常）都能被正确释放。典型场景：

1. 文件操作 ：with open(...) as f: 确保文件被关闭
2. 数据库连接：获取连接 -> 使用 -> 归还连接池
3. 事务管理：正常 commit，异常 rollback
4. 锁管理 ：with lock: 确保锁被释放
5. 临时状态：临时修改环境变量/工作目录/配置，退出后恢复
6. 计时/性能分析：进入时记录时间，退出时计算耗时
7. 测试 mock ：with mock.patch(...): 临时替换对象

Q2：@contextmanager 装饰器的实现原理？

A：@contextmanager 将一个包含单个 yield 的生成器函数转换为上下文管理器。原理是：

• __enter__ 时调用 next(gen)，执行到 yield 暂停，yield 的值作为 as 变量
• __exit__ 时：
  • 如果没有异常，继续调用 next(gen) 执行 yield 之后的代码
  • 如果有异常，调用 gen.throw(exc_type, exc_val, exc_tb) 将异常注入生成器
• 生成器中的 try/finally 块确保清理代码一定执行

关键点：生成器函数中只能有一个 yield，yield 之前是 __enter__ 的逻辑，yield 之后是 __exit__ 的逻辑。

Q3：__exit__ 的三个参数是什么？返回 True 有什么效果？

A：__exit__(self, exc_type, exc_val, exc_tb) 的三个参数分别是：

• exc_type：异常类型（None 表示没有异常）
• exc_val：异常实例
• exc_tb：回溯对象（traceback）

如果 __exit__ 返回 True（truthy value），异常会被吞掉 （suppressed），不会继续传播。contextlib.suppress 就是利用这个机制工作的。通常不建议吞掉异常，除非你明确知道如何处理。

Q4：Python 的类型标注在运行时有什么开销？

A：类型标注在运行时的开销非常小 。在 Python 3.7+ 中，如果使用 from __future__ import annotations，所有标注会被延迟求值（变为字符串），不会在模块导入时创建类型对象。即使不用 __future__，标注信息也只是存储在函数/类的 __annotations__ 字典中，不影响实际执行。唯一需要注意的是，某些框架（如 Pydantic）会在运行时读取和解析类型标注做数据校验，这会带来额外开销。

---

本章总结

本文系统性地讲解了 Python 的资源管理与类型系统两大主题：

1. 上下文管理器协议 ：with 语句通过 __enter__ 和 __exit__ 方法实现资源的自动管理。__exit__ 无论是否发生异常都会被调用，返回 True 可以吞掉异常。这是 Python 中"RAII"模式的核心实现。

2. contextlib 工具箱 ：@contextmanager 让你用生成器函数快速实现上下文管理器，suppress 简洁地忽略指定异常，ExitStack 动态管理多个上下文。asynccontextmanager 为异步代码提供了相同的便利。

3. 实战上下文管理器 ：数据库连接池（connection() + transaction()）、嵌套计时器（Timer）、临时环境变量（temp_env）、重试机制（RetryContext）-- 这些模式在后端开发中反复出现。

4. Python 类型系统 ：从基础的 str/int/Optional 到高级的 Generic/Protocol/TypeGuard/ParamSpec，Python 的类型标注体系已经非常完善。类型标注不是运行时约束，但配合 mypy 可以大幅提升代码质量和可维护性。

5. mypy 实践 ：推荐渐进式类型标注策略：先标注公共 API，逐步扩展。常见类型错误包括未处理 Optional 的 None、未收窄 Union 类型、可变默认参数等。

核心原则：上下文管理器让资源管理从"记住释放"变成"不可能忘记释放"；类型标注让接口契约从"文档里写的"变成"工具可以验证的"。两者都是提升代码健壮性的重要工具。

---

下一篇预告

第 09 篇：GIL 深度解析与并发编程实战 -- 多线程、多进程、协程的选型

下一篇文章将进入异步编程与高性能 Python 模块。你将了解：

• GIL 的本质与影响：GIL 的历史背景、获取与释放机制、对 CPU 密集型 vs I/O 密集型任务的不同影响
• 多线程编程：线程同步原语（Lock、RLock、Semaphore、Event）、死锁的产生与避免
• 多进程编程：进程间通信、共享内存、进程池的使用模式
• concurrent.futures ：ThreadPoolExecutor 和 ProcessPoolExecutor 的统一接口
• 选型指南：什么时候用多线程、多进程、协程？如何根据任务特征做出正确选择

GIL 是 Python 面试中最高频的考点之一。理解它的工作原理，你就能解释"Python 的多线程是不是假的"这个经典问题。

---

Python 后端开发技术博客专栏 | 作者：耿雨飞

本文为专栏第 08 篇，共 25 篇。完整目录请参阅《Python技术博客专栏大纲》。