第28章播放器SDK封装

课程目录第28章播放器SDK封装

28、播放器SDK封装：API设计、回调接口、模块化与解耦。

说实话，做播放器SDK封装这件事，我踩过的坑比走过的路还多。早期我接手过一个项目，代码全写在一个类里，播放、解码、渲染、网络切换全揉在一起。那叫一个酸爽——改一行代码，崩三个功能。后来我痛定思痛，才有了今天这套封装思路。

今天咱们聊的，就是怎么把播放器SDK封装得既好用又抗造。核心就三件事：API设计、回调接口、模块化解耦。说白了，就是让调用方用得爽，让维护方改得动。

API设计：少即是多

我见过很多SDK，暴露了几十个方法，调用方一脸懵。我个人习惯是：能藏的都藏起来，只给调用方最必要的接口。

一个播放器SDK，核心API其实就这几个：

方法	说明	备注
`init(context)`	初始化SDK	全局只调一次
`setDataSource(url)`	设置播放源	支持本地/网络
`prepare()`	异步准备	内部启动预加载
`start()`	开始播放	自动从暂停处恢复
`pause()`	暂停播放	保留当前进度
`seekTo(position)`	跳转到指定位置	单位毫秒
`release()`	释放资源	必须调用

你想想看，调用方拿到这7个方法，基本就能搞定90%的场景。剩下的10%，比如设置音量、切换音轨、调整播放速度，我建议用配置模式来处理。

核心原则：API越少，学习成本越低，出bug的概率也越低。不要为了「灵活性」把接口设计得跟瑞士军刀似的——没人需要一把能开罐头的播放器。

回调接口：让调用方知道发生了什么

播放器内部的状态变化，必须通过回调通知出去。我早期犯过一个错：用广播来通知状态变化。结果呢？广播满天飞，调试的时候根本不知道谁在监听。

后来我统一用接口回调，而且只暴露一个监听器：

public interface OnPlayerEventListener {
    void onPrepared();           // 准备完成
    void onPlaying();            // 开始播放
    void onPaused();             // 暂停
    void onCompletion();         // 播放完成
    void onError(int code, String msg);  // 错误回调
    void onProgress(long current, long total);  // 进度回调
    void onBuffering(int percent);  // 缓冲进度
}

嗯，这里要注意：回调一定要在主线程执行。我见过有人直接在解码线程里回调，调用方更新UI直接崩溃。解决方案很简单——用Handler切到主线程。

我的小技巧：回调接口里不要放太多方法。超过7个，调用方就会觉得烦。如果确实需要更多回调，拆成多个接口，比如OnErrorListener、OnBufferingListener，让调用方按需实现。

模块化与解耦：拆！拆！拆！

播放器SDK内部，我一般拆成这几个模块：

数据源模块：负责网络请求、本地文件读取、缓存管理
解码模块：音视频解码，支持硬解/软解切换
渲染模块：视频画面渲染、音频输出
控制模块：播放、暂停、seek等逻辑调度
状态管理模块：维护播放器状态机

模块之间怎么通信？我用的方式是接口依赖。每个模块只依赖接口，不依赖具体实现。举个例子：

// 解码模块接口
public interface IDecoder {
    void start();
    void stop();
    void seekTo(long position);
    void setOutputSurface(Surface surface);
    void setDecoderListener(DecoderListener listener);
}

// 控制模块只依赖IDecoder，不关心具体是MediaCodec还是FFmpeg
public class PlayerController {
    private IDecoder decoder;
    
    public PlayerController(IDecoder decoder) {
        this.decoder = decoder;
    }
}

这样做的好处是什么？你想想看，哪天你想把硬解换成软解，只需要新写一个实现类，控制模块一行代码都不用改。这就是解耦的魅力。

避坑指南：模块之间不要直接传对象，一定要通过接口。我曾经图省事，让控制模块直接调了解码模块的具体方法。结果后来换解码方案，改了一堆代码。从那以后，我再也不敢偷这个懒了。

状态机：播放器的灵魂

播放器内部的状态流转，必须用状态机来管理。我见过有人用一堆boolean变量来控制——isPlaying、isPaused、isPrepared……结果状态一多，逻辑就乱成一锅粥。

我推荐用枚举状态机：

public enum PlayerState {
    IDLE,           // 空闲
    INITIALIZED,    // 已设置数据源
    PREPARING,      // 正在准备
    PREPARED,       // 准备完成
    STARTED,        // 播放中
    PAUSED,         // 暂停
    COMPLETED,      // 播放完成
    ERROR,          // 错误
    RELEASED        // 已释放
}

每个状态只允许特定的操作。比如在IDLE状态下调用start()，直接返回错误。这样调用方用错了也能及时发现。

下面是我画的播放器状态流转图，你看一眼就明白了：

模块通信：事件总线 vs 接口回调

模块之间怎么通信？我试过两种方式：

事件总线：比如用LiveData或者自己写一个简单的事件总线。优点是解耦彻底，缺点是调试困难——你不知道事件是谁发的。
接口回调：模块A定义接口，模块B实现。优点是调用链清晰，缺点是模块之间还是有一定耦合。

我个人更倾向接口回调。原因很简单：代码可读性高。你打开一个类，看它实现了哪些接口，就知道它跟谁通信。事件总线虽然灵活，但查起来太费劲了。

我的经验：如果模块之间是「一对一」的关系，用接口回调。如果是「一对多」，比如状态变化要通知多个模块，用事件总线。别一刀切，看场景选方案。

总结一下

播放器SDK封装，说白了就是三件事：

API设计：少暴露，多封装。7个核心方法搞定90%场景。
回调接口：统一监听器，主线程回调，别超过7个方法。
模块化解耦：拆成数据源、解码、渲染、控制、状态管理五个模块，接口依赖，实现可替换。

嗯，这套方案我在好几个项目里验证过，效果都不错。你拿去用，遇到问题随时找我聊。

公众号:蓝海资料掘金营，微信deep3321

📚 课程目录

28、播放器SDK封装：API设计、回调接口、模块化与解耦。

API设计：少即是多

回调接口：让调用方知道发生了什么

模块化与解耦：拆！拆！拆！

状态机：播放器的灵魂

模块通信：事件总线 vs 接口回调

总结一下