加一层轻量适配器是可行做法：不改旧逻辑，只做参数、返回值和异常的精准对齐；明确目标接口、被适配者、适配器三角色；用组合而非继承；处理三类不匹配；增强可观测性与可切换性。
直接在业务代码里硬套老接口调用，会把系统拖进维护泥潭。真正可行的做法，是加一层轻量适配器：不碰旧逻辑、不改已有流程，只做参数、返回值和异常的精准对齐。
先分清三个角色，别一上来就写类
目标接口是你新系统正在用的标准契约，比如 UserQueryService.queryById(String id)；被适配者是第三方或遗留模块提供的原始能力，比如 LegacyApi.fetchUser(long userId)，参数类型、返回结构、异常都不同；适配器就是个普通 Java 类，实现目标接口，内部持有被适配者实例，专干“翻译”活——不是改它，而是让它能被新系统自然调用。
用组合，别用继承
适配器类里声明一个私有字段，类型是被适配者的具体类（如 private final LegacyApi legacyApi），构造时注入实例。这样单元测试可以直接 mock 它，上线后也能快速切换实现。避免继承被适配者类，它可能带状态、有副作用，还限制后续扩展。
重点处理三类不匹配
- 参数不匹配：目标传对象，老接口只收字符串 → 适配器从中提取字段，做非空校验和格式转换
- 返回值不匹配：老接口返回 Map 或 JSON 字符串，目标要 VO 对象 → 适配器做字段映射、空值兜底、时间戳转 LocalDateTime 等类型转换
- 异常语义不一致：老接口抛 IOException 或自定义异常，业务层统一捕获 BizException → 适配器在 try-catch 中完成异常翻译，不向上暴露底层细节
让适配行为可观察、可切换
上线后不能变黑盒：
- 关键路径加日志，标记 “via LegacyUserAdapter”，方便链路追踪
- 用配置开关控制启用（如 feature.legacy-user.enabled=true），灰度期可秒级回退
- 对外暴露健康检查方法（如 isLegacyBackendHealthy()），供监控系统采集
后续老服务下线，只需替换或删除适配器，业务代码完全不动。
Java免费学习笔记：立即使用
解锁 Java 大师之旅：从入门到精通的终极指南
