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