面向使用 Go、MySQL、Redis 与 go-zero 的生产服务。本文从表结构、生成代码到故障恢复,梳理一条可靠 CRUD 的落地路径。
摘要
goctl model 能消除大量单表 CRUD 样板代码,但它不能决定订单是否可重复支付、事务提交后缓存如何恢复、批量更新怎样失效,也不能替业务判断关键读是否允许陈旧。
本文以订单支付为例:用数据库条件更新和唯一约束维护业务不变量;用本地事务绑定订单、支付流水和 outbox 事件;让缓存成为可容忍陈旧的加速层,并让失效失败能够被重试和观测。
文中的 go-zero API 语义需要在发布前对照锁定版本的源码复核。不同版本的生成文件名、字段类型、缓存键前缀和配置字段可能不同,不要将示例中的私有名称直接复制到项目中。
1. 结论与适用范围
本文讨论单个 MySQL 数据库内的订单支付确认和 Redis 行缓存,不试图解决跨库强一致事务、支付渠道最终状态查询或全局分布式 ID 的全部问题。
先明确四个原则:
- 数据库裁决业务事实。状态条件、版本号、唯一约束和本地事务负责维护业务正确性。
- 缓存服务于读取性能。支付、库存、额度等决策不能以 Redis 或异步从库作为唯一事实来源。
- 提交后删缓存不是原子协议。它能降低陈旧概率,但无法阻止提交后崩溃和旧读回填。
- 可靠性需要可恢复事件。订单变更和 outbox 事件在同一事务中提交,后台 worker 负责重试、幂等与告警。
目标不是承诺“绝对没有陈旧读”,而是区分哪些接口必须正确、哪些展示接口允许陈旧多久,以及故障发生后如何恢复。
2. 从一次事故理解问题
支付回调将订单更新为已支付,HTTP 响应也返回成功;用户立刻刷新订单详情,却仍然看到待支付。常见错误有两类:
- 自定义
UPDATE 直接经底层连接执行,绕过 Model 的缓存删除,旧行直到 TTL 到期才消失。
- 在事务提交前删除缓存。并发读请求回源读到旧数据库行;事务提交后,该请求又把旧值写回 Redis。
即使把删除操作移到提交之后,仍可能出现下面的竞态:
读请求 R: SELECT 旧订单 ───────────────────────── SET Redis(旧订单)
写请求 W: UPDATE + COMMIT ─ DEL Redis
时间: ─────────────────────────────────────────────────────>
W 提交后删除了缓存,R 却可能在删除后完成回填。缩短 TTL 只能限制陈旧时长,不能消除这个窗口。因此,关键正确性必须由 MySQL 维护,缓存失效也必须有恢复路径。
3. 先读源码:缓存 Model 保证了什么
讨论框架行为前,先核对当前版本 CachedConn 的三个相关语义:
ExecCtx 先运行数据库函数。数据库失败时返回空结果和错误;数据库成功、删除缓存失败时返回结果和错误。
QueryRowsNoCacheCtx 明确绕过缓存,源码注释指出列表缓存可能带来一致性问题。
WithSession 会把 session 包装为新的连接,但源码明确建议事务内不要使用缓存读取未提交数据。
这些语义有明确边界:
| 操作 |
可以依赖的语义 |
不可推导的语义 |
CachedConn.ExecCtx |
SQL 成功后才尝试删除传入键 |
SQL 和 Redis 删除原子成功 |
| 单行缓存查询 |
可减少相同键回源 |
跨实例只发生一次回源,或一定读到最新值 |
QueryRowsNoCacheCtx |
列表直接查询数据库 |
列表天然具有正确的快照语义 |
WithSession |
可以使用同一 session 访问数据库 |
事务内可以安全使用普通缓存查询 |
生成器通常能为主键和唯一索引生成单行访问;普通索引的集合查询、聚合和游标分页需要自行实现。重新生成前后必须审查 diff:DDL、goctl 版本和模板变化都可能改变接口与缓存键。
4. 工程基线:迁移、生成与目录边界
将迁移脚本和生成输入纳入仓库,并划分机器生成层与手写扩展层:
order-service/
├── deploy/sql/ # 迁移与 goctl 输入
├── internal/model/
│ ├── ordersmodel_gen.go # 机器生成:禁止手改
│ ├── ordersmodel.go # 手写扩展:条件写、列表、事务辅助
│ └── vars.go
├── internal/logic/ # 用例编排,不直接拼缓存键
├── internal/svc/ # 连接、Model 与 worker 注入
├── internal/worker/ # outbox 投递与缓存修复
└── Makefile
.PHONY: gen-model check-model
gen-model:
goctl model mysql ddl -src ./deploy/sql/orders.sql -dir ./internal/model -cache
check-model: gen-model
git diff --exit-code -- ./internal/model
在构建工具或依赖文件中锁定 goctl 与 github.com/zeromicro/go-zero 版本,并在 CI 中运行 check-model。
表结构演进遵循前向兼容:先增加字段和索引,再发布兼容读写的代码,然后回填与切流,最后删除旧结构。不可逆迁移应设置备份、校验和人工决策点。
4.1 发布前的版本核验清单
首次接入或升级框架时,生成一张最小样表,保存以下检查结果:
BIGINT UNSIGNED、INT UNSIGNED、DATETIME(3) 对应的 Go 字段类型。
- 生成的主键与唯一键查询方法、缓存键前缀和唯一键映射方式。
- 生成的
Insert、Update、Delete 实际传给缓存层的键。
ExecCtx 在“SQL 成功、删缓存失败”时的返回语义。
TransactCtx、sqlx.Session 与 WithSession 的实际签名。
这份检查表应与 go-zero 版本一起进入代码评审记录。
5. DDL:让不变量在数据库层有落点
金额使用最小货币单位;退款单独建模,不通过负订单金额表达。以下 CHECK 约束需要目标 MySQL 版本支持并实际执行;若不能依赖它,应在应用层验证,并在迁移规范中明确限制。
CREATE TABLE orders (
id BIGINT UNSIGNED NOT NULL AUTO_INCREMENT,
order_no VARCHAR(64) NOT NULL,
user_id BIGINT UNSIGNED NOT NULL,
total_amount BIGINT UNSIGNED NOT NULL,
status TINYINT UNSIGNED NOT NULL COMMENT '1:pending, 2:paid, 3:cancelled',
version INT UNSIGNED NOT NULL DEFAULT 0,
created_at DATETIME(3) NOT NULL DEFAULT CURRENT_TIMESTAMP(3),
updated_at DATETIME(3) NOT NULL DEFAULT CURRENT_TIMESTAMP(3)
ON UPDATE CURRENT_TIMESTAMP(3),
PRIMARY KEY (id),
UNIQUE KEY uk_order_no (order_no),
KEY idx_user_id_id (user_id, id),
CONSTRAINT chk_order_status CHECK (status IN (1, 2, 3))
) ENGINE=InnoDB DEFAULT CHARSET=utf8mb4;
CREATE TABLE payment_records (
id BIGINT UNSIGNED NOT NULL AUTO_INCREMENT,
order_id BIGINT UNSIGNED NOT NULL,
provider VARCHAR(32) NOT NULL,
provider_trade_no VARCHAR(128) NOT NULL,
amount BIGINT UNSIGNED NOT NULL,
created_at DATETIME(3) NOT NULL DEFAULT CURRENT_TIMESTAMP(3),
PRIMARY KEY (id),
UNIQUE KEY uk_provider_trade (provider, provider_trade_no),
UNIQUE KEY uk_order_provider (order_id, provider)
) ENGINE=InnoDB DEFAULT CHARSET=utf8mb4;
CREATE TABLE outbox_events (
id BIGINT UNSIGNED NOT NULL AUTO_INCREMENT,
event_id CHAR(36) NOT NULL,
topic VARCHAR(128) NOT NULL,
aggregate_type VARCHAR(64) NOT NULL,
aggregate_id BIGINT UNSIGNED NOT NULL,
payload JSON NOT NULL,
status TINYINT UNSIGNED NOT NULL DEFAULT 0 COMMENT '0:pending,1:processing,2:done',
retry_count INT UNSIGNED NOT NULL DEFAULT 0,
locked_until DATETIME(3) NULL,
last_error VARCHAR(512) NULL,
created_at DATETIME(3) NOT NULL DEFAULT CURRENT_TIMESTAMP(3),
published_at DATETIME(3) NULL,
PRIMARY KEY (id),
UNIQUE KEY uk_event_id (event_id),
KEY idx_claim (status, locked_until, id)
) ENGINE=InnoDB DEFAULT CHARSET=utf8mb4;
支付回调的幂等身份是 (provider, provider_trade_no),不是 HTTP 重试次数。uk_order_provider 是否合理,取决于一个订单能否存在多笔合法支付;如果支持多次尝试,应改成能表达业务规则的唯一约束,不能机械复制。
索引 (user_id, id) 服务于按用户、ID 倒序的游标分页。若经常按状态过滤,应结合真实数据分布和 EXPLAIN ANALYZE 评估 (user_id, status, id),不要为每个筛选条件都增加索引。
6. 条件更新:先判断业务结果,再谈缓存
订单支付转换应以旧状态和版本为条件:
UPDATE orders
SET status = 2, version = version + 1, updated_at = UTC_TIMESTAMP(3)
WHERE id = ? AND status = 1 AND version = ?;
RowsAffected = 0 不等于“支付失败”:它可能代表已支付重放、已取消、版本冲突或订单不存在。判断顺序可以是:
- 插入或读取支付流水,通过唯一约束识别渠道重复回调;重复时验证订单、金额和渠道交易号一致。
- 条件更新订单,判断本次是否完成合法状态转换。
- 如需决定 API 错误码,再从主库读取订单与流水;回读只用于分类,不能替代前两步的并发裁决。
外部支付超时后不能直接再次扣款。应先向支付渠道查询最终状态,并在事实未完整时返回“处理中”或“待核查”。
6.1 自定义单行写入的 Model 实现骨架
下面的代码展示关键错误处理。orderIDCacheKey 和 orderNoCacheKey 必须按项目实际生成的键格式实现,不要由 Logic 层复制私有常量。
type orderModel struct {
sqlc.CachedConn
table string
}
func (m *orderModel) TransitionStatus(
ctx context.Context, id uint64, orderNo string, from, to, version uint64,
) (affected int64, err error) {
res, execErr := m.ExecCtx(ctx, func(ctx context.Context, conn sqlx.SqlConn) (sql.Result, error) {
query := "UPDATE " + m.table +
" SET status=?, version=version+1, updated_at=UTC_TIMESTAMP(3)" +
" WHERE id=? AND status=? AND version=?"
return conn.ExecCtx(ctx, query, to, id, from, version)
}, m.orderIDCacheKey(id), m.orderNoCacheKey(orderNo))
// res 非空而 execErr 非空意味着:SQL 已成功,缓存删除失败。
if res == nil {
return 0, execErr
}
affected, rowsErr := res.RowsAffected()
if rowsErr != nil {
return 0, errors.Join(execErr, rowsErr)
}
return affected, execErr
}
关键是返回语义:调用方拿到 affected=1 和非空错误时,不能把操作当作未执行并盲目重试。它应读取业务事实、记录缓存修复任务,并根据幂等键返回结果。
身份类唯一字段最好不可修改;若必须修改,旧键和新键都应失效。此单行写入骨架本身不包含 outbox,不能单独保证修复任务与业务更新原子提交。
7. 多表事务:订单、流水与 outbox 同时提交
事务内部只使用同一个 sqlx.Session 查询和执行数据库操作,不能混用普通缓存 Model 的 FindOne。以下伪代码不依赖生成接口名,用于表达事务边界:
func (s *PaymentService) ConfirmPayment(ctx context.Context, cmd ConfirmCmd) error {
return s.conn.TransactCtx(ctx, func(ctx context.Context, session sqlx.Session) error {
order, err := s.loadOrderForUpdate(ctx, session, cmd.OrderID)
if err != nil {
return err
}
if order.TotalAmount != cmd.Amount {
return ErrAmountMismatch
}
// 唯一键冲突时,读取既有流水,校验后返回幂等成功或明确冲突。
if err := s.insertPaymentRecord(ctx, session, cmd); err != nil {
return s.classifyExistingPayment(ctx, session, cmd, err)
}
affected, err := s.transitionPendingToPaid(ctx, session, order.ID, order.Version)
if err != nil {
return err
}
if affected != 1 {
return ErrUnexpectedOrderState
}
// 订单事件同时承担业务消息和缓存修复的可靠来源。
return s.insertOutbox(ctx, session, NewOrderPaidEvent(order.ID, order.OrderNo))
})
}
是否使用 SELECT ... FOR UPDATE,取决于不变量是否需要串行化。如果一条条件更新加唯一约束已经足够表达规则,应优先考虑更短的事务和更小的锁范围,不必把所有读取都升级为排他锁。
提交后可同步做一次最佳努力的缓存删除,以缩短窗口,但不能把它当作唯一保障。进程在提交后崩溃时,outbox 中已提交的事件仍可由 worker 处理。
8. Outbox worker:租约、幂等、重试与最终失败
worker 至少需要处理四件事:避免多个实例同时领取同一事件;进程崩溃后让事件能够重新领取;保证下游重复收到事件时不会重复生效;持续失败时不能无限静默重试。
8.1 领取事件
在 MySQL 8 中,可在短事务内用 FOR UPDATE SKIP LOCKED 选出一批 pending 或租约过期的事件,更新 status=processing 与 locked_until 后提交。实际 SQL 应结合批大小和索引验证:
SELECT id
FROM outbox_events
WHERE status = 0
OR (status = 1 AND locked_until < UTC_TIMESTAMP(3))
ORDER BY id
LIMIT ?
FOR UPDATE SKIP LOCKED;
UPDATE outbox_events
SET status = 1,
locked_until = DATE_ADD(UTC_TIMESTAMP(3), INTERVAL 30 SECOND),
retry_count = retry_count + 1
WHERE id IN (...);
完成领取后,worker 在事务外执行 Redis 删除和消息投递。成功时将事件标记为 done;失败时记录截断后的错误信息并恢复为 pending,或保留 processing 等待租约到期。
重试间隔应使用指数退避与抖动;超过次数或事件年龄阈值后,应转入明确的失败状态并告警。上面的示例表只定义了 pending、processing 和 done,落地最终失败状态时需要同步扩展状态定义及处理逻辑。
租约过期后,原 worker 仍可能继续运行,因此处理结果和状态更新也需要考虑过期 worker 与新领取者并发的情况。不要在持有数据库行锁时访问 Redis、Kafka 或 HTTP 下游。
8.2 消息“至少一次”不等于业务“恰好一次”
worker 可能在消息已发送后、数据库标记 done 前崩溃,因此消息会被重复发送。消费者必须依据 event_id 做幂等去重,或让消费写入受唯一约束保护的处理记录。缓存 DEL 天然幂等,业务消息消费通常不是。
若一条 outbox 事件既要删除缓存又要发布领域消息,应分别观测两类下游结果。删除成功、消息失败时不应标记整体完成;可以使用多个投递状态,或拆成具有独立重试语义的事件。选择哪一种取决于业务的可观测性要求。
9. 展示读、决策读与缓存策略
讨论缓存一致性时,先说明接口用途,并为读路径建立契约:
| 读取类型 |
例子 |
数据源与约束 |
| 决策读 |
是否允许发货、是否可再次扣款、库存是否足够 |
主库或事务内读取;由条件更新和约束裁决 |
| 确认读 |
支付成功页的最终状态 |
主库读取,或轮询到已达成状态 |
| 展示读 |
历史订单详情、订单列表 |
可使用行缓存或从库,但需声明最大陈旧时间 |
| 分析读 |
运营报表、搜索索引 |
异步副本或数仓;明确延迟和补偿机制 |
若展示也需要较高一致性,可考虑版本化缓存值:缓存中携带 orders.version,失效事件也携带新版本,通过明确的版本比较规则限制旧值覆盖或回填。要真正覆盖缓存键被删除后的旧读回填,还需要保留可供比较的版本信息,并明确序列化、原子比较和回源逻辑。
延迟双删可在少数场景降低竞争概率,但延迟值无法证明严格正确,不能代替 outbox。CDC 可补偿绕过应用的写路径,却会引入 binlog 延迟、重放、顺序、唯一键变更与运维复杂度;它也不是强一致协议。
10. 列表、分页和批量写入
生成的单行缓存不会自动缓存列表。按 ID 倒序的 keyset 分页使用稳定游标,首屏传入约定的最大哨兵值:
SELECT id, order_no, status, total_amount, created_at
FROM orders
WHERE user_id = ? AND id < ?
ORDER BY id DESC
LIMIT ?;
下一页使用上一页最后一条 ID。若产品要求按创建时间排序,游标应为 (created_at, id),索引也需与之匹配;还应写清翻页期间的新数据是否进入后续页面。
UPDATE orders SET ... WHERE user_id = ? 会影响未知数量的行,行缓存层无法从这条 SQL 推导出所有键。可选方案包括:
- 分页找出受影响 ID,分批条件更新,并为每批写入失效事件。
- 对此类集合采用用户版本号或有界 TTL,避免维护无限缓存键。
- 将批处理做成可恢复任务,持久化游标、成功数、失败原因和最后心跳。
不要一次性把全部 ID 读进内存,也不要认为逐条更新总是更安全。批大小、事务时长、锁等待和恢复策略需要通过压测确定。
11. 用故障实验验证设计
正确性主张应落到自动化测试和演练中,而不只是停留在代码评审意见里。
| 场景 |
注入方式 |
断言 |
| 重复支付回调 |
同一渠道交易号并发调用两次 |
仅一条合法支付流水;订单只转换一次 |
| 乐观锁冲突 |
两个请求携带相同订单版本 |
最多一个请求 affected=1 |
| Redis 删除失败 |
在缓存客户端注入 DEL 错误 |
SQL 结果可查;outbox 最终修复;错误被分类 |
| 提交后进程崩溃 |
提交成功后立即终止进程 |
新实例领取 outbox 并完成失效或投递 |
| 旧读回填 |
阻塞读请求的缓存写入,穿插订单提交和删除 |
证明存在窗口;验证版本化策略或 SLA |
| worker 重复投递 |
发送后、done 前终止 worker |
消费者按 event_id 幂等 |
| 扩容与发布 |
增加副本并施加稳定负载 |
连接数、建连速率、p99 与错误率在预算内 |
集成测试应使用接近生产版本的 MySQL 和 Redis 容器,而不是只 mock repository。并发测试需要屏障或 hook 精确控制时序;否则只能偶尔碰到竞态,无法充分验证设计。
12. 指标、告警与发布门槛
至少采集以下指标:
- SQL 延迟分布、错误率、连接池等待时间、活跃和空闲连接数。
- Redis 命中率、回源次数、删除失败率、空值命中与超时。
- 事务提交和回滚数量,以及条件更新
affected=0 的业务分类。
- outbox pending 数量、最老事件年龄、处理延迟、重试次数和最终失败数。
- 支付回调重复率、幂等成功率、金额不匹配与状态冲突数。
可将以下条件设为发布或告警门槛:最老 pending outbox 事件超过展示一致性 SLA;最终失败事件非零;Redis 删除失败持续升高;连接池等待导致的请求超时增加;支付状态冲突异常偏离基线。
日志和 tracing 中不要记录 DSN、完整支付凭证、完整敏感 SQL 参数或个人信息。
13. 演进时由证据而非阈值驱动
读写分离以可接受复制延迟为前提,支付校验仍留在主库。CDC 可用于漏删补偿、搜索索引和分析链路,但必须治理延迟、重放、乱序与唯一键变化。分库分表取决于写吞吐、容量、索引成本、租户分布和运维复杂度,不能由“达到五千万行”这一单一阈值决定。
引入分片代理后,需要重新验证分片键路由、跨分片查询和事务、全局唯一约束、缓存键全局唯一性,以及扩容迁移期间的兼容路径。goctl 的生成代码仍能减少样板代码,但不会自动解决这些领域问题。
结语:把 CRUD 做成可恢复的系统行为
可靠 CRUD 不是写库成功就结束。面对支付重试、Redis 故障、进程崩溃、并发回填和流量扩容,系统还需要说明发生了什么、正确性由什么保障,以及故障如何恢复。
可以将以下规则固化到团队模板和评审清单中:
- 固定 DDL、迁移、goctl 与 go-zero 版本,确保生成结果可验证。
- 生成代码负责标准单表访问,复杂写入收口到扩展 Model。
- 业务不变量由数据库条件、唯一约束和本地事务维护。
- 事务内使用同一 session 的纯数据库操作,不读取缓存。
- 将缓存失效失败作为一等故障,依靠同事务 outbox 事件提供最终恢复路径。
- 用可重复的故障实验和指标验证设计,而不只依赖代码直觉。
这样,go-zero Model 生成才能成为可靠交付的加速器,而不是掩盖一致性问题的便利层。
参考资料
- go-zero:goctl Model 命令
- go-zero:MySQL Model 生成指南
- go-zero:Redis Cache
- go-zero:CachedConn 源码