封装第三方sdk的核心是建立可控边界，定义业务语义接口（如loginservice）、用适配器封装实现、统一dto与异常、支持灰度兜底，并通过maven合理打包交付。
封装第三方 SDK 的核心不是“包一层”，而是建立一道可控的边界——让业务代码只和稳定、语义清晰、可演进的接口打交道，把所有变化、异常、版本差异都锁在边界之内。
定义业务语义接口，不暴露 SDK 细节
不要让调用方看到 AlipayClient、WxPayService 这类技术名称。按真实场景抽象接口，比如：
- LoginService：含 login(String code)、logout()，隐藏 OAuth 流程与 token 刷新逻辑
- OcrProcessor：含 recognize(ImageData image)、getStatus(String taskId)，屏蔽 v1/v2 路径、签名、base64 编码等差异
- PushChannel：含 sendToUser(String userId, PushPayload payload)，统一处理华为/小米/FCM 多通道适配
接口方法名体现“做什么”，而非“怎么调”。一旦定下，就尽量保持不变——变的是内部实现，不是契约。
用适配器封装 SDK 实现，输入输出全走自定义 DTO
新建 AlipayAdapter、WechatPayAdapter 等具体实现类，它们：
- 私有字段持有原始 SDK 客户端实例（如 AlipayClient），不做 public 暴露
- 构造时完成 SDK 初始化（单例、region、endpoint、签名密钥等），支持多种方式（配置中心、Spring Bean、Builder）
- 所有入参用你定义的 OrderRequest、RefundRequest 等 DTO，不接收 SDK 原生 Request 对象
- 所有出参返回 Result
、ApiResponse 等统一封装，不直接返回 AlipayTradePayResponse
这样即使 SDK 升级后返回结构从 {"code":0,"msg":"ok"} 变成 {"data":{"order_id":"xxx"},"status_code":200}，只需改适配器内的 JSON 解析逻辑，上层完全无感。
把风险收口到适配器内，支持灰度与兜底
一个健壮的适配器不止做转换，还要承担以下职责：
- 多版本共存：用策略模式（如 PayStrategyV1 / PayStrategyV2），通过租户 ID 或配置开关决定走哪条路径，便于灰度验证
- 并发控流：对不可重入 SDK，用 Semaphore 控制并发数，且只在真正成功响应后 release，避免限流失效
- 异常归一化：捕获 SocketTimeoutException、JSONException、SDK 自定义异常，统一转为 PaymentNetworkException、OcrServiceUnavailableException 等业务异常
- 软隔离退出行为：若 SDK 可能触发 System.exit()，在适配器执行前安装 SecurityManager 拦截，并用 try-catch 做恢复（注意 Java 17+ 已弃用，生产环境建议子进程隔离）
交付时用 Maven 合理打包，避免依赖泄露
组件发布为独立 artifact（如 com.company.payment:alipay-adapter:2.1.0），关键点：
- build.gradle 中对 SDK 依赖使用 api 声明（不是 implementation），确保下游能安全引用其类型（如需扩展回调）
- 主应用只需引入该 adapter，无需重复声明 com.alipay.sdk，Gradle 自动传递并仲裁版本
- 必要时用 Maven Shade Plugin 重定位底层冲突依赖（如 guava），避免与宿主工程冲突
不复杂但容易忽略
Java免费学习笔记：立即使用
解锁 Java 大师之旅：从入门到精通的终极指南
