模块化迁移需重构上下文归属与生命周期：模块变量非真正全局，仅限当前进程；隐式全局状态须转为显式传参或上下文对象；并发场景用contextvars或threading.local隔离；挂载全局API须严控执行时机。

直接把全局执行上下文代码搬到模块里，不加改造很容易出问题——变量看似“还在”，实则作用域已变、并发时互相干扰、跨文件访问失效。关键不是“搬”，而是按模块化规则重构上下文的归属与生命周期。

明确模块级变量的真实作用域

模块顶层定义的变量（如 CONFIG = {"debug": True}）不是真正全局的，只在该模块导入后生效于当前 Python 进程实例。它不会自动跨进程、跨请求、跨线程共享。

• 不要假设 import utils 后就能在另一个模块里直接改 utils.CONFIG["debug"] = False 并期望所有地方同步——这仅对单线程同步场景“看起来”有效
• 若需多模块读取同一份配置，统一定义在 config.py，其余模块用 from config import CONFIG 或 import config; config.CONFIG，避免各写一遍
• 禁止在函数内用 global CONFIG 动态覆盖模块变量，除非你清楚控制所有调用路径且无并发

替换隐式全局状态为显式传参或上下文对象

原全局上下文（如用户信息、请求 ID、数据库连接）若靠 current_user 或 request_id 这类变量隐式传递，迁入模块后必须显式暴露。

• 把上下文数据封装成轻量对象，例如 context = {"user": user, "req_id": "abc123", "db": db_conn}
• 业务函数签名从 def process_order(): 改为 def process_order(context):，调用方负责传入
• 对 Web 框架（FastAPI/Flask），优先使用框架原生机制：fastapi.Request.state、flask.g 或 contextvars.ContextVar，而非模块变量

异步与并发场景必须隔离上下文

模块级变量在 asyncio 协程或线程中会被所有任务共享，A 请求修改了 CACHE，B 请求可能读到脏数据。

• 同步服务可用 threading.local() 实现线程局部存储
• 异步服务必须用 contextvars（Python 3.7+），定义 request_context = ContextVar("request_context", default=None)，每次请求开始时 request_context.set(...)
• 更推荐引入轻量库如 context0，它自动适配 sync/async 环境，API 简洁：ctx.set("user", user) / ctx.get("user")

保留全局挂载点时严控执行时机

若遗留系统依赖 window.api.doSomething() 或 globalThis.helper，迁移模块后不能简单写 window.api = api 就完事。

• 确保挂载发生在模块执行完成之后：用 type="module" 脚本 + 同样是模块的调用方，或触发 moduleReady 自定义事件通知
• 避免在模块顶部立即赋值 window.xxx = fn 后，又被其他非模块脚本在 DOM 解析阶段就调用——此时模块尚未执行
• 动态导入场景下，用 import('./module.js').then(m => window.api = m.api) 确保顺序