Python 深入浅出：inspect 模块与运行时自省魔法

在计算机科学中，“自省（Introspection）”是指程序在运行期能够获取、检查和修改自身结构与行为的能力。这是动态语言最迷人的特性之一。

虽然 Python 内置了 type()、dir()、hasattr() 等基础自省函数，但在开发高级框架（如依赖注入容器、ORM 映射器、或者动态路由解析器）时，我们需要更专业、更底层的运行时分析工具。

Python 内置的 inspect 模块就是这扇通往运行时魔法的后门。它能让我们在运行期获取函数签名、动态读取源代码、甚至直接穿透和遍历当前线程的系统调用栈（Call Stack）。

本文将带您领略 inspect 模块的运行时自省黑魔法。

一、 动态解析函数签名：inspect.signature()

在开发 Web 框架（如 FastAPI）时，框架需要根据你编写的函数参数，自动把前端传来的 JSON 字段填入参数中。这是如何做到的？

核心就在于动态解析函数签名：

import inspect

def process_order(order_id: int, coupon_code: str = None) -> bool:
    """处理用户订单"""
    return True

# 1. 获取函数签名对象
sig = inspect.signature(process_order)

print("返回值注解:", sig.return_annotation)  # 输出: <class 'bool'>

# 2. 遍历函数的每一个参数定义
for name, param in sig.parameters.items():
    print(f"参数名: {name}")
    print(f"  - 类型标注: {param.annotation}")
    print(f"  - 默认值: {param.default}")
    print(f"  - 参数类型: {param.kind}")  # 例如是位置参数还是关键字参数

借助 sig.parameters，你可以获取每个参数的名字、类型提示和默认值，从而在运行时动态进行数据校验和填充。

二、 动态获取运行期源代码：inspect.getsource()

你是否遇到过这种场景：在调试时，你想看看当前正在运行的某第三方库函数到底是怎么写的，却懒得去翻磁盘上的 Python 文件。

inspect 允许我们在内存中直接把函数、类甚至是整个模块的源代码给提取出来：

import inspect
import json

# 直接获取标准库 json.dumps 函数的底层 Python 源码！
source_code = inspect.getsource(json.dumps)
print(source_code[:300])  # 打印前 300 个字符

注意：这只对纯 Python 编写的函数有效，如果函数是用 C 语言编写的扩展（内置 C 模块），会抛出 TypeError。

三、 穿透调用栈：inspect.stack()

当程序报错时，我们会看到 Traceback（堆栈追踪）。在运行期，我们可以使用 inspect.stack() 随时“拍摄”当前的调用栈快照，查看是谁调用了当前函数。

• 经典场景：编写自定义 Logger 库，需要自动获取是哪一个文件的哪一行代码触发了日志打印。

import inspect

def inner_helper():
    # 获取当前的堆栈帧列表
    stack = inspect.stack()

    # stack[0] 代表当前函数（inner_helper）
    # stack[1] 代表调用当前函数的上一级函数（outer_run）
    caller_frame = stack[1]

    print(f"📢 [自省探针] 当前函数被以下代码调用：")
    print(f"      函数名: {caller_frame.function}")
    print(f"      文件名: {caller_frame.filename}")
    print(f"      行号: {caller_frame.lineno}")

def outer_run():
    inner_helper()

outer_run()

四、 实战：手写一个简单的依赖注入（DI）容器

结合 inspect.signature，我们可以实现一个轻量级的依赖注入容器，自动为函数填入所需的实例化对象：

import inspect

class DIContainer:
    def __init__(self):
        self._registry = {}

    def register(self, cls):
        # 注册一个单例服务
        self._registry[cls] = cls()

    def resolve_and_call(self, func):
        # 1. 分析目标函数的参数签名
        sig = inspect.signature(func)
        kwargs = {}

        for name, param in sig.parameters.items():
            param_type = param.annotation
            # 2. 如果参数类型在我们的服务注册表中，自动提取并注入
            if param_type in self._registry:
                kwargs[name] = self._registry[param_type]

        # 3. 传入自动组装的参数并执行函数
        return func(**kwargs)

# ==================== 测试运行 ====================
class Database:
    def query(self):
        return "Data from DB"

# 注册服务
container = DIContainer()
container.register(Database)

# 被调用的业务函数，声明了 Database 类型注解
def get_user_profile(db: Database):
    print("成功调用！注入的数据库数据:", db.query())

# 容器自动解析依赖并调用
container.resolve_and_call(get_user_profile)

五、 总结

1. 自省是黑魔法，但也需要克制：动态自省（尤其是通过 inspect.stack() 穿透堆栈）会产生显著的性能开销。在核心高频计算链路上应避免频繁调用。
2. 构建框架的基石：如果你的目标是编写高重用性的轮子（如自定义测试框架、参数验证中间件），inspect 模块是您不可或缺的神兵利器。

掌握自省机制，让您的代码不仅能“埋头苦干”，更能随时“仰望星空”，在运行时深刻洞悉自己的一切！