怎样使用 inspect 模块实现运行时函数签名检查与参数自动注入

在构建复杂的 Python 框架、Web 框架或依赖注入（DI）系统时，我们经常需要动态地知道一个函数需要哪些参数，并根据这些需求从一个可用的资源池中自动提供相应的参数。Python 标准库中的 inspect 模块正是解决这类问题的利器。

本文将重点介绍如何利用 inspect.signature 来获取函数签名，并基于此实现一个简单但高效的参数自动注入（Auto-Injection）机制。

1. 为什么需要运行时签名检查？

想象一个场景：你有一个服务容器，存储了数据库连接、日志实例、配置对象等资源。当用户定义了一个新的处理函数，它可能只需要日志实例和配置，而不需要数据库连接。通过运行时检查函数签名，我们可以只将函数所需的资源传递进去，从而解耦代码并提高灵活性。

2. 核心工具：inspect.signature

inspect.signature(callable) 函数返回一个 Signature 对象，该对象包含了函数的所有参数信息。你可以通过 .parameters 属性访问这些参数，它们是 Parameter 对象的有序映射（Ordered Mapping）。

import inspect

def my_handler(logger, user_id, optional_data=None):
    pass

sig = inspect.signature(my_handler)

# 打印所有参数
print(sig.parameters)
# Output: OrderedDict([('logger', <Parameter "logger">), ('user_id', <Parameter "user_id">), ('optional_data', <Parameter "optional_data=None">)])

# 访问特定参数的名称和类型
for name, param in sig.parameters.items():
    print(f"Name: {name}, Kind: {param.kind.name}, Default: {param.default}")

3. 实现参数自动注入

我们将创建一个 auto_inject 函数，它接受一个目标函数 func 和一个包含所有可用资源的字典 resources。该函数将解析 func 的签名，从中提取所需参数，并从 resources 中查找并注入。

示例代码

import inspect

# 模拟可用的资源池 (例如：服务容器)
available_resources = {
    "user_id": 1001,
    "database_conn": "PostgreSQL Connection",
    "logger": "ApplicationLoggerInstance",
    "config_path": "/etc/app.conf"
}

# 定义几个需要不同参数的函数
def save_data(database_conn, user_id):
    """需要数据库连接和用户ID"""
    return f"[DATA SAVE] Saving data for user {user_id} using {database_conn}"

def log_event(logger, user_id, message="Default Message"):
    """需要日志实例和用户ID，消息可选"""
    return f"[LOGGING] Log via {logger}: User {user_id} event: {message}"

def simple_task(config_path):
    """只需要配置路径"""
    return f"[TASK] Executing simple task with config at {config_path}"


# 实现自动注入函数
def auto_inject(func, resources):
    """动态检查函数签名，从资源池中注入所需参数并调用函数"""
    # 1. 获取函数签名
    sig = inspect.signature(func)
    injected_args = {}

    # 2. 遍历签名中的参数
    for name, param in sig.parameters.items():
        # 重点处理 POSITION/KEYWORD 类型的参数
        if param.kind in (inspect.Parameter.POSITIONAL_OR_KEYWORD, inspect.Parameter.KEYWORD_ONLY):

            if name in resources:
                # 如果资源池中有对应名称的资源，则注入
                injected_args[name] = resources[name]

            elif param.default is inspect.Parameter.empty:
                # 如果是必需参数（没有默认值），但资源池中没有，则抛出错误
                raise TypeError(f"Auto-Injection failed: Missing required parameter '{name}' for function '{func.__name__}'")

    # 3. 调用函数
    print(f"\n--- Calling {func.__name__} ---")
    print(f"Injected Arguments: {list(injected_args.keys())}")
    return func(**injected_args)

# 4. 运行示例

# 注入 save_data (只接收 database_conn 和 user_id)
result1 = auto_inject(save_data, available_resources)
print(f"Result 1: {result1}")

# 注入 log_event (只接收 logger 和 user_id)
result2 = auto_inject(log_event, available_resources)
print(f"Result 2: {result2}")

# 注入 simple_task (只接收 config_path)
result3 = auto_inject(simple_task, available_resources)
print(f"Result 3: {result3}")

# 尝试注入一个缺少资源的必需参数的函数
def needs_missing_key(missing_key):
    pass

try:
    auto_inject(needs_missing_key, available_resources)
except TypeError as e:
    print(f"\n--- Error Example ---")
    print(f"Error caught: {e}")

运行结果（摘要）

--- Calling save_data ---
Injected Arguments: ['database_conn', 'user_id']
Result 1: [DATA SAVE] Saving data for user 1001 using PostgreSQL Connection

--- Calling log_event ---
Injected Arguments: ['logger', 'user_id']
Result 2: [LOGGING] Log via ApplicationLoggerInstance: User 1001 event: Default Message

--- Calling simple_task ---
Injected Arguments: ['config_path']
Result 3: [TASK] Executing simple task with config at /etc/app.conf

--- Error Example ---
Auto-Injection failed: Missing required parameter 'missing_key' for function 'needs_missing_key'

总结

通过 inspect 模块，我们可以轻松实现复杂的内省（Introspection）功能。上述 auto_inject 函数的实现展示了如何读取函数的需求（签名），与可用资源进行匹配，并安全地调用函数，这为开发高度自动化和可扩展的 Python 代码库提供了强大的基础。