在音视频系统中，一次上传可能因为网络超时被客户端重试三次，一次转码任务可能因为消息队列的至少一次投递语义被消费两遍，一次回调通知可能因为第三方重发机制被推送多次。如果API本身不具备幂等性，这些重复请求会转化为重复转码浪费计算资源、重复计费、媒体库出现多个相同文件等实际业务损失。本文围绕音视频API的幂等性设计展开，从请求去重、异步任务幂等、回调防重三个核心场景给出可落地的方案。
为什么音视频API特别需要幂等性
音视频处理有几个天然放大重复危害的特点。第一，处理成本高，一次高清视频转码可能耗时几分钟并占用大量CPU或GPU资源，重复执行直接造成资源浪费。第二，链路长，从上传、转码、截图、审核到CDN分发，中间任何一个环节的重试都可能放大成下游多次执行。第三，计费敏感，存储、流量、转码时长都涉及计费，重复处理会直接导致账单异常。
重复请求的来源通常有三类：客户端重试（用户点击、超时重发）、网关或负载均衡重试、消息队列的重复投递。HTTP本身是无状态协议，POST请求天然不幂等，而音视频的上传、转码提交又几乎都是POST，所以幂等性必须由服务端主动设计，不能指望调用方自觉。
一个常见的误区是认为接口内部用数据库唯一索引就够了。唯一索引只能防止重复落库，无法防止重复触发转码流水线、重复调用外部转码服务等副作用。幂等性的正确目标是：同一业务请求无论被触发多少次，系统的最终状态和产生的副作用都只发生一次。
幂等请求令牌的实现方案
最通用的方案是幂等令牌，即客户端在发起请求前先申请一个唯一的token，之后每次重试都携带同一个token，服务端根据token判断请求是否已经处理过。流程通常分为申请和使用两步：客户端调用申请接口获取token，服务端将token写入Redis并设置过期时间；客户端提交业务请求时携带token，服务端尝试原子性地删除token，删除成功才执行业务。
用Redis实现时，关键在于原子操作，绝不能用先查询后删除的两步操作，否则并发请求会在查询阶段同时通过判断。正确做法是使用SETNX或者Lua脚本保证原子性。下面是一个转码提交接口的示例：
// 提交转码请求，携带幂等令牌
public TranscodeResult submitTranscode(TranscodeRequest req) {
String idempotentKey = req.getIdempotentKey();
// SETNX 原子写入，EX 设置过期时间，比如24小时
Boolean ok = redis.opsForValue().setIfAbsent(
"idem:transcode:" + idempotentKey, "1", 24, TimeUnit.HOURS);
if (Boolean.FALSE.equals(ok)) {
// 令牌已存在，说明是重复请求，直接返回上次的结果
return getResultFromCache(idempotentKey);
}
try {
TranscodeResult result = doTranscode(req);
cacheResult(idempotentKey, result);
return result;
} catch (Exception e) {
// 处理失败必须删除令牌，允许客户端重试
redis.delete("idem:transcode:" + idempotentKey);
throw e;
}
}这里有一个容易被忽视的细节：失败时必须回滚令牌，否则客户端的一次临时故障会导致这个请求永远无法重新提交。另一个细节是令牌的粒度要绑定到具体业务操作上，比如转码提交用transcode前缀，上传分片合并用upload前缀，避免不同接口的令牌互相干扰。对于没有申请令牌能力的旧客户端，也可以退化为使用业务指纹作为幂等键，例如对文件MD5加上用户ID加上操作类型做哈希，效果类似。
数据库层面的兜底同样重要。给任务表的业务流水号加上唯一索引，即使Redis中的令牌因故障丢失，重复插入也会被数据库拦截。Redis负责拦截大部分重复请求提升性能，唯一索引负责极端情况下的最终一致性，两层防护配合使用。
分布式锁与去重表在异步任务中的应用
音视频的核心处理通常是异步任务：消息队列把转码任务投递给消费者集群，而主流消息队列如Kafka、RabbitMQ都提供至少一次投递语义，重复消费是常态而非异常。任务消费侧的幂等设计有两种主流做法：分布式锁和去重表。
分布式锁适合任务执行时间较长的场景。消费者收到消息后先尝试获取以任务ID为键的锁，获取成功才执行转码，失败则说明有其他实例正在处理，可以直接丢弃或延后重试。需要注意锁的过期时间必须大于最长处理时长，否则一个两小时的大文件转码任务可能在锁过期后被另一个实例重复执行。更稳妥的做法是采用看门狗机制自动续期，并在锁中写入持有者标识，释放锁时校验持有者，避免误删他人的锁。
// 消费转码任务消息
public void onTranscodeMessage(TranscodeMessage msg) {
String lockKey = "lock:task:" + msg.getTaskId();
String ownerId = UUID.randomUUID().toString();
// 加锁并启动看门狗自动续期
boolean locked = redisLock.tryLock(lockKey, ownerId, 30, TimeUnit.SECONDS);
if (!locked) {
return; // 其他实例正在处理，本条消息直接确认
}
try {
// 先查任务状态，已完成则跳过，双重保险
Task task = taskRepo.findById(msg.getTaskId());
if (task.getStatus() == TaskStatus.DONE) {
return;
}
doTranscode(task);
taskRepo.updateStatus(task.getId(), TaskStatus.DONE);
} finally {
redisLock.unlock(lockKey, ownerId);
}
}去重表方案则是在数据库中维护一张已处理消息表，消息的唯一ID加唯一索引，消费者处理前先插入去重记录，插入成功说明是首次处理，插入冲突则说明已处理过。这种方案不依赖Redis的可用性，且记录可以长期保留便于审计，缺点是高并发下数据库写入压力较大。实践中常将两者结合：锁保证同一时刻只有一个实例处理，去重表保证跨时间的重复消息被识别。
状态机校验是第三道防线。音视频任务的生命周期通常是待处理、处理中、成功、失败，每次状态变更前都检查当前状态是否允许迁移。例如只有处于待处理或失败状态的任务才能进入处理中，已完成任务的重复消息会被状态检查直接拒绝。状态机把幂等逻辑内化到业务模型中，即使前面的去重手段全部失效，也能保证业务不被重复执行。
回调通知与客户端重试的防重设计
音视频服务处理完成后向业务方推送回调，这个环节的防重经常被忽略。回调接收方如果直接信任每一次通知，可能出现重复入库、重复触发后续业务的问题。正确做法是要求回调携带全局唯一的消息ID，接收方用这个ID做去重，处理成功后返回明确的成功应答，处理失败或超时则允许对方重推。
回调处理本身也要考虑乱序问题。重试机制可能导致旧状态的通知晚于新状态到达，例如先收到处理成功的回调，又收到一条延迟的处理中回调。解决办法是在回调中携带版本号或时间戳，接收方只接受版本更高的通知，低版本通知直接确认丢弃。对于上传场景，客户端分片上传的最后一步合并请求尤其需要幂等，通常以上传ID加文件MD5作为幂等键，保证合并操作只执行一次，重复的合并请求返回上次的确认结果即可。
最后需要强调的是幂等结果的缓存策略。对客户端而言，重复请求返回相同结果比返回错误更友好，所以首次处理成功后应将结果与幂等键关联缓存一段时间，缓存时长要覆盖客户端最长的重试窗口，一般不少于24小时。同时要区分幂等键的失效场景：主动失效用于业务取消，被动失效用于防止键被无限累积。整套幂等体系建成后，还应该在压测中专门加入重复请求的测试用例，验证各层防护真正生效，而不是停留在设计文档里。