Python · import 机制与模块系统

场景 1 · Lambda 冷启动 3.2s → 800ms: importtime 定位最贵 import

函数平台按冷启动收体验费, 而 90% 的冷启动就是 import: 用 -X importtime 找出花钱大户, 延迟到真正用它的那条路由里:

# $ python -X importtime app.py 2> import.log   ← 分析树走 stderr
# import time: self [us] | cumulative | imported package
# import time: _   9157 |    81240 | socket
# import time: _ 128450 | 1327800 | boto3     ← 累计 1.3s, 一家占 40%

def handler(event, ctx):               # 冷启动 = 所有顶层 import 的总价
    import boto3                        # 惰性导入: 只在真正用到时付这 1.3s
    s3 = boto3.client("s3")
    return {"buckets": [b["Name"] for b in s3.list_buckets()["Buckets"]]}

# 健康检查/预热路由绝不 import 重库 — 指标采不到"没发生的导入"

改完冷启动 -1.3s; 代价是首次业务请求慢约 50ms — 对低频管理类函数稳赚。

场景 2 · 模型层互相引用成环, 抽公共 schemas 打断

user.py 和 order.py 彼此 import 对方的类型做注解, 某次入口变更后开始偶发 partially initialized module。治本解法是让公共类型下沉, 依赖图恢复成 DAG:

# 重构前: models/user.py:    from .order import Order
#          models/order.py:  from .user import User     ← 成环
# 重构后: 新建 models/schemas.py, 只放双方都需要的"薄"类型
from dataclasses import dataclass

@dataclass(frozen=True)
class Ref:
    id: int
    kind: "str"                        # 跨模块只传引用, 不传行为

# user.py / order.py 都只 import schemas → 单向依赖, 环消失
# 验收: python -c "import app.main" 在任意入口下都必须稳定通过

场景 3 · 插件系统: entry points 协议 + importlib 动态加载

报表导出格式要做插件化: 装了就能用, 没装不报错。用标准库入口点协议注册, 主程序按名动态加载:

# 插件侧声明 (插件的 pyproject.toml, pip 装上即注册):
# [project.entry-points."report.exporters"]
# csv  = "report_csv:export_csv"
# json = "report_json:export_json"

from importlib.metadata import entry_points

def load_exporters():
    return {ep.name: ep.load() for ep in entry_points(group="report.exporters")}

def export(fmt, rows):
    try:
        return load_exporters()[fmt](rows)    # 插件缺依赖在这里炸, 拦得住
    except KeyError:
        raise ValueError(f"unknown exporter: {fmt}") from None
    except Exception as e:                   # 插件失败不拖垮主流程
        log.warning("plugin failed", fmt=fmt, exc_info=True); raise

场景 4 · 测试隔离: sys.modules.pop 防单例串味

被测模块在 import 时读环境变量并缓存成单例, 测试之间互相污染。fixture 里把单例丢弃, 让模块体按新环境重跑:

# conftest.py — 模块单例让"改环境再测"变成不可能, 必须能重置
import sys, pytest

@pytest.fixture
def fresh_settings(monkeypatch):
    monkeypatch.setenv("APP_ENV", "test")      # 先改环境再谈导入
    sys.modules.pop("app.settings", None)      # 丢弃单例, 下次 import 重跑模块体
    import app.settings as s               # 用新环境重新初始化
    yield s
    sys.modules.pop("app.settings", None)      # 不把状态漏给下一个用例
    monkeypatch.undo()                        # 顺手还原被 patch 的属性

场景 5 · __init__.py 门面: __all__ + 惰性属性加速包导入

geo 包里 reverse 模块拖着 800ms 的 shapely 链, 但多数调用方只用 distance。门面只导出公共 API, 重子模块延迟到首次点名:

# geo/__init__.py — 公共 API 收口, 重库延迟到首次属性访问
__all__ = ["reverse_geocode", "distance"]

def __getattr__(name):                     # PEP 562 模块级惰性属性
    if name == "reverse_geocode":
        from .reverse import reverse_geocode  # 800ms 的链此刻才进内存
        return reverse_geocode
    raise AttributeError(f"module {__name__!r} has no {name!r}")

# 调用方无感: from geo import reverse_geocode — 包导入 3ms 不变

import geo 从 823ms → 3ms; 只有真正调用 reverse 的路径付那 800ms。

场景 6 · 脚本直跑相对导入报错: -m 与直跑的部署差异

同一个文件, 直跑报 ImportError, -m 却正常 — 差异全在 sys.path[0] 与包上下文。统一入口 + 护栏提示:

# ImportError: attempted relative import with no known parent package
# ✗ python geo/reverse.py   → sys.path[0]='geo/', __package__=None, 相对导入无锚点
# ✓ python -m geo.reverse   → sys.path[0]=cwd,   __package__='geo',  相对导入成立

# 部署脚本/systemd/Dockerfile CMD 统一走 -m; 文件尾加护栏防手滑直跑:
if __name__ == "__main__" and __package__ is None:
    raise SystemExit("run as: python -m geo.reverse")

场景 7 · 灰度机 PYTHONPATH 污染, 导入了旧版同名包

同一镜像的代码在灰度机行为不同: 新参数直接 TypeError。三行排查确认导的不是同一个包:

# 症状: 灰度机 requests=2.6.0, 其余机器 2.31 — 用到新参数直接 TypeError
import requests, os
print(requests.__file__)              # /opt/legacy/.../requests/__init__.py ← 导的不是 venv 里那个!
from importlib.metadata import version
print(version("requests"))          # 2.6.0 — 真身版本现形
print(os.environ.get("PYTHONPATH"))    # /opt/legacy:... ← 污染源
# 修复: 清掉 systemd 单元 Environment=PYTHONPATH; requirements 锁版 + pip check 进 CI

根因: 早年运维往 /etc/profile 写的 PYTHONPATH 让 /opt/legacy 排到了 venv 前面 — 先到先得, 版本漂移。

场景 8 · pickle 存档遭遇模块路径迁移, meta_path 垫片续命

工具模块从 utils.geo 迁到 geo.core, 三年的二进制存档 unpickle 全部 ModuleNotFoundError。迁移期加一个查找器垫片:

# 旧存档里类的路径是 utils.geo.Point — 模块没了, pickle 按路径找类
import sys, pickle
from importlib.abc import MetaPathFinder
from importlib.util import find_spec

class LegacyAlias(MetaPathFinder):
    OLD2NEW = {"utils.geo": "geo.core"}          # 旧路径 → 新家
    def find_spec(self, name, path=None, target=None):
        if name in self.OLD2NEW:
            return find_spec(self.OLD2NEW[name])     # 让新模块顶上

sys.meta_path.insert(0, LegacyAlias())            # 迁移期垫片, 存档迁完即删
records = pickle.load(open("archive-2023.pkl", "rb"))

场景 9 · 模块级惰性单例 vs 显式依赖注入的取舍

连接持有者怎么拿? 小服务用模块级惰性单例最省事; 多环境/重测试的 服务用显式注入, 依赖看得见才好替换:

# 写法A: 模块级惰性单例 — import 期零 IO, 首次调用才连接
_db = None
def get_db():
    global _db
    if _db is None:
        _db = create_engine(DB_URL, pool_size=10)
    return _db

# 写法B: 显式注入 — 依赖出现在签名里, 测试不用 hack sys.modules
# app = create_app(db=engine(DB_URL), cache=Redis("redis://cache:6379/0"))
# 取舍: 单服务单环境用A; SaaS 多租户/多配置用B, 组合根统一装配

场景 10 · 依赖环境漂移: 锁版 + src 布局让 sys.path 只有一条可信来源

47 台机器 pip 装出 3 个小版本, 同一段代码行为漂移查无此案。用镜像锁死依赖层, 用 src 布局防 cwd 影子覆盖:

# Dockerfile — 依赖层与代码层分离, requirements 锁到精确版本
# COPY requirements.txt .
# RUN pip install --no-cache-dir -r requirements.txt   # orjson==3.10.7
# COPY src/ ./src/
# CMD ["python", "-m", "app.main"]                      # 入口统一 -m

# pyproject.toml — src 布局: 项目包只在安装后可见, cwd 里的同名文件骗不到人
# [tool.pytest.ini_options]
# pythonpath = ["src"]
# 铁律: 生产进程的 PYTHONPATH 必须为空, sys.path 只有一条可信来源