如何使用Java适配器模式将旧版接口无缝接入全新业务系统

直接在业务代码里硬套老接口调用，迟早会把系统拖进维护泥潭。别急，这事有更好的解法——加一层轻量适配器就行。不改旧逻辑、不动已有流程，只做三件事：参数、返回值和异常的精准对齐。说白了，就是让老接口“假装”自己是新接口，两边都能舒舒服服干活。

咱们先搞清楚三个角色，别一上来就闷头写类。目标接口是你新系统正在用的标准契约，比如 UserQueryService.queryById(String id)；被适配者通常是第三方或遗留模块提供的原始能力，比如 LegacyApi.fetchUser(long userId)，参数类型、返回结构、异常处理都可能跟新系统不一样；适配器就是个普通 Ja va 类，它实现目标接口，内部持有被适配者的实例，干的全是“翻译”活——不是改它，而是让它能被新系统自然调用。

用组合，别用继承

适配器类里声明一个私有字段，类型是被适配者的具体类（比如 private final LegacyApi legacyApi），构造时注入实例。这样一来，单元测试可以直接 mock 它，上线后也能快速切换实现。为什么不用继承？继承被适配者类风险不小——它可能带着状态、有副作用，还会给后续扩展设限。

重点处理三类不匹配

• 参数不匹配：目标接口传的是对象，老接口只认字符串 → 适配器从中提取字段，做非空校验和格式转换
• 返回值不匹配：老接口返回 Map 或 JSON 字符串，目标要的是 VO 对象 → 适配器做字段映射、空值兜底、时间戳转 LocalDateTime 等类型转换
• 异常语义不一致：老接口抛出 IOException 或自定义异常，业务层统一捕获 BizException → 适配器在 try-catch 中完成异常翻译，不让底层细节冒到上层

让适配行为可观察、可切换

上线之后不能变黑盒，得留几个心眼：

• 关键路径加日志，标记 “via LegacyUserAdapter”，方便链路追踪
• 用配置开关控制启用（比如 feature.legacy-user.enabled=true），灰度期如果出问题，能秒级回退
• 对外暴露健康检查方法（比如 isLegacyBackendHealthy()），供监控系统采集

等哪天老服务正式下线，只需要替换或删除适配器就行，业务代码完全不用动。