设计模式之适配器模式：接口转换原理与工程实战应用

如果你在公司里对接过第三方支付、老一套订单系统、新上线的中台服务，大概率经历过这种尴尬：两个模块接口长得完全不像，业务逻辑又没法改，改老代码怕炸，强改新系统又不合理。最后要么在调用方写一堆 if-else 解析，要么复制一份转型逻辑。这个场景，其实就是适配器模式（Adapter Pattern）最经典的出场时机。设计模式系列写到第七篇，今天不绕弯子，直接聊适配器模式：它解决什么问题、三种实现形态该怎么选、在真实项目和 Android 源码里怎么用，以及我实际踩坑后的一些取舍建议。

适配器模式算是我个人使用频率最高的结构型模式之一。它不像工厂、单例那样被天天挂在嘴边，但几乎每个中型项目里都能找到它的影子。它的核心思想听起来特别朴素：把一个类的接口转换成客户端期望的另一个接口。说得再直白一点，就是给两个“方言不通”的模块请一个翻译官。这个翻译官不改变业务逻辑，只负责把一方说的话翻译成另一方听得懂的话。我接触适配器模式多年后最大的感受是：这个模式好不好用，关键不在于记不记得定义，而在于你能不能快速判断，现在这个“不匹配”到底应该由谁来负责适配。

1. 没有适配器之前，接口不匹配的现场有多惨

1.1 从电源转换头看适配器的本质

我先用一个生活里的例子把调性定下来。你从国内带了一个两脚插头的笔记本充电器去国外出差，酒店墙上是三脚圆孔的插座，这时你会怎么办？你不会去改充电器的电路，也不会拆墙换插座，而是找一个转换头，一头插充电器，一头插墙上的插座。转换头做的事就是适配：它不发电，不变压，只改变物理接口的形态，让两个原本无法直接连接的设备协同工作。

代码里的适配器就是这个转换头。它可能有自己的内部逻辑，比如把 A 接口返回的 XML 转换成 B 接口需要的 JSON，把 A 类的同步方法包装成 B 接口想要的异步回调，但本质上它做的事和电源转换头一模一样。理解了这一点，就不容易把适配器和其他模式搞混。例如你为了扩展功能而包一层类，那是装饰器；为了让外部能访问内部子系统而建一个统一入口，那是门面；而适配器非常单纯：让两个已经存在、但接口不匹配的模块能合作。它不增加新功能，也不隐藏整个子系统，只是做接口之间的“翻译”。

1.2 没有适配层，调用方会变成什么样

我见过太多没有适配层的历史代码。最典型的情况是：新系统定义了一个 UnifiedOrderService，接口方法返回结构化的 OrderInfo 对象；老系统里只有一个 XmlOldOrderService，方法是 String fetchXmlOrder(String orderId)。如果直接在业务代码里去对接老系统，会发生什么？

字段解析、状态码映射、异常转换、日志格式定制，这一大坨解析逻辑会全部散落在业务层。更麻烦的是，这种代码通常不是一个地方需要，而是十几个调用点各写一遍。一旦老系统的字段名改了，你要在这十几个地方同时修改；一旦发现解析逻辑有 bug，排查范围遍布整个项目。业务的本质需求其实很简单：给我一个订单对象。结果因为接口不匹配，调用方被迫了解了 XML 的标签结构和解析细节，这就是典型的耦合失控。

适配器模式的引入方式很直接：定义一个客户端真正需要的目标接口，写一个适配器实现这个接口，内部持有老系统的服务，在调用时完成翻译。调用方只依赖目标接口，完全不感知老系统存在。后续哪怕把老系统替换成新服务，只要适配器的实现变了，业务代码一行都不用动。

2. 类适配器、对象适配器和接口适配器：三种形态怎么选

2.1 对象适配器：组合优先于继承的默认答案

适配器模式最常用的实现是对象适配器，也就是通过组合关系持有被适配者的引用。我用一个订单对接的场景举例：

java复制// 客户端真正需要的目标接口
public interface UnifiedOrderService {
    OrderInfo queryOrder(String orderId);
}

// 老系统：只提供 XML 订单接口
public class XmlOldOrderService {
    public String fetchXmlOrder(String orderId) {
        return "<order><id>1001</id><status>PAID</status><amount>199</amount></order>";
    }
}

// 适配器：翻译 XML 到统一订单模型
public class XmlOrderAdapter implements UnifiedOrderService {
    private final XmlOldOrderService oldService;

    public XmlOrderAdapter(XmlOldOrderService oldService) {
        this.oldService = oldService;
    }

    @Override
    public OrderInfo queryOrder(String orderId) {
        String xml = oldService.fetchXmlOrder(orderId);
        // 这里做 XML 解析和字段映射
        OrderInfo order = new OrderInfo();
        order.setId(parseValue(xml, "id"));
        order.setStatus(parseValue(xml, "status"));
        order.setAmount(new BigDecimal(parseValue(xml, "amount")));
        return order;
    }

    private String parseValue(String xml, String tag) {
        // 极简解析，真实项目建议使用成熟的 XML 工具
        String openTag = "<" + tag + ">";
        String closeTag = "</" + tag + ">";
        int start = xml.indexOf(openTag) + openTag.length();
        int end = xml.indexOf(closeTag);
        return xml.substring(start, end);
    }
}

这种实现为什么是默认答案？因为它只依赖被适配者的公开方法，不需要继承老类，也就不会被子类继承的负担和私有字段问题缠住。同时，适配器可以通过构造方法动态传入不同的被适配者实现，灵活性很高。如果你在 Spring 工程里，可以把适配器注册成一个 Bean，在配置阶段指定它包装哪个老服务实例，后续切换实现非常方便。我在实际项目里，95% 以上的适配器都写成了这种形态。

2.2 类适配器：多重继承场景下的特殊手段

类适配器通过继承被适配类、同时实现目标接口来完成适配。在支持多重继承的语言里，它的写法长这样：

cpp复制// 目标接口
class Target {
public:
    virtual void request() = 0;
};

// 老接口：实际提供一个 specificRequest 方法
class Adaptee {
public:
    void specificRequest() {
        // 原始实现
    }
};

// 类适配器：继承老类，同时实现目标接口
class Adapter : public Target, private Adaptee {
public:
    void request() override {
        specificRequest();
    }
};

类适配器的优势是无需再组合一个被适配者对象，可以直接访问被适配者的 protected 方法，甚至在某些情况下重写它的行为。但它的代价也很明显：适配器和被适配者之间是强绑定关系，一旦被适配者不是一个可继承的类，或者它的构造方法需要复杂参数，这条路就不好走；而且 Java、C# 这类单继承语言很难用纯粹的类适配器适配一个具体的旧类。除非你需要重写被适配者内部逻辑，否则我不建议优先选择它。类适配器更像是理论完整性的补充，在实际业务里出现频率远低于对象适配器。

2.3 接口适配器：把不需要的方法空实现掉

第三种常见形态叫接口适配器，也叫缺省适配器。它主要用于“一个接口方法太多，而调用方只关心其中几个”的情况。比如你定义一个文件操作接口，里面有上传、下载、删除、移动、复制五个方法，但某个仅需要上传功能的调用方如果直接实现接口，就得把其他四个方法都写上。这时可以写一个抽象类，把五个方法全部空实现，让调用方只重写需要的方法：

java复制public interface FileOperator {
    void upload(String file);
    void download(String file);
    void delete(String file);
    void move(String src, String dest);
}

public abstract class FileOperatorAdapter implements FileOperator {
    @Override public void upload(String file) { }
    @Override public void download(String file) { }
    @Override public void delete(String file) { }
    @Override public void move(String src, String dest) { }
}

// 使用方只需要实现自己关心的 upload
public class UploadOnlyOperator extends FileOperatorAdapter {
    @Override
    public void upload(String file) {
        // 真正的上传逻辑
    }
}

这样的好处是调用方不需要关心它当前不用的方法，新增接口方法时，也只需要在适配器抽象类里补一个空实现。不过要注意，空实现本身是一种“沉默的纵容”：如果调用方误用了一个没有真正实现的方法，它会静默失败，调试时容易出现“为什么没反应”的困惑。所以接口适配器更适合用于临时平滑实现、给调用方提供选择余地，不适合作为长期主线；一旦调用方明确需要的功能增多，还是应该拆成更小的接口。

三种形态对比下来，选择规则其实很清晰：

3. 从 Android 源码到多 Agent 编排：适配器的应用视野

3.1 RecyclerView.Adapter：Android 开发者最熟悉的适配器

Android 开发者第一次接触“适配器”大概率不是从设计模式书里，而是从 RecyclerView.Adapter 开始。很多人只把它当做一个必须继承的基类，却没意识到它本质上就是一个典型的适配器模式实现。

RecyclerView 作为客户端，并不关心你的数据是 List<User>、List<Order> 还是 Cursor 里的查询结果，它只认 ViewHolder 和 onBindViewHolder 这套接口。RecyclerView.Adapter 在这里扮演的就是“翻译官”：它把开发者自定义的数据模型，翻译成 RecyclerView 能理解的列表项数量 getItemCount()、视图类型 getItemViewType() 和视图绑定操作。你换数据库、换接口返回类型，只要改写 Adapter 内部实现，RecyclerView 本身完全不需要动。我在早期写 Android 时总把业务逻辑塞进 Adapter，后来才意识到，Adapter 的正确用法是只做“数据到视图的适配”，业务判断应该放在外面，这样列表项复杂了也容易维护。这一段的理解很关键，因为你不是在“继承一个框架类”，而是在实现一个针对特定数据的适配器。

3.2 Spring MVC 和 API 网关里的调度器适配

再往框架层看，适配器模式更是被大量藏在了源码深处。Spring MVC 里有一个经典组件 HandlerAdapter，它的职责就是让 DispatcherServlet 以一个统一的 handle() 方法调用不同类型的处理器。你写的是注解版的 @Controller，还是老式的 Controller 接口实现，又或是 HttpRequestHandler，DispatcherServlet 根本不管，它只拿到适配器，让适配器去调用具体处理器。这个设计让 Spring MVC 能够支持多种处理器风格，而核心调度逻辑不用跟着每种风格变。

微服务网关里的“协议转换插件”也是差不多的思路：上游可能是 HTTP 接口，下游可能是 Dubbo 接口、gRPC 接口。网关在中间做一层适配，把 HTTP 请求翻译成下游协议能理解的数据。如果你在公司内部维护过这类网关，就会深有体会：协议越来越多，如果每个新协议都让调用方去适配，整个调用链会迅速混乱。相反，在网关内部用适配器封装老协议，业务方永远只面向统一 API，这就是适配器模式在架构层面的价值。

3.3 新趋势：多 Agent 编排里的“另类工具”

最近两年的多 Agent 设计越来越多，有一个现象很有意思：很多框架在处理主 Agent 和子 Agent 协作时，会把 subagent 包装成一个“另类的 tool”交给主 Agent 统一调度。为什么这么做？因为主 Agent 的工具调用协议是固定的，比如工具名加参数字典，子 Agent 的输入输出却各有各的结构。直接让主 Agent 理解每个子 Agent 的独特交互方式，Prompt 和代码都会变得很难维护；而把子 Agent 的调用过程封装进一个统一的工具接口，让主 Agent 像调用普通工具一样去调用它，本质上就是适配器思想在 AI 编排层的延伸。

我自己在做一个内部知识库助手时就有类似体验。早期主 Agent 直接调用各种子 Agent，每个子 Agent 对外暴露的函数签名都不同，主 Agent 的 system prompt 里要写一大堆“什么时候调用谁”。后来我把子 Agent 都包成了统一的 search_agent、summary_agent 工具，主 Agent 只按“工具名 + 参数”的协议去选择。代码更收敛，后续新增子 Agent 时，主 Agent 的调度核心完全不用改，只需要注册一个新工具适配器。这提醒我，设计模式从来不只是老语言里的八股，它的思想在新架构里依然反复出现。

4. 实战：订单状态同步模块从 XML 到 JSON 的适配改造

4.1 先定义调用方真正需要的目标接口

光讲理论和源码还不够，我拿一个前不久做的适配器改造案例完整走一遍。场景是这样：一个订单系统需要从老订单服务同步订单状态，老服务对外暴露的是 String fetchXmlOrder(String orderId)，返回 XML 字符串；新的风控和财务系统只吃结构化的 OrderInfo JSON。理想情况显然是让老服务增加一个 JSON 接口，但那要排期，还要牵扯老团队改造，短期不现实。于是我在中间加一个适配层。

第一步不是写转换代码，而是先定义客户端真正需要的目标接口。这个接口要站在调用方的角度去设计，不能照抄老服务的方法名，否则适配器就只是“披着新壳的旧方法”。我最终定义的是：

java复制public interface OrderQueryService {
    OrderInfo queryOrder(String orderId);
}

为什么只返回一个 OrderInfo？因为调用方关心的就是“根据订单号拿到订单状态”，XML、JSON、内部字段叫 order_no 还是 orderId，都不该让它知道。目标接口越贴近业务语义，适配器的价值越大；如果目标接口定义得像老接口的翻版，以后替换实现时反而会限制新实现。

4.2 把老接口包装成新接口

目标接口确定后，适配器就变得顺理成章。我新建了一个 XmlOrderQueryServiceAdapter，实现 OrderQueryService，内部注入老的 XML 服务。核心逻辑就是把老字段名映射成调用方关心的字段，并且处理好状态码翻译。这里有两个细节我想强调。

字段映射不是简单的一一对应，往往需要加一层业务规则。比如老系统返回状态 1 表示“已支付”，2 表示“已退款”，但新系统里统一用枚举 OrderStatus.PAID、OrderStatus.REFUNDED，适配器内部必须维护这张映射表，并且对未知状态做兜底处理而不是直接抛空指针。另一个细节是异常处理。老服务如果网络超时或返回非法 XML，适配器不能把这个低级异常裸抛给上层，要翻译成调用方认知范围内的异常类型，不然业务方会哭的。

实现完毕后的调用方式：

java复制OrderQueryService orderQuery = new XmlOrderQueryServiceAdapter(new XmlOldOrderService());
OrderInfo info = orderQuery.queryOrder("1001");

调用方根本不知道老服务的存在。以后老服务如果下线，我只需要写一个 NewOrderQueryServiceAdapter，注入新服务实现，把改造点圈定在适配器内部。用四个字来形容这个改造效果，就是“局部替换”。

4.3 为什么选择对象适配器而不是直接改造老代码

在这个案例里我坚决用了对象适配器，而不是去修改老服务，也不是用类适配器。理由有三：

第一，老服务被其他老模块大量依赖，直接改它的返回格式是高风险动作，谁也不能保证没有隐藏调用方。适配器把影响范围压缩到最小。第二，老服务用 XML 返回，解析过程占用了较多逻辑，适配器可以将解析、映射、异常转换集中管理，后续测试只需要针对适配器做单测。第三，对象适配器允许我在不同环境注入不同实例。本地联调用 mock 服务，测试环境接测试服务，生产接生产服务，这种灵活性是修改老代码很难得到的。

如果这时候因为嫌“多写一个类”而直接在业务代码里解析 XML，短期写起来是快，但后期三个月的维护成本会远超写适配器的半小时。这也是我一直坚持的观点：适配器的成本在人月里几乎可以忽略，它买的其实是未来半年到一年的变更安全。

5. 适配器不是万能包装纸：和代理、装饰器、门面的边界

5.1 四种“包装者”到底谁是谁

很多初学者学会了适配器，看到任何包一层的代码都喊适配器，这是个大坑。设计模式里同样表现为“包在目标外面”的模式还有好几个，但它们想解决的问题完全不同。

代理模式（Proxy）的核心是控制访问，它强调在调用目标前后插入权限校验、延迟加载、远程通信等控制逻辑，而不改变接口本身；装饰器模式（Decorator）的核心是增强功能，它和代理一样保持原接口，但在方法调用前后动态叠加额外行为，比如加缓存、加日志；门面模式（Facade）的核心则是简化调用，它把子系统背后一整套复杂交互收口成一个简单入口。适配器模式和它们的核心差异，一句话就能说清：适配器必须改变接口形态，它要让客户端看到的接口和被适配者原本暴露的接口不一样；如果接口形状没有变化，只是加了控制、加了增强或做了一站式封装，那就不该叫适配器。

画成一张表更直观：

5.2 什么时候别硬上适配器

还有一类情况，其实根本不需要适配器。比如你正在开发一个全新的微服务，接口从一开始就是你自己设计，完全可以通过调整参数、统一 DTO 来避免不匹配，这时候引入适配器就是过度设计。适配器的最好使用场景是“既有代码不能改或不想改，而新的调用方又希望统一”。如果两侧代码都在你手里且可以低成本修改，优先改源头，而不是包一层又一层。

另一个信号是“为了适配而适配”。我有一次在代码评审里看到，有人给同一份数据模型同时又写了对象适配器、又写了接口适配器，最后绕了一圈，返回结果和不用适配器时完全一样。这说明没有真实的不匹配问题存在。适配器模式应该由接口冲突驱动，而不是由“我想展示设计模式”驱动。判断标准很简单：你把适配器删掉，调用方是否会被迫去了解另一个模块的细节？如果有，那适配器值得；如果没有，删掉它。

另外，适配层也不是越多越好。如果一个系统里出现了几十个适配器，而且彼此互相适配，说明系统架构已经出现了分裂症状。你真正要做的可能不是继续加适配器，而是找机会统一核心模型。适配器解决局部问题，不能掩盖全局设计问题。

6. 适配器模式实战中我踩过的几个坑

6.1 无脑为每个接口建一个 Adapter 类

最早我刚学会适配器模式时，特别喜欢到处建 XxxAdapter，项目里十几二十个适配器，看起来很“整洁”。结果代码量膨胀不说，每次修改模型都要连跳五六层。后来我想明白一个问题：适配器的粒度应该跟着业务接口走，而不是跟着“感觉不匹配”走。只有确实两个接口无法直接对接，且需要长期共存的场景，才值得专门建一个类。如果只是单次数据转换，直接写一个工具方法或转换函数就够了，过度封装反而会让新同事看不懂代码在做什么。

6.2 适配器里藏着大量解析逻辑却没人测试

适配器看起来是个薄薄的转换层，但实际业务里它经常变成最容易藏 bug 的地方。很多人的适配器类里包装了解析方法、日期格式化、金额单位换算、字段校验一堆逻辑，却没有对应的单元测试。一旦老系统上线后返回了一个新字段或变更了日期格式，适配器会在某个深夜直接抛异常，而你连出问题的是哪一层都很难定位。

我的习惯是给适配器写独立单测，尤其是对字段映射和异常分支做覆盖。测试用例里准备几种典型老接口返回值，包括正常字段、未知状态码、非法日期等，保证适配器每次改动都能快速回归。这个方法帮我避过很多次线上事故，也是我想特别提醒的一点：适配器是多个系统的交汇点，它对异常的吞噬和翻译能力，直接影响整条链路的稳定性。

6.3 忽略批量接口和分页场景的适配陷阱

还有一次我在做批量订单同步时踩了坑。老服务没有批量查询接口，我当时的适配器直接在 queryOrders 方法里循环调用老接口的单个查询。小批量时没啥问题，一旦订单量上到几千，接口响应越来越慢，最终把老服务拖垮。后来我才意识到，适配器不仅要适配“接口形态”，还要适配数据交换的频率和批量限制。如果老接口只支持单笔查询，适配器应该在内部做分批或缓存合并，而不是把压力原封不动透传。设计适配方案时，别只盯着字段翻译，要把时序、批量、流控这类非功能性因素一起考虑。这也是业务型适配器和书本示例最大的区别。

6.4 适配器名字起得太随意

最后说一个特别小的细节：命名。很多人写适配器喜欢用 Adapter 后缀，但对象适配器内部具体包装的是谁，在类名里完全看不出来。例如 OrderAdapter 到底是把 OldOrder 适配成 NewOrder，还是把 Order 适配成 OrderView？建议命名时明确写出两侧语义，比如 XmlOldOrderToOrderInfoAdapter，虽然长，但看代码的人能立刻明白。如果类名是 OrderAdapter，未来你大概率需要通过阅读整个类实现才能确定它的职责。代码是写给人维护的，适配器又是一个频繁被修改的位置，名字含糊会给后人留下很多头疼时刻。

适配器模式看起来是所有设计模式里最好讲的模式之一，因为它太贴近生活。但越是简单的模式，在实际工程里越容易被误用或滥用。说到底，适配器的存在是为了在不稳定和不一致之间建立缓冲区，让系统在不断变化时还能保持局部稳定。我每次需要对两个接口做翻译时，都会先回到最原始的问题：调用方到底需要怎样的接口？谁负责变成那个样子？答案想清楚了，适配器自然会出现在合适的位置。