显式传参与上下文代理对比选型：从一段“凭空取请求”的代码说起

在很多 Web 框架里，都会出现这样一种写法：函数签名里没有任何请求参数，但函数体里却可以直接读取当前请求的信息。

@app.get("/hello")
def hello():
    name = get_param("name", "world")
    return f"hello {name}"

这段代码平时写起来很顺，但多想一层就会有点奇怪：这个“当前请求”是从哪来的？如果同一时间有 100 个用户访问，读取到的参数到底算谁的？

要回答这个问题，就必须先厘清两条完全不同的技术路线：显式参数传递与上下文代理（Context）。本文将围绕这两种方式展开系统对比，说明它们各自的定义、相同点、核心差异、适用场景与选型依据。

一、对比背景：为什么会出现“上下文”这个概念

在工程实践中，有一类信息非常多地方都要用，例如当前用户、当前请求、当前事务、当前追踪标识、当前语言环境等。如果每个函数都显式声明一遍，调用链很快就会被这些参数占满。

典型的问题场景是：

• 视图层调用服务层，服务层调用数据访问层；
• 中间还夹着鉴权、日志、模板渲染、错误处理；
• 每一层都需要一部分环境信息，但并不是每一层都真正使用全部信息；
• 结果是大量函数被迫“接一下再传下去”，代码变成搬箱子。

Context（上下文）就是为了解释并解决这类问题而出现的：它可以先理解成“当前这段代码运行时默认带着的一包环境信息”。代码没有把这些信息写进参数，框架、运行时、线程或协程会把它挂在当前执行流程上。

二、对象定义：两种方式分别是什么

1. 显式参数传递

显式参数传递指的是：需要什么信息，就通过函数参数逐层传入。

def view(request):
    user = get_user(request)
    return render_page(request, user)
def get_user(request):
    token = request.headers.get("Authorization")
    return load_user_by_token(token)
def render_page(request, user):
    lang = request.headers.get("Accept-Language")
    return f"{lang}: {user.name}"

它的特点是没有歧义：任何需要请求信息的函数，都把请求对象写进参数。

2. 上下文代理

上下文代理指的是：框架把当前请求放进一个“请求上下文”，代码访问的不是请求对象本身，而是一个代理。当代码访问属性时，代理会去当前执行流程里查找“这一刻对应的请求”。

@app.get("/hello")
def hello():
    name = request.args.get("name", "world")
    return f"hello {name}"

当前处理到 A 用户，代理指向 A 的请求；切到 B 用户，它又指向 B 的请求。写法像全局变量，运行时却不是全局共享那一份。

三、相同点分析

尽管两种方式在写法上差异明显，它们的目标其实高度一致：

• 都是为了在调用链中共享环境信息，避免重复构造或重复查询；
• 都要求信息与当前执行流程绑定，否则并发场景下会取错数据；
• 都需要考虑生命周期管理，即信息何时创建、何时销毁、何时可见；
• 都会影响可测试性，只是影响的方式不同：显式传参更容易构造输入，上下文代理更依赖运行环境。

四、核心差异分析

1. 调用链与代码可读性

显式传参的调用链是“透明”的：看函数签名就知道它依赖什么。缺点是当依赖变多时，签名会迅速膨胀，中间层被迫传递自己并不使用的参数。

上下文代理的调用链是“隐式”的：函数签名干净，但阅读代码时需要知道当前处于什么上下文，才能判断某个变量从哪里来。对于不熟悉框架的新成员，这会带来一定的理解成本。

2. 并发与隔离模型

这是两者最关键的技术差异之一。

• 显式传参天然是并发安全的：每个请求持有自己的对象，参数按值或按引用传递，不共享可变状态。
• 上下文代理依赖运行时的隔离机制：可能基于线程本地存储、协程本地存储或执行上下文快照。只要隔离机制正确，不同请求之间不会串数据；但如果跨线程、跨协程传递，或在异步任务中错误地复用上下文，就可能出现取错对象的问题。

因此，上下文代理并不是“全局变量”，而是“跟着当前执行流程走的变量”。理解这一点，是正确使用它的前提。

3. 可测试性

显式传参的单元测试非常直接：构造一个请求对象传入即可，不需要启动框架运行时。

上下文代理的测试通常需要先建立上下文，例如通过测试客户端发起一次请求，或在测试夹具中手动压入上下文。测试成本略高，但框架通常会提供相应的测试支持。

4. 接入与改造成本

对比维度	显式参数传递	上下文代理
调用链透明度	高	中
函数签名简洁度	低	高
并发安全	天然安全	依赖运行时隔离
可测试性	直接	需构造上下文
改造现有代码	需逐层改签名	通常改动局部
对新人的理解成本	低	中
适合的调用链深度	浅到中等	中到较深
跨线程/协程风险	低	需重点关注

5. 使用边界

上下文代理并不适合承载所有信息。它更适合“跟着当前执行流程走”的短生命周期数据，例如当前请求、当前用户、当前事务、当前追踪标识。它不适合承载：

• 需要长期保存的业务状态；
• 需要跨请求共享的缓存数据；
• 需要明确审计来源的关键配置。

显式传参则更适合依赖关系明确、数量可控、需要长期维护的核心业务参数。

五、典型场景选择

场景一：小型脚本或工具函数。 依赖少，显式传参最直接，无需引入上下文机制。

场景二：中等规模 Web 服务。 请求级信息（请求对象、当前用户、追踪标识）适合放入上下文，业务参数仍然显式传递，形成“环境走上下文、业务走参数”的分层。

场景三：深层调用链与横切关注点。 鉴权、日志、埋点、事务管理这类跨越多个层次的逻辑，使用上下文可以显著减少参数搬运。

场景四：异步与并发密集场景。 需要特别关注上下文的隔离模型，确认线程本地或协程本地机制是否覆盖所有执行路径。

场景五：需要强可测试性与显式依赖的团队。 可以优先采用显式传参，或仅在框架层使用上下文，业务层保持显式依赖。

六、选型建议

选型不应绝对化，可以按以下条件判断：

• 如果依赖信息数量少、调用链浅、团队强调显式依赖，优先考虑显式传参；
• 如果请求级信息被大量横切逻辑使用、调用链较深、希望保持函数签名干净，可以考虑上下文代理；
• 如果同时存在两类需求，可以采用混合模式：环境信息走上下文，业务参数走显式传递；
• 无论选择哪种方式，都应明确信息的生命周期与隔离边界，避免把上下文当作全局变量使用。

七、迁移与使用注意事项

从显式传参迁移到上下文代理，或反向迁移，都需要注意以下几点：

• 接口兼容性：函数签名变化会影响所有调用方，需要评估改动范围；
• 并发正确性：迁移到上下文后，必须验证线程、协程、异步任务中的隔离是否成立；
• 可观测性：上下文中隐式携带的信息，应在日志和追踪中显式输出，避免排障时“看不到来源”；
• 测试覆盖：迁移后需要补充上下文构造与清理相关的测试用例；
• 边界清晰：不要把业务状态塞进上下文，否则会削弱代码的可维护性。

八、总结

显式参数传递与上下文代理并不是互相替代的关系，而是解决同一类问题的两种思路。显式传参以透明换冗余，上下文代理以简洁换隐式约定。理解“当前执行流程”这一核心概念，是正确使用上下文的关键；而根据调用链深度、并发模型、团队习惯和可测试性要求做出条件化选择，才是更稳妥的工程实践。