go-backend-handbook 1.0.2 → 1.1.0

package/21-complete-project.md

@@ -0,0 +1,902 @@
+# 第 21 章 完整实战：从需求到上线实现 mini-coin
+
+> 这一章不是知识点索引，而是一条可以照着走完的开发主线。
+> 你会从一句需求开始，依次完成 API 契约、领域模型、MySQL 表、事务、幂等、HTTP 接口、缓存、消息、测试、容器化、监控和发布。代码与表名全部属于虚构项目 `mini-coin`。
+
+---
+
+## 21.1 需求不是“写一个充值接口”
+
+先把一句模糊需求改写成可以验收的行为：
+
+> 用户可以给账户充值；同一个请求重复提交只能成功一次；金额只能为正整数分；冻结账户不能充值；成功后能查询余额；接口要能处理并发；失败要返回稳定错误码。
+
+这里已经包含六类信息：
+
+| 类型 | 示例 | 如果不写清楚会怎样 |
+|---|---|---|
+| 功能 | 充值、查余额 | 开发完才发现少功能 |
+| 规则 | 金额 > 0、单位分 | 前端传元、后端按分，金额差 100 倍 |
+| 幂等 | 同一 `request_id` 不重复加钱 | 用户重试导致重复充值 |
+| 状态 | 冻结账户拒绝 | 业务状态被绕过 |
+| 非功能 | 并发、超时、监控 | 单测通过，上线出错 |
+| 可观测 | 请求 ID、错误码、指标 | 出问题只会说“接口挂了” |
+
+### 先写验收用例
+
+```text
+GIVEN 账户 u-1001 余额 100 分，状态正常
+WHEN 提交 req_id=r-1、amount=50
+THEN 返回余额 150 分
+AND 同一 req_id 再提交一次
+THEN 仍返回余额 150 分，不能变成 200 分
+
+GIVEN 账户不存在
+WHEN 充值
+THEN 返回 NOT_FOUND，不创建“幽灵”订单
+
+GIVEN 账户已冻结
+WHEN 充值
+THEN 返回 ACCOUNT_FROZEN，余额不变
+
+GIVEN 20 个并发请求，每个 req_id 都不同
+WHEN 同时充值 10 分
+THEN 余额精确增加 200 分，不丢更新
+```
+
+**判断需求是否可开发的标准**：任何一个验收句都能被自动化测试翻译出来。如果只能靠口头解释，就还没到开发阶段。
+
+---
+
+## 21.2 先定 API，再写实现
+
+### 请求
+
+```http
+POST /v1/recharges
+Content-Type: application/json
+X-Request-Id: trace-demo-001
+
+{
+  "req_id": "r-20261101-001",
+  "uid": "u-1001",
+  "amount": 50,
+  "channel": "manual"
+}
+```
+
+字段约束：
+
+| 字段 | 类型 | 规则 |
+|---|---|---|
+| `req_id` | string | 1~64，客户端生成，同一业务请求复用 |
+| `uid` | string | 1~64，必须存在 |
+| `amount` | int64 | 单位分，必须 > 0，设置业务上限 |
+| `channel` | string | 枚举白名单，例如 `manual`、`coupon` |
+
+### 成功响应
+
+```json
+{
+  "code": "OK",
+  "message": "success",
+  "request_id": "trace-demo-001",
+  "data": {
+    "order_id": "90001",
+    "uid": "u-1001",
+    "balance": 150,
+    "duplicated": false
+  }
+}
+```
+
+### 失败响应
+
+```json
+{
+  "code": "ACCOUNT_FROZEN",
+  "message": "account is frozen",
+  "request_id": "trace-demo-001"
+}
+```
+
+**接口设计三条硬规则**：
+
+1. HTTP 状态码表达协议层结果，业务 `code` 表达领域结果；
+2. 错误码是稳定契约，不能被日志文案随意替换；
+3. 成功和失败都必须带 `request_id`，否则线上无法串联日志。
+
+### 查询余额
+
+```http
+GET /v1/accounts/u-1001/balance
+```
+
+查询接口不应该要求传用户余额，因为余额只能由服务端算出来。**客户端传来的金额、余额、状态都不可信。**
+
+---
+
+## 21.3 目录结构：让依赖方向固定
+
+```text
+mini-coin/
+├── cmd/server/main.go          # 组装依赖、启动、优雅退出
+├── internal/httpapi/           # HTTP 适配层
+├── internal/service/           # 业务规则和事务边界
+├── internal/repository/        # MySQL 实现
+├── internal/cache/             # Redis/内存缓存实现
+├── internal/mq/                # Kafka/RabbitMQ/内存实现
+├── internal/model/             # 领域数据结构
+├── migrations/                 # 数据库迁移
+├── api/openapi.yaml            # HTTP 契约
+└── deploy/                     # Docker/K8s 配置
+```
+
+依赖只能这样流动：
+
+```text
+main -> httpapi -> service -> repository/cache/mq interfaces
+                         ^
+                         |
+              MySQL/Redis/MQ adapters
+```
+
+反向依赖是错误信号：`repository` 不应 import `httpapi`；`model` 不应知道 HTTP 状态码；业务层不应直接读取环境变量。
+
+---
+
+## 21.4 领域模型：金额、状态和请求 ID
+
+```go
+package model
+
+type Account struct {
+    ID        int64
+    UID       string
+    Balance   int64 // 分
+    Status    int
+    Version   int64
+}
+
+const (
+    AccountNormal = 1
+    AccountFrozen = 2
+)
+
+type RechargeOrder struct {
+    ID        int64
+    ReqID     string
+    UID       string
+    Amount    int64
+    Channel   string
+    Status    string
+    CreatedAt int64
+}
+```
+
+### 为什么金额用 int64
+
+`0.1 + 0.2` 在浮点数里不一定等于 `0.3`。钱的金额、余额、手续费必须使用最小货币单位整数，例如“分”；如果业务需要更细精度，使用数据库 `DECIMAL` 和明确的定点数规则。
+
+### 为什么不能只靠自增 ID 做幂等
+
+自增 ID 只能区分“两次插入”，不能识别“同一个业务请求被客户端重试”。业务幂等键必须由请求方提供，例如 `req_id`，并在数据库中建立唯一索引。
+
+---
+
+## 21.5 建表：约束必须落到数据库
+
+```sql
+CREATE TABLE account (
+    id          BIGINT UNSIGNED NOT NULL AUTO_INCREMENT,
+    uid         VARCHAR(64) NOT NULL,
+    balance     BIGINT NOT NULL DEFAULT 0 COMMENT '余额，单位：分',
+    status      TINYINT NOT NULL DEFAULT 1 COMMENT '1正常 2冻结',
+    version     BIGINT 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_uid (uid),
+    CONSTRAINT chk_balance_nonnegative CHECK (balance >= 0)
+) ENGINE=InnoDB DEFAULT CHARSET=utf8mb4;
+```
+
+```sql
+CREATE TABLE recharge_order (
+    id          BIGINT UNSIGNED NOT NULL AUTO_INCREMENT,
+    req_id      VARCHAR(64) NOT NULL,
+    uid         VARCHAR(64) NOT NULL,
+    amount      BIGINT NOT NULL,
+    channel     VARCHAR(32) NOT NULL,
+    status      TINYINT NOT NULL DEFAULT 0 COMMENT '0处理中 1成功 2失败',
+    balance_after BIGINT NULL,
+    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_req_id (req_id),
+    KEY idx_uid_created (uid, created_at),
+    KEY idx_status_created (status, created_at),
+    CONSTRAINT chk_amount_positive CHECK (amount > 0)
+) ENGINE=InnoDB DEFAULT CHARSET=utf8mb4;
+```
+
+```sql
+CREATE TABLE recharge_flow (
+    id            BIGINT UNSIGNED NOT NULL AUTO_INCREMENT,
+    uid           VARCHAR(64) NOT NULL,
+    order_id      BIGINT UNSIGNED NOT NULL,
+    delta         BIGINT NOT NULL,
+    balance_after BIGINT NOT NULL,
+    created_at    DATETIME(3) NOT NULL DEFAULT CURRENT_TIMESTAMP(3),
+    PRIMARY KEY (id),
+    UNIQUE KEY uk_order (order_id),
+    KEY idx_uid_created (uid, created_at)
+) ENGINE=InnoDB DEFAULT CHARSET=utf8mb4;
+```
+
+三张表职责不同：
+
+- `account` 保存当前余额，是高频点查；
+- `recharge_order` 保存请求和幂等状态；
+- `recharge_flow` 保存每一次余额变化，便于审计和对账。
+
+**不要只保存最终余额。** 没有流水，出现“为什么少了 50 分”时无法解释。
+
+---
+
+## 21.6 正确的事务边界
+
+充值必须在**同一个数据库事务**里完成：
+
+```text
+BEGIN
+  1. INSERT recharge_order(req_id...)，唯一键冲突表示重复请求
+  2. SELECT account ... FOR UPDATE
+  3. 检查账户存在且状态正常
+  4. UPDATE account SET balance = balance + ?, version = version + 1
+  5. INSERT recharge_flow
+  6. UPDATE recharge_order SET status = 成功, balance_after = ?
+COMMIT
+```
+
+任何一步失败都回滚。尤其不能先插入订单、提交事务，再去加余额；进程在两步之间崩溃会留下“订单成功但钱没加”的脏数据。
+
+### Go 中的事务轮廓
+
+```go
+func (r *MySQLRepository) Recharge(ctx context.Context, req model.RechargeOrder) (Result, error) {
+    tx, err := r.db.BeginTx(ctx, &sql.TxOptions{Isolation: sql.LevelReadCommitted})
+    if err != nil {
+        return Result{}, err
+    }
+    defer tx.Rollback() // 已 Commit 后 Rollback 返回 ErrTxDone，可安全 defer
+
+    // 唯一键冲突用 MySQL error 1062 判断，演示代码不依赖具体驱动的错误类型。
+    if _, err := tx.ExecContext(ctx,
+        `INSERT INTO recharge_order(req_id, uid, amount, channel, status)
+         VALUES (?, ?, ?, ?, 0)`, req.ReqID, req.UID, req.Amount, req.Channel); err != nil {
+        if isDuplicateKey(err) {
+            return r.loadDuplicateOrLock(ctx, tx, req)
+        }
+        return Result{}, err
+    }
+
+    var acc model.Account
+    err = tx.QueryRowContext(ctx,
+        `SELECT id, uid, balance, status, version
+           FROM account WHERE uid = ? FOR UPDATE`, req.UID).
+        Scan(&acc.ID, &acc.UID, &acc.Balance, &acc.Status, &acc.Version)
+    if errors.Is(err, sql.ErrNoRows) {
+        return Result{}, ErrNotFound
+    }
+    if err != nil {
+        return Result{}, err
+    }
+    if acc.Status != model.AccountNormal {
+        return Result{}, ErrFrozen
+    }
+
+    newBalance := acc.Balance + req.Amount
+    if _, err := tx.ExecContext(ctx,
+        `UPDATE account SET balance = balance + ?, version = version + 1
+          WHERE id = ?`, req.Amount, acc.ID); err != nil {
+        return Result{}, err
+    }
+    if _, err := tx.ExecContext(ctx,
+        `INSERT INTO recharge_flow(uid, order_id, delta, balance_after)
+         VALUES (?, ?, ?, ?)`, req.UID, req.ID, req.Amount, newBalance); err != nil {
+        return Result{}, err
+    }
+    if _, err := tx.ExecContext(ctx,
+        `UPDATE recharge_order SET status = 1, balance_after = ? WHERE id = ?`,
+        newBalance, req.ID); err != nil {
+        return Result{}, err
+    }
+    if err := tx.Commit(); err != nil {
+        return Result{}, err
+    }
+    return Result{Balance: newBalance, Duplicated: false}, nil
+}
+```
+
+### 唯一键冲突后还能不能继续查
+
+MySQL 中普通 `INSERT` 触发唯一键冲突时，语句失败但事务通常仍可继续，所以示例可以在同一个事务里查询已有订单。PostgreSQL 在语句报错后默认会把整个事务标记为 aborted，必须使用 `SAVEPOINT`/`ROLLBACK TO SAVEPOINT`，或者先独立查询再决定是否开启写入事务。**数据库不同，错误恢复语义也不同，不能照抄。**
+
+另外，同一 `req_id` 再次出现时必须比较 `uid`、`amount`、`channel` 是否与首次请求一致。如果同一个幂等键被用于不同参数，应返回 `REQ_ID_CONFLICT`，不能把另一笔请求的结果当成成功结果。
+
+### `SELECT ... FOR UPDATE` 解决什么
+
+两个请求同时给同一账户加 10 分。没有行锁时，它们可能都读到 100，再分别写 110，最终只增加 10 分。`FOR UPDATE` 让同一账户的更新串行化，后一个事务必须等待前一个提交，再读到 110 并写 120。
+
+### 事务不能做的事
+
+- 不要在持有数据库事务时调用慢速 HTTP/gRPC 下游；
+- 不要在事务里发 Kafka、发短信或写日志到远程服务；
+- 不要以为 Redis 操作会跟随 MySQL 回滚；
+- 事务要短，先做参数校验，再开启事务。
+
+---
+
+## 21.7 幂等的正确理解
+
+幂等不是“第二次请求直接返回成功”。要分清楚以下几种状态：
+
+| 数据库里的请求状态 | 第二次请求应该怎么处理 |
+|---|---|
+| 不存在 | 首次执行 |
+| 处理中 | 返回处理中，或短暂等待；不能重复加钱 |
+| 已成功 | 返回首次结果或当前结果，`duplicated=true` |
+| 已失败且可重试 | 按明确状态机重试，不能盲目插入 |
+| 已失败且不可重试 | 返回原失败原因 |
+
+最危险的做法是“先查再插”：
+
+```text
+请求 A 查询 req_id 不存在
+请求 B 查询 req_id 不存在
+请求 A 插入并执行
+请求 B 也插入并执行
+```
+
+必须依赖数据库唯一键或原子条件写入来兜底。
+
+### 唯一键冲突后的读取
+
+冲突发生后，不要直接返回 `nil`。应读取已有订单状态和 `balance_after`：
+
+```go
+func (r *MySQLRepository) loadDuplicateOrLock(
+    ctx context.Context, tx *sql.Tx, req model.RechargeOrder,
+) (Result, error) {
+    var status int
+    var balanceAfter sql.NullInt64
+    err := tx.QueryRowContext(ctx,
+        `SELECT status, balance_after FROM recharge_order WHERE req_id = ?`,
+        req.ReqID).Scan(&status, &balanceAfter)
+    if err != nil {
+        return Result{}, err
+    }
+    switch status {
+    case 1:
+        return Result{Balance: balanceAfter.Int64, Duplicated: true}, nil
+    case 0:
+        return Result{}, ErrProcessing
+    default:
+        return Result{}, ErrPreviouslyFailed
+    }
+}
+```
+
+### 幂等失败时的原则
+
+**不要在同一事务里把订单标记失败后继续加钱。** 状态机必须清晰：先校验、再改变余额、最后把订单标记成功。失败时事务回滚，订单是否保留由业务决定；如果保留失败流水，要有单独的失败表或明确状态，不要伪装成成功。
+
+---
+
+## 21.8 HTTP 层：薄，不做业务
+
+```go
+type rechargeRequest struct {
+    ReqID   string `json:"req_id"`
+    UID     string `json:"uid"`
+    Amount  int64  `json:"amount"`
+    Channel string `json:"channel"`
+}
+
+func (h *Handler) recharge(w http.ResponseWriter, r *http.Request) {
+    if r.Method != http.MethodPost {
+        writeError(w, r, http.StatusMethodNotAllowed, "METHOD_NOT_ALLOWED", nil)
+        return
+    }
+
+    var body rechargeRequest
+    dec := json.NewDecoder(http.MaxBytesReader(w, r.Body, 1<<20))
+    dec.DisallowUnknownFields()
+    if err := dec.Decode(&body); err != nil {
+        writeError(w, r, http.StatusBadRequest, "INVALID_JSON", err)
+        return
+    }
+
+    result, err := h.recharge.Recharge(r.Context(), service.RechargeRequest{
+        ReqID: body.ReqID, UID: body.UID,
+        Amount: body.Amount, Channel: body.Channel,
+    })
+    if err != nil {
+        writeServiceError(w, r, err)
+        return
+    }
+    writeJSON(w, http.StatusOK, successResponse(r, result))
+}
+```
+
+### HTTP 层负责什么
+
+- 解析 JSON、限制请求体；
+- 校验字段格式和枚举；
+- 把请求上下文传给 service；
+- 把 service 错误映射为 HTTP 状态码和稳定业务码；
+- 设置响应头、记录请求耗时。
+
+### HTTP 层不负责什么
+
+- 不直接拼 SQL；
+- 不直接读写 Redis；
+- 不决定“余额扣多少”；
+- 不把底层数据库错误原样返回给前端。
+
+### 错误映射示例
+
+```go
+func writeServiceError(w http.ResponseWriter, r *http.Request, err error) {
+    switch {
+    case errors.Is(err, service.ErrInvalidAmount):
+        writeError(w, r, http.StatusBadRequest, "INVALID_AMOUNT", nil)
+    case errors.Is(err, service.ErrMissingReqID):
+        writeError(w, r, http.StatusBadRequest, "MISSING_REQ_ID", nil)
+    case errors.Is(err, service.ErrFrozen):
+        writeError(w, r, http.StatusConflict, "ACCOUNT_FROZEN", nil)
+    case errors.Is(err, service.ErrProcessing):
+        writeError(w, r, http.StatusAccepted, "PROCESSING", nil)
+    default:
+        log.Printf("recharge failed request_id=%s err=%v", r.Header.Get("X-Request-Id"), err)
+        writeError(w, r, http.StatusInternalServerError, "INTERNAL_ERROR", nil)
+    }
+}
+```
+
+---
+
+## 21.9 缓存：只缓存能容忍短暂过期的数据
+
+余额缓存是高危场景。缓存能提升查询 QPS，但必须回答：
+
+1. 写入数据库后，缓存何时失效？
+2. 删除缓存失败怎么办？
+3. 两个请求同时读写，是否会把旧值写回？
+4. 缓存是不是一致性来源？
+
+推荐策略：
+
+```text
+读：先读缓存 -> 未命中读 DB -> 回填短 TTL
+写：先提交 DB 事务 -> 删除缓存 -> 失败则重试/发失效消息
+兜底：TTL 自动过期，监控缓存陈旧率
+```
+
+### Cache-Aside 的伪代码
+
+```go
+func (s *Service) Balance(ctx context.Context, uid string) (int64, error) {
+    key := "account:balance:" + uid
+    if v, ok := s.cache.Get(ctx, key); ok {
+        return v.(int64), nil
+    }
+
+    acc, err := s.repo.GetAccount(ctx, uid)
+    if err != nil {
+        return 0, err
+    }
+    _ = s.cache.Set(ctx, key, acc.Balance, 30*time.Second)
+    return acc.Balance, nil
+}
+```
+
+更新后：
+
+```go
+if err := s.repo.Recharge(ctx, order); err != nil {
+    return Result{}, err
+}
+if err := s.cache.Delete(ctx, "account:balance:"+order.UID); err != nil {
+    // 记录指标，交给 TTL 和后台修复任务，不要让缓存故障伪装成充值失败。
+    s.metrics.CacheDeleteFailed.Inc()
+}
+```
+
+### 三个常见问题
+
+| 问题 | 现象 | 处理 |
+|---|---|---|
+| 缓存穿透 | 查不存在的数据，每次都打 DB | 空值短 TTL、参数校验、布隆过滤器 |
+| 缓存击穿 | 热 key 过期瞬间打爆 DB | 单飞/互斥回源、逻辑过期 |
+| 缓存雪崩 | 大量 key 同时过期 | TTL 加随机抖动、分批预热 |
+
+**重要边界**：余额查询可以短 TTL 缓存，但充值扣款判断必须读数据库事务中的最新值。不能拿缓存余额做资金判断。
+
+---
+
+## 21.10 消息队列：只传递已经提交的事实
+
+充值成功后发送消息，消息应该表达事实，而不是命令另一个服务“必须加钱”：
+
+```json
+{
+  "event_id": "evt-90001",
+  "event_type": "recharge.succeeded",
+  "occurred_at": "2026-11-01T10:00:00Z",
+  "request_id": "r-20261101-001",
+  "uid": "u-1001",
+  "amount": 50,
+  "balance_after": 150
+}
+```
+
+流程：
+
+```text
+DB 事务提交 -> 记录 outbox 事件 -> 异步发布 MQ -> 消费端按 event_id 幂等
+```
+
+如果直接在事务里调用 MQ，可能出现：数据库提交成功，但 MQ 发送失败；或者 MQ 发送成功，数据库回滚。使用 **Transactional Outbox** 可以把“业务成功”和“待发送事件”放进同一个 DB 事务，再由后台发布。
+
+### 消费端幂等表
+
+```sql
+CREATE TABLE consumed_event (
+    event_id    VARCHAR(64) NOT NULL,
+    consumer    VARCHAR(64) NOT NULL,
+    consumed_at DATETIME(3) NOT NULL DEFAULT CURRENT_TIMESTAMP(3),
+    PRIMARY KEY (event_id, consumer)
+) ENGINE=InnoDB;
+```
+
+消费逻辑：
+
+```text
+开始消费
+  INSERT consumed_event(event_id, consumer)
+  如果唯一键冲突 -> 已经处理过，直接 ACK
+  执行本地业务
+  提交本地事务
+ACK
+```
+
+注意：消费成功但 ACK 丢失时，消息会再次投递；幂等表必须和本地业务处在同一个数据库事务里，或者使用等价的原子方案。
+
+---
+
+## 21.11 配置、日志、指标和追踪
+
+### 配置
+
+```json
+{
+  "address": "127.0.0.1:8081",
+  "mysql": {
+    "dsn_env": "MINICOIN_MYSQL_DSN",
+    "max_open_conns": 20,
+    "max_idle_conns": 10,
+    "conn_max_lifetime_seconds": 300
+  },
+  "redis": {
+    "addr": "127.0.0.1:6379",
+    "dial_timeout_seconds": 1
+  }
+}
+```
+
+配置里不写密码。敏感值通过环境变量或秘密管理系统注入。
+
+### 结构化日志
+
+每次请求至少记录：
+
+```text
+level, timestamp, service, request_id, trace_id, route,
+method, status, latency_ms, user_id_masked, error_code
+```
+
+不要打印密码、完整 token、完整手机号、身份证、银行卡和完整请求体。
+
+### 指标
+
+```text
+http_requests_total{route="/v1/recharges", status="200"}
+http_request_duration_seconds_bucket{route="/v1/recharges", le="0.1"}
+recharge_total{result="success"}
+recharge_failures_total{code="ACCOUNT_FROZEN"}
+db_pool_in_use
+redis_errors_total
+mq_publish_failures_total
+```
+
+### 追踪
+
+```go
+ctx, span := tracer.Start(ctx, "RechargeService.Recharge")
+defer span.End()
+
+span.SetAttributes(attribute.String("request_id", req.ReqID))
+```
+
+原则：日志回答“发生了什么”，指标回答“有多少、多快、是否恶化”，追踪回答“慢在哪一段”。三者缺一不可。
+
+---
+
+## 21.12 测试：从规则到集成
+
+### 单元测试
+
+测试业务规则时使用可控的内存 repository，不启动 MySQL：
+
+```go
+func TestRechargeRejectsInvalidAmount(t *testing.T) {
+    svc := NewRecharge(newMemoryRepo(), noopCache{}, noopPublisher{})
+    _, err := svc.Recharge(context.Background(), RechargeRequest{
+        ReqID: "r-1", UID: "u-1", Amount: 0,
+    })
+    if !errors.Is(err, ErrInvalidAmount) {
+        t.Fatalf("got %v, want ErrInvalidAmount", err)
+    }
+}
+```
+
+### 表驱动测试
+
+```go
+tests := []struct{
+    name string
+    amount int64
+    want error
+}{
+    {"zero", 0, ErrInvalidAmount},
+    {"negative", -1, ErrInvalidAmount},
+    {"normal", 1, nil},
+}
+```
+
+### 幂等测试
+
+```go
+first, err := svc.Recharge(ctx, req)
+require.NoError(t, err)
+
+second, err := svc.Recharge(ctx, req)
+require.NoError(t, err)
+require.True(t, second.Duplicated)
+require.Equal(t, first.Balance, second.Balance)
+```
+
+### 并发测试
+
+```go
+const n = 100
+var wg sync.WaitGroup
+for i := 0; i < n; i++ {
+    wg.Add(1)
+    go func(i int) {
+        defer wg.Done()
+        _, _ = svc.Recharge(ctx, RechargeRequest{
+            ReqID: fmt.Sprintf("r-%d", i),
+            UID: "u-1",
+            Amount: 1,
+        })
+    }(i)
+}
+wg.Wait()
+
+acc, _ := repo.GetAccount(ctx, "u-1")
+if acc.Balance != initial+n {
+    t.Fatalf("got %d, want %d", acc.Balance, initial+n)
+}
+```
+
+### 集成测试
+
+集成测试必须连接真实 MySQL 或 testcontainers，至少覆盖：
+
+- 唯一键冲突；
+- 事务回滚；
+- `SELECT FOR UPDATE` 并发；
+- 字段长度、CHECK、字符集；
+- 数据库连接断开后的恢复；
+- 迁移脚本从空库执行成功。
+
+### `-race`
+
+```bash
+go test ./... -count=1
+go test -race ./... -count=1
+```
+
+`-race` 只能发现实际访问到的竞争，不证明没有竞争；并发路径要设计能同时触发。
+
+---
+
+## 21.13 自测和接口验证
+
+### curl 自测
+
+```bash
+curl -i -X POST http://127.0.0.1:8081/v1/recharges \
+  -H 'Content-Type: application/json' \
+  -H 'X-Request-Id: trace-demo-001' \
+  -d '{"req_id":"r-1","uid":"u-1001","amount":50,"channel":"manual"}'
+```
+
+### 验证幂等
+
+```bash
+for i in 1 2; do
+  curl -sS -X POST http://127.0.0.1:8081/v1/recharges \
+    -H 'Content-Type: application/json' \
+    -H 'X-Request-Id: trace-idem-$i' \
+    -d '{"req_id":"r-idem","uid":"u-1001","amount":10,"channel":"manual"}'
+done
+```
+
+第二次结果必须显示重复标记，余额不能增加两次。
+
+### 验证错误路径
+
+- `amount=0`；
+- 缺 `req_id`；
+- 不存在账户；
+- 冻结账户；
+- 超大请求体；
+- 非 JSON；
+- 方法错误；
+- 下游数据库超时。
+
+真正的自测不是只测 happy path，而是把错误路径变成可重复的命令。
+
+---
+
+## 21.14 CI、镜像和发布
+
+### CI 门禁
+
+```yaml
+stages: [lint, test, build]
+lint:
+  script:
+    - test -z "$(gofmt -l .)"
+    - go vet ./...
+test:
+  script:
+    - go test ./... -count=1
+    - go test -race ./... -count=1
+build:
+  script:
+    - CGO_ENABLED=0 go build -trimpath -ldflags="-s -w" -o app ./cmd/server
+```
+
+### 多阶段 Dockerfile
+
+```dockerfile
+FROM golang:1.22-alpine AS build
+WORKDIR /src
+COPY go.mod go.sum ./
+RUN go mod download
+COPY . .
+RUN CGO_ENABLED=0 GOOS=linux go build \
+    -trimpath -ldflags="-s -w" -o /out/server ./cmd/server
+
+FROM gcr.io/distroless/static-debian12:nonroot
+COPY --from=build /out/server /server
+USER nonroot:nonroot
+EXPOSE 8081
+ENTRYPOINT ["/server"]
+```
+
+发布前检查：
+
+- 镜像带不可变 tag 或 digest；
+- 不把 `.env`、证书、token 打进镜像；
+- 进程以非 root 运行；
+- 有 CPU/内存限制；
+- 有启动、存活、就绪探针；
+- 有回滚版本和数据库迁移回滚方案。
+
+### 优雅退出
+
+```go
+ctx, stop := signal.NotifyContext(context.Background(), syscall.SIGTERM, os.Interrupt)
+defer stop()
+<-ctx.Done()
+
+shutdownCtx, cancel := context.WithTimeout(context.Background(), 10*time.Second)
+defer cancel()
+_ = server.Shutdown(shutdownCtx)
+_ = repo.Close()
+```
+
+收到 SIGTERM 后停止接新请求，等待在途请求完成，再退出。不能直接 `os.Exit(0)`，否则请求可能写一半。
+
+### 数据库迁移顺序
+
+1. 先执行向后兼容的 DDL；
+2. 再发布能读写新结构的代码；
+3. 观察指标；
+4. 最后删除旧字段或旧代码。
+
+禁止把不可回滚的 DROP 和代码发布绑在同一步。
+
+---
+
+## 21.15 上线后的观察顺序
+
+上线后 10 分钟内按下面顺序看：
+
+1. **流量**：QPS 是否达到预期，入口有没有被限流；
+2. **错误率**：5xx、业务错误码、数据库错误、MQ 错误；
+3. **延迟**：P50/P95/P99，是否出现长尾；
+4. **饱和度**：CPU、内存、goroutine、连接池、Redis、磁盘；
+5. **业务结果**：充值成功数、重复请求数、余额变化总量是否与订单一致；
+6. **日志与追踪**：挑选几个失败 request_id 追踪完整链路。
+
+报警要围绕用户影响，不要只报 CPU 80%。例如：
+
+```text
+5 分钟错误率 > 2%
+P99 > 800ms 持续 5 分钟
+连续 3 分钟没有成功充值
+数据库连接池使用率 > 90% 持续 10 分钟
+消息积压持续增长
+```
+
+---
+
+## 21.16 本章综合练习
+
+### 练习 A：需求转验收
+
+把“用户充值”改成至少 8 条可自动化验收用例，必须覆盖幂等、并发、金额、账户状态和错误响应。
+
+### 练习 B：事务设计
+
+写出“创建订单、锁账户、加余额、写流水、更新订单”的 SQL 事务，并解释为什么不能把 MQ 发送放在事务中。
+
+### 练习 C：幂等状态机
+
+分别画出 `不存在/处理中/成功/可重试失败/不可重试失败` 五种状态下的第二次请求流程。
+
+### 练习 D：故障注入
+
+人为让缓存删除失败、数据库提交超时、消息消费重复，分别写观察指标和恢复方案。
+
+### 练习 E：上线演练
+
+为一个只读接口设计发布、灰度和回滚步骤，要求说明如何判断是否可以扩大流量。
+
+---
+
+## 参考答案
+
+<details>
+<summary>展开参考答案</summary>
+
+**A**：至少包括：正常充值；重复 `req_id` 不重复加钱；并发不同 `req_id` 不丢更新；金额为 0；金额为负；账户不存在；账户冻结；非法 JSON；请求体过大；数据库超时。每条都应给出输入、预期 HTTP 状态、业务码和最终余额。
+
+**B**：事务内先插入订单并依赖唯一键防重，再用 `SELECT ... FOR UPDATE` 锁账户，校验状态后更新余额，写流水，更新订单状态，最后一起提交。MQ 发送是外部副作用，不能跟随事务回滚，应使用 outbox 或提交后可靠发布。
+
+**C**：不存在则首次执行；处理中返回 `PROCESSING`，客户端退避重试；成功返回首次 `balance_after` 和 `duplicated=true`；可重试失败只允许明确状态机重试，不可重试失败返回稳定错误码。任何状态都不能绕过唯一键和账户状态校验。
+
+**D**：缓存删除失败记录 `cache_delete_failed_total`，依靠短 TTL 和后台修复；数据库提交超时先按事务结果未知处理，使用 `req_id` 查询订单确认，禁止盲目重试加钱；重复消费通过消费幂等表识别，ACK 丢失后用同一 `event_id` 重试。
+
+**E**：先在同版本测试环境验证，再发布小流量实例；观察 5xx、P99、业务成功率和日志错误；逐级扩大流量；回滚时先摘流量，再切回旧镜像或旧配置，确认数据库结构仍向后兼容。没有指标证据就不能宣布发布成功。
+
+</details>