视频点播：日志系统

概念介绍

什么是 LogHub？

LogHub 是 AliPlayerKit 中所有日志输出的统一入口，采用单例模式设计。它封装了 iOS 原生日志 API（NSLog），在保留原有功能的基础上，增加了以下核心能力：

什么是日志观察者？

日志观察者 (LogObserver) 是用于接收 LogHub 输出日志的回调协议。通过实现该协议，可以自定义日志的处理方式，例如：

• 将日志写入文件，便于问题排查时提供给技术支持团队

• 将日志上传到远程服务器，实现远程日志收集

• 在 UI 上展示日志，用于调试面板

混合线程模型

LogHub 采用混合线程模型：

功能特性

核心能力

核心组件

使用方式

基本用法 — 全局快捷配置

通过 AliPlayerKit 类方法快速配置日志系统（推荐方式）：

// 在 AppDelegate 中，setup 之后配置
[AliPlayerKit setup];

// 设置日志级别
[AliPlayerKit setLogLevel:LogLevelVerbose];

// 启用/禁用控制台日志
[AliPlayerKit enableConsoleLog:YES];

基本用法 — 输出日志

使用 SLOG 系列便捷宏输出各级别日志，宏会自动捕获源文件名和行号：

#import <AliPlayerKit/LogMacros.h>

// 输出各级别日志（自动捕获 __FILE_NAME__ 和 __LINE__）
SLOGV(@"viewDidLoad called");
SLOGD(@"配置播放器: videoId=%@", videoId);
SLOGI(@"开始播放视频: %@", videoTitle);
SLOGW(@"缓冲中，当前进度: %.1f%%", progress * 100);
SLOGE(@"播放失败，错误码: %ld", (long)errorCode);

便捷宏列表：

也可以直接调用 LogHub 实例方法，手动指定 tag：

// 使用 tag 标识日志来源
[[LogHub sharedHub] i:@"PlayerVC" msg:@"开始播放"];
[[LogHub sharedHub] e:@"MediaPlayer" msg:@"播放失败" error:error];

基本用法 — 配置日志级别

通过 LogHub 直接配置日志属性：

LogHub *logHub = [LogHub sharedHub];

#ifdef DEBUG
    // 开发环境：详细日志 + 控制台输出
    logHub.logEnabled = YES;
    logHub.consoleLogEnabled = YES;
    logHub.logLevel = LogLevelVerbose;
#else
    // 生产环境：精简日志 + 关闭控制台
    logHub.logEnabled = YES;
    logHub.consoleLogEnabled = NO;
    logHub.logLevel = LogLevelInfo;
#endif

三重控制机制：

高级用法 — 注册日志观察者

通过实现 LogObserver 协议自定义日志处理：

// 创建并注册文件日志观察者
FileLogObserver *fileObserver = [[FileLogObserver alloc] init];
[[LogHub sharedHub] addObserver:fileObserver];

// 移除观察者（不再需要时）
[[LogHub sharedHub] removeObserver:fileObserver];

高级用法 — 日志面板

LogPanelSlot 是一个内置的调试插槽，可在播放器视图中实时展示关键日志信息：

// 启用日志面板（建议仅在调试场景中启用）
[AliPlayerKit setLogPanelEnabled:YES];

自定义开发

日志观察者协议 (LogObserver)

@protocol LogObserver <NSObject>

@required

/// 日志输出回调
/// @param logInfo 日志信息对象，包含级别、标签、消息和时间戳
/// @warning 回调在后台串行队列执行，如需更新 UI 请 dispatch 到主线程
- (void)onLog:(LogInfo *)logInfo;

@end

LogInfo数据模型

格式化输出格式：

2024-04-22 10:30:00.123 I/AliPlayerKit [version] [FileName:line] [threadName] : message

如果存在错误，将附加额外一行：

Error: domain=xxx code=xxx userInfo=xxx

自定义文件日志观察者示例

以下是一个文件日志观察者的完整实现：

@interface MyFileLogObserver : NSObject <LogObserver>
- (instancetype)initWithLogDirectory:(NSString *)directory;
@end

@implementation MyFileLogObserver {
    NSString *_logFilePath;
    dispatch_queue_t _writeQueue;
    NSFileHandle *_fileHandle;
}

- (instancetype)initWithLogDirectory:(NSString *)directory {
    self = [super init];
    if (self) {
        _writeQueue = dispatch_queue_create("com.example.filelog",
                                            DISPATCH_QUEUE_SERIAL);
        [self setupLogFileAtDirectory:directory];
    }
    return self;
}

- (void)setupLogFileAtDirectory:(NSString *)directory {
    NSFileManager *fm = [NSFileManager defaultManager];
    if (![fm fileExistsAtPath:directory]) {
        [fm createDirectoryAtPath:directory
      withIntermediateDirectories:YES
                       attributes:nil
                            error:nil];
    }

    NSDateFormatter *formatter = [[NSDateFormatter alloc] init];
    formatter.dateFormat = @"yyyy-MM-dd";
    NSString *fileName = [NSString stringWithFormat:@"player_%@.log",
                          [formatter stringFromDate:[NSDate date]]];
    _logFilePath = [directory stringByAppendingPathComponent:fileName];

    if (![fm fileExistsAtPath:_logFilePath]) {
        [fm createFileAtPath:_logFilePath contents:nil attributes:nil];
    }
    _fileHandle = [NSFileHandle fileHandleForWritingAtPath:_logFilePath];
    [_fileHandle seekToEndOfFile];
}

#pragma mark - LogObserver

- (void)onLog:(LogInfo *)logInfo {
    NSString *formatted = [logInfo formattedString];

    dispatch_async(_writeQueue, ^{
        NSString *line = [formatted stringByAppendingString:@"\n"];
        NSData *data = [line dataUsingEncoding:NSUTF8StringEncoding];
        @try {
            [self->_fileHandle writeData:data];
        } @catch (NSException *exception) {
            // 忽略写入异常
        }
    });
}

- (void)dealloc {
    [_fileHandle closeFile];
}

@end

完整集成示例

// AppDelegate.m
#import <AliPlayerKit/AliPlayerKit.h>

@interface AppDelegate ()
@property (nonatomic, strong) MyFileLogObserver *fileLogObserver;
@end

@implementation AppDelegate

- (BOOL)application:(UIApplication *)application
    didFinishLaunchingWithOptions:(NSDictionary *)launchOptions {

    // 1. 初始化 AliPlayerKit
    [AliPlayerKit setup];

    // 2. 配置日志系统
#ifdef DEBUG
    [AliPlayerKit setLogLevel:LogLevelVerbose];
    [AliPlayerKit enableConsoleLog:YES];
    // 可选：启用日志面板
    [AliPlayerKit setLogPanelEnabled:YES];
#else
    [AliPlayerKit setLogLevel:LogLevelInfo];
    [AliPlayerKit enableConsoleLog:NO];

    // 3. 注册文件日志观察者（仅生产环境）
    NSString *logDir = [NSSearchPathForDirectoriesInDomains(
        NSDocumentDirectory, NSUserDomainMask, YES).firstObject
        stringByAppendingPathComponent:@"PlayerLogs"];
    self.fileLogObserver = [[MyFileLogObserver alloc] initWithLogDirectory:logDir];
    [[LogHub sharedHub] addObserver:self.fileLogObserver];
#endif

    return YES;
}

@end

最佳实践

环境配置建议

常见错误

错误 1：观察者回调中直接更新 UI

// ✗ 错误：onLog: 在后台串行队列执行，直接更新 UI 会崩溃
- (void)onLog:(LogInfo *)logInfo {
    self.logLabel.text = [logInfo formattedString];  // 崩溃！
}

// ✓ 正确：切换到主线程更新 UI
- (void)onLog:(LogInfo *)logInfo {
    NSString *formatted = [logInfo formattedString];
    dispatch_async(dispatch_get_main_queue(), ^{
        self.logLabel.text = formatted;
    });
}

错误 2：观察者中同步阻塞操作

// ✗ 错误：在回调中同步写文件，阻塞日志分发队列
- (void)onLog:(LogInfo *)logInfo {
    NSString *log = [logInfo formattedString];
    [log writeToFile:path atomically:YES encoding:NSUTF8StringEncoding error:nil];
}

// ✓ 正确：异步写入文件
- (void)onLog:(LogInfo *)logInfo {
    NSString *log = [logInfo formattedString];
    dispatch_async(_writeQueue, ^{
        // 异步写入...
    });
}

错误 3：忘记移除观察者导致循环引用

// LogHub 弱引用观察者，不移除不会造成循环引用，但可能在页面消失后仍收到日志回调
- (void)viewDidLoad {
    [[LogHub sharedHub] addObserver:self];
}

// ✓ 推荐：在生命周期结束时主动移除
- (void)viewWillDisappear:(BOOL)animated {
    [super viewWillDisappear:animated];
    [[LogHub sharedHub] removeObserver:self];
}

API 速查

日志级别 (LogLevel)

LogHub 核心 API

AliplayerKit日志快捷API

SLOG便捷宏

LogInfo属性

LogObserver 协议