一款优秀的 SDK 接口设计十大原则

这些年我参与和主导过多款音视频 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 caseclass RtcEngine {public:    static int GetSdkVersion();    static void SetLogLevel(int loglevel);};

条款 3 ：关键的异步方法附带上闭包回调告知结果

// good casetypedef 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 caseclass 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 caseclass RtcUser{    string userId;    string metadata;};class RtcEngineEventListenr {public:    // 未来可以很容易扩展 User 的信息和属性    virtual void OnUserJoined(const RtcUser& user) = 0;};// bad caseclass 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 caseenum 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 caseclass 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 的接口设计经验就介绍到这里了，每个人都会有自己的风格和喜好，这里仅代表我个人的一些观点和看法，欢迎留言讨论或者来信 lujun.hust@gmail.com 交流，或者关注我的微信公众号 @Jhuster 获取后续更多的文章和资讯~~

每一份赞赏源于懂得

赞赏

0人进行了赞赏支持