编码与格式 / 系统课时
模块接口与日志
模块接口与日志
本课把媒体处理代码整理成边界清晰、可替换、可追踪的工程模块。完成后,你将能用统一接口约束初始化、处理与释放流程,并通过结构化日志快速定位某一路流、某一帧和某个模块的异常。
学习目标
- 设计稳定的媒体模块接口与生命周期
- 为处理链路传递统一的追踪上下文
- 记录可检索、可关联且不过量的结构化日志
先定义模块边界
媒体系统通常由解封装、解码、同步、渲染和输出等模块组成。接口不应暴露某个库的内部对象,而应只传递业务真正需要的数据,例如时间戳、轨道类型、负载和追踪标识。
一个实用接口至少包含三个阶段:start 负责申请资源,process 处理输入,close 负责释放资源。调用方只依赖接口,具体实现才能在 FFmpeg、硬件解码器或测试替身之间切换。

用统一接口约束生命周期
下面示例使用 Java 17 实现一个最小解码模块。代码不依赖第三方库,可以直接编译运行;真实项目中只需把 DecoderModule 内部逻辑替换为具体解码器。
import java.util.LinkedHashMap;
import java.util.Map;
public class MediaPipelineDemo {
record MediaPacket(String streamId, long pts, byte[] payload) {}
interface MediaModule extends AutoCloseable {
void start();
void process(MediaPacket packet);
@Override
void close();
}
static final class StructuredLogger {
static void info(String event, Map<String, Object> fields) {
StringBuilder json = new StringBuilder("{\"level\":\"INFO\",\"event\":\"")
.append(event).append("\"");
fields.forEach((key, value) -> json.append(",\"")
.append(key).append("\":\"").append(value).append("\""));
System.out.println(json.append("}"));
}
}
static final class DecoderModule implements MediaModule {
private final String traceId;
private boolean started;
DecoderModule(String traceId) {
this.traceId = traceId;
}
public void start() {
started = true;
Map<String, Object> fields = new LinkedHashMap<>();
fields.put("traceId", traceId);
fields.put("module", "decoder");
StructuredLogger.info("module_started", fields);
}
public void process(MediaPacket packet) {
if (!started) {
throw new IllegalStateException("decoder is not started");
}
Map<String, Object> fields = new LinkedHashMap<>();
fields.put("traceId", traceId);
fields.put("module", "decoder");
fields.put("streamId", packet.streamId());
fields.put("pts", packet.pts());
fields.put("bytes", packet.payload().length);
StructuredLogger.info("packet_decoded", fields);
}
public void close() {
started = false;
Map<String, Object> fields = new LinkedHashMap<>();
fields.put("traceId", traceId);
fields.put("module", "decoder");
StructuredLogger.info("module_closed", fields);
}
}
public static void main(String[] args) {
try (MediaModule decoder = new DecoderModule("trace-001")) {
decoder.start();
decoder.process(new MediaPacket("video-0", 3600, new byte[128]));
}
}
}编译并运行:
javac MediaPipelineDemo.java
java MediaPipelineDemo预期输出:
{"level":"INFO","event":"module_started","traceId":"trace-001","module":"decoder"}
{"level":"INFO","event":"packet_decoded","traceId":"trace-001","module":"decoder","streamId":"video-0","pts":"3600","bytes":"128"}
{"level":"INFO","event":"module_closed","traceId":"trace-001","module":"decoder"}日志字段要能回答问题
日志不是越多越好,而是要让一次检索回答“哪一路流、哪个模块、什么时间点、发生了什么”。建议所有模块统一保留 traceId、streamId、module、event 和 pts,错误日志再增加错误码、异常类型及关键参数。
帧级成功日志在高帧率场景中容易形成写入风暴。生产环境通常只记录状态变化、周期统计和异常事件;需要逐帧分析时,再临时提高指定流或指定模块的日志级别。
接口与日志的常见边界
模块接口应返回稳定的领域结果,不要把底层库的错误码直接扩散到上层。可以在模块内部把底层错误转换为统一异常,同时在日志中保留原始错误码,兼顾调用方稳定性与排障细节。
释放资源必须具备幂等性,即重复调用 close 不应再次释放同一资源。异步模块还要在关闭前停止接收新任务、等待工作线程退出,并记录队列长度和未完成任务数。
验收检查
完成实现后,至少验证三件事:未调用 start 时能够明确失败;同一 traceId 可以串起完整链路;关闭后没有线程、缓冲区或句柄泄漏。日志检索应能在一分钟内定位到具体模块和媒体时间戳。