API 与 SDK 的异同

qinqinzhang
3 阅读5分钟

这是一个非常经典的问题。SDK 和 API 是两个紧密相关但层次不同的概念。

简单来说：API 是“接口”，SDK 是“工具箱”。

一、核心区别

维度APISDK
全称Application Programming InterfaceSoftware Development Kit
中文应用程序编程接口软件开发工具包
本质一套调用规范/协议一套完整的开发工具集合
包含内容接口定义、请求/响应格式、协议代码库、文档、示例、调试工具、编译器等
使用方式发送 HTTP 请求或调用函数引入依赖、调用封装好的方法
粒度细粒度（单个功能）粗粒度（整套解决方案）
上手难度低（知道怎么调用就行）中（需要理解整体架构）

二、打个比方

想象你要在餐厅吃一顿饭：

  • API = 菜单

    • 菜单告诉你：有什么菜、价格多少、怎么点
    • 你只需要按菜单下单，不需要知道后厨怎么做

  • SDK = 外卖厨房全包服务

    • 不仅给你菜单
    • 还给你锅、灶台、食材、食谱、甚至厨师指导
    • 你可以直接开火做饭，不用自己去买厨具和调料

三、技术层面的区别

API 是什么？

API 是一套预先定义好的接口规范，告诉开发者：

  • 可以调用哪些功能
  • 需要传什么参数
  • 会返回什么数据
  • 用什么协议/格式
// 这是一个 REST API 的调用示例
GET /api/users/123
Authorization: Bearer token

// 返回
{
  "id": 123,
  "name": "张三",
  "email": "zhangsan@example.com"
}

API 的特点：

  • 通常是网络请求（HTTP/REST、GraphQL、gRPC）
  • 与语言无关（任何语言都能调用）
  • 只定义“能做什么”，不提供具体实现工具

SDK 是什么？

SDK 是一个工具包，封装了调用 API 所需的全部能力：

// 这是 SDK 的使用示例（如微信支付 SDK）
const payment = new WechatPay({
  appId: 'xxx',
  secret: 'xxx'
});

// SDK 内部帮你处理了签名、加密、请求、重试等
const result = await payment.createOrder({
  amount: 100,
  description: '测试订单'
});

SDK 通常包含：

  • 封装好的代码库（Java、Python、JavaScript 等）
  • 认证/签名逻辑
  • 请求封装和错误处理
  • 数据模型定义
  • 示例代码和文档
  • 调试工具

四、对比表格

对比项APISDK
形态接口文档 + 网络端点代码包（npm/maven/pip 安装）
语言依赖语言无关特定语言（Java SDK、Python SDK）
封装程度低（需要自己处理 HTTP、认证）高（开箱即用）
集成成本中等（需要写 HTTP 请求代码）低（引入依赖，调用方法）
维护责任调用方自己处理细节SDK 提供方负责封装和维护
灵活性高（可以自由控制请求）中（受 SDK 设计限制）

五、应用场景

API 的典型应用场景

场景说明
跨平台服务服务需要被多种语言/平台调用（如微信登录、支付宝支付接口）
开放平台对外开放能力，让第三方开发者集成（如 GitHub API、OpenAI API）
微服务间通信后端服务之间通过 REST/gRPC 交互
前端调用后端前端直接 fetch/axios 调用后端接口

举例：

  • 支付宝支付 API：任何语言都可以发 HTTP 请求调用
  • OpenAI API：curl 或任何 HTTP 客户端都能调用

SDK 的典型应用场景

场景说明
降低接入门槛让开发者几行代码就能集成复杂功能（如 AWS SDK、阿里云 SDK）
官方最佳实践官方封装了签名、重试、错误处理等最佳实践
移动端/客户端开发推送 SDK、地图 SDK、支付 SDK（iOS/Android 原生集成）
内部服务治理公司内部封装统一的 RPC SDK，供各业务线调用

举例：

  • 微信支付 SDK：封装了签名、证书管理、支付回调等复杂逻辑
  • AWS SDK：封装了所有 AWS 服务的调用，自动处理认证和重试
  • Firebase SDK：提供客户端直接访问数据库/存储的能力

六、关系示意图

┌─────────────────────────────────────────────┐
│                   SDK                        │
│  ┌───────────────────────────────────────┐  │
│  │   封装好的语言库 (Java/Python/JS)     │  │
│  │   - 认证逻辑                          │  │
│  │   - 请求封装                          │  │
│  │   - 错误处理                          │  │
│  │   - 数据模型                          │  │
│  └───────────────────────────────────────┘  │
│                      │                       │
│                      ▼                       │
│  ┌───────────────────────────────────────┐  │
│  │            API 调用                    │  │
│  │   HTTP/REST / gRPC / WebSocket        │  │
│  └───────────────────────────────────────┘  │
└─────────────────────────────────────────────┘

关系：SDK 内部封装并调用 API，开发者通过 SDK 间接使用 API，无需处理底层细节。

七、什么时候用 API？什么时候用 SDK？

场景推荐原因
前端调用后端API前端通常直接发 HTTP 请求，引入 SDK 会增加体积
后端服务间调用SDK公司内部可封装统一 SDK，简化调用
集成第三方服务SDK（如有）官方 SDK 已处理好认证、重试等坑
简单/单次调用APIcurl 或直接发请求就够了
移动端集成SDKiOS/Android 平台通常以 SDK 形式提供
跨语言服务APISDK 是语言相关的，API 才通用

八、真实案例对比

案例 1：OpenAI

  • API：POST https://api.openai.com/v1/chat/completions，需自己处理 Header、Body、错误
  • SDK：openai npm 包，一行代码 openai.chat.completions.create() 搞定

案例 2：微信支付

  • API：需要自己处理签名、证书、XML 解析、回调验证，非常复杂
  • SDK：官方/社区 SDK 封装了所有细节，几行代码完成支付

案例 3：阿里云 OSS

  • API：需要自己签 Authorization Header，处理分片上传等
  • SDK：ali-oss npm 包，client.put() 一行代码上传

九、总结

问题答案
API 是什么接口规范，定义“能做什么”
SDK 是什么开发工具包，提供“怎么做”的具体工具
API 的形态网络端点 + 接口文档
SDK 的形态语言特定的代码库（npm/maven/pip）
关系SDK 封装并调用 API
选择原则简单场景用 API，复杂/高频场景用 SDK

一句话记忆：

API 是餐厅的菜单，告诉你有什么菜；SDK 是外卖厨房的全套工具，让你直接做菜。

avatar
文章
阅读
粉丝