1. 错误码概述

先问个问题：你调试 SDK 的时候，最怕遇到什么？
我猜很多人会说“没日志”或者“返回个空对象”。但其实啊，最要命的是——返回了一个错误码，你却看不懂它想说什么。

我刚开始做 SDK 集成那几年，遇到过好几次这样的场景：App 跑着跑着突然弹了个 1001，文档里翻半天只写着“系统错误”。你想想看，这叫什么事？调试全靠猜，定位问题全靠重启。说白了，这根本不是错误处理，这就是在碰运气。

后来我学乖了。每接一个 SDK，先花半小时把它的错误码体系理清楚。这个习惯帮我省了不知道多少加班时间。今天咱们就来聊聊这个基础但关键的知识——错误码到底是什么，它有什么用，以及业界怎么给它分类。

1.1 什么是错误码？

错误码，本质上就是一个数字（或字符串）标识符，用来代表某个特定错误状态。它不是随便乱写的——每个码都对应一个预定义的错误场景。

举个例子，你用微信支付 SDK 发起了一笔支付，结果返回 -1。这个 -1 在它们的文档里通常代表“签名错误”。你看，光靠一个数字，你就能立刻知道：哦，我哪里的参数签名计算不对。

• 唯一性：同一个 SDK 里，每个错误码只对应一种错误。
• 可读性：配合错误消息，让人（或者机器）能定位问题。
• 可追踪性：通过错误码，可以追溯到源代码里的具体分支。

1.2 错误码的作用

错误码这东西，看着简单，但它在 SDK 设计里扮演着几个关键角色：

1. 标准化沟通：SDK 开发者和你不需要直接说人话，一个码就传递了全部含义。
2. 快速定位：生产环境里日志滚滚，你不可能看完几百行日志。搜索错误码，秒级定位。
3. 自动化处理：你的业务代码可以根据不同错误码做不同逻辑，比如重试、降级、弹提示。
4. 质量度量：统计每个错误码出现的频率，就能评估 SDK 的稳定性。我在一次压测中，就是靠错误码统计发现了一个内存泄漏的规律。

说白了，错误码就是 SDK 跟你之间的“暗号”。你懂了这个暗号，才能跟 SDK 好好合作。

1.3 通用分类方式

市面上的 SDK 五花八门，错误码也各有各的体系。但万变不离其宗，常见的分类维度有三个：

分类维度	分类举例	典型场景
按来源	SDK 内部错误、服务端错误、网络错误、硬件错误	40001 请求参数错误（服务端） vs -1004 网络连接失败（客户端）
按严重程度	Info（信息）、Warning（警告）、Error（错误）、Fatal（致命）	Info 级别通常只作日志记录，Fatal 则需要手动复位或中断流程
按协议	HTTP 状态码、RPC 错误码、自定义业务码	HTTP 200/404/500 是通用协议码，而 10010 需要查 SDK 业务文档

1.4 错误码设计的核心原则

如果你以后自己设计 SDK，或者评估一个 SDK 的错误码是否合理，可以用这几条原则来检验：

• 前缀标识来源：比如 1xxx 是网络错误，2xxx 是业务错误。看一眼就能知道问题出哪一层。
• 预留扩展空间：不要用满所有数字。我见过一个 SDK 用了 99 到 109，结果版本二又新增了 110，风格立马乱了。
• 配套错误消息：纯数字让人抓狂。好的 SDK 会同时给你 errorCode 和 errorMessage，而且消息是本地化的。
• 文档完整：每个错误码的触发原因、解决方案、示例代码都要清清楚楚。否则就是在浪费集成者的生命。

嗯，这里要注意：有些 SDK 为了兼容旧版本，错误码不会轻易改变。所以你在集成时看到的码和文档里写的，必须以运行时返回的为准。我曾经就被一个过期的文档坑过一次——跑了一天发现文档里少写了一个 50002，最后去翻 GitHub Issue 才找到解释。

1.5 一个真实案例

记得几年前，我接一个蓝牙 SDK 做智能硬件控制。文档里只写了几个错误码，比如 0 成功，-1 失败。我当时没在意，觉得这么简单能出什么事？

结果测试的时候，手机连上设备后发指令，有 30% 的概率返回 -1。我查了半天，以为是代码逻辑问题。后来实在没办法，用串口抓了设备侧的日志，才发现 -1 背后藏了至少三种完全不同的原因：蓝牙断开、参数格式错、设备忙碌。SDK 设计者居然把它们全合并成了一个码。

这就是典型的错误码设计失当——粒度太粗，让你无从下手。从那以后，我每次选 SDK 都会先检查它的错误码是否清晰，有没有按我们上面说的分类来设计。如果一塌糊涂，我会直接建议团队换方案。毕竟，错误码就是你跟 SDK 之间的“翻译官”，翻译官不靠谱，后面的合作全是坑。