1. 从“上下文模式”这个命名说起：它到底在解决什么问题
第一次看到“context-mode”这个词，很多人会下意识地把它当成某个框架里的配置项，或者某个库的开关参数。但如果你真的在工程里跟“上下文”打过几年交道，就会明白这个词背后藏着的是一类非常具体、非常磨人的问题：同一段逻辑，在不同上下文里需要表现出不同行为，而你又不想把上下文信息一层层手动透传下去。
举个最直白的例子。你写了一个数据校验函数，在用户注册流程里，密码强度要求是“至少8位含大小写”；但在管理员重置密码流程里，要求变成“至少12位含特殊字符”。大多数人的第一反应是加参数：
def validate_password(pwd, strict=False): if strict: # 管理员流程的规则 ... else: # 普通用户流程的规则 ...这个写法在只有两三种场景时还能忍，但场景一旦膨胀到七八种，参数就会变成strict、is_admin、is_migration、is_batch_import这样一堆布尔标志，函数签名越来越长，调用方越来越容易传错。更麻烦的是，这些标志会沿着调用链一路往下传，中间经过五六个函数，每个函数都得在签名里带上它们，哪怕它自己根本不用，只是“帮忙转交”。
context-mode这个命名所指向的思路，就是把这层“当前处于什么场景”的信息从显式参数里抽出来，放进一个隐式的、可切换的上下文容器中。代码在运行时读取当前上下文，决定走哪条分支。听起来有点像全局变量，但它比全局变量克制得多——它是有作用域的、可嵌套的、可临时覆盖的。
我最早接触这类模式是在处理多租户系统的权限校验时。同一个接口，租户A要求操作必须二次确认，租户B允许直接执行，租户C则要求走审批流。如果每个校验点都手动传租户配置，代码会脏得没法看。后来把租户策略塞进上下文，校验函数只读上下文，调用方在入口处设置一次，整条链路就都干净了。
所以这篇内容适合谁看？如果你正在被“参数透传地狱”折磨，如果你的代码里出现了大量if mode == 'xxx'的分支，如果你在写中间件、拦截器、插件系统时总觉得上下文信息没地方放，那context-mode这套思路值得你花时间吃透。它不是什么高深的新技术，而是一种组织代码的纪律。
2. 上下文模式的核心机制：作用域、嵌套与恢复
2.1 上下文不是全局变量，作用域才是关键
很多人一听“隐式传递”就皱眉，觉得这不就是全局变量换了个马甲吗？区别在于作用域的管理方式。全局变量是“设一次，到处可见，直到你手动改回来”，而上下文模式强调的是“进入某个范围时设置，离开时自动恢复”。
用生活化的类比：全局变量像是把家里的总电闸拉了，全屋都断电；上下文模式像是给某个房间装了一个独立开关，你进这个房间时按一下，出来时它自动弹回原位，其他房间不受影响。
在代码层面，这个“自动恢复”通常靠两种机制实现：一是语言自带的with/using/defer语法，二是框架提供的钩子函数。以 Python 为例，一个最朴素的上下文模式实现大概长这样：
import contextvars _current_mode = contextvars.ContextVar('mode', default='normal') class mode_scope: def __init__(self, mode): self.mode = mode self.token = None def __enter__(self): self.token = _current_mode.set(self.mode) return self def __exit__(self, *args): _current_mode.reset(self.token) def get_mode(): return _current_mode.get()用的时候：
def handle_request(req): with mode_scope('admin_reset'): do_validation(req.password) do_audit_log(req)do_validation内部只需要调用get_mode()，就能知道当前是管理员重置流程，不需要任何参数透传。而且一旦with块结束，模式自动回到之前的值，不会污染后续代码。
这里有个细节值得注意：contextvars是 Python 3.7 引入的标准库，它和线程本地存储（threading.local）最大的区别在于，它原生支持异步任务。在 asyncio 里，每个协程有自己独立的上下文副本，不会出现“A协程设了模式，B协程读到了”这种串台问题。如果你用的是多线程模型，threading.local也能凑合，但一旦引入异步，就必须换成contextvars。
2.2 嵌套上下文的叠加规则
上下文模式真正体现设计功力的地方，是嵌套场景。假设你在一个“批量导入”的大上下文里，对其中某几条特殊记录又要走“严格校验”的小上下文，这时候内外两层模式怎么叠加？
常见的有三种策略：
| 策略 | 行为 | 适用场景 |
|---|---|---|
| 覆盖式 | 内层完全替换外层 | 内外模式互斥，内层是更具体的场景 |
| 合并式 | 内层字段合并到外层，同名字段内层优先 | 上下文是多字段配置，各管各的 |
| 栈式 | 内层压栈，读取时从栈顶往下找第一个匹配 | 需要保留完整历史，支持回退查询 |
覆盖式最简单，但容易丢信息。合并式适合上下文本身是个字典的情况，比如{'tenant': 'A', 'strict': True}，内层只想改strict，不想动tenant。栈式最灵活，但读取逻辑复杂，容易写出难以调试的代码。
我个人的经验是：如果上下文只有一个维度（比如只有“模式”这一个字段），用覆盖式就够了；如果上下文是多维配置，优先用合并式；栈式只在极少数需要追溯“我到底经过了哪些上下文”的场景才用，比如审计日志。
还有一个坑：嵌套时的异常安全。如果内层with块里抛了异常，__exit__必须保证外层上下文被正确恢复。上面那个mode_scope实现里，reset放在__exit__里，即使异常也会执行，这是对的。但如果你手动写set和reset而不用with，就很容易在异常路径上漏掉reset，导致上下文泄漏到后续请求里。这种 bug 特别隐蔽，因为它在正常流程下不出现，只在异常分支才暴露。
2.3 读取时的默认值与降级逻辑
上下文模式还有一个容易被忽视的设计点：当上下文没有被显式设置时，读取应该返回什么？
最粗暴的做法是抛异常，强制调用方必须设置。这在某些严格场景下是合理的，比如支付流程必须明确当前是“扣款”还是“退款”，不允许有默认行为。但更多时候，我们需要一个合理的默认值，让代码在“没有特别指定”时也能正常工作。
默认值的设计要遵循“最安全”原则。比如权限校验的默认模式应该是“最严格”，而不是“最宽松”。我见过一个反例：某系统的上下文默认模式是'skip_check'，结果某次调用方忘了设置上下文，所有校验都被跳过了，直接导致线上事故。后来改成默认'strict'，忘了设置最多是功能不可用，不会造成安全问题。
降级逻辑则是指：当上下文里缺少某个字段时，不是直接报错，而是回退到上一级或全局配置。比如多租户场景，租户级配置没设，就回退到系统默认配置。这种降级链要显式定义清楚，不能靠“碰巧读到了某个值”来工作。
3. 在真实项目里落地 context-mode 的完整路径
3.1 先别急着写代码：梳理上下文的维度
我见过太多人一上来就建一个Context类，往里塞十几个字段，结果用了两个月发现一半字段根本没人读，另一半字段的更新时机混乱不堪。正确的做法是先做一轮“上下文审计”。
拿一张纸，把所有“需要根据场景变化的行为”列出来，然后问三个问题：
- 这个行为的变化频率高吗？如果整个系统生命周期里只有启动时确定一次，那它不该进上下文，应该进配置。
- 这个行为的变化范围大吗？如果只在某一个函数内部变化，那用局部变量就够了，不需要上下文。
- 这个行为需要跨多少个调用层级？如果只跨一层，直接传参更清晰；跨三层以上，上下文模式才开始体现价值。
经过这三轮筛选，真正需要进上下文的维度通常不会超过五个。比如一个典型的多租户SaaS系统，上下文可能只有：tenant_id、user_role、request_source（web/api/batch）、strict_mode。就这四个，足够覆盖绝大多数分支需求。
3.2 上下文的设置点应该放在哪里
设置点的选择直接决定了上下文模式是“好用”还是“添乱”。原则是：在尽可能靠近入口的地方设置，在尽可能少的的地方设置。
Web 应用里，入口就是请求进入框架的那一刻。以常见的 WSGI 框架为例，你可以在中间件里根据请求头、URL 路径、用户会话等信息，一次性把上下文设好，后续所有业务代码都直接读。
class ContextMiddleware: def __init__(self, app): self.app = app def __call__(self, environ, start_response): tenant = environ.get('HTTP_X_TENANT_ID', 'default') source = 'api' if environ['PATH_INFO'].startswith('/api') else 'web' with mode_scope('normal'), tenant_scope(tenant), source_scope(source): return self.app(environ, start_response)注意这里用了多个with嵌套，每个维度一个作用域。这样写的好处是每个维度的生命周期独立，将来要加新维度只需要多一层with，不影响已有逻辑。
但这里有个性能考量：如果每个请求都要创建四五个ContextVar的 token 并重置，在高并发下会不会有开销？实测下来，contextvars的 set/reset 操作在微秒级别，相比一次数据库查询或一次网络调用，完全可以忽略。真正需要注意的是不要在循环内部频繁 set/reset，那才会累积成可观测的开销。
3.3 业务代码如何优雅地消费上下文
上下文设好之后，业务代码的写法就变得很清爽。但“清爽”不等于“随便读”。我建议在团队里约定一条规则：业务函数不直接调用底层的get_mode()，而是通过一个语义化的封装函数来读。
比如不要写：
if get_mode() == 'admin_reset': ...而是写：
if is_admin_reset(): ...这个is_admin_reset()内部去读上下文，但对外暴露的是一个业务语义。这样做的好处是：将来上下文的存储方式变了（比如从contextvars换成别的机制），只需要改封装函数，业务代码不动；而且封装函数的名字本身就是文档，读代码的人一眼就知道这个分支在判断什么。
更进一步，可以把常用的上下文组合判断也封装起来：
def should_apply_strict_validation(): return get_mode() in ('admin_reset', 'migration') or get_tenant_config().strict这种封装函数应该放在一个专门的模块里，集中管理，避免散落在各个业务文件里。我通常叫它context_rules.py或policy.py，名字不重要，重要的是“所有跟上下文相关的判断逻辑都在这一个地方”。
3.4 测试时如何模拟不同上下文
上下文模式对测试其实很友好，因为你可以用with块精确控制测试用例的上下文，不需要构造复杂的参数组合。
def test_password_validation_admin(): with mode_scope('admin_reset'): assert validate_password('Short1') is False assert validate_password('LongEnough123!') is True def test_password_validation_normal(): with mode_scope('normal'): assert validate_password('Short1') is False assert validate_password('Longenough1') is True每个测试用例只关心自己那一个上下文维度，互不干扰。而且因为上下文在with块结束后自动恢复，测试之间不会串台，不需要在tearDown里手动清理。
但有一个坑：如果你用的是 pytest 的 fixture，fixture 的作用域和with块的作用域可能不匹配。比如一个session级别的 fixture 里设置了上下文，但测试函数结束后上下文并没有恢复，会影响后续测试。解决办法是把上下文设置放在function级别的 fixture 里，或者用yieldfixture 确保清理。
4. 那些只有踩过才知道的坑与应对策略
4.1 异步任务里的上下文丢失
这是最常见也最致命的问题。在 asyncio 里，如果你用asyncio.create_task创建一个新任务，新任务会复制当前上下文的一份快照。这意味着：在任务创建之后、任务开始执行之前，如果你修改了上下文，新任务读到的还是旧值。
async def main(): with mode_scope('normal'): task = asyncio.create_task(do_something()) # 这里切换模式 with mode_scope('admin'): await task # do_something 读到的仍然是 'normal'这个行为在 Python 文档里有说明，但很容易被忽略。如果你的业务逻辑依赖“任务执行时的上下文”，而不是“任务创建时的上下文”，就会出问题。解决办法是：要么在任务内部重新设置上下文，要么用contextvars.copy_context()显式传递。
另一个相关问题是线程池。如果你把任务提交到ThreadPoolExecutor，工作线程不会自动继承调用线程的上下文。需要在提交任务时手动包装：
ctx = contextvars.copy_context() executor.submit(ctx.run, my_function, arg1, arg2)这个ctx.run的写法能保证my_function在工作线程里读到的是提交时的上下文快照。如果不做这层包装，工作线程读到的是它自己的默认上下文，跟调用方完全无关。
4.2 上下文泄漏导致的“幽灵 bug”
上下文泄漏是指：某个请求设置了上下文，但因为异常或逻辑漏洞，没有正确恢复，导致后续请求读到了错误的上下文。这种 bug 的可怕之处在于它不可复现——取决于请求的先后顺序和并发情况，本地测试永远正常，线上偶发。
我遇到过一次：某个接口在特定条件下会提前return，而return之前没有走with的__exit__（因为当时是手动 set/reset 而不是用with）。结果那个请求的tenant_id留在了上下文里，下一个请求如果没设置租户，就会读到上一个租户的数据。这种跨租户数据泄漏，在安全审计里是最高级别的缺陷。
防范措施有三条：
- 强制使用
with语法，禁止手动 set/reset。可以在代码审查里加一条规则，看到_current_mode.set(就必须有对应的reset，且必须在finally里。 - 在请求入口处做一次“上下文重置”，确保每个请求开始时上下文是干净的。即使上一个请求泄漏了，也会被这次重置覆盖。
- 加监控：在请求结束时检查上下文是否回到了初始状态，如果不是就告警。这个检查可以在中间件的
finally里做。
4.3 上下文维度膨胀后的性能与可维护性
一开始上下文只有两三个维度，代码很清爽。但随着业务发展，有人往里加is_mobile、is_premium_user、experiment_group、feature_flag_xxx……半年后上下文里有二十个字段，每个业务函数都要读好几个，判断逻辑散落各处。
这时候上下文模式就从“解药”变成了“毒药”。应对策略是分层：把上下文分成“核心上下文”和“扩展上下文”。核心上下文是那些跨多个模块、生命周期贯穿整个请求的维度，比如租户、用户角色。扩展上下文是那些只在特定模块内使用的维度，比如某个实验的分组信息，它应该由那个模块自己管理，不放进全局上下文。
另一个策略是用配置对象替代布尔标志。不要往上下文里塞is_strict、is_audit、is_async这样的布尔值，而是塞一个policy对象，对象里包含所有策略字段。这样上下文只有一个维度（policy），但策略本身可以无限扩展，而且策略的默认值、合并规则、校验逻辑都集中在策略类里，不会污染上下文机制。
@dataclass class Policy: strict_validation: bool = False audit_level: str = 'basic' async_processing: bool = True _current_policy = contextvars.ContextVar('policy', default=Policy()) def get_policy() -> Policy: return _current_policy.get()用的时候get_policy().strict_validation，语义清晰，扩展方便，而且策略对象可以序列化、可以打日志、可以做 diff，比一堆散落的布尔标志好维护得多。
4.4 与依赖注入框架的配合
很多项目已经在用依赖注入（DI）框架，比如 FastAPI 的Depends、Spring 的@Autowired。这时候上下文模式和 DI 会有职责重叠：DI 也能把配置注入到函数参数里，为什么还要上下文？
区别在于注入的时机和范围。DI 是在函数调用时注入，每个函数需要显式声明依赖；上下文是在请求入口设置，所有函数隐式可读。对于“每个函数都需要知道”的信息（比如当前租户），DI 会导致每个函数签名都带一个tenant参数，跟参数透传的问题一样。对于“只有部分函数需要知道”的信息，DI 更合适，因为它是显式的。
我的做法是：跨切面的、全局性的信息用上下文；模块内的、局部的配置用 DI。两者不冲突，各管各的。比如租户ID用上下文，数据库连接池配置用 DI。
5. 从 context-mode 延伸出的设计思考
5.1 上下文模式与策略模式的边界
有人会把上下文模式和策略模式混为一谈，觉得都是“根据场景选不同行为”。但两者的关注点不同：策略模式关注的是“算法可替换”，上下文模式关注的是“场景信息可传递”。
策略模式里，你显式地把策略对象传给执行者；上下文模式里，执行者自己去读当前场景。策略模式更适合“同一个功能有多种实现，调用方选择用哪种”；上下文模式更适合“同一个实现需要根据场景微调行为，但调用方不想关心细节”。
实际项目里两者经常一起用：上下文里存一个策略标识，执行者根据标识去策略注册表里取具体策略。这样既有上下文的隐式传递便利，又有策略模式的灵活替换。
5.2 上下文模式在插件系统中的应用
插件系统是上下文模式的天然应用场景。主程序加载插件时，每个插件可能需要在不同的“模式”下运行：有的插件只在开发环境启用，有的插件只在特定租户下启用，有的插件需要更高的权限。
如果每个插件都手动传这些信息，插件的接口会变得很复杂。用上下文模式，主程序在调用插件前设置好上下文，插件内部直接读，接口保持干净。
但这里有个安全考量：插件读上下文时，应该只能读它被授权读的字段。如果上下文是一个大字典，插件可能读到敏感信息。解决办法是给插件提供一个“受限视图”，只暴露它需要的字段。这层隔离在插件数量多、来源不可控时尤其重要。
5.3 什么时候不该用上下文模式
说了这么多上下文模式的好处，最后必须泼一盆冷水：它不是银弹，很多场景下不该用。
如果一段逻辑只在两三个地方调用，直接传参最清晰；如果上下文信息只在单个函数内使用，局部变量就够了；如果团队里新人对隐式传递不熟悉，上下文模式会增加理解成本，不如显式参数来得直白。
我判断的标准很简单：当你发现同一个信息被透传超过三层，且透传的中间层根本不使用这个信息时，才考虑上下文模式。如果中间层至少有一处会用到，那它就不算纯粹的“透传”，显式传递反而更合理。
还有一个信号：当你开始写if get_mode() == 'xxx'超过五处时，说明上下文模式可能被滥用了。这时候应该回头看看，是不是有些判断可以合并，有些场景可以拆成独立的函数，而不是靠上下文在运行时分支。
6. 一套可复用的上下文模式落地清单
把上面这些经验浓缩成一份可执行的清单，方便你在自己的项目里对照落地。
第一步：审计。列出所有“需要根据场景变化”的行为，按变化频率、变化范围、跨层级数三个维度筛选，只保留真正需要进上下文的维度。通常不超过五个。
第二步：选型。同步代码用contextvars或threading.local；异步代码必须用contextvars；跨线程池要手动copy_context。不要自己造轮子实现上下文存储，标准库已经够用。
第三步：封装。每个上下文维度一个ContextVar，配一个xxx_scope的with上下文管理器，配一个get_xxx()的读取函数。业务代码只调用语义化的封装函数，不直接碰底层ContextVar。
第四步：设置。在请求入口（中间件、拦截器、装饰器）统一设置，不在业务代码里零散设置。设置时用with嵌套，确保异常安全。
第五步：测试。每个上下文维度至少一个正向测试和一个边界测试。测试用例用with块控制上下文，不依赖全局状态。注意 fixture 作用域和with作用域的匹配。
第六步：监控。在请求出口检查上下文是否恢复初始状态，不恢复就告警。定期审查上下文维度的数量，超过十个就要考虑分层或合并。
第七步：文档。在团队文档里写清楚：有哪些上下文维度、每个维度的含义、默认值是什么、在哪些地方设置、哪些模块可以读。新人入职第一周就应该看这份文档。
这套清单不是理论推演，是我在三个不同规模的项目里反复调整后沉淀下来的。每个项目的情况不同，具体数字可以变，但“审计-选型-封装-设置-测试-监控-文档”这个顺序不能乱。跳过审计直接写代码，最后一定会返工；跳过监控不做泄漏检查，线上一定会出幽灵 bug。
最后分享一个我在实际使用中养成的习惯：每次往上下文里加新维度之前，先问自己“如果这个维度不存在，代码会怎样”。如果答案是“也能跑，只是某些场景下行为不够精确”，那说明这个维度是锦上添花，可以缓一缓；如果答案是“跑不起来”或“会出安全问题”，那它才是真正必要的。这个习惯帮我挡掉了至少一半的上下文膨胀。
