rtc sdk 自定义错误码开发规范：像老司机一样写代码
前几天有个朋友问我，他们团队在对接 rtc sdk 的时候，被各种错误码折腾得够呛。他说每次线上出问题，光是看错误码就要耗半天，更别说定位问题了。这让我意识到，很多团队在使用 RTC SDK 时，往往只关注功能实现，却忽略了错误码设计这个"小事"。
但我要说，错误码设计这件小事，实际上关乎整个项目的可维护性。今天咱们就来聊聊 RTC SDK 自定义错误码的开发规范，我尽量用大白话讲清楚，不搞那些云里雾里的概念。
一、先搞明白：为什么要自定义错误码？
你可能会说，RTC SDK 本身不是有现成的错误码吗？为什么还要自己定义？这问题问得好。
RTC SDK 原生的错误码主要是针对底层通信层面的问题，比如网络连接失败、媒体流建立超时这类基础问题。但实际业务中，很多问题是发生在业务层的。比如用户被封禁了、房间人数已达上限、 VIP 服务到期了——这些业务场景，原生的错误码可管不了。
举个子，你在做一个1V1社交应用，用户充了 VIP 但因为特殊原因无法享受服务，这时候你需要一个明确的错误提示告诉用户"您的高级服务已过期，请续费后再试"。如果只用原生的错误码，你只能告诉用户"连接失败"，这让用户一脸懵。
所以自定义错误码的本质，是让业务问题和用户之间架起一座清晰的沟通桥梁。
二、自定义错误码的分类哲学
说到错误码分类，我见过不少团队的设计，那叫一个"随意"。有的是按数字顺序随便排，有的干脆用中文描述当错误码。这两种做法，短期内可能没事，等维护个一两年，保管你后悔莫及。
我建议采用分段式分类法，简单说就是给错误码划定几个"势力范围"。以下是一个经过实战检验的分类框架：
| 错误码范围 | 分类用途 | 说明 |
| 0 | 成功状态 | 一切正常的情况 |
| 1 - 999 | 基础错误码 | SDK 预留或通用错误 |
| 1000 - 1999 | 业务权限类 | 用户权限、角色权限等问题 |
| 2000 - 2999 | 业务逻辑类 | 房间状态、参数校验等问题 |
| 3000 - 3999 | 资源类错误 | 配额限制、资源不足等问题 |
| 4000 - 4999 | 第三方服务类 | 集成导致的问题|
| 5000 以上 | 自定义扩展 | 业务自行扩展使用 |
这个分类方式有几个好处。首先是一目了然，看到错误码数字，你大概就能猜到是哪类问题。其次是扩展性强，预留了足够的空间给你慢慢加。最后是冲突概率低，因为 SDK 原生错误码和你的自定义错误码在数字上不会打架。
举个实际的例子，你做一个秀场直播应用，假设用户被管理员禁言了，错误码可以设计成 1001，提示语写成"您已被管理员禁言，无法发送消息"。再做秀场 PK 场景，如果对方已经开始了 PK 无法再接受挑战，错误码可以设计成 2003，提示语是"对方正在进行 PK，无法接受新的挑战"。
这种设计方式最大的好处是，出了问题你不用猜，看错误码数字就知道大概是哪个模块的问题。
三、错误码设计的几个"坑"
在分享了几个朋友的代码后，我发现有几个坑几乎是必踩的。我来说说，你对照着检查一下自己的项目。
第一个坑：零散的数字，无规律可循
很多团队早期的错误码是这么加的：1001 是房间满，1002 是用户被禁言，1003 是麦克风故障，1004 是美颜初始化失败……
这种做法在当时可能觉得挺省事，但问题会随着项目变大而显现。当你需要加新错误码时，你会陷入"下一個数字是多少"的沉思，而且当你看到 3005 这个错误码时，你完全不知道它代表什么含义，必须去查文档或者代码。
我的建议是：给错误码加前缀，用模块缩写来区分。比如权限相关用 PERM_，房间相关用 ROOM_，资源相关用 RES_。虽然实际存储可能还是数字，但你在文档和注释里用这种语义化的方式，代码可读性会提升很多。
第二个坑：错误信息写得太"技术"
这个坑我踩过，也见过无数人踩。错误信息写成"ERR_ROOM_NOT_FOUND"或者"User permission denied"，对外展示给用户看，用户根本不知道什么意思。
记住，错误信息是给人看的，不是给机器看的。如果你的错误信息要展示给普通用户，请用人类能理解的语言。如果是给开发者看的技术日志，那可以保留技术化的描述。
举个对比："房间不存在"对比"ERR_ROOM_NOT_FOUND"，显然是前者更友好。或者"您的账号已被封禁，请联系客服处理"对比"User is banned"，前者明确告诉用户下一步该怎么做。
第三个坑：没有错误码文档，或者文档不更新
这个太常见了。团队里有份错误码文档，上次更新可能是两年前，现在新增了几十个错误码，但文档里根本没有。
我建议的做法是，错误码信息和代码放在一起。可以用枚举类或者常量定义的方式来写，每个错误码都带着说明。比如在 Java 里可以用注释标明含义，在 Swift 里可以用枚举的 case 附带文档注释。
这样做的好处是，改代码的时候你大概率会顺便更新注释，而单独的文档很容易被遗忘。
第四个坑：HTTP 状态码和业务错误码混用
有些团队为了省事，直接把 HTTP 状态码当业务错误码用。比如 403 表示"没有权限"，但这个 403 到底是用户被禁了还是 VIP 过期了，根本区分不开。
虽然这样短期内能跑通，但长期来看是给自己挖坑。HTTP 状态码有它特定的语义，应该回归它的本职工作——表示 HTTP 层面的问题。业务层面的错误，应该用独立定义的业务错误码。
四、让错误码"活"起来的实践建议
说完坑，咱们来点实操的。我整理了几个能让错误码更好用的实践建议。
建立错误码的层级关系
有些错误是包含关系，比如"没有权限"可能是因为"账号被封禁"，也可能是因为"不是房间管理员"。这时候你可以设计成父错误码和子错误码的形式。
比如权限相关的父错误码是 10xx 段，其中 1001 是"没有操作权限"，而 1002 是"账号状态异常"（这是 1001 的子情况），1003 是"房间角色限制"（这也是 1001 的子情况）。
这样设计的好处是，你可以捕获父错误码统一处理，也可以精确捕获子错误码做特殊处理，灵活度很高。
错误码和错误处理逻辑分离
我见过不少代码，错误码和处理逻辑写在一起，比如 if (errCode == 1001) { doSomething() }。这种写法的问题在于，一旦错误码变了，你得满世界找这些判断语句。
更好的做法是建立一个错误码到处理函数的映射表，或者使用策略模式。每种错误码对应一种处理策略，新增错误码只需要加一行映射，修改处理逻辑不影响错误码定义。
给错误码加上"严重程度"
不是所有错误都同等重要。有些错误需要立刻报警，有些只需要记录日志，还有些可以静默忽略。
你可以在错误码系统里加入严重程度的定义，比如分为 INFO（信息）、WARNING（警告）、ERROR（错误）、CRITICAL（严重）四个级别。不同级别的错误，你可以配置不同的处理策略，重要的错误走报警通道，不重要的错误默默记录就行。
考虑多语言支持
如果你的应用要出海，多语言是必须考虑的。错误信息最好别直接写死在中文字符串里，而是用资源 ID 的方式管理。比如"房间人数已满"对应资源 ID 是 ERR_ROOM_FULL_EN、ERR_ROOM_FULL_JP 这样。
虽然前期准备工作多一点，但后续维护和出海的时候会省心很多。
五、结合声网 SDK 的最佳实践
前面说了这么多理论，咱们结合实际场景聊聊。我以声网的 RTC SDK 为例，说说怎么在它的基础上设计业务错误码。
声网的 RTC SDK 本身有一整套错误码体系，主要是处理底层音视频通信的问题，比如网络质量差、设备不支持等。当你基于声网 sdk 开发上层业务时，需要明确区分哪些是声网 SDK 的错误，哪些是你业务层的错误。
具体怎么做呢？可以在错误回调里先判断是否是声网 SDK 的错误（通常 SDK 自己的错误码在某个特定范围内），如果是，就按 SDK 的文档处理。如果不是，那就是你的业务错误，需要你自己的错误码体系来处理。
举个例子，你在做 1V1 社交场景。用户发起通话时，可能遇到几种情况：声网 SDK 返回网络不可用（这是 SDK 层面的问题），用户 VIP 已过期（这是业务层面的问题），或者对方正在通话中（这也是业务层面的问题）。
对于业务层面的问题，你就可以用前面说的 2000-2999 段的错误码来定义。比如 VIP 过期可以用 2001，对方忙碌可以用 2002。处理的时候，你对不同错误码做不同的提示，用户体验就很清晰了。
再比如秀场直播场景，假设你用声网的实时音视频能力做主播连麦。当用户要申请连麦时，可能遇到主播设置了连麦人数上限（业务错误，需要提示用户"连麦人数已达上限"），或者主播已经开启了 PK 无法连麦（业务错误，提示"主播正在 PK 中"）。这些都用自定义错误码来处理，用户就能明白到底怎么回事。
六、错误码文档的正确姿势
前面提到错误码文档很重要，那文档应该怎么写呢？我建议包含以下几个字段：
- 错误码：数字编号
- 错误名称：简短的技术名称，比如 ERR_ROOM_FULL
- 错误描述：详细说明这个错误是什么意思
- 触发场景：在什么情况下会触发这个错误
- 解决方案：开发者看到这个错误应该怎么处理
- 用户提示：如果需要展示给用户，应该怎么措辞
有了这份文档，开发者定位问题的速度会快很多。而且我建议把这份文档放在团队都能访问到的地方，比如内部 Wiki，并且指定一个人定期维护，避免文档过期。
写在最后
唠了这么多，其实核心思想就一个：错误码不是小事，它是你和应用用户之间的对话窗口。一个好的错误码系统，能让用户清楚知道发生了什么，也能让开发者快速定位问题。
设计错误码的时候，多站在用户的角度想想，多站在后来维护你代码的同事角度想想。有些功夫是省不得的，前期多花点时间把错误码体系搭建好，后期能少踩很多坑。
如果你正在使用声网的 RTC SDK，记得区分好 SDK 层面的错误和业务层面的错误，用不同的体系来处理。这样既不会和 SDK 的错误码冲突，也能让自己的业务逻辑更清晰。
好了，关于 RTC SDK 自定义错误码的开发规范，就聊到这里。如果你有什么想法或者实践经验，欢迎在评论区交流。
