第1章 SDK集成概述：概念、方式与排查哲学
大家好，我是老李。在这行摸爬滚打了十来年，跟SDK打交道的时间估计占了一半。今天咱们来聊聊SDK集成这件事。说白了，SDK就是别人写好的一堆代码，打包成工具包，让你能快速调用一些复杂功能——比如支付、地图、推送、登录。
1.1 到底什么是SDK？
SDK的全称是Software Development Kit——软件开发工具包。我个人习惯把它理解成“积木盒”。
你想盖房子，不用从烧砖开始吧？拿现成的积木拼就好。SDK就是那些积木块。我刚开始做移动端开发时，也以为SDK是什么玄乎的东西，后来发现其实就是.jar、.aar、.framework、.dll这些文件，外加一份文档。
为什么要用SDK？原因很简单——省时间。
- 你不需要自己写一套支付协议
- 你不需要自己对接几十家银行
- 你不需要自己搞推送长连接
嗯，直接用SDK，几天就搞定。
1.2 集成方式：三种主流路子
说到集成，我经历过最原始的做法——手动下载jar包，丢进libs文件夹。现在想想，那简直是刀耕火种。目前主流的集成方式有三种，我列个表对比一下。
| 集成方式 | 典型做法 | 优点 | 缺点 |
|---|---|---|---|
| 手动集成 | 下载aar/jar/framework，复制到项目 | 完全可控，不依赖网络 | 升级麻烦，容易遗漏文件 |
| 包管理器集成 | Gradle/Maven/CocoaPods/npm一行配置 | 自动处理依赖，轻松升级 | 容易产生依赖冲突 |
| 通过脚手架集成 | 使用SDK提供的CLI工具一键接入 | 最省事，自动配置 | 黑盒操作，出了问题难排查 |
我个人更喜欢用包管理器。举个例子，Android集成某个推送SDK，你只需要在build.gradle里加一行：
implementation 'com.example.push:sdk:2.1.0'搞定。但有一次我接手一个项目，发现里面同时引用了同一个SDK的两个版本——嗯，这就要说到报错了。
3. 常见报错分类
报错千千万，但万变不离其宗。我归纳了一下，SDK集成报错基本就这四类。
3.1 依赖冲突
这是最常见的一种。比如你的项目用了okhttp:4.9.0，SDK用了okhttp:3.12.0，两个版本不兼容，运行时就崩了。
报错信息通常长这样：
Duplicate class okhttp3.internal.http2.ErrorCode
...怎么解决？我曾在项目中手写了一份依赖排除规则，后来发现直接用force或exclude更省事。
3.2 版本不兼容
SDK的API变了，你的代码没跟上。或者SDK要求最低API 21，你项目里却用了API 16的特性。
3.3 混淆规则
开启ProGuard后，SDK里的一些类被混淆了，运行时反射找不到。
我记得有个客户，集成我们的支付SDK，一支付就闪退。查了半天，发现是混淆配置里没有加-keep class * extends ...。
3.4 权限与清单配置
SDK需要在AndroidManifest.xml里声明权限，或者在Info.plist里加白名单。少一个都不行。
SecurityException。为什么？因为Android 6.0+需要运行时申请权限，仅声明是不够的。
4. 排查思路：别慌，一步步来
遇到报错，很多同学的第一个反应是“怎么回事？怎么办？要不重启一下？”
嗯，其实有套路。
- 看日志：先看堆栈，找到第一行自己项目里的代码。SDK内部的异常通常不用细看。
- 定位类型：是编译报错？运行时崩溃？还是功能异常？
- 查文档：SDK官方文档里，通常都会有常见问题列表。别自己闷头瞎试。
- 隔离验证：新建一个空工程，只集成这个SDK。如果能跑，说明是你的项目环境有问题。
- 看版本号：是不是最新版？旧版有没有已知Bug？
我曾经被一个Bug卡了两天——集成的SDK总是初始化失败。最后发现，是因为我把Application类里的onCreate写了个空回调，把SDK的初始化线程卡死了。
你想想看，这种问题，看堆栈根本看不出来。
5. 本章知识体系总览
下面这张图，是我为你梳理的本章脉络。它把SDK的概念、集成方式、报错分类和排查思路串在了一起。你后面每学完一章，都能回来对照这张图。
做集成开发，最怕的是遇到报错就慌。我见过不少同事，一报错就去问别人，连日志都没看。其实，你自己能解决大部分问题。
记得有一次，我在排查一个支付SDK的初始化失败问题。日志里只有一句话：“initialize failed: -1”。你说这什么玩意儿？后来我打开SDK的源码一看，发现-1代表“网络未连接”。
嗯，所以说，报错处理本质上是用经验+方法论去对抗未知——而这一章，就是给你那个方法论。