SDK 测试专项
这一篇会从最基础的问题讲起：SDK 到底是什么，它和接口、Web 页面、App 页面到底有什么区别；然后再往下讲，为什么 SDK 测试不能只看“调通没有”，而要看初始化、契约、回调、流式、版本兼容、日志和接入体验。你如果之前对 SDK 没有概念，这篇就把概念先搭起来，再进测试。
先把 SDK 说人话。
SDK 全称是 Software Development Kit，中文通常叫“软件开发工具包”。如果底层 API 像后厨窗口，SDK 就像已经帮你配好锅具、调料、步骤卡的一套厨具。你当然也能直接调 API，但业务团队不想每次都自己拼鉴权、重试、流式解析、错误处理，所以平台方会把这些常见动作包起来，做成别人更容易接、也更不容易接错的代码层。 这就是为什么 SDK 不能被理解成“一个接口文档”或者“一个压缩包”。它本身就是一个要被别人接入、使用、升级、排障的产品。只要它提供了初始化、默认值、回调、错误码、日志、示例代码、升级说明，它就值得被单独测试。 你可以先记住一句话：API 解决的是能不能通信，SDK 解决的是别人能不能顺利用、稳定用、出错时能不能看懂。
图 1：AI SDK 在项目里的位置 业务代码：聊天页、后台服务、自动化脚本 ↓ SDK：初始化、参数封装、鉴权、重试、流式、日志 ↓ 平台接口：网关、模型服务、文件服务、回调服务 ↓ 最终对接入方可见的结果：成功响应、错误对象、事件流
| 如果没有 SDK | 接入方得自己做什么 | 为什么容易翻车 |
|---|---|---|
| 直接调 API | 自己拼 URL、Header、签名、重试 | 每个项目各写一套，行为不一致 |
| 自己处理流式 | 解析 chunk、结束帧、错误帧 | 很容易出现收口不完整、消息乱序 |
| 自己包装错误 | 区分网络错、鉴权错、业务错 | 失败时很难快速判断问题边界 |
| 自己写示例 | 摸索最小 demo、上传 demo、多轮对话 demo | 每个团队都重复踩一遍接入坑 |
小白最容易误解 1
“SDK 不就是接口套了一层壳吗？” 不完全是。只要它引入了默认值、对象模型、异步事件、文档和升级策略，它就已经不是简单转发。
小白最容易误解 2
“happy path 调通了，SDK 就没问题了吧？” 也不对。SDK 最大的价值往往体现在失败场景、日志排障、兼容升级和接入体验上。
02. 它和 API / 页面有什么不同
这个边界如果不先分清，后面的测试重点很容易全乱掉。很多团队嘴上说“在测 SDK”，其实测的是接口；也有很多页面缺陷，根因其实埋在 SDK 的默认值或流式封装里。
| 对象 | 本质 | 谁直接用它 | 测试重点 |
|---|---|---|---|
| API | 系统对外暴露的通信契约 | 前后端、服务、脚本 | 协议、请求、响应、状态码、鉴权、性能 |
| SDK | 对 API 或底层能力的封装层 | 开发者、业务接入方 | 初始化、参数映射、默认值、事件、兼容性、文档一致性 |
| Web / App 页面 | 最终用户操作的界面层 | 终端用户 | 交互、展示、状态管理、端体验 |
| Demo / CLI | 帮助验证是否能快速跑通的入口 | 测试、售前、开发者 | 最小可用性、安装依赖、文档复现性 |
为什么 SDK 要单独测？
因为 SDK 解决的不是“平台接口有没有返回”，而是“别人第一次接的时候会不会被坑”。很多平台接口本身是通的，但 SDK 的参数名、默认值、错误对象、流式结束事件、升级行为一旦不稳定，业务方照着文档写照样会挂。
图 2：一个问题可能停在哪层
接口协议错 → SDK 封装错 → 业务接入代码错 → 页面展示错
好的 SDK 测试，不是把所有锅都背下来，而是能更快判断问题到底停在哪一层。
03. 一个 SDK 通常包含什么
如果你不先拆清一个 SDK 的组成，测试就很容易写成“校验接口是否正常”这种空话。下面这张表，你可以直接当成拆解模板使用。
| 模块 | 它负责什么 | 新手最容易漏的风险 |
|---|---|---|
| 安装与依赖 | 包管理、导入方式、系统依赖 | 文档命令能复制，但全新环境安装失败 |
| 初始化层 | 创建客户端、注入 key、环境、超时 | 缺参数时不早报错，拖到发请求才炸 |
| 请求封装层 | 方法名、参数名、默认值、重试策略 | 文档和代码不一致，业务照写也会踩坑 |
| 响应对象层 | 普通响应、分页对象、流式事件对象 | 字段命名变化、空值策略不统一 |
| 错误处理层 | 异常类、错误码、是否可重试 | 只抛一句 request failed，完全没法定位 |
| 日志与诊断层 | request id、调试日志、脱敏、链路信息 | 日志缺失或直接打印敏感信息 |
| 示例与文档 | 最小 demo、复杂 demo、升级说明 | 示例已过时，但没人知道 |
3.1 AI SDK 一次完整调用链
业务代码 new Client() → SDK 校验参数 → HTTP / SSE / WebSocket 请求 → 平台返回数据帧 → SDK 解析成对象 / 回调 / 事件流
所以 SDK 测试绝不只是“拿没拿到一段文本”，而是每一步的入参、出参、时序、失败提示、默认行为是不是都合理。
3.2 你到底在替谁把关
| 角色 | 他最关心什么 | SDK 测试应该帮他确认什么 |
|---|---|---|
| 接入开发 | 我能不能半小时跑通 | 安装、初始化、最小 demo、错误提示 |
| 业务研发 | 升级会不会影响线上逻辑 | 兼容性、字段稳定性、默认值变化 |
| 排障同学 | 线上出错怎么定位 | 错误码、日志、request id、重试信息 |
| 测试同学 | 主流程之外会不会有隐患 | 异步、取消、流式、弱网、边界参数 |
04. 初始化与配置为什么是第一关
项目里很多看上去像“调用失败”的问题，其实压根没走到真正调用，而是初始化阶段就埋雷了。比如 key 配错、base URL 不对、默认超时太短、代理没生效、重复初始化污染了旧状态。
client = AIClient(
api_key="demo-key",
base_url="https://api.example.com",
timeout=30,
enable_stream=True,
max_retries=2,
)4.1 初始化测试该怎么拆
| 测试点 | 为什么要测 | 预期应该长什么样 |
|---|---|---|
| 完整参数初始化 | 验证最短 happy path | 对象创建成功，可直接发起请求 |
| 缺少 api_key | 这是最常见接入错误 | 初始化就报出缺字段，不要等到首次请求 |
| 非法 base_url | 测试环境最容易配错 | 错误信息能区分“域名错”和“服务端错” |
| 超时配置边界值 | 0、负数、极小值都可能出现 | 要么明确拦截，要么文档说明行为 |
| 重复初始化 | 旧连接、旧 token、旧日志对象可能残留 | 状态隔离清楚，不串请求 |
| 代理 / 证书配置 | 企业内网环境经常需要 | 失败时错误归因清楚 |
初始化回归单
- 文档里的安装命令能否在全新环境直接执行成功。
- 示例代码是否需要额外依赖、环境变量或系统权限。
- 最小 demo 是否足够短，是否能在 5 分钟内跑通。
- 缺 key、错 key、错地址、错代理时，报错是否可读。
- 初始化失败后再次重试，是否会带着脏状态。
4.2 为什么我一直强调“最小 demo”
因为业务方真正想要的不是一篇很长的文档，而是一个最短、最稳、最不容易写错的例子。测试同学最好自己维护一份最小 demo，把它当成 SDK 回归的第一入口。谁都可以在全新环境里先跑它，能跑通再谈其他复杂能力。
4.3 典型缺陷长什么样
| 表面现象 | 高概率根因 | 为什么业务方会很痛苦 |
|---|---|---|
| 第一次调用必报错，第二次又好了 | 初始化异步没等完就允许发请求 | 问题偶发，开发和测试都难复现 |
| 文档没说代理，企业环境全失败 | SDK 默认只能直连公网 | 业务方会误以为平台整体不可用 |
| 错误提示只有 401 | 错误封装太薄 | 不知道是 key 失效、权限不足还是地址错 |
05. 接口契约和参数怎么测
这里的“契约”不只是 API 文档里的 JSON 字段，而是 SDK 对外承诺的一整套使用方式：函数名、参数名、必填/可选、默认值、异常风格、返回对象、是否支持流式、取消怎么做、文档怎么写。
5.1 为什么这一层风险很大
- 文档说参数可选，实际不传就抛异常。
- 文档说默认超时 30 秒，代码里写成 5 秒。
- 返回对象有时叫
message，有时又叫content。 - 同一类错误，有时抛异常，有时返回错误对象，风格混杂。
接入方不会关心你内部怎么实现，他只会盯着他实际调用的这一层。如果这里不稳定，别人就会觉得这个 SDK 不靠谱。
5.2 参数测试建议至少拆成 6 类
| 类别 | 要覆盖什么 | 典型提问方式 |
|---|---|---|
| 必填参数 | 缺失、空值、非法值 | 是不是尽早报错，错误指向是否明确 |
| 可选参数 | 默认值、生效顺序、互斥关系 | 不传和传默认值是否等价 |
| 边界值 | 超长字符串、超大文件、极端数字 | 会拦截、截断还是透传 |
| 组合参数 | 流式与非流式、多模态与文本、工具调用 | 组合后是否出现隐藏限制 |
| 类型容错 | null 、空数组、错误枚举 | 异常是否统一，不要一会儿兜底一会儿崩 |
| 版本参数 | 旧字段、新字段、废弃字段 | 升级后旧调用姿势还能不能用 |
5.3 返回结构不要只看“有值就行”
| 检查点 | 要确认什么 | 为什么重要 |
|---|---|---|
| 字段稳定性 | 同类请求下，必填字段是否每次都在 | 业务代码通常默认必填字段存在 |
| 空值策略 | 空字符串、空数组、字段缺失怎么区分 | 影响调用方判空逻辑 |
| 对象层级 | 嵌套对象名字是否一致 | 文档和代码生成器都依赖它 |
| 异常对象 | 错误时有没有稳定结构 | 方便日志、监控、自动重试 |
5.4 文档与代码对账表
| 对账项 | 应该从哪里看 | 常见错法 |
|---|---|---|
| 安装命令 | README、官网、示例仓库 | 文档是旧命令，包名已改 |
| 参数名 | 方法签名、类型定义、示例代码 | 文档沿用旧字段 |
| 默认值 | 源码、配置对象、FAQ | 口口相传和实际代码不一致 |
| 错误码 | 错误类、接口文档、日志平台 | 同一个场景不同语言 SDK 文案不统一 |
教学里一定要强调的一点。
SDK 测试不是只验证“能不能成功调用”，还要验证“调用失败时有没有把人往正确方向引导”。真实接入时，大家第一次遇到的常常不是成功，而是配置不完整、参数写错、文档看岔。
06. 回调、事件、流式为什么难测
只要 SDK 进入异步世界，难度就一下上去了。因为你不再只是验证“最后结果对不对”，还要验证“过程顺不顺”“先后顺序对不对”“取消之后是不是真的停了”“结束信号有没有收口”。 图 3：一个流式请求通常经历的事件序列 请求发出 ↓ 收到首包 / on_open ↓ 多次 on_message / on_token ↓ on_complete 或结束帧 ↓ 资源回收、状态清零、日志落盘
6.1 这类问题为什么总像线上问题
因为它跟时序强相关。测试环境里网络稳、请求少、点击慢，看起来什么都正常；一到线上，用户会快速连续提问、取消、切页面、断网、重试，这些动作叠起来才会暴露问题。
6.2 回调 / 流式测试矩阵
| 场景 | 重点看什么 | 典型缺陷 |
|---|---|---|
| 正常流式完成 | 事件顺序、结束信号、资源释放 | 少一次完成回调，UI 一直在 loading |
| 用户主动取消 | 取消后是否继续回流事件 | 旧请求被取消，但晚到 chunk 仍写进界面 |
| 服务端中断 | 异常是否可感知、是否可重试 | 中间断流却没有错误，业务方只能等超时 |
| 超时自动重试 | 新旧请求是否隔离 | 重试后混进两份结果 |
| 并发两个请求 | 回调对象、request id 是否串线 | A 的响应回到了 B 的监听器 |
6.3 这里最好怎么留证据
- 记录请求 id、线程 id、回调顺序号。
- 把每个事件的时间戳打出来，方便看先后关系。
- 必要时录屏或保留控制台日志，因为很多问题只看最终结果看不出来。
- 如果有 demo 页面，最好能显示“已开始 / 已接收 / 已完成 / 已取消”这些中间态。
标题：取消流式后旧请求仍继续回调，导致业务端消息重复落库
前置条件：Python SDK 2.4.1，流式模式开启
步骤：
1. 发起流式请求 A
2. 在返回第 3 个 chunk 后调用 cancel()
3. 立即发起请求 B
4. 观察 A/B 的事件回调与业务日志
实际结果：A 在 cancel 后仍收到 2 个晚到 chunk，并被业务端作为 B 的内容写入数据库
预期结果：A cancel 后不再回调业务监听器，B 的事件流独立完整07. 兼容性、升级、宿主环境
SDK 不像页面只跑在一个前端工程里。它会被接进 Python 服务、Java 后台、Node 脚本、移动端应用、低代码平台。环境一多，兼容性立刻变成主战场。
| 兼容维度 | 具体要看什么 | 建议怎么测 |
|---|---|---|
| 语言 / 运行时版本 | Python 3.9/3.10/3.11，JDK 8/11/17 等 | 至少覆盖官方支持矩阵的头尾版本 |
| 依赖兼容 | HTTP 库、序列化库、日志库 | 抽样验证与宿主常见依赖是否冲突 |
| 平台接口版本 | 老接口、新字段、废弃字段 | 保留旧 demo 回归，不要只测最新写法 |
| 宿主环境 | 代理、证书、内网、容器、不同 OS | 选 1~2 个真实企业环境做冒烟 |
| 升级方式 | 小版本升级、大版本升级、灰度发布 | 对比升级前后默认值和行为差异 |
最危险的不是大改版
很多线上事故来自一个看似无害的小版本：默认超时变了、错误类名换了、流式结束帧换了、字段名改了。
升级回归怎么做更稳
保留旧 demo、旧参数、旧监听器用法。新版本发布前先用旧代码跑一遍，比只测新示例更能发现问题。
兼容性优先级
P0 先保主流运行时和核心调用链，P1 再补高风险依赖组合，P2 按用户量处理边缘环境。
08. 日志、错误码、排障能力
一个 SDK 好不好用，失败的时候最能看出来。成功路径每家都能吹，出错时能不能让人快速判断是“自己配错了”还是“平台真出故障了”，这才见功底。
{
"code": "AUTH_EXPIRED",
"message": "token 已过期，请重新获取",
"retryable": false,
"request_id": "req-20260415-001",
"hint": "请检查服务器时间和鉴权配置"
}8.1 什么叫“够用的错误信息”
| 项 | 差的写法 | 更好的写法 |
|---|---|---|
| 错误文案 | request failed | 认证失败：token 已过期，请重新获取 |
| 错误归类 | 全部抛 RuntimeError | 区分鉴权错、网络错、参数错、服务端错 |
| 排障线索 | 没有 request id | 附带 request id、重试次数、目标地址 |
| 重试建议 | 不说明是否可重试 | 明确 retryable=true/false |
| 安全性 | 日志打印完整 key | 只打印脱敏后的关键片段 |
8.2 测日志不是比对文案，而是确认这 4 件事
- 定位维度够不够：能不能知道错在初始化、请求、解析还是回调。
- 可追踪性够不够：有没有 request id、会话 id、重试次数。
- 对人友好够不够：接入方看完知道下一步该查什么。
- 安全够不够：日志里不能裸奔 token、手机号、原始敏感内容。
一句很现实的话。
如果 SDK 的错误信息只有研发自己看得懂，后面你会看到大量“麻烦帮忙看看”式群聊。这不是用户懒，是 SDK 没把排障入口设计好。
09. 怎么设计 SDK 测试策略
真的要落地时，不要一上来铺满一百条散乱用例。更稳的方式，是按层收口：先保证别人能接起来，再保证不会误接，再保证异步过程不乱，最后才是长期兼容与可维护性。
| 层次 | 目标 | 样例 |
|---|---|---|
| 第 1 层：接入冒烟 | 5~10 分钟内跑通最小 demo | 安装、导入、初始化、单次请求 |
| 第 2 层：契约回归 | 防止参数、返回对象、文档走偏 | 参数校验、默认值、错误对象对账 |
| 第 3 层：时序回归 | 防止流式、回调、取消类问题 | 并发、取消、超时、重试、断网 |
| 第 4 层：兼容回归 | 防止升级破坏旧业务 | 旧 demo、旧字段、主流环境矩阵 |
| 第 5 层：文档体验 | 确保别人真能跟着文档接入 | 官网示例、README、FAQ 抽样复跑 |
测试对象：Python AI SDK 2.4.1
本轮目标：发布前验证接入可用性、流式稳定性、升级兼容性
风险重点：初始化、流式取消、旧字段兼容、错误码可读性
环境：Python 3.10 / macOS，Python 3.11 / Linux
范围：chat、stream、upload、error handling、README demo
产出：回归结果表、兼容矩阵、阻塞问题单、升级说明建议上线前必勾
| 项 | 是否确认 | 备注 |
|---|---|---|
| 最小 demo 可运行 | □ | 全新环境复跑过 |
| 核心参数与文档对账 | □ | 至少抽样 3 个方法 |
| 流式完成 / 取消 / 超时已回归 | □ | 保留日志证据 |
| 主流运行时兼容通过 | □ | 头尾版本各一套 |
| 错误码、日志、脱敏规则已检查 | □ | 失败场景不低于 5 条 |
| 升级说明已补齐 | □ | 包含 breaking change |
10. 常见缺陷和用例模板
10.1 典型缺陷库
| 缺陷现象 | 高概率根因 | 如果不拦住会怎样 |
|---|---|---|
| 业务方按文档写，结果参数名报错 | 文档和代码版本不一致 | 大量接入咨询、信任度下降 |
| 同一次请求收到了两次完成事件 | 回调收口缺陷 | 业务方重复记账、重复落库 |
| 升级后旧代码不报错但结果变了 | 默认值悄悄变化 | 线上行为漂移，排查很慢 |
| 错误提示只有网络异常 | 错误归类不清 | 定位成本极高，支持团队压力大 |
| 并发流式下消息串线 | 监听器隔离不彻底 | 用户数据互串，风险很高 |
10.2 可直接复制的用例模板
| 用例名 | 前置条件 | 步骤 | 预期 |
|---|---|---|---|
| 初始化缺少 key | 安装 SDK 成功 | 创建客户端时不传 api_key | 初始化立即失败，提示缺少 key，文案指出配置方法 |
| 流式取消后不再回调 | 流式模式开启 | 请求返回第 2 个 token 后调用 cancel() | 后续不再收到 token / complete 事件，资源正常释放 |
| 旧 demo 在新版本可继续运行 | 保留上一版本示例代码 | 仅升级 SDK 版本，不改业务代码 | 核心功能仍可用，如有不兼容需明确报废弃提示 |
标题：Java SDK 3.1.0 流式完成事件重复触发，导致业务方重复消费
版本：Java SDK 3.1.0
环境：JDK 17 / Ubuntu 22.04
前置条件：开启 stream=true，业务方监听 onToken / onComplete
步骤：
1. 使用官方 README 中 chatStream 示例代码
2. 发起一次普通问答请求
3. 观察回调日志和最终落库记录
实际结果：onComplete 触发 2 次；业务侧重复执行“结束后入库”逻辑
预期结果：同一 request_id 仅触发 1 次完成事件
证据：控制台日志、request_id、录屏、最小复现代码
价值：会直接影响接入业务的数据正确性，不是单纯日志问题一个很实用的经验。
测 SDK 时，别把自己代入“平台内部研发”，要代入“第一次接这个 SDK 的业务开发”。你越能从接入方的视角提问题，越能拦住真正会在项目里放大的缺陷。
11. 下一步怎么接着学
如果你已经能分清 SDK、API、页面三层边界了，接下来去看 Web 端 AI 测试会更顺。因为很多 Web 页面上的“发送中、停止生成、文件上传、流式展示”问题，其实跟 SDK 这一层是连着的。
先看什么
继续看 Web 端 AI 测试专项，把浏览器页面、会话状态、流式渲染和文件上传这几层串起来。
回头怎么练
找一份你们项目里真实在用的 SDK 文档，把本页的初始化、契约、流式、兼容、日志五张表逐项对一遍，收获会非常明显。
补充练习与参考答案
补充练习
- 列出 3 条 SDK 测试必须覆盖的兼容性维度。
- 如果同一接口在 Android SDK 和 iOS SDK 上表现不同，你会怎样定位？
- 为什么 SDK 测试不能只看 demo 跑通？
参考答案要点
- 兼容性至少包括版本兼容、平台兼容、参数兼容和错误码兼容。
- 定位时要先分清是 SDK 封装差异、平台能力差异，还是后端接口本身不一致。
- demo 跑通只能说明主路径可用，不能说明异常分支、升级路径和边界参数都稳定。