上周门店系统上线后第一天，老板打电话说后台对不上："今天明明只做了 50 笔，怎么后台收到 300 条？"查日志发现是门店收银终端断网期间本地缓存了操作，网络恢复后一次性全推上来，但中间超时重试了好几次，同一笔操作重复了五六条。

前后花了两天把幂等那层加上，记录下来。

## 一、问题根因：客户端不知道请求到底成没成

终端上报一笔操作的流程是：POST /api/sync → 等响应。如果网络超时（5 秒没回），客户端会重试。但服务端可能已经处理完了，只是响应丢了。这时重试就会造成重复数据。

核心问题不是"重试"，而是客户端和服务端对"这笔操作有没有成功"没有统一标识。

## 二、本地操作 ID：每笔操作一个全局唯一 ID

在终端本地生成操作时，就生成一个 UUID 作为操作 ID：

```txt
// 终端伪代码
String opId = UUID.randomUUID().toString();
Operation op = new Operation(opId, type, payload, System.currentTimeMillis());
localDb.save(op);
api.post("/api/sync", op);
```

这个 opId 一旦生成就不变。网络重试时，同一个 opId 重复发送，服务端可以靠它判断是不是重复请求。

## 三、服务端幂等表：同一个 opId 只处理一次

服务端收到请求后，先查幂等表，这个 opId 处理过就直接返回上次结果：

```txt
// 服务端伪代码
String opId = request.getHeader("X-Operation-Id");
IdempotentRecord exist = idempotentDao.findByOpId(opId);
if (exist != null) {
    return Result.success(exist.getResult());  // 直接返回上次结果
}
// 没处理过，执行业务
Result result = businessService.doOperation(request);
idempotentDao.save(opId, result, 24, TimeUnit.HOURS);
return Result.success(result);
```

幂等表存 opId 和处理结果，保留 24 小时。同一个 opId 的重复请求直接返回缓存结果，不重复执行业务。

## 四、重试队列：别让客户端自己盲目重试

客户端不要在 HTTP 超时后立即重试，而是把操作丢进本地重试队列，按指数退避重试：

```txt
// 终端重试逻辑
function retry(op) {
    int delay = Math.min(1000 * (1 << retryCount), 30000);  // 1s,2s,4s...最长30s
    setTimeout(() => {
        api.post("/api/sync", op).then(() => localDb.markDone(op.id))
                                 .catch(() => retry(op));
    }, delay);
}
```

关键是：重试时携带同一个 opId，服务端靠 opId 去重。客户端重试多少次都没关系，服务端只会处理一次。

## 五、踩坑清单（5 条实际踩过的）

1. opId 必须在客户端生成，不能让服务端生成——否则网络重试时客户端不知道用什么 ID。
2. 幂等表别用唯一索引直接挡住重复请求，要返回上次处理结果，否则客户端会报错而不是成功。
3. 幂等记录要设过期时间（24 小时），别无限增长，否则表会越来越大。
4. 重试间隔要指数退避，别固定 1 秒狂试，服务器恢复时会被重试请求冲垮。
5. 本地操作要持久化到 SQLite/IndexedDB，不能只放内存——终端重启后未上报的操作不能丢。

| 方案 | 重复数据 | 实现复杂度 | 适合场景 |
|---|---|---|---|
| 不做幂等 | 有 | 低 | 内网可靠网络 |
| 客户端去重 | 少 | 中 | 单终端 |
| opId+服务端幂等表 | 无 | 中高 | 多终端弱网 |

这次门店终端上报的幂等改造是在唯顿收银系统的终端同步模块上做的，我主要负责加本地操作 ID、写服务端幂等表和重试队列那套逻辑，改完后断网恢复的重复上报从每天几百条降到 0。

## 复盘

- 弱网环境下重复请求是必然的，问题在于有没有唯一操作 ID 去重。
- opId 在客户端生成，服务端幂等表存结果，重复请求直接返回缓存结果。
- 客户端重试要指数退避，操作要持久化，别靠内存。

以上是个人实践记录，各平台具体功能以官方实时信息为准。

你们做终端数据同步时，幂等是放在客户端还是服务端？

上周门店系统上线后第一天，老板打电话说后台对不上："今天明明只做了 50 笔，怎么后台收到 300 条？"查日志发现是门店收银终端断网期间本地缓存了操作，网络恢复后一次性全推上来，但中间超时重试了好几次，同一笔操作重复了五六条。

终端断网恢复后数据重复上报：本地操作 ID、服务端幂等表与重试队列的落地记录

门店终端断网恢复后同一笔操作重复上报五六条。记录在客户端生成UUID操作ID、服务端幂等表缓存处理结果、指数退避重试队列的完整方案，以及幂等表过期、死锁等踩坑。

人工智能

门店收银终端弱网环境下重复上报导致后台数据对不上，根因是客户端重试时缺少统一操作标识。本文分享幂等改造方案：客户端生成全局唯一opId，服务端通过幂等表去重并缓存结果，配合指数退避重试队列和本地持久化。改造后重复上报从每天几百条降到零，适合多终端弱网场景。

数据同步

代码解释

服务器

SQLite

文章

问答

视频

教程

学习中心

腾讯云实验室

直播

竞赛

腾讯云代码分析专区

腾讯iOA零信任安全管理系统专区

腾讯云架构师技术同盟交流圈

腾讯云数据库专区

腾讯云智能顾问专区

腾讯云原生专区

腾讯混元专区

腾讯云TCE专区

腾讯云Lighthouse专区

腾讯云HAI专区

腾讯云Edgeone专区

腾讯云存储专区

腾讯云智能专区

腾讯轻联专区 

腾讯云开发专区

TAPD专区

腾讯轻量云游戏服专区

EdgeOne AI 安全实战专区

腾讯云最具价值专家

腾讯云架构师技术同盟

腾讯云创作之星

腾讯云开发者先锋

腾讯云代码助手

云原生构建

TAPD 敏捷项目管理

Cloud Studio

SDK中心

API中心

命令行工具

涵盖代码开发、场景应用、自动测试全流程，助你从零构建专属AI助手

一站式MCP教程库，解锁AI应用新玩法

聚焦“写作效率、视觉美观与运行性能”三方面进行全面升级，为您提供更高效、稳定的创作环境

社区富文本&Markdown编辑器全新改版上线，欢迎大家体验!

诚挚邀请您参与本次调研，分享您的真实使用感受与建议。您的反馈至关重要，感谢您的支持与参与！

社区新版编辑器体验调研

终端断网恢复后数据重复上报：本地操作 ID、服务端幂等表与重试队列的落地记录-腾讯云开发者社区-腾讯云

终端断网恢复后数据重复上报：本地操作 ID、服务端幂等表与重试队列的落地记录

终端断网恢复后数据重复上报：本地操作 ID、服务端幂等表与重试队列的落地记录

社区

活动

圈层

关于

腾讯云开发者

热门产品

热门推荐

更多推荐