rtc sdk 异常处理代码编写规范

做音视频开发这些年，我见过太多因为异常处理不当导致的"翻车"现场。有次凌晨三点，线上直播突然大面积卡顿，运维同事排查半天，发现只是一个网络状态变化的回调没有正确处理。说实话，这种问题如果一开始就把异常处理写规范了，根本不会闹出这么大动静。

今天想和大家聊聊 rtc sdk 的异常处理规范这个话题。这不是什么高深的理论，而是实实在在的实践经验。我会尽量用大白话把这些规范讲清楚，让你在实际开发中能直接用上。

为什么异常处理这么重要

先说个事儿。去年有个朋友的公司做在线教育，课堂功能做得挺完善，结果有次网络波动，学生那边麦克风权限弹窗没处理好，整个直播间瞬间"安静"了。家长的投诉电话差点把客服打爆。你说亏不亏？功能没问题，反而是异常处理出了岔子。

实时音视频这个领域和普通的业务开发不太一样。网络波动、设备兼容、权限变化……这些情况随时可能发生，而且往往发生在你最意想不到的时候。RTC SDK 的异常处理之所以重要，主要有这几个原因：

• 实时性要求高：音视频通话讲究的是"实时"二字，出了问题必须在毫秒级做出响应，否则用户体验直接崩塌。
• 异常场景复杂：从网络问题、设备问题、权限问题到服务器问题，异常类型五花八门，每一种都得有对应的处理策略。
• 用户感知强烈：画面卡了、声音断了、视频糊了……这些问题用户一眼就能看出来，容不得半点马虎。

所以，异常处理不是"加分项"，而是"必选项"。写 RTC SDK 代码，异常处理规范不到位，后面等着你的就是无尽的 Bug 修复和用户投诉。

异常分类：你得先搞清楚敌人是谁

在开始写代码之前，我们得先把这些异常分分类。知己知彼，才能百战不殆嘛。

按照我的经验，RTC SDK 的异常大致可以分为这几类：

异常类型	典型场景	处理优先级
网络异常	断网、弱网、IP 切换、网络类型变化	最高
设备异常	摄像头不可用、麦克风被占用、扬声器故障	高
权限异常	权限被拒绝、权限被撤回、权限状态未知	高
服务端异常	连接断开、鉴权失败、服务端过载	高
业务异常	房间已满、用户被踢出、角色权限不足	中

这个分类不是绝对的，不同业务场景可能有不同的优先级划分。比如在线教育场景，音频异常可能比视频异常更让人头疼；而秀场直播场景，画质问题可能更受关注。但总体来说，网络、设备和权限这三类异常是最常见、也是影响最大的，必须优先处理。

核心规范一：建立统一的异常码体系

先说个我踩过的坑。早年写代码的时候，异常处理特别随意，网络断了就打个 log，权限拒绝弹个窗，麦克风故障发个通知……代码里到处都是 if-else，异常码更是满天飞。后来维护的时候，自己都看不懂哪个错误对应哪个场景。

规范的异常处理第一步，就是建立统一的异常码体系。这一点特别重要，相当于给所有异常发一个"身份证"。

异常码设计原则

异常码的设计有几个要注意的地方。首先是要有规律，比如用三位数字表示：第一位代表大类，第二三位代表具体场景。拿声网的实时音视频云服务来说，他们的异常码体系就做得挺清晰，网络相关用 1xx，设备相关用 2xx，权限相关用 3xx，以此类推。

其次是异常码要有明确的描述信息。每次抛出异常的时候，除了错误码本身，还得附带一段人话，让开发者一眼就能明白问题出在哪里。比如错误码 1032，描述信息是"网络连接被拒绝，请检查网络权限设置"，这就比单纯一个数字强太多了。

最后是要预留扩展空间。业务会发展，异常场景也会增加，异常码设计的时候一定要留出足够的余量，别写着写着发现没号可用了。

示例代码结构

我建议把异常码集中管理，像这样：

// 异常码定义
public class RTCErrorCode {
    // 网络异常 10x
    public static final int NETWORK_DISCONNECTED = 1001;
    public static final int NETWORK_QUALITY_POOR = 1002;
    public static final int NETWORK_RECONNECTING = 1003;
    
    // 设备异常 20x
    public static final int DEVICE_CAMERA_INVALID = 2001;
    public static final int DEVICE_MICROPHONE_OCCUPIED = 2002;
    public static final int DEVICE_SPEAKER_ERROR = 2003;
    
    // 权限异常 30x
    public static final int PERMISSION_CAMERA_DENIED = 3001;
    public static final int PERMISSION_MIC_DENIED = 3002;
    public static final int PERMISSION_CAMERA_REVOKED = 3003;
}

这样集中管理的好处是，改一处就能全局生效，而且代码看起来也整洁。千万别把异常码散落在代码各个角落，到后面维护的时候你会感谢自己的。

核心规范二：异常回调的标准化设计

说完异常码，再聊聊回调。RTC SDK 里面大量的信息都是通过回调传给上层的，异常信息的传递也不例外。回调设计得好不好，直接影响上层业务代码的复杂度。

回调参数设计

我见过一些 SDK，异常回调的参数特别简单，就传一个错误码。这种设计看起来省事儿，但上层拿到错误码还得自己去查表，很麻烦。好的做法是把关键信息都封装进去，比如错误码、错误描述、可能的原因、建议的解决方案等等。

举个例子，当检测到网络质量变差时，回调可以这样设计：

public interface OnNetworkQualityCallback {
    void onNetworkQualityChanged(int errorCode, String description, 
                                 NetworkQuality quality, String suggestion);
}

上层拿到这些信息，可以直接展示给用户，或者做相应的重试操作，不用再去查文档或者源码猜这个错误码是什么意思。

回调线程注意

这里有个特别容易被忽视的点：回调线程。很多 SDK 为了性能，会在后台线程触发回调。如果上层在回调里直接更新 UI，就会出现崩溃。这种问题还特别难排查，因为不是必现的。

所以，SDK 的回调设计最好能指定线程，或者默认在主线程回调。如果必须在后台线程回调，一定要在文档里明确标注，让上层做好线程切换。声网在这块的处理就挺周到的，他们的 SDK 会自动处理线程问题，上层基本不用担心。

核心规范三：分级处理策略

异常来了，不是所有的都要往上抛。有些异常可以自动恢复，有些需要提示用户，有些则需要结束整个通话。分级处理是关键。

可恢复异常 vs 不可恢复异常

拿到一个异常，先判断它能不能自动恢复。比如网络闪断，可能过几秒就自己重连成功了，这时候 SDK 应该自动尝试重连，而不是直接把错误抛给上层。但如果是权限被永久拒绝了，那就没得商量，必须让用户去系统设置里打开。

我的经验是，至少要区分三个级别：

• 自动恢复：SDK 自动处理，不需要上层干预。比如短暂的信号波动。
• 提示用户：需要让用户知道发生了什么，可能需要用户配合操作。比如网络变差提示切换网络。
• 终止流程：无法继续，必须结束通话或退房。比如服务器拒绝连接。

降级策略

说到分级处理，就不得不提降级策略。这也是音视频 SDK 的一个特色功能。当高清视频跑不动的时候，自动降成标清；标清也跑不动，就降成流畅。音频同理，带宽不够的时候可以只传语音不传视频。

降级策略的异常处理需要考虑几个问题：什么时候触发降级？降级的顺序是什么？降级后如何恢复？这些都要在代码里定义清楚。

我见过一些实现，触发降级后就再也升不回来了，这显然不合理。好的做法是周期性地探测网络状况，条件允许了就尝试升级画质。或者给上层暴露一个手动控制的接口，让业务方自己决定什么时候升降级。

核心规范四：重试机制的设计

网络问题、音视频传输问题，很多情况下重试一下就解决了。但重试不是简单地写个 while 循环，里面有很多讲究。

指数退避

重试最忌讳的就是疯狂重试。服务器可能只是暂时过载，你这一秒重试十次，直接把人家搞挂了。指数退避是业界标准做法：第一次重试等 1 秒，第二次等 2 秒，第三次等 4 秒，以此类推。

同时要设置一个最大重试次数，超过次数就放弃或者上报错误。声网的 SDK 内部就有完善的重试机制，他们会根据不同的错误类型采用不同的重试策略，比如网络错误会多试几次，鉴权错误则直接终止。

重试条件判断

不是所有错误都应该重试。比如用户主动挂断，这种情况下重试只会适得其反。在重试之前，最好判断一下当前的状态，确保重试是有意义的。

另外，重试之前最好检查一下网络状况。如果网络完全断了，重试也是白费电量。这时候可以等网络状态变了之后再重试，而不是傻傻地定时重试。

核心规范五：日志与监控

异常处理很重要的一环是日志。我见过太多线上问题，因为日志不全，根本无法复现。音视频 SDK 的日志尤其重要，因为问题可能发生在几百毫秒之间，错过了就找不到了。

日志记录规范

首先，异常发生时的上下文信息要记录完整。错误码、时间戳、用户ID、房间ID、网络状态、设备信息……这些最好都能记下来。很多问题需要这些信息组合在一起才能定位。

其次，日志级别要对。ERROR 级别用于需要立即处理的异常，WARN 级别用于可能有问题但不影响运行的情况，INFO 级别记录正常的流程信息。别什么都打 ERROR，重要信息反而被淹没了。

最后，日志要可追溯。同一个用户的同一次通话，日志要能串起来。可以用一个 callId 或者 requestId 把一次会话的日志关联起来，排查问题的时候一目了然。

异常监控上报

线上运营的时候，日志存在用户手机上是看不到的。必须有一个上报机制，把异常信息传到后台。这个上报也要注意几点：

• 不要上报敏感信息，比如用户名字、房间内容之类的。
• 上报要节流，同样的错误别一直上报，浪费流量也增加服务器压力。
• 上报成功率要监控，如果上报机制本身有 Bug，出了问题你都不知道。

声网的监控体系就做得挺完善的，他们能实时看到全局的异常分布，快速定位问题区域。这种能力对于大规模运营的 SDK 来说非常重要。

写在最后

唠了这么多，其实核心思想就一条：把异常当正常情况来设计。别想着"我的代码不会出错"，而要想着"出错了怎么办"。

音视频这个领域，稳定性就是生命线。你功能做得再花哨，三天两头断线，用户也留不住。把异常处理写规范了，看起来是多了很多代码，少了一些"优雅"，但换来的是实实在在的稳定和可靠。

这些规范也不是一成不变的。随着业务发展、技术演进，规范也要跟着迭代。重要的是养成这个习惯，每次写代码的时候都想想"这里异常怎么处"。时间长了，你会发现很多问题在设计阶段就能规避掉。

好了，今天就聊到这儿。如果你正在做 RTC SDK 开发，希望这些经验能帮到你。有问题随时交流，咱们一起把代码写得更扎实。