一款优秀的 SDK 接口设计十大原则
这些年我参与和主导过多款音视频 SDK 的设计和开发，也服务过大大小小几十家 toB 客户，其中，有一条深深的感悟：微信
一个 PaaS 技术中间件产品，不管它的服务端 & 内核设计和实现的多么牛逼多么漂亮，最终交付给客户开发者的 SDK 才是最最关键的要素和门面，它设计得好，即便背后有不足也能有必定程度上的弥补；它设计的烂，就几乎废弃掉了底层全部的努力，还会平添无数的无效加班和问题排障的投入。
本文关注一款优秀的 SDK 应该如何设计接口规格，以实现以下几个目标： 闭包
- 简洁明了，边界清晰，接口正交（不存在 2 个接口相互冲突），使用者不容易踩坑
- 每个 API 的行为肯定，调用错误或者运行时异常的反馈及时准确
- 面向高级客户：配置丰富，回调丰富，业务扩展性和灵活性好
这里致敬 《Effective C++》的行文模式，以条款的形式来描述和示例个人我的思考和总结（以最近深度参与的 RTC SDK 接口设计为例子）。app
条款 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 的接口设计经验就介绍到这里了，每一个人都会有本身的风格和喜爱，这里仅表明我我的的一些观点和见解，欢迎留言讨论或者来信 lujun.hust@gmail.com 交流，或者关注个人微信公众号 @Jhuster 获取后续更多的文章和资讯~~ide
相关文章
- 1. 优秀API设计的十大原则
- 2. 优秀的API接口设计原则及方法（转）
- 3. RESTful 接口设计原则 和 优势
- 4. RESTful接口设计原则和优点
- 5. 如何设计一款优秀的短视频 SDK
- 6. 优秀网页设计_优秀Web设计的69条设计原则
- 7. 接口设计六大原则
- 8. App接口设计原则
- 9. 优秀设计师应当知道的几大UI设计原则（一）
- 10. 设计模式的七大原则(2) --接口隔离原则
- 更多相关文章...
- • Web 创建设计 - 网站建设指南
- • Hibernate的核心接口 - Hibernate教程
- • 算法总结-滑动窗口
- • JDK13 GA发布：5大特性解读
相关标签/搜索
每日一句
-
每一个你不满意的现在，都有一个你没有努力的曾经。
最新文章
欢迎关注本站公众号,获取更多信息
相关文章