3. SDK基础知识：什么是SDK、SDK与API的关系、RESTful API与SDK的封装
我记得刚开始做集成时，很多人把SDK和API混着叫。开会时有人说“调一下SDK”，又有人说“调一下API”，结果对接时发现说的根本不是一回事。今天我把这三块拆开讲清楚：什么是SDK，它跟API到底啥关系，RESTful API又是怎么被SDK包起来的。
3.1 什么是SDK
说白了，SDK就是一套帮你偷懒的工具箱。全称Software Development Kit，软件开发工具包。你写程序时，有些功能不需要自己从头造轮子——比如跟DSPM系统通信、解析数据包、处理认证——这些事SDK帮你干好了。
一个典型的SDK包含这些部分：
| 组件 | 用途 | 我见过的翻车点 |
|---|---|---|
| 库文件（.jar/.dll/.so） | 编译或运行时链接的代码实体 | 版本不匹配，class找不到 |
| API封装类/函数 | 把底层接口变成你熟悉的编程语言调用 | 返回值类型跟文档对不上 |
| 开发文档 | 告诉你每个函数怎么用、参数含义、示例 | 文档没更新，照着写就报错 |
| 示例代码 | 开箱即用的Demo，帮你快速跑通 | 示例里用硬编码密钥，上线前忘改 |
| 工具链（CLI、代码生成器） | 自动化一些繁琐操作，比如生成客户端桩代码 | 工具生成的代码有缩进混乱的bug |
我在项目中遇到过这种情况：客户拿了一整套SDK，却只用了里面的API封装层，连文档都不看。结果遇到网络重试场景，SDK内部其实已经帮他们处理了，他们自己又写了一套重试逻辑，双重重试把服务打挂了……所以，你拿到一个SDK，至少花半小时读完README和核心类的注释，别想当然。
3.2 SDK与API的关系
好多新人问我：“老师，我直接调API不就行了吗，为啥还要额外装SDK？”
嗯，这个问题很好。我把它们比作两样东西：API是门，SDK是钥匙串加工具箱。
API告诉你门在哪儿、怎么敲门、能拿到什么东西。但你要自己处理钥匙形状、开门姿势、甚至门卡住时怎么踹一脚。SDK呢？它把这些问题全包了——你只需要说“帮我开这扇门”，SDK就把钥匙插好、转一下、门推开，还顺便帮你检查门有没有锁好。
一句话总结： API是抽象接口，SDK是对该接口的具体实现封装，更贴近你写代码的习惯。
用一个表格对比更清楚：
| 维度 | API | SDK |
|---|---|---|
| 本质 | 通信协议接口定义 | 代码工具包 + 文档 + 示例 |
| 使用方式 | 发送HTTP请求、处理响应 | 导入库、调用对象方法 |
| 是否必须 | 是，后端总会暴露一套API | 否，你可以自己写封装层 |
| 学习成本 | 需要理解协议细节（URL、状态码、认证） | 只需要学SDK的方法签名和配置 |
| 灵活性 | 高，你能控制每个请求的每个参数 | 有些SDK抽得太厚，想改底层行为很难 |
| 生产效率 | 低，大量重复代码 | 高，一行调完一个业务动作 |
你想想看，如果DSPM的数据发现API有十几个端点，每个都要处理认证令牌刷新、超时重试、错误码映射……你自己手写封装，三天能写完还不一定对。SDK一装，这些脏活它全干了。我自己的经验是：除非你要做的调用极其简单（比如只调一个状态查询接口），否则优先用官方SDK，省下的时间拿来写业务逻辑才是正事。
3.3 RESTful API与SDK的封装
现在大部分新系统的API都是RESTful风格的。RESTful API基于HTTP，用GET/POST/PUT/DELETE表示操作，返回JSON/XML。这东西设计得挺干净，但直接调嘛……有点烦。
举个例子，你想在DSPM系统里触发一次数据发现扫描：
# 原始REST调用（Python requests）
import requests
url = "https://dspm.company.com/api/v1/scans"
headers = {
"Authorization": "Bearer " + get_(),
"Content-Type": "application/json"
}
payload = {
"target": "s3://my-bucket",
"scan_type": "full",
"callback_url": "https://myapp/callback"
}
resp = requests.post(url, headers=headers, json=payload)
if resp.status_code != 201:
# 你要自己查文档看各个错误码的含义
raise Exception(f"Scan failed: {resp.json().get('error')}")
scan_id = resp.json().get("scan_id")
你看看，这几行代码里有多少坑：令牌过期没人管、网络超时你得自己加、状态码判断要手写、JSON结构错了你还得调试半天。而SDK把这一切都封装成你熟悉的对象调用：
# SDK调用（假设Python SDK）
from dspm_sdk import DSPMClient
client = DSPMClient(
="your-key",
base_url="https://dspm.company.com",
timeout=30 # SDK内部自带重试和超时
)
scan = client.scans.create(
target="s3://my-bucket",
scan_type="full",
callback_url="https://myapp/callback"
)
print(scan.id) # 直接拿对象属性，不用关心底层HTTP细节
看到了吧？SDK帮你把HTTP请求、令牌管理、错误处理全藏到了方法背后。我在写DSPM集成SDK时，特意把RESTful API的封装设计成三层：
- 底层传输层：处理HTTP连接池、重试策略、超时、TLS证书。这一层用户完全不用碰。
- 资源层：把REST端点映射成Python/Java对象（如Scans、Reports），每个对象的方法对应一个HTTP操作。
- 业务层：提供更高级的组合操作，比如“一键发现并报告”，内部会依次调用多个API，你只用花一块钱硬币那么大的功夫。
到这里，我想你已经清楚了SDK、API、RESTful这三者的关系。我画了张图帮你串起来：
这张图把SDK的封装层次和RESTful API的对应关系画出来了。你从最上层调用业务方法，中间经过资源映射和传输层，最后变成RESTful HTTP请求。反过来，API返回的JSON经过传输层解析，一层层往上变成你代码里的对象。
我自己在做DSPM SDK时，核心原则就是：让用户写代码时感觉不到网络的存在。 用户不需要知道端点是POST还是GET，更不需要手动处理401重新获取令牌。这些脏活，SDK内部默默干完就好。
最后补一句：拿到一个SDK后，先看它的错误处理机制。有的SDK把HTTP 4xx全抛成同一个异常，你想区分“资源不存在”和“参数格式错误”就得解析异常消息——这种封装体验就很差。好的SDK会定义多个异常子类，比如NotFoundException、ValidationException，你写catch时直接按类型区分，清爽得很。