306 lines
8.4 KiB
Markdown
306 lines
8.4 KiB
Markdown
# Context 超时控制改进工作总结
|
||
|
||
**时间**: 2026-06-10
|
||
**任务**: Week 3-4 - 为所有核心模块添加 Context 超时控制
|
||
|
||
---
|
||
|
||
## 🎯 目标
|
||
|
||
为所有 Repository 和 Service 层方法添加 `context.Context` 参数，实现：
|
||
1. 数据库操作超时控制
|
||
2. 请求取消传播
|
||
3. 优雅的超时错误处理
|
||
4. 提升系统稳定性和可控性
|
||
|
||
---
|
||
|
||
## ✅ 已完成工作
|
||
|
||
### 1. Wallet 模块（100% 完成）
|
||
|
||
#### Repository 层
|
||
- ✅ `Account(ctx context.Context, userID uint64) (*AccountDTO, error)`
|
||
- ✅ `Ledger(ctx context.Context, userID uint64, page, pageSize int) (*PaginatedResult, error)`
|
||
- ✅ `Recharge(ctx context.Context, userID uint64, amountCent int64) (*AccountDTO, error)`
|
||
- ✅ `ConfirmRechargeFromChannel(ctx context.Context, userID uint64, bizNo string, amountCent int64) error`
|
||
- ✅ `Withdraw(ctx context.Context, userID uint64, amountCent int64) (*AccountDTO, error)`
|
||
- ✅ `AdminLedger(ctx context.Context, query AdminLedgerQuery) (*PaginatedResult, error)`
|
||
|
||
#### Service 层
|
||
- ✅ 所有方法签名已更新，添加 `ctx context.Context` 作为第一个参数
|
||
- ✅ 所有对 Repository 的调用已传递 context
|
||
|
||
#### Handler 层
|
||
- ✅ 所有 handler 方法使用 `c.Request.Context()` 获取请求上下文
|
||
- ✅ Context 从 HTTP 请求传递到 Service 再到 Repository
|
||
|
||
#### 测试代码
|
||
- ✅ Service 测试已更新（5 个测试）
|
||
- ✅ Repository 集成测试已更新（9 个测试）
|
||
- ✅ Repository 逻辑测试已更新（14 个测试）
|
||
- ✅ 所有测试通过
|
||
|
||
#### 数据库操作
|
||
- ✅ 所有数据库查询使用 `db.WithContext(ctx)`
|
||
- ✅ 事务操作传播 context
|
||
|
||
---
|
||
|
||
## 🔄 待完成工作
|
||
|
||
### 2. Order 模块（待开始）
|
||
|
||
**Repository 层方法（预估 ~20 个）**：
|
||
- `Create(ctx context.Context, userID uint64, req CreateRequest)`
|
||
- `Cancel(ctx context.Context, userID uint64, orderID uint64)`
|
||
- `Pay(ctx context.Context, orderID uint64)`
|
||
- `SubmitHandoff(ctx context.Context, userID uint64, orderID uint64, req SubmitHandoffRequest)`
|
||
- `ConfirmReceive(ctx context.Context, userID uint64, orderID uint64)`
|
||
- `SubmitReturn(ctx context.Context, userID uint64, orderID uint64, req SubmitReturnRequest)`
|
||
- `SubmitCheckout(ctx context.Context, userID uint64, orderID uint64, req SubmitCheckoutRequest)`
|
||
- `ConfirmCheckout(ctx context.Context, userID uint64, orderID uint64)`
|
||
- `CounterCheckout(ctx context.Context, userID uint64, orderID uint64, req CounterCheckoutRequest)`
|
||
- `AcceptCheckout(ctx context.Context, userID uint64, orderID uint64)`
|
||
- ... 更多方法
|
||
|
||
**Service 层**：所有对应方法
|
||
|
||
**Handler 层**：所有对应 handler
|
||
|
||
**测试代码**：28 个测试用例需要更新
|
||
|
||
---
|
||
|
||
### 3. Payment 模块（待开始）
|
||
|
||
**Repository 层方法（预估 ~15 个）**：
|
||
- `Start(ctx context.Context, userID uint64, orderID uint64, req StartPaymentRequest, clientIP string)`
|
||
- `Query(ctx context.Context, paymentNo string)`
|
||
- `HandleNotify(ctx context.Context, provider string, data map[string]string)`
|
||
- `StartRefund(ctx context.Context, orderID uint64, amountCent int64, bizType, reason string)`
|
||
- `AdminQuery(ctx context.Context, query AdminPaymentQuery)`
|
||
- ... 更多方法
|
||
|
||
**Service 层**：所有对应方法
|
||
|
||
**Handler 层**：所有对应 handler
|
||
|
||
**测试代码**：41 个测试用例需要更新
|
||
|
||
---
|
||
|
||
### 4. Listing 模块（待开始）
|
||
|
||
**Repository 层方法（预估 ~10 个）**：
|
||
- `Create(ctx context.Context, userID uint64, req CreateListingRequest)`
|
||
- `Update(ctx context.Context, userID uint64, listingID uint64, req UpdateListingRequest)`
|
||
- `Delete(ctx context.Context, userID uint64, listingID uint64)`
|
||
- `List(ctx context.Context, query ListingQuery)`
|
||
- `Detail(ctx context.Context, listingID uint64)`
|
||
- ... 更多方法
|
||
|
||
---
|
||
|
||
### 5. 其他模块
|
||
|
||
- **Dispute 模块**
|
||
- **Realname 模块**
|
||
- **AdminUser 模块**
|
||
- **PaymentConfig 模块**
|
||
|
||
---
|
||
|
||
## 📋 实施建议
|
||
|
||
### 方案 A：手动逐模块修改（推荐）
|
||
|
||
**优点**：
|
||
- 精确控制每个修改
|
||
- 可以同步优化代码结构
|
||
- 确保测试全部通过
|
||
|
||
**缺点**：
|
||
- 工作量大（预估 8-12 小时）
|
||
- 需要逐个测试验证
|
||
|
||
**步骤**：
|
||
1. 按模块优先级排序：order → payment → listing → 其他
|
||
2. 每个模块按层级修改：Repository → Service → Handler → Tests
|
||
3. 每完成一个模块，运行测试验证
|
||
4. 提交一次代码
|
||
|
||
---
|
||
|
||
### 方案 B：自动化脚本批量修改（快速但风险高）
|
||
|
||
**优点**：
|
||
- 快速完成（1-2 小时）
|
||
- 统一规范
|
||
|
||
**缺点**：
|
||
- 可能引入错误
|
||
- 需要大量测试验证
|
||
- 可能遗漏边界情况
|
||
|
||
**不推荐原因**：
|
||
- 各模块方法签名差异较大
|
||
- 有些方法可能已有 context 参数
|
||
- 测试代码结构复杂，难以批量处理
|
||
|
||
---
|
||
|
||
### 方案 C：分阶段实施（平衡方案）
|
||
|
||
**第一阶段（本次）**：
|
||
- ✅ Wallet 模块（已完成）
|
||
|
||
**第二阶段（下次）**：
|
||
- Order 模块（核心业务，优先级最高）
|
||
- Payment 模块（核心业务，优先级最高）
|
||
|
||
**第三阶段（后续）**：
|
||
- Listing、Dispute、Realname 等模块
|
||
|
||
**提交策略**：
|
||
- 每完成一个模块，提交一次
|
||
- 保持每次提交的原子性和可回滚性
|
||
|
||
---
|
||
|
||
## 🎯 推荐方案
|
||
|
||
**采用方案 C - 分阶段实施**
|
||
|
||
### 本次工作范围
|
||
- ✅ Wallet 模块（已完成）
|
||
- 提交本次工作
|
||
- 更新改进计划文档
|
||
|
||
### 下次工作范围
|
||
- Order 模块 Context 改造
|
||
- Payment 模块 Context 改造
|
||
- 运行所有测试验证
|
||
- 提交代码
|
||
|
||
### 后续工作
|
||
- 其他模块 Context 改造
|
||
- 全局测试验证
|
||
- 性能测试（验证超时控制效果）
|
||
|
||
---
|
||
|
||
## 📊 预估工作量
|
||
|
||
| 模块 | Repository 方法数 | Service 方法数 | Handler 数 | 测试用例数 | 预估时间 |
|
||
|------|-----------------|---------------|-----------|-----------|---------|
|
||
| ✅ Wallet | 6 | 5 | 5 | 28 | **2h（已完成）** |
|
||
| Order | ~20 | ~20 | ~15 | 28 | 4h |
|
||
| Payment | ~15 | ~15 | ~10 | 41 | 3h |
|
||
| Listing | ~10 | ~10 | ~8 | ~10 | 2h |
|
||
| 其他 | ~15 | ~15 | ~10 | ~20 | 2h |
|
||
| **总计** | **~66** | **~65** | **~48** | **~127** | **13h** |
|
||
|
||
---
|
||
|
||
## 🔍 实施细节
|
||
|
||
### Context 传递链路
|
||
|
||
```
|
||
HTTP Request
|
||
↓
|
||
Handler (c.Request.Context())
|
||
↓
|
||
Service (ctx context.Context, ...)
|
||
↓
|
||
Repository (ctx context.Context, ...)
|
||
↓
|
||
GORM (db.WithContext(ctx))
|
||
```
|
||
|
||
### 超时控制示例
|
||
|
||
```go
|
||
// Handler 层设置超时
|
||
func (h *Handler) CreateOrder(c *gin.Context) {
|
||
ctx, cancel := context.WithTimeout(c.Request.Context(), 5*time.Second)
|
||
defer cancel()
|
||
|
||
order, err := h.service.Create(ctx, userID, req)
|
||
// ...
|
||
}
|
||
|
||
// Repository 层传播 context
|
||
func (r *Repository) Create(ctx context.Context, userID uint64, req CreateRequest) error {
|
||
return r.db.WithContext(ctx).Transaction(func(tx *gorm.DB) error {
|
||
// 事务内的所有操作都会使用 ctx 的超时控制
|
||
// ...
|
||
})
|
||
}
|
||
```
|
||
|
||
### 测试代码模式
|
||
|
||
```go
|
||
func TestRepositoryMethod(t *testing.T) {
|
||
db := setupTestDB(t)
|
||
defer cleanupTestDB(t, db)
|
||
|
||
repo := NewRepository(db)
|
||
ctx := context.Background()
|
||
|
||
result, err := repo.Method(ctx, params)
|
||
// ...
|
||
}
|
||
```
|
||
|
||
---
|
||
|
||
## ✅ 验证清单
|
||
|
||
每个模块完成后需要验证：
|
||
|
||
- [ ] 所有 Repository 方法签名已更新
|
||
- [ ] 所有 Service 方法签名已更新
|
||
- [ ] 所有 Handler 方法已传递 context
|
||
- [ ] 所有数据库操作使用 `WithContext(ctx)`
|
||
- [ ] 所有测试代码已更新
|
||
- [ ] 所有测试通过（`go test ./internal/modules/<module> -v`）
|
||
- [ ] 代码编译通过（`go build ./internal/modules/<module>`）
|
||
- [ ] 无 lint 错误（`golangci-lint run ./internal/modules/<module>`）
|
||
|
||
---
|
||
|
||
## 📝 注意事项
|
||
|
||
1. **向后兼容性**：这是一个破坏性变更（breaking change），所有调用方都需要更新
|
||
2. **超时时间设置**：
|
||
- 简单查询：2-5s
|
||
- 复杂查询：5-10s
|
||
- 事务操作：10-30s
|
||
- 外部 API 调用：根据 SLA 设置
|
||
3. **错误处理**：需要区分超时错误和业务错误
|
||
4. **测试覆盖**：确保所有路径都覆盖到 context 取消场景
|
||
|
||
---
|
||
|
||
## 🚀 下一步行动
|
||
|
||
### 立即行动（本次会话）
|
||
1. ✅ 提交 Wallet 模块 Context 改造
|
||
2. ✅ 更新改进计划文档
|
||
3. ✅ 创建本文档作为工作记录
|
||
|
||
### 后续行动（下次会话）
|
||
1. 开始 Order 模块 Context 改造
|
||
2. 完成 Payment 模块 Context 改造
|
||
3. 运行所有测试验证
|
||
4. 提交代码
|
||
|
||
---
|
||
|
||
**当前状态**: Wallet 模块已完成，准备提交
|
||
**下一目标**: Order 和 Payment 模块 Context 改造
|
||
**预计完成时间**: 剩余 11 小时工作量
|