适配器模式 - Python进阶编程-学习笔记-上海佼艾

一、适配器模式概述

适配器模式（Adapter Pattern）是一种结构性设计模式，它充当两个不兼容接口之间的桥梁。当一个已有类的接口与客户端代码期望的接口不匹配时，适配器模式可以在不修改已有代码的前提下，通过引入一个中间转换层来解决接口不兼容问题。

适配器模式的核心思想非常直观，用现实生活中的例子来理解最为方便：当我们从中国前往美国旅行时，中国标准的扁脚两孔插头无法直接插入美国标准的圆孔插座。这时我们需要一个"电源转换插头"——它一端接入中国插头，另一端适配美国插座。这个转换插头就是适配器，它隐藏了接口转换的复杂性，让原本不兼容的两端能够正常协作。

在软件工程中，适配器模式解决了同样的问题。我们经常会遇到这样的场景：系统中有现成的类（被适配者），它的功能完全符合需求，但它的接口（方法名、参数列表、返回值格式）与当前系统所期望的接口不一致。如果直接修改这个已有的类，可能引入回归风险，或者该类来自第三方库我们无权修改。适配器模式提供了一个优雅的解决方案——创建一个适配器类，将原有接口转换为目标接口。

核心定义：适配器模式将一个类的接口转换成客户端期望的另一个接口，使得原本因接口不兼容而无法一起工作的类能够协同工作。

适配器模式的组成角色

目标接口（Target）：客户端所期待的接口规范，定义了客户端将要调用的方法。
被适配者（Adaptee）：已经存在的、功能正确但接口不兼容的类，需要被适配。
适配器（Adapter）：处于中间层的核心类，负责将Adaptee的接口转换成Target接口，使客户端能够透明地使用Adaptee的功能。
客户端（Client）：通过Target接口与对象交互的业务代码，无需感知适配过程的存在。

适配器模式的应用场景

想要使用一个已有的类，但它的接口不符合当前系统需求。
需要创建多个可复用的类，这些类的功能相关但接口不统一。
需要整合多个第三方库或老旧系统，它们的接口各不相同。
不想修改已有代码，希望通过增加新类来解决兼容性问题（符合开闭原则）。
系统需要对接多种外部服务（如不同支付网关、不同数据库、不同日志框架）。

二、适配器模式的两种经典结构

适配器模式在经典面向对象设计中有两种结构变体：类适配器和对象适配器。理解这两种变体的区别，是掌握适配器模式的关键。

类适配器（Class Adapter）

类适配器通过多重继承来实现适配。适配器类同时继承目标接口（Target）和被适配者类（Adaptee），并将对目标接口方法的调用委托给从Adaptee继承来的方法。这种方式的优点是无需重新实现Adaptee的功能，但如果目标接口和被适配者的方法存在命名冲突，可能引入复杂性。

对象适配器（Object Adapter）

对象适配器通过组合来实现适配。适配器类实现目标接口，并在内部持有被适配者对象的引用。当客户端调用适配器的目标接口方法时，适配器内部将调用转发给被适配者的对应方法。这种方式的优点是利用了组合的灵活性和低耦合性，是面向对象设计中优先推荐的方式（组合优于继承）。

对比维度	类适配器	对象适配器
实现方式	多重继承（继承Target和Adaptee）	组合（实现Target接口，持有Adaptee引用）
耦合程度	高（与Adaptee紧密耦合）	低（通过引用访问Adaptee）
灵活性	较低（适配单一具体类）	高（可以适配Adaptee的所有子类）
额外功能	可以覆盖Adaptee的方法	无法覆盖Adaptee的方法
语言支持	需要多重继承支持	所有面向对象语言都支持

GoF建议：《设计模式：可复用面向对象软件的基础》一书中建议优先使用对象适配器，因为组合比继承更灵活，且不会强迫Adaptee的所有子类都被适配。

三、Python类适配器实现

Python支持多重继承，因此实现类适配器非常自然。下面是一个完整的类适配器示例，演示如何将一个XML格式的日志系统适配为JSON格式的日志接口。

# 目标接口：当前系统期望的JSON日志接口
class JsonLogger:
    def log(self, message: str) -> None:
        raise NotImplementedError

    def error(self, message: str) -> None:
        raise NotImplementedError


# 被适配者：已有但接口不兼容的XML日志系统
class XmlLogSystem:
    def write_log(self, xml_message: str) -> None:
        # 写入XML格式日志
        print(f"[XML-LOG]: {xml_message}")

    def write_error(self, xml_error: str) -> None:
        print(f"[XML-ERROR]: {xml_error}")


# 类适配器：通过多重继承适配接口
class XmlToJsonAdapter(JsonLogger, XmlLogSystem):
    def log(self, message: str) -> None:
        # 将JSON格式消息转换为XML再传给被适配者
        xml_msg = f"<log>{message}</log>"
        self.write_log(xml_msg)

    def error(self, message: str) -> None:
        xml_msg = f"<error>{message}</error>"
        self.write_error(xml_msg)


# 客户端代码
def client_code(logger: JsonLogger):
    logger.log("用户登录成功")
    logger.error("数据库连接超时")


# 使用适配器
adapter = XmlToJsonAdapter()
client_code(adapter)

在这个例子中，类适配器`XmlToJsonAdapter`同时继承了`JsonLogger`（目标接口）和`XmlLogSystem`（被适配者），将客户端期望的`log()`和`error()`方法调用转发为`write_log()`和`write_error()`调用，并在转发过程中完成了数据格式的转换。客户端完全不知晓底层使用的是XML日志系统。

Python优势：不同于Java和C#等单继承语言，Python的多继承特性使类适配器的实现极为简洁，不需要显式持有被适配者的引用，所有功能通过继承直接获得。

四、Python对象适配器实现

对象适配器通过组合实现适配，是更灵活、更推荐的方式。适配器类实现目标接口，并在构造函数中接受被适配者对象。

# 目标接口
class NotificationService:
    def send(self, recipient: str, message: str) -> None:
        raise NotImplementedError


# 被适配者A：短信服务提供商
class SmsProvider:
    def send_sms(self, phone: str, text: str) -> None:
        print(f"[短信] 发送至 {phone}: {text}")


# 被适配者B：邮件服务提供商
class EmailProvider:
    def send_email(self, to_addr: str, subject: str,
                     body: str) -> None:
        print(f"[邮件] 收件人: {to_addr}")
        print(f"[邮件] 主题: {subject}")
        print(f"[邮件] 正文: {body}")


# 对象适配器：通过组合适配不同的通知渠道
class SmsAdapter(NotificationService):
    def __init__(self, sms_provider: SmsProvider):
        self._sms = sms_provider  # 组合被适配者

    def send(self, recipient: str, message: str) -> None:
        # 适配：转换参数并调用被适配者的方法
        self._sms.send_sms(recipient, message)


class EmailAdapter(NotificationService):
    def __init__(self, email_provider: EmailProvider):
        self._email = email_provider

    def send(self, recipient: str, message: str) -> None:
        # 将统一的消息内容拆分为邮件所需的主题和正文
        subject, body = message.split("\n", 1)
        self._email.send_email(recipient, subject, body)


# 客户端：统一发送通知
def notify_user(service: NotificationService, user: str, msg: str):
    service.send(user, msg)


# 使用
sms_adapter = SmsAdapter(SmsProvider())
email_adapter = EmailAdapter(EmailProvider())

notify_user(sms_adapter, "13800138000", "您的验证码是1234")
notify_user(email_adapter, "user@example.com",
            "登录通知\n您的账号于10分钟前在新设备登录")

对象适配器的优势在这个例子中非常明显：同一个`NotificationService`接口可以适配多种完全不同的通知渠道。每个渠道有自己的参数约定和调用方式（有的需要分开主题和正文、有的只需要一条文本），但通过适配器的封装，客户端可以用统一的方式发送所有类型的通知。新增一个通知渠道（如微信推送）只需要再写一个适配器类即可，完全不需要修改现有代码。

五、Python特有的适配器实现方案

Python的动态特性为适配器模式提供了几种非常独特的实现方式。这些方式在静态类型语言中是很难做到的，充分体现了Python"灵活即正义"的设计哲学。

5.1 使用 getattr 实现动态适配

Python的`__getattr__`特殊方法在属性查找失败时被调用。利用这一机制，我们可以构建一个通用的动态适配器：当客户端访问目标接口上的某个方法时，如果适配器本身没有这个方法，`__getattr__`会被触发，将调用动态转发给被适配者。

class DynamicAdapter:
    """通用动态适配器：将任意对象适配到任意接口"""

    def __init__(self, adaptee, **mappings):
        self._adaptee = adaptee
        # mappings: {目标方法名: 被适配者方法名}
        self._mappings = mappings

    def __getattr__(self, name):
        if name in self._mappings:
            # 将目标方法调用转发到被适配者的对应方法
            mapped_name = self._mappings[name]
            return getattr(self._adaptee, mapped_name)
        return getattr(self._adaptee, name)


# 使用示例
class LegacyApi:
    def fetch_user_data(self, uid):
        return {"id": uid, "name": "张三"}

    def save_record(self, data):
        print(f"保存记录: {data}")


# 动态适配：将旧接口映射为新接口
legacy = LegacyApi()
adapter = DynamicAdapter(
    legacy,
    get_user="fetch_user_data",   # adapter.get_user → legacy.fetch_user_data
    save="save_record"           # adapter.save → legacy.save_record
)

# 客户端使用新接口
user = adapter.get_user(42)
adapter.save(user)

这种动态适配方案的精妙之处在于：适配器甚至不需要预先知道被适配者有哪些方法。`__getattr__`在运行时动态解析，如果目标方法没有在映射表中命中，就直接回退到被适配者的同名方法。这使得适配器可以"透明地"包装任意对象，只在需要接口转换的地方进行映射。

5.2 基于 collections.abc 的接口适配

Python标准库中的`collections.abc`模块定义了各种抽象基类（Abstract Base Classes），如`MutableMapping`、`Sequence`、`Iterable`等。通过继承这些抽象基类并实现必要的方法，我们可以快速将自己的类适配为标准集合接口，从而获得大量免费的功能（如`in`运算符、`.keys()`、`.values()`、`.items()`等）。

from collections.abc import MutableMapping
import json


class ConfigAdapter(MutableMapping):
    """将JSON配置文件适配为字典接口，支持嵌套属性访问"""

    def __init__(self, filepath: str):
        self._filepath = filepath
        with open(filepath, "r", encoding="utf-8") as f:
            self._data = json.load(f)

    # 实现MutableMapping必须的三个核心方法
    def __getitem__(self, key):
        return self._data[key]

    def __setitem__(self, key, value):
        self._data[key] = value
        self._persist()

    def __delitem__(self, key):
        del self._data[key]
        self._persist()

    def __iter__(self):
        return iter(self._data)

    def __len__(self):
        return len(self._data)

    def _persist(self):
        with open(self._filepath, "w", encoding="utf-8") as f:
            json.dump(self._data, f, ensure_ascii=False, indent=2)

    # 扩展：支持属性风格的访问 (config.database.host)
    def __getattr__(self, name):
        if name.startswith("_"):
            raise AttributeError(name)
        try:
            value = self._data[name]
            if isinstance(value, dict):
                return ConfigAdapter._NestedConfig(value)
            return value
        except KeyError:
            raise AttributeError(name)


# 使用：配置文件像普通字典一样使用
config = ConfigAdapter("config.json")
print(config["database"])     # 字典风格访问
print("timeout" in config)   # in 运算符自动可用
for key in config:             # 迭代自动可用
    print(key, config[key])

通过继承`MutableMapping`，我们的`ConfigAdapter`自动从抽象基类继承了`get()`、`pop()`、`update()`、`keys()`、`values()`、`items()`、`__contains__`（即`in`运算符）等一系列方法。我们只需要实现五个核心方法（`__getitem__`、`__setitem__`、`__delitem__`、`__iter__`、`__len__`），就能获得一个完整的字典接口。这本质上是适配器模式的另一种应用——将任意数据源适配为Python标准集合接口。

六、适配器在第三方库封装中的应用

在实际项目中，我们经常需要集成第三方库，而不同库的接口风格差异很大。适配器模式是隔离第三方库依赖、防止供应商锁定的有效手段。

实战案例：统一支付网关

假设我们的系统需要接入两个不同的支付服务商——支付宝和微信支付。它们的接口完全不同，但我们的业务代码希望使用统一的支付接口。

# 统一的支付接口（目标接口）
class PaymentGateway:
    def charge(self, amount: float, currency: str,
                  source: str) -> dict:
        raise NotImplementedError

    def refund(self, transaction_id: str) -> dict:
        raise NotImplementedError


# 第三方支付宝SDK（被适配者）
class AlipaySdk:
    def trade_create(self, total_amount: str,
                       subject: str, buyer_id: str) -> dict:
        return {"alipay_trade_no": "202401011234",
                "status": "success"}

    def trade_refund(self, trade_no: str) -> dict:
        return {"refund_status": "success"}


# 第三方微信支付SDK（被适配者）
class WechatPaySdk:
    def submit_payment(self, fee: int, desc: str,
                        openid: str) -> dict:
        return {"transaction_id": "wx202401011234",
                "result": "ok"}

    def process_refund(self, transaction_id: str) -> dict:
        return {"refund_result": "success"}


# 支付宝适配器
class AlipayAdapter(PaymentGateway):
    def __init__(self, alipay: AlipaySdk):
        self._alipay = alipay

    def charge(self, amount: float, currency: str,
                  source: str) -> dict:
        # 适配：转换参数格式
        resp = self._alipay.trade_create(
            total_amount=str(amount),
            subject=f"支付 {amount} {currency}",
            buyer_id=source
        )
        return {"id": resp["alipay_trade_no"],
                "status": resp["status"]}

    def refund(self, transaction_id: str) -> dict:
        resp = self._alipay.trade_refund(transaction_id)
        return {"status": resp["refund_status"]}


# 微信支付适配器
class WechatAdapter(PaymentGateway):
    def __init__(self, wechat: WechatPaySdk):
        self._wechat = wechat

    def charge(self, amount: float, currency: str,
                  source: str) -> dict:
        # 适配：微信金额以"分"为单位，需要乘以100并取整
        fee_in_cents = int(amount * 100)
        resp = self._wechat.submit_payment(fee_in_cents, desc=currency, openid=source)
        return {"id": resp["transaction_id"],
                "status": resp["result"]}

    def refund(self, transaction_id: str) -> dict:
        resp = self._wechat.process_refund(transaction_id)
        return {"status": resp["refund_result"]}


# 客户端代码：完全不知道底层是哪个支付服务商
def process_order(gateway: PaymentGateway, order):
    result = gateway.charge(order["amount"], "CNY", order["user_id"])
    print(f"支付结果: {result}")


# 切换支付服务商只需更换适配器实例
gateway = AlipayAdapter(AlipaySdk())    # 使用支付宝
# gateway = WechatAdapter(WechatPaySdk())  # 切换为微信支付
process_order(gateway, {"amount": 99.9, "user_id": "user_001"})

这个案例展示了适配器模式的典型价值：业务代码完全被隔离在第三方SDK的细节之外。即使SDK版本升级导致接口变化，我们也只需要修改对应的适配器类，而无需触及上层业务逻辑。同时，这种设计也使得在运行时动态切换支付渠道变得轻而易举。

七、适配器在统一不同数据库API中的应用

适配器模式在实际系统中的一个经典应用场景是统一不同数据库的访问接口。Python生态中有多种数据库驱动，它们的API虽然都遵循DB-API 2.0规范，但具体的使用方式、连接参数、错误处理等方面仍有差异。通过适配器模式可以构建一个统一的数据库访问层。

# 统一数据库接口
class DatabaseAdapter:
    def connect(self) -> None: ...
    def execute(self, sql: str, params: tuple = ()) -> list: ...
    def close(self) -> None: ...


class SQLiteAdapter(DatabaseAdapter):
    def __init__(self, db_path: str):
        self._path = db_path
        self._conn = None

    def connect(self) -> None:
        import sqlite3
        self._conn = sqlite3.connect(self._path)

    def execute(self, sql: str, params: tuple = ()) -> list:
        cursor = self._conn.cursor()
        cursor.execute(sql, params)
        self._conn.commit()
        return cursor.fetchall()

    def close(self) -> None:
        if self._conn:
            self._conn.close()


class MySQLAdapter(DatabaseAdapter):
    def __init__(self, host: str, port: int,
                  user: str, password: str, database: str):
        self._config = {"host": host, "port": port,
                        "user": user, "password": password,
                        "database": database}
        self._conn = None

    def connect(self) -> None:
        import pymysql
        self._conn = pymysql.connect(**self._config)

    def execute(self, sql: str, params: tuple = ()) -> list:
        with self._conn.cursor() as cursor:
            cursor.execute(sql, params)
            self._conn.commit()
            return cursor.fetchall()

    def close(self) -> None:
        if self._conn:
            self._conn.close()


# 业务代码只需面向DatabaseAdapter编程
def get_user_count(db: DatabaseAdapter) -> int:
    db.connect()
    result = db.execute("SELECT COUNT(*) FROM users")
    db.close()
    return result[0][0]


# 开发环境用SQLite，生产环境用MySQL
if __name__ == "__main__":
    # db = SQLiteAdapter("test.db")           # 开发环境
    db = MySQLAdapter("localhost", 3306,
                      "root", "password", "myapp")  # 生产环境
    print(f"用户总数: {get_user_count(db)}")

通过适配器模式封装数据库访问层，我们获得了几个关键好处：第一，开发环境和生产环境可以使用不同的数据库后端，只需替换一行代码；第二，业务逻辑完全与具体的数据库驱动解耦，更换数据库驱动时不需要修改业务代码；第三，统一的接口使得编写数据库无关的测试更加容易——可以创建一个模拟适配器来替代真实数据库。

八、适配器模式与外观模式对比

适配器模式和外观模式（Facade Pattern）都是结构性设计模式，都涉及对已有类的封装，但它们的意图和应用场景有本质区别。初学者经常混淆这两个模式，明确它们的差异非常重要。

核心区别

对比维度	适配器模式	外观模式
核心意图	接口转换：让不兼容的接口协同工作	接口简化：为子系统提供统一的高层接口
解决的问题	已有接口与期望接口不匹配	子系统过于复杂，客户端需要简化调用
变化维度	接口发生变化	子系统的复杂性变化
对客户端的影响	客户端透过适配器看到被适配者的功能	外观隐藏了子系统的细节
设计原则	侧重于接口兼容	侧重于封装和解耦
类比	电源转换插头	酒店前台（你不需要知道客房服务、餐饮、维修的细节）

简单记忆：适配器解决的是"接口不匹配"的问题（不兼容→兼容），外观模式解决的是"接口太复杂"的问题（复杂→简单）。前者改变接口，后者简化接口。

实际区别示例

假设我们需要对接一个第三方数据分析库，它提供了`analyze_csv()`、`plot_data()`、`generate_report()`等十几个方法。如果我们只需要让调用方式符合团队规范（比如统一命名为`run()`），这是适配器模式——接口转换。但如果我们希望用一个简单的`analyze(filepath)`方法隐藏内部所有复杂的分析流程，这是外观模式——接口简化。

适配器模式：接口转换

适配器将旧接口方法重新映射为符合团队命名规范的新接口，但功能一一对应。

外观模式：接口简化

外观将多个子系统方法的调用编排成一个简洁的高层方法，大大减少了客户端的调用负担。

两者也可以协同使用：先用适配器模式将多个第三方库的接口统一为内部标准接口，再用外观模式将这些统一后的接口封装为更易于使用的高层接口。

九、Python中适配器模式的灵活实现

除了经典的类和对象适配器，Python的灵活语法还允许我们用更简洁的方式实现适配器。以下是几种在Python项目中实际有用的适配形式。

9.1 函数适配器

当被适配的功能只是一个函数而不是完整的类时，可以使用函数适配器或闭包来适配。

from functools import wraps
import json


# 需要适配的旧函数——接受XML字符串
def old_data_processor(xml_data: str) -> dict:
    # 假装处理XML并返回结果
    return {"parsed_from": "xml", "length": len(xml_data)}


# 函数适配器：将JSON输入适配为XML输入
def json_to_xml_adapter(func):
    """装饰器形式的适配器：将JSON格式参数转换为XML后调用原函数"""
    @wraps(func)
    def wrapper(json_data: dict, *args, **kwargs):
        # 将JSON dict转换为简易XML
        xml_parts = [f"<{k}>{v}</{k}>" for k, v in json_data.items()]
        xml_str = "<root>" + "".join(xml_parts) + "</root>"
        return func(xml_str, *args, **kwargs)
    return wrapper


# 使用适配器
@json_to_xml_adapter
def process_json_data(json_data: dict) -> dict:
    """这个函数名义上接受JSON，但底层通过适配器调用了旧处理器"""
    return old_data_processor(json_data)


# 客户端使用新接口
result = process_json_data({"name": "测试", "value": "42"})
print(result)

这种"装饰器适配器"的模式在Python中非常实用。当我们需要对整个函数或方法的接口进行适配时，使用装饰器可以避免创建额外的类。这种模式尤其适合适配那些功能简单、接口单一的旧函数。

9.2 属性适配器

有时接口不匹配发生在属性级别的访问上。Python的`@property`装饰器可以优雅地解决这类问题。

# 旧的用户类——使用getter/setter风格
class OldUser:
    def __init__(self, first, last):
        self._first = first
        self._last = last

    def get_full_name(self):
        return f"{self._first} {self._last}"

    def get_initial(self):
        return f"{self._first[0]}.{self._last[0]}."


# 客户端期望的属性风格接口
class UserAdapter:
    """将getter风格适配为属性风格"""

    def __init__(self, old_user: OldUser):
        self._user = old_user

    @property
    def full_name(self) -> str:
        return self._user.get_full_name()

    @property
    def initial(self) -> str:
        return self._user.get_initial()

    @full_name.setter
    def full_name(self, value: str):
        first, last = value.split(" ", 1)
        self._user._first = first
        self._user._last = last


# 客户端使用
old = OldUser("张", "三丰")
adapter = UserAdapter(old)
print(adapter.full_name)  # 属性访问，而非方法调用
print(adapter.initial)

Python的`@property`让属性适配变得极其自然。通过适配器，我们将旧类的`get_full_name()`方法调用转换为了`adapter.full_name`属性访问，满足了客户端对属性风格接口的期望。这种适配方式是Python独有的优雅之处。

十、最佳实践与核心总结

何时使用适配器模式

集成遗留系统： 新旧系统接口不匹配时，用适配器桥接。
封装第三方库： 隔离外部依赖变化，防止供应商锁定。
统一多样接口： 多个类似功能的类接口不统一时，用适配器统一。
渐进式重构： 在不修改现有代码的前提下引入新接口。
测试驱动开发： 适配真实对象到测试替身接口。

设计建议

优先使用对象适配器： 组合比继承更灵活，建议优先选择对象适配器。
接口要小： 适配器的目标接口尽量精简，只包含客户端真正需要的方法。
文档化适配逻辑： 清晰记录适配器内部的转换规则（如单位换算、格式转换）。
考虑使用抽象基类： Python的ABC可以明确目标接口的协议，增强类型安全。
不要过度适配： 如果一个类的接口符合预期，就不需要引入适配器增加复杂性。

常见陷阱

陷阱一（适配器泛滥）： 每个类都写一个适配器会导致代码膨胀。只在接口确实不匹配且无法修改已有代码时使用适配器。

陷阱二（性能开销）： 适配器引入了一层间接调用。在性能敏感的路径中，如果适配逻辑过于复杂（如大量数据格式转换），要考虑性能影响。

陷阱三（忽略鸭子类型）： Python是鸭子类型语言。在某些情况下，如果被适配者已经具备目标接口的所有方法，不需要适配器——直接替换使用即可。

核心要点总结

适配器模式通过中间层解决接口不兼容问题，让原本无法协作的类协同工作。
两种结构：类适配器基于继承，对象适配器基于组合。对象适配器更灵活，是推荐方案。
Python特有方案包括__getattr__动态适配和collections.abc接口适配，充分利用了Python的动态特性。
实际应用包括封装第三方SDK（如支付网关）、统一数据库API（如SQLite/MySQL切换）、适配遗留系统接口等。
与外观模式区别：适配器解决"接口不匹配"（转换接口），外观模式解决"接口太复杂"（简化接口）。
Python灵活实现：可以利用装饰器实现函数级别的适配，利用@property实现属性级别的适配。
最佳实践：组合优于继承，目标接口保持精简，善用但不过度使用适配器。

一句话总结：适配器模式的核心价值在于——在不修改已有代码的前提下，用一个中间层让不兼容的接口能够无缝协作。它完美体现了设计模式中的"开闭原则"：对扩展开放（新增适配器），对修改关闭（不修改已有类）。Python的动态特性使得适配器的实现更加灵活和简洁。