这些年我参与和主导过多款音视频 SDK 的设计和开发,也服务过大大小小几十家 toB 客户,其中,有一条深深的感悟:
一个 PaaS 技术中间件产品,无论它的服务端 & 内核设计和实现的多么牛逼多么漂亮,最终交付给客户开发者的 SDK 才是最最关键的要素和门面,它设计得好,即使背后有不足也能有一定程度上的弥补;它设计的烂,就几乎废弃掉了底层所有的努力,还会平添无数的无效加班和问题排障的投入。
本文关注一款优秀的 SDK 应该如何设计接口规格,以实现如下几个目标:
- 简洁明了,边界清晰,接口正交(不存在 2 个接口相互冲突),使用者不容易踩坑
- 每一个 API 的行为确定,调用错误或者运行时异常的反馈及时准确
- 面向高级客户:配置丰富,回调丰富,业务扩展性和灵活性好
这里致敬 《Effective C++》的行文模式,以条款的形式来描述和示例我的个人思考和总结(以最近深度参与的 RTC SDK 接口设计为例子)。
条款 1 :参数配置提供独立的 profile 类,不要每个参数都提供一个 set 方法
// good case // 记得给出合理的默认值 class AudioProfile { int samplerate{44100}; int channels{1}; }; // 记得给出合理的默认值 class VideoProfile { int maxEncodeWidth{1280}; int maxEncodeHeight{720}; int maxEncodeFps{15}; }; // 可以很好地进行扩展,比如 SystemProfile,ScreenProfile... class EngineProfile { AudioProfile audio; VideoProfile video; }; class RtcEngine { public: static RtcEngine* CreateRtcEngine(const EngineProfile& profile) = 0; }; // bad case // 1. 核心接口类 RtcEngine 的函数数量爆炸 // 2. 无法约束业务方调用 API 的时间(可能在加入房间后或者某个不合适的时间去配置参数) // 3. 如果某个配置期望支持动态更新怎么办 ?通常配置是不建议频繁动态更新的(会影响 SDK 内部行为), // 如有必须,请显式在 engine 提供 updateXXXX or switchXXX 接口 class RtcEngine { public: static RtcEngine* CreateRtcEngine() = 0; virtual void setAudioSampelerate(int samplerate) = 0; virtual void setAudioChannels(int channels) = 0; virtual void setVideoMaxEncodeResolution(int width, int height) = 0; virtual void setVideoMaxEncodeFps(int fps) = 0; };
条款 2 :非运行时的状态 & 信息的查询和配置接口提供静态方法
// good case class RtcEngine { public: static int GetSdkVersion(); static void SetLogLevel(int loglevel); };
条款 3 :关键的异步方法附带上闭包回调告知结果
// good case typedef std::function<void(int code, string message)> Callback; class RtcEngine { public: // 客户可及时在 callback 中处理事件,比如:改变 UI 状态|提示错误|再次重试 virtual void Publish(Callback const& callback = nullptr) = 0; virtual void Subscribe(Callback const& callback = nullptr) = 0; }; // bad case class RtcEngine { public: class Listener { // 需要根据 code 来详细判断错误事件,且不一定能对得上哪一次 API 调用产生的错误 // 错误种类繁多,且跳出原来的逻辑,很多业务方会忽略在这里处理一些关键错误 virtual void OnError(int code, string message) = 0; }; void SetListener(Listener * listener) { _listener = listener; } virtual void Publish() = 0; virtual void Subscribe() = 0; private: Listener * _listener; };
条款 4 :所有接口尽量保证 “正交” 关系(不存在 2 个接口相互冲突)
// bad case // EnalbeAudio 与其他 API 接口并不 “正交”,组合起来容易用错 // MuteLocalAudioStream(true) & MuteAllRemoteAudioStreams(true) 依赖了使用者先调用 EnalbeLocalAudio(true) class RtcEngine { public: // EnalbeLocalAudio + MuteLocalAudioStream + MuteRemoteAudioStream virtual void EnalbeAudio(bool enable) = 0; // 打开本地的音频设备(麦克风 & 扬声器) virtual void EnalbeLocalAudio(bool enable) = 0; // 发布/取消发布本地音频流 virtual void MuteLocalAudioStream(bool mute) = 0; // 订阅/取消订阅远端音频流 virtual void MuteAllRemoteAudioStreams(bool mute) = 0; };
条款 5 :考虑扩展性,可抽象的对象尽量用结构体代替原子类型
// good case class RtcUser { string userId; string metadata; }; class RtcEngineEventListenr { public: // 未来可以很容易扩展 User 的信息和属性 virtual void OnUserJoined(const RtcUser& user) = 0; }; // bad case class RtcEngineEventListenr { public: // 一旦接口提供出去后,未来关于 User 对象的一些扩展信息和属性无法添加 virtual void OnUserJoined(string userId, string metadata) = 0; };
条款 6 :不可恢复的退出事件使用明确的 OnExit 且给出原因
客户在面对 SDK 提供的 OnError 回调事件的时候,由于错误种类特别多,他们往往不知道该如何应对和处理,建议有明确的文档告知处理方案。另外,当 SDK 内部发生了必须销毁对象退出页面的事件时,建议给出独立的 callback 函数让客户专门处理。
enum ExitReason { EXIT_REASON_FATAL_ERROR, // 未知的关键异常 EXIT_REASON_RECONNECT_FAILED, // 断线后自动重连达到次数&时间上限 EXIT_REASON_ROOM_CLOSED, // 房间被关闭了 EXIT_REASON_KICK_OUT, // 被踢出房间了 }; class RtcEngineEventListenr { public: // 一些警告消息,不碍事,接着用 virtual void OnWarning(int code, const string &message) = 0; // 发生了必须销毁 SDK 对象的事件,请关闭页面 virtual void OnExit(ExitReason reason, const string &message) = 0; };
条款 7 :PaaS 产品的 SDK 不要包含业务逻辑和信息
// bad case enum ClientRole { CLIENT_ROLE_BROADCASTER, // 主播,可以推流也可以拉流 CLIENT_ROLE_AUDIENCE // 观众,不能推流仅可以拉流 }; class RtcEngine { public: // 需要明确的文档介绍不同的 role 所对应的角色,以及 role 切换产生的行为 // 该 API 与其他的 API 不是 “正交” 的,比如:Publish virtual void SetClientRole(ClientRole& role) = 0; }; // good case // 建议在 examples 或者最佳实践中,封装多个 SDK 的原子接口,以达成上述 API 所起到的作用 class RoleManager { public: // 通过这种方式,客户可以显式地感知到这个 API 背后的一系列的行为动作 void SetClientRole(ClientRole& role) { // _engine->xxxxx1(); // _engine->xxxxx2(); // _engine->xxxxx3(); } private: RtcEngine * _engine; };
条款 8 :请提供所有必要的状态查询和事件回调,别让使用方 cache 状态
// good case class RtcUser { string userId; string metadata; bool audio{false}; // 是否打开并且发布了音频流 bool video{false}; // 是否打开并且发布了视频流 bool screen{false}; // 是否打开并且发布了屏幕流 }; class RtcEngine { public: // 由 SDK 内部来保持用户状态(最准确实时),并提供明确的查询 API // 而不是让客户在自己的代码中 cache 状态(很容易出现两边状态不一致的问题) virtual list<RtcUser> GetUsers() = 0; virtual RtcUser GetUsers(const string& userId) = 0; };
条款 9 :尽可能为参数配置提供枚举能力,并且返回 bool 告知配置结果
class VideoProfile { public: // 提供能力的枚举和配置结果,从而防止客户以为的配置跟实际的情况不一致 bool IsHwEncodeSupported(); bool SetHwEncodeEnabled(bool enabled); // 提供能力的枚举和配置结果,从而防止客户以为的配置跟实际的情况不一致 int GetSupportedMaxEncodeWidth(); int GetSupportedMaxEncodeHeight(); bool SetMaxEncodeResolution(int width, int height); };
条款 10 :接口文件的位置和命名风格保持一定的规则和关系
// good case // 某个代码 repo 的目录结构(当然,仅 Android 的包客户可感知,C++ 的库外部无法感知目录结构) // 建议所有的对外的 interface 头文件都在根目录下,而实现文件隐藏在内部文件夹中 // 合理的头文件位置关系,能够帮助开发者自己 & 客户准确地感知哪些是接口文件,哪些是内部文件 // 所有的对外的头文件,不允许 include 内部的文件,否则存在头文件污染问题 // 所有的接口 Class 命名都以统一的风格开头,比如 RtcXXXX,回调都叫 XXXCallback 等等 src - base - audio - video - utils - metrics - rtc_types.h - rtc_engine.h - rtc_engine_event_listener.h
小结
关于 SDK 的接口设计经验就介绍到这里了,每个人都会有自己的风格和喜好,这里仅代表我个人的一些观点和看法,欢迎留言讨论或者来信 [email protected] 交流,或者关注我的微信公众号 @Jhuster 获取后续更多的文章和资讯~~