门面模式是结构型设计模式，通过显式类封装子系统并委托调用，不改变逻辑、无状态、不掺杂业务判断；禁用装饰器模拟，必须用组合而非继承，并需管理子系统生命周期。
门面模式不是装饰器，别用 @functools.wraps 去套
门面（Facade）是结构型设计模式，核心目标是提供一个统一入口，屏蔽子系统内部多个类、接口或依赖的调用细节。它和装饰器、代理、适配器容易混淆——装饰器改行为，代理控访问，适配器转接口；门面只做「封装+委托」，不改变原有逻辑，也不新增语义。
常见误操作是试图用函数装饰器模拟门面，结果导致职责不清：比如给每个子系统方法都加一层 @log_call 或 @retry，这实际是横切关注点，不是门面。真正门面必须是一个显式的类，持有对子系统组件的引用，并暴露精简的公共方法。
- 门面类应无状态（或仅持不可变配置），避免在多个实例间共享子系统对象引发竞态
- 不要在门面里做业务判断（如“如果用户是VIP就走缓存路径”），那是上层服务该干的事
- 子系统类名若带
Impl、Handler、Service后缀，正是门面要藏起来的东西
FileProcessorFacade：典型文件处理子系统的整合示例
假设你有三个独立类：TextParser 解析文本，ImageCompressor 压缩图片，FileUploader 上传到对象存储。业务侧每次都要手动初始化三者、传参、按顺序调用、处理各自异常——这就是门面要解决的场景。
正确做法是定义一个门面类，把协作逻辑收进来：
立即学习“Python免费学习笔记（深入）”；
class FileProcessorFacade:
def __init__(self, upload_endpoint: str, compression_level: int = 6):
self._parser = TextParser()
self._compressor = ImageCompressor(level=compression_level)
self._uploader = FileUploader(endpoint=upload_endpoint)
def process_and_upload(self, file_path: str) -> str:
try:
text = self._parser.parse(file_path)
compressed = self._compressor.compress(file_path)
return self._uploader.upload(compressed, metadata={"text_preview": text[:100]})
except (ParseError, CompressionError, UploadError) as e:
raise ProcessingFailedError(f"Failed at {type(e).__name__}: {e}") from e
关键点：
创建 Flask + Vue.js 全栈项目，采用单端口架构、uv 依赖管理、结构化日志和生产级前端设计。当用户要求以下操作时触发：创建新的 Flask+Vue 项目、搭建 Web 应用、构建全栈 Python+Vue 应用、初始化 Flask Web 项目、设置单端口 Flask 前后端项目。触发词：新建项目、创建项目、搭建项目、Flask项目、Vue项目。
- 构造函数接收外部配置（如
upload_endpoint），而非子系统实例——否则门面失去封装性 - 所有子系统异常被统一转换为门面自己的异常类型（
ProcessingFailedError），上层无需导入一堆子系统异常 - 方法名
process_and_upload表达业务意图，不暴露parse/compress等底层动词
什么时候不该用门面？看子系统是否真「复杂」
门面的价值在「降低认知负荷」，不是为了设计而设计。以下情况建议跳过：
- 子系统只有 1–2 个类，且接口本身已足够清晰（例如
requests.get()就是良好封装，无需再包一层HttpFacade） - 调用方需要细粒度控制流程（比如有时只解析不上传，有时要并行压缩多图），强行塞进门面会导致方法爆炸或参数臃肿
- 子系统本身正在快速迭代，接口不稳定——门面会变成维护包袱，每次子系统改名/删方法，门面也得同步改
一个实用判断标准：如果你写单元测试时，发现 70% 的 mock 都集中在同一组类上，且这些类总是一起出现，那它们就是门面的天然候选。
继承 vs 组合：门面必须用组合，禁止继承子系统类
错误写法：class FileProcessorFacade(ImageCompressor, TextParser): ...——这违反里氏替换原则，也破坏封装。门面不是子系统的“加强版”，而是它的“前台接待员”。
必须坚持组合：
- 子系统类变更不影响门面签名（只要门面自己暴露的方法不变，上层代码完全无感）
- 便于测试：可轻松注入 mock 子系统（
facade = FileProcessorFacade(..., uploader=MockUploader())） - 支持运行时切换实现：比如开发环境用
DiskUploader，生产用S3Uploader，门面构造时传入即可
真正容易被忽略的是生命周期管理：如果某个子系统需要 close() 或 shutdown()（如数据库连接池、异步事件循环），门面必须提供对应方法并确保按序调用——这不是可选优化，而是资源泄漏风险点。
