这些年我参予和主导力量过数款音频 SDK 的结构设计和合作开发，也服务项目过大小不一十多家 toB 顾客，其中，有两条深深地的体悟：
两个 PaaS 技术合作开发工具产品，不论它的服务项目器端 & Mach结构设计和同时实现的何等牛逼何等很漂亮，最后转给顾客合作开发人员的 SDK 才是东齐县关键性的基本要素和门脸，它结构设计得好，即便另一面有严重不足也能有一定某种程度上的填补；它结构设计的烂，就基本上弃置掉了下层所有的不懈努力，还会增添不计其数的合宪上工和问题角蕨的资金投入。这款杰出的 SDK 应该如何结构设计USB技术标准，以同时实现如下表所示几个最终目标：
瑞维尼，边界线明晰，USB共轭（不存在 2 个USB互相武装冲突），普通用户不难踩坑每两个 API 的犯罪行为确认，初始化严重错误或是运转时极度的意见反馈及时处理准确面向全国高阶顾客：实用性多样，反弹多样，销售业务可扩展性和稳定性好这里致意 《Effective C++》的措词商业模式，以条文的方式来叙述和实例我的对个人思索和归纳（以前段时间广度参予的 RTC SDK USB结构设计为范例）。
条文 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. 核心USB类 RtcEngine 的函数数量爆炸
// 2. 无法约束销售业务方初始化 API 的时间（可能在加入房间后或是某个不合适的时间去实用性模块）// 3. 如果某个实用性期望支持动态更新怎么办 ？通常实用性是不建议频繁动态更新的（会影响 SDK 内部犯罪行为），
// 如有必须，请显式在 engine 提供更多 updateXXXX or switchXXX USBclass 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 ：非运转时的状态 & 信息的查询和实用性USB提供更多静态方法
// good caseclass 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 ：所有USB尽量保证 “共轭” 关系（不存在 2 个USB互相武装冲突）
// bad case
// EnalbeAudio 与其他 API USB并不 “共轭”，组合起来难用错
// 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:
// 一旦USB提供更多出去后，未来关于 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 的原子USB，以达成上述 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 ：USB文件的位置和命名风格保持一定的规则和关系
// good case
// 某个代码 repo 的目录结构（当然，仅 Android 的包顾客可感知，C++ 的库外部无法感知目录结构）// 建议所有的对外的 interface 头文件都在根目录下，而同时实现文件隐藏在内部文件夹中
// 科学合理的头文件位置关系，能够帮助合作开发人员自己 & 顾客精确地感知哪些是USB文件，哪些是内部文件// 所有的对外的头文件，不允许 include 内部的文件，否则存在头文件污染问题
// 所有的USB Class 命名都以统一的风格开头，比如 RtcXXXX，反弹都叫 XXXCallback 等等src
– base
– audio
– video
– utils
– metrics
– rtc_types.h
– rtc_engine.h
– rtc_engine_event_listener.h
小结
关于 SDK 的USB结构设计经验就介绍到这里了，每一人都会有自己的风格和喜好，这里仅代表我对个人的一些观点和看法，欢迎留言讨论或是来信 [email protected]
