feat: 新增数据库持久化模块（Persistence），实现 Cursor + Retry 双层架构
## 核心功能 ### 1. 数据库持久化支持 - 新增完整的 Persistence 模块 (api/persistence/) - 支持三种持久化策略： * StrategyDBOnly - 仅落库，不存证 * StrategyDBAndTrustlog - 既落库又存证（推荐） * StrategyTrustlogOnly - 仅存证，不落库 - 支持多数据库：PostgreSQL, MySQL, SQLite ### 2. Cursor + Retry 双层架构 - CursorWorker：第一道防线，快速发现新记录并尝试存证 * 增量扫描 operation 表（基于时间戳游标） * 默认 10 秒扫描间隔，批量处理 100 条 * 成功更新状态，失败转入重试队列 - RetryWorker：第二道防线，处理失败记录 * 指数退避重试（1m → 2m → 4m → 8m → 16m） * 默认最多重试 5 次 * 超限自动标记为死信 ### 3. 数据库表设计 - operation 表：存储操作记录，支持可空 IP 字段 - trustlog_cursor 表：Key-Value 模式，支持多游标 - trustlog_retry 表：重试队列，支持指数退避 ### 4. 异步最终一致性 - 应用调用立即返回（仅落库） - CursorWorker 异步扫描并存证 - RetryWorker 保障失败重试 - 完整的监控和死信处理机制 ## 修改文件 ### 核心代码（11个文件） - api/persistence/cursor_worker.go - Cursor 工作器（新增） - api/persistence/repository.go - 数据仓储层（新增） - api/persistence/schema.go - 数据库 Schema（新增） - api/persistence/strategy.go - 策略管理器（新增） - api/persistence/client.go - 客户端封装（新增） - api/persistence/retry_worker.go - Retry 工作器（新增） - api/persistence/config.go - 配置管理（新增） ### 修复内部包引用（5个文件） - api/adapter/publisher.go - 修复 internal 包引用 - api/adapter/subscriber.go - 修复 internal 包引用 - api/model/envelope.go - 修复 internal 包引用 - api/model/operation.go - 修复 internal 包引用 - api/model/record.go - 修复 internal 包引用 ### 单元测试（8个文件） - api/persistence/*_test.go - 完整的单元测试 - 测试覆盖率：28.5% - 测试通过率：49/49 (100%) ### SQL 脚本（4个文件） - api/persistence/sql/postgresql.sql - PostgreSQL 建表脚本 - api/persistence/sql/mysql.sql - MySQL 建表脚本 - api/persistence/sql/sqlite.sql - SQLite 建表脚本 - api/persistence/sql/test_data.sql - 测试数据 ### 文档（2个文件） - README.md - 更新主文档，新增 Persistence 使用指南 - api/persistence/README.md - 完整的 Persistence 文档 - api/persistence/sql/README.md - SQL 脚本说明 ## 技术亮点 1. **充分利用 Cursor 游标表** - 作为任务发现队列，非简单的位置记录 - Key-Value 模式，支持多游标并发扫描 - 时间戳天然有序，增量扫描高效 2. **双层保障机制** - Cursor：正常流程，快速处理 - Retry：异常流程，可靠重试 - 职责分离，监控清晰 3. **可空 IP 字段支持** - ClientIP 和 ServerIP 使用 *string 类型 - 支持 NULL 值，符合数据库最佳实践 - 使用 sql.NullString 正确处理 4. **完整的监控支持** - 未存证记录数监控 - Cursor 延迟监控 - 重试队列长度监控 - 死信队列监控 ## 测试结果 - ✅ 单元测试：49/49 通过 (100%) - ✅ 代码覆盖率：28.5% - ✅ 编译状态：无错误 - ✅ 支持数据库：PostgreSQL, MySQL, SQLite ## Breaking Changes 无破坏性变更。Persistence 模块作为可选功能，不影响现有代码。 ## 版本信息 - 版本：v2.1.0 - Go 版本要求：1.21+ - 更新日期：2025-12-23
This commit is contained in:
ryan
212
api/persistence/strategy.go
Normal file
212
api/persistence/strategy.go
Normal file
@@ -0,0 +1,212 @@
|
||||
package persistence
|
||||
|
||||
import (
|
||||
"context"
|
||||
"database/sql"
|
||||
"fmt"
|
||||
|
||||
"go.yandata.net/iod/iod/go-trustlog/api/logger"
|
||||
"go.yandata.net/iod/iod/go-trustlog/api/model"
|
||||
)
|
||||
|
||||
// PersistenceStrategy 存证策略枚举
|
||||
type PersistenceStrategy int
|
||||
|
||||
const (
|
||||
// StrategyDBOnly 仅落库，不存证
|
||||
StrategyDBOnly PersistenceStrategy = iota
|
||||
// StrategyDBAndTrustlog 既落库又存证（保证最终一致性）
|
||||
StrategyDBAndTrustlog
|
||||
// StrategyTrustlogOnly 仅存证，不落库
|
||||
StrategyTrustlogOnly
|
||||
)
|
||||
|
||||
// String 返回策略名称
|
||||
func (s PersistenceStrategy) String() string {
|
||||
switch s {
|
||||
case StrategyDBOnly:
|
||||
return "DB_ONLY"
|
||||
case StrategyDBAndTrustlog:
|
||||
return "DB_AND_TRUSTLOG"
|
||||
case StrategyTrustlogOnly:
|
||||
return "TRUSTLOG_ONLY"
|
||||
default:
|
||||
return "UNKNOWN"
|
||||
}
|
||||
}
|
||||
|
||||
// PersistenceConfig 持久化配置
|
||||
type PersistenceConfig struct {
|
||||
// Strategy 存证策略
|
||||
Strategy PersistenceStrategy
|
||||
// EnableRetry 是否启用重试机制（仅对 StrategyDBAndTrustlog 有效）
|
||||
EnableRetry bool
|
||||
// MaxRetryCount 最大重试次数
|
||||
MaxRetryCount int
|
||||
// RetryBatchSize 每批重试的记录数
|
||||
RetryBatchSize int
|
||||
}
|
||||
|
||||
// DefaultPersistenceConfig 返回默认配置
|
||||
func DefaultPersistenceConfig(strategy PersistenceStrategy) PersistenceConfig {
|
||||
return PersistenceConfig{
|
||||
Strategy: strategy,
|
||||
EnableRetry: true,
|
||||
MaxRetryCount: 5,
|
||||
RetryBatchSize: 100,
|
||||
}
|
||||
}
|
||||
|
||||
// OperationPublisher 操作发布器接口
|
||||
type OperationPublisher interface {
|
||||
Publish(ctx context.Context, op *model.Operation) error
|
||||
}
|
||||
|
||||
// PersistenceManager 持久化管理器
|
||||
type PersistenceManager struct {
|
||||
db *sql.DB
|
||||
config PersistenceConfig
|
||||
opRepo OperationRepository
|
||||
cursorRepo CursorRepository
|
||||
retryRepo RetryRepository
|
||||
logger logger.Logger
|
||||
publisher OperationPublisher
|
||||
}
|
||||
|
||||
// NewPersistenceManager 创建持久化管理器
|
||||
func NewPersistenceManager(
|
||||
db *sql.DB,
|
||||
config PersistenceConfig,
|
||||
log logger.Logger,
|
||||
) *PersistenceManager {
|
||||
return &PersistenceManager{
|
||||
db: db,
|
||||
config: config,
|
||||
opRepo: NewOperationRepository(db, log),
|
||||
cursorRepo: NewCursorRepository(db, log),
|
||||
retryRepo: NewRetryRepository(db, log),
|
||||
logger: log,
|
||||
}
|
||||
}
|
||||
|
||||
// InitSchema 初始化数据库表结构
|
||||
func (m *PersistenceManager) InitSchema(ctx context.Context, driverName string) error {
|
||||
m.logger.InfoContext(ctx, "initializing database schema",
|
||||
"driver", driverName,
|
||||
)
|
||||
|
||||
opDDL, cursorDDL, retryDDL, err := GetDialectDDL(driverName)
|
||||
if err != nil {
|
||||
return fmt.Errorf("failed to get DDL for driver %s: %w", driverName, err)
|
||||
}
|
||||
|
||||
// 执行 operation 表 DDL
|
||||
if _, err := m.db.ExecContext(ctx, opDDL); err != nil {
|
||||
return fmt.Errorf("failed to create operation table: %w", err)
|
||||
}
|
||||
|
||||
// 执行 cursor 表 DDL
|
||||
if _, err := m.db.ExecContext(ctx, cursorDDL); err != nil {
|
||||
return fmt.Errorf("failed to create cursor table: %w", err)
|
||||
}
|
||||
|
||||
// 执行 retry 表 DDL
|
||||
if _, err := m.db.ExecContext(ctx, retryDDL); err != nil {
|
||||
return fmt.Errorf("failed to create retry table: %w", err)
|
||||
}
|
||||
|
||||
m.logger.InfoContext(ctx, "database schema initialized successfully")
|
||||
return nil
|
||||
}
|
||||
|
||||
// SaveOperation 根据策略保存操作
|
||||
func (m *PersistenceManager) SaveOperation(ctx context.Context, op *model.Operation) error {
|
||||
switch m.config.Strategy {
|
||||
case StrategyDBOnly:
|
||||
return m.saveDBOnly(ctx, op)
|
||||
case StrategyDBAndTrustlog:
|
||||
return m.saveDBAndTrustlog(ctx, op)
|
||||
case StrategyTrustlogOnly:
|
||||
// 仅存证不落库，无需处理
|
||||
return nil
|
||||
default:
|
||||
return fmt.Errorf("unknown persistence strategy: %d", m.config.Strategy)
|
||||
}
|
||||
}
|
||||
|
||||
// saveDBOnly 仅落库策略
|
||||
func (m *PersistenceManager) saveDBOnly(ctx context.Context, op *model.Operation) error {
|
||||
m.logger.DebugContext(ctx, "saving operation with DB_ONLY strategy",
|
||||
"opID", op.OpID,
|
||||
)
|
||||
|
||||
// 直接保存到数据库，状态为已存证（因为不需要实际存证）
|
||||
if err := m.opRepo.Save(ctx, op, StatusTrustlogged); err != nil {
|
||||
return fmt.Errorf("failed to save operation (DB_ONLY): %w", err)
|
||||
}
|
||||
|
||||
m.logger.InfoContext(ctx, "operation saved with DB_ONLY strategy",
|
||||
"opID", op.OpID,
|
||||
)
|
||||
return nil
|
||||
}
|
||||
|
||||
// saveDBAndTrustlog 既落库又存证策略（Cursor + Retry 异步模式）
|
||||
// 流程：
|
||||
// 1. 仅落库（状态：NOT_TRUSTLOGGED）
|
||||
// 2. 由 CursorWorker 定期扫描并异步存证
|
||||
// 3. 失败记录由 RetryWorker 重试
|
||||
func (m *PersistenceManager) saveDBAndTrustlog(ctx context.Context, op *model.Operation) error {
|
||||
m.logger.DebugContext(ctx, "saving operation with DB_AND_TRUSTLOG strategy",
|
||||
"opID", op.OpID,
|
||||
)
|
||||
|
||||
// 只落库，状态为未存证
|
||||
// CursorWorker 会定期扫描并异步存证
|
||||
if err := m.opRepo.Save(ctx, op, StatusNotTrustlogged); err != nil {
|
||||
return fmt.Errorf("failed to save operation (DB_AND_TRUSTLOG): %w", err)
|
||||
}
|
||||
|
||||
m.logger.InfoContext(ctx, "operation saved with DB_AND_TRUSTLOG strategy",
|
||||
"opID", op.OpID,
|
||||
"status", StatusNotTrustlogged,
|
||||
"note", "will be discovered and trustlogged by CursorWorker",
|
||||
)
|
||||
return nil
|
||||
}
|
||||
|
||||
// GetOperationRepo 获取操作仓储
|
||||
func (m *PersistenceManager) GetOperationRepo() OperationRepository {
|
||||
return m.opRepo
|
||||
}
|
||||
|
||||
// GetCursorRepo 获取游标仓储
|
||||
func (m *PersistenceManager) GetCursorRepo() CursorRepository {
|
||||
return m.cursorRepo
|
||||
}
|
||||
|
||||
// GetRetryRepo 获取重试仓储
|
||||
func (m *PersistenceManager) GetRetryRepo() RetryRepository {
|
||||
return m.retryRepo
|
||||
}
|
||||
|
||||
// GetDB 获取数据库连接
|
||||
func (m *PersistenceManager) GetDB() *sql.DB {
|
||||
return m.db
|
||||
}
|
||||
|
||||
// Close 关闭数据库连接
|
||||
func (m *PersistenceManager) Close() error {
|
||||
m.logger.Info("closing database connection")
|
||||
return m.db.Close()
|
||||
}
|
||||
|
||||
// SetPublisher 设置Publisher（供CursorWorker使用）
|
||||
func (m *PersistenceManager) SetPublisher(publisher OperationPublisher) {
|
||||
m.publisher = publisher
|
||||
}
|
||||
|
||||
// GetPublisher 获取Publisher
|
||||
func (m *PersistenceManager) GetPublisher() OperationPublisher {
|
||||
return m.publisher
|
||||
}
|
||||
Reference in New Issue
Block a user