幂等函数必须拒绝副作用和状态依赖:需以持久化存储(如Redis原子操作、DB唯一约束)校验幂等键,确保输入相同则输出与外部状态终态均相同,禁止依赖内存缓存或隐式上下文,且须全链路透传幂等键。

幂等函数必须拒绝副作用和状态依赖
Go 函数本身没有“自动幂等”机制,所谓幂等函数,是指你写的 func 在多次调用时,对共享状态(DB、Redis、文件、全局变量)的修改效果与调用一次完全一致。常见错误是把“只执行一次”的逻辑硬编码进函数里,比如用 sync.Once 或本地 map 记录已执行,这在多实例、重启、分布式场景下立刻失效。
真正安全的幂等函数必须满足:输入相同 → 输出相同 + 外部状态终态相同。这意味着它不能依赖当前内存状态做判断,而要靠外部持久化存储(如 Redis 原子操作、DB 唯一约束)来识别“是否已处理过”。
- 禁止在函数内初始化全局
sync.Map或map[string]bool来缓存执行标记 - 禁止调用
os.WriteFile、http.Post、db.Exec等带副作用的操作前不校验幂等上下文 - 函数签名应显式接收幂等键(
idempotencyKey string),而不是从 context 或配置中隐式读取 - 若函数需返回结果,应支持传入
result *T或返回(T, bool)表示“是否命中缓存”
用 Redis.SetNX + TTL 实现函数入口原子拦截
最常用且轻量的方式是在函数最外层用 Redis 做“占位锁”,确保同一 idempotencyKey 不会并发进入业务逻辑。关键不是“加锁”,而是“原子注册+过期”,避免死锁或残留。
使用 github.com/go-redis/redis/v8 时,必须用 client.SetNX,而非先 Exists 再 Set —— 后者有竞态窗口。
-
key格式建议为"idempotent:" + businessType + ":" + idempotencyKey,避免跨业务冲突 -
TTL必须 ≥ 函数最长可能耗时(含下游重试),例如支付回调函数设为120 * time.Second - 若
SetNX返回false,说明已有请求在处理或已完成,此时应直接查缓存或 DB 获取结果,而非报错 - Redis 故障时,
err != nil不能跳过校验——应返回503 Service Unavailable,而不是降级为非幂等执行
数据库唯一索引才是最终一致性兜底
Redis 只能防“重复触发”,不能保“重复写入不发生”。只要函数涉及写库,就必须在 DB 层设置唯一约束,并在 INSERT 或 UPDATE 后主动捕获冲突错误。这不是异常处理,而是正常业务分支。
使用 uber-go/dig 在 Golang 中实现依赖注入——基于反射容器,提供 Provide/Invoke、dig.In/dig.Out 参数与结果对象,支持命名依赖等
例如订单创建函数中,插入前不查、不预占,直接 INSERT INTO orders (order_no, user_id, amount) VALUES (?, ?, ?),然后判断错误类型:
- MySQL:用
errors.Is(err, mysql.ErrDupKey)或正则匹配"Duplicate entry" - PostgreSQL:检查
pgx.ErrCodeUniqueViolation - 捕获到后,不做
return err,而是查出该order_no对应记录,返回完整订单数据 - 唯一字段必须是业务语义唯一,如
(user_id, order_no)或(idempotency_key),不能是自增id
异步任务函数要自带状态机,不能只靠一次 SetNX
如果函数启动 goroutine 或发消息到队列,仅靠入口拦截是不够的。因为 goroutine 可能失败、消息可能重复投递、Worker 可能重启。这时函数内部要维护三态状态机:pending → success / failed,并用 CAS 更新。
典型模式是:首次调用时,用 INSERT INTO idempotent_records (key, status, created_at) VALUES (?, 'pending', ?);成功后 UPDATE ... SET status = 'success', result = ? WHERE key = ? AND status = 'pending';重复请求则查状态并返回对应结果。
- 不要用布尔字段
is_executed,无法区分“正在执行中”和“已成功”,会导致并发请求阻塞或误判 - 状态更新必须和业务主表操作同事务(如 PostgreSQL 的 CTE 或 MySQL 的事务内嵌套查询),否则状态和数据可能不一致
- 若函数触发的是外部 HTTP/gRPC 调用,幂等键必须透传给下游,并要求对方也实现幂等,否则本端再严谨也没用
真正的难点不在“怎么写一个幂等函数”,而在于如何让整个调用链路每一环都接受并传递同一个幂等键——从 HTTP header 提取、到中间件校验、到 DAO 层写库、再到异步任务落库、最后到下游接口透传。漏掉任意一环,幂等性就形同虚设。
golang免费学习笔记(深入):立即使用
在学习笔记中,你将探索golang的核心概念和高级技巧!










