Files
go-trustlog/api/persistence/client.go

441 lines
13 KiB
Go
Raw Permalink Normal View History

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
2025-12-23 18:59:43 +08:00
package persistence
import (
"context"
"errors"
"fmt"
"github.com/ThreeDotsLabs/watermill/message"
"go.yandata.net/wangsiyuan/go-trustlog/api/adapter"
"go.yandata.net/wangsiyuan/go-trustlog/api/logger"
"go.yandata.net/wangsiyuan/go-trustlog/api/model"
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
2025-12-23 18:59:43 +08:00
)
// operationPublisherAdapter 适配器,将 PersistenceClient 的 publishToTrustlog 方法适配为 OperationPublisher 接口
type operationPublisherAdapter struct {
client *PersistenceClient
}
func (a *operationPublisherAdapter) Publish(ctx context.Context, op *model.Operation) error {
return a.client.publishToTrustlog(ctx, op)
}
// PersistenceClient 支持数据库持久化的存证客户端
// 在原有 HighClient 功能基础上,增加了数据库持久化支持
type PersistenceClient struct {
publisher message.Publisher
logger logger.Logger
envelopeConfig model.EnvelopeConfig
manager *PersistenceManager
cursorWorker *CursorWorker
retryWorker *RetryWorker
}
// PersistenceClientConfig 客户端配置
type PersistenceClientConfig struct {
// Publisher 消息发布器(用于存证)
Publisher message.Publisher
// Logger 日志记录器
Logger logger.Logger
// EnvelopeConfig SM2密钥配置用于签名和序列化
EnvelopeConfig model.EnvelopeConfig
// DBConfig 数据库配置
DBConfig DBConfig
// PersistenceConfig 持久化策略配置
PersistenceConfig PersistenceConfig
// CursorWorkerConfig Cursor工作器配置可选
CursorWorkerConfig *CursorWorkerConfig
// EnableCursorWorker 是否启用Cursor工作器仅对 StrategyDBAndTrustlog 有效)
EnableCursorWorker bool
// RetryWorkerConfig 重试工作器配置(可选)
RetryWorkerConfig *RetryWorkerConfig
// EnableRetryWorker 是否启用重试工作器(仅对 StrategyDBAndTrustlog 有效)
EnableRetryWorker bool
}
// NewPersistenceClient 创建支持数据库持久化的存证客户端
func NewPersistenceClient(ctx context.Context, config PersistenceClientConfig) (*PersistenceClient, error) {
if config.Logger == nil {
return nil, errors.New("logger is required")
}
// 创建数据库连接
db, err := NewDB(config.DBConfig)
if err != nil {
config.Logger.ErrorContext(ctx, "failed to create database connection",
"error", err,
)
return nil, fmt.Errorf("failed to create database connection: %w", err)
}
// 创建持久化管理器
manager := NewPersistenceManager(db, config.PersistenceConfig, config.Logger)
// 初始化数据库表结构
if err := manager.InitSchema(ctx, config.DBConfig.DriverName); err != nil {
db.Close()
return nil, fmt.Errorf("failed to initialize database schema: %w", err)
}
client := &PersistenceClient{
publisher: config.Publisher,
logger: config.Logger,
envelopeConfig: config.EnvelopeConfig,
manager: manager,
}
// 创建 Operation Publisher 适配器(将 PersistenceClient 的 publishToTrustlog 方法适配为 OperationPublisher 接口)
opPublisher := &operationPublisherAdapter{
client: client,
}
manager.SetPublisher(opPublisher)
// 如果启用Cursor工作器且策略为 StrategyDBAndTrustlog
if config.EnableCursorWorker && config.PersistenceConfig.Strategy == StrategyDBAndTrustlog {
var workerConfig CursorWorkerConfig
if config.CursorWorkerConfig != nil {
workerConfig = *config.CursorWorkerConfig
} else {
workerConfig = DefaultCursorWorkerConfig()
}
// 确保 Enabled 字段被正确设置
workerConfig.Enabled = true
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
2025-12-23 18:59:43 +08:00
client.cursorWorker = NewCursorWorker(workerConfig, manager)
if err := client.cursorWorker.Start(ctx); err != nil {
db.Close()
return nil, fmt.Errorf("failed to start cursor worker: %w", err)
}
config.Logger.InfoContext(ctx, "cursor worker started",
"strategy", config.PersistenceConfig.Strategy.String(),
"scanInterval", workerConfig.ScanInterval,
)
}
// 如果启用重试工作器且策略为 StrategyDBAndTrustlog
if config.EnableRetryWorker && config.PersistenceConfig.Strategy == StrategyDBAndTrustlog {
var workerConfig RetryWorkerConfig
if config.RetryWorkerConfig != nil {
workerConfig = *config.RetryWorkerConfig
} else {
workerConfig = DefaultRetryWorkerConfig()
}
client.retryWorker = NewRetryWorker(workerConfig, manager, config.Publisher, config.Logger)
go client.retryWorker.Start(ctx)
config.Logger.InfoContext(ctx, "retry worker started",
"strategy", config.PersistenceConfig.Strategy.String(),
"retryInterval", workerConfig.RetryInterval,
)
}
config.Logger.InfoContext(ctx, "persistence client created",
"strategy", config.PersistenceConfig.Strategy.String(),
"cursorEnabled", config.EnableCursorWorker,
"retryEnabled", config.EnableRetryWorker,
)
return client, nil
}
// OperationPublish 发布操作记录
// 根据配置的策略,选择仅落库、既落库又存证或仅存证
func (c *PersistenceClient) OperationPublish(ctx context.Context, operation *model.Operation) error {
if operation == nil {
c.logger.ErrorContext(ctx, "operation publish failed: operation is nil")
return errors.New("operation cannot be nil")
}
c.logger.DebugContext(ctx, "publishing operation with persistence",
"opID", operation.OpID,
"opCode", operation.OpCode,
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
2025-12-23 18:59:43 +08:00
"strategy", c.manager.config.Strategy.String(),
)
strategy := c.manager.config.Strategy
switch strategy {
case StrategyDBOnly:
// 仅落库
return c.publishDBOnly(ctx, operation)
case StrategyDBAndTrustlog:
// 既落库又存证
return c.publishDBAndTrustlog(ctx, operation)
case StrategyTrustlogOnly:
// 仅存证
return c.publishTrustlogOnly(ctx, operation)
default:
return fmt.Errorf("unknown persistence strategy: %s", strategy.String())
}
}
// publishDBOnly 仅落库策略
func (c *PersistenceClient) publishDBOnly(ctx context.Context, operation *model.Operation) error {
c.logger.DebugContext(ctx, "publishing operation with DB_ONLY strategy",
"opID", operation.OpID,
)
// 保存到数据库
if err := c.manager.SaveOperation(ctx, operation); err != nil {
c.logger.ErrorContext(ctx, "failed to save operation to database",
"opID", operation.OpID,
"error", err,
)
return err
}
c.logger.InfoContext(ctx, "operation saved with DB_ONLY strategy",
"opID", operation.OpID,
)
return nil
}
// publishDBAndTrustlog 既落库又存证策略
func (c *PersistenceClient) publishDBAndTrustlog(ctx context.Context, operation *model.Operation) error {
c.logger.DebugContext(ctx, "publishing operation with DB_AND_TRUSTLOG strategy",
"opID", operation.OpID,
)
// 先保存到数据库(状态为未存证)
if err := c.manager.SaveOperation(ctx, operation); err != nil {
c.logger.ErrorContext(ctx, "failed to save operation to database",
"opID", operation.OpID,
"error", err,
)
return err
}
// 尝试发布到存证系统
if err := c.publishToTrustlog(ctx, operation); err != nil {
c.logger.WarnContext(ctx, "failed to publish to trustlog, will retry later",
"opID", operation.OpID,
"error", err,
)
// 发布失败,但数据库已保存,重试工作器会处理
return nil
}
// 发布成功,更新状态为已存证
if err := c.manager.GetOperationRepo().UpdateStatus(ctx, operation.OpID, StatusTrustlogged); err != nil {
c.logger.ErrorContext(ctx, "failed to update operation status",
"opID", operation.OpID,
"error", err,
)
// 状态更新失败,但消息已发送,重试工作器会清理
}
// 删除重试记录(如果存在)
c.manager.GetRetryRepo().DeleteRetry(ctx, operation.OpID)
c.logger.InfoContext(ctx, "operation published with DB_AND_TRUSTLOG strategy",
"opID", operation.OpID,
)
return nil
}
// publishTrustlogOnly 仅存证策略
func (c *PersistenceClient) publishTrustlogOnly(ctx context.Context, operation *model.Operation) error {
c.logger.DebugContext(ctx, "publishing operation with TRUSTLOG_ONLY strategy",
"opID", operation.OpID,
)
// 直接发布到存证系统
if err := c.publishToTrustlog(ctx, operation); err != nil {
c.logger.ErrorContext(ctx, "failed to publish to trustlog",
"opID", operation.OpID,
"error", err,
)
return err
}
c.logger.InfoContext(ctx, "operation published with TRUSTLOG_ONLY strategy",
"opID", operation.OpID,
)
return nil
}
// publishToTrustlog 发布到存证系统(使用 Envelope 格式)
func (c *PersistenceClient) publishToTrustlog(ctx context.Context, operation *model.Operation) error {
messageKey := operation.Key()
c.logger.DebugContext(ctx, "starting envelope serialization",
"messageKey", messageKey,
)
// 使用 Envelope 序列化
envelopeData, err := model.MarshalTrustlog(operation, c.envelopeConfig)
if err != nil {
c.logger.ErrorContext(ctx, "envelope serialization failed",
"messageKey", messageKey,
"error", err,
)
return fmt.Errorf("failed to marshal envelope: %w", err)
}
c.logger.DebugContext(ctx, "envelope serialized successfully",
"messageKey", messageKey,
"envelopeSize", len(envelopeData),
)
msg := message.NewMessage(messageKey, envelopeData)
c.logger.DebugContext(ctx, "publishing message to topic",
"messageKey", messageKey,
"topic", adapter.OperationTopic,
)
if publishErr := c.publisher.Publish(adapter.OperationTopic, msg); publishErr != nil {
c.logger.ErrorContext(ctx, "failed to publish to topic",
"messageKey", messageKey,
"topic", adapter.OperationTopic,
"error", publishErr,
)
return fmt.Errorf("failed to publish message to topic %s: %w", adapter.OperationTopic, publishErr)
}
c.logger.DebugContext(ctx, "message published to topic successfully",
"messageKey", messageKey,
"topic", adapter.OperationTopic,
)
return nil
}
// RecordPublish 发布记录Record 类型不支持数据库持久化)
func (c *PersistenceClient) RecordPublish(ctx context.Context, record *model.Record) error {
if record == nil {
c.logger.ErrorContext(ctx, "record publish failed: record is nil")
return errors.New("record cannot be nil")
}
c.logger.DebugContext(ctx, "publishing record",
"recordID", record.ID,
"rcType", record.RCType,
)
// Record 类型直接发布到存证系统,不落库
messageKey := record.Key()
envelopeData, err := model.MarshalTrustlog(record, c.envelopeConfig)
if err != nil {
c.logger.ErrorContext(ctx, "envelope serialization failed",
"recordID", record.ID,
"error", err,
)
return fmt.Errorf("failed to marshal envelope: %w", err)
}
msg := message.NewMessage(messageKey, envelopeData)
if publishErr := c.publisher.Publish(adapter.RecordTopic, msg); publishErr != nil {
c.logger.ErrorContext(ctx, "failed to publish record to topic",
"recordID", record.ID,
"error", publishErr,
)
return fmt.Errorf("failed to publish record to topic %s: %w", adapter.RecordTopic, publishErr)
}
c.logger.InfoContext(ctx, "record published successfully",
"recordID", record.ID,
"rcType", record.RCType,
)
return nil
}
// GetLow 获取底层 Publisher
func (c *PersistenceClient) GetLow() message.Publisher {
return c.publisher
}
// GetManager 获取持久化管理器
func (c *PersistenceClient) GetManager() *PersistenceManager {
return c.manager
}
// Close 关闭客户端
func (c *PersistenceClient) Close() error {
ctx := context.Background()
c.logger.Info("closing persistence client")
// 停止Cursor工作器
if c.cursorWorker != nil {
if err := c.cursorWorker.Stop(ctx); err != nil {
c.logger.Error("failed to stop cursor worker",
"error", err,
)
}
}
// 停止重试工作器
if c.retryWorker != nil {
c.retryWorker.Stop()
}
// 关闭数据库连接
if err := c.manager.Close(); err != nil {
c.logger.Error("failed to close database",
"error", err,
)
return err
}
// 关闭 Publisher如果存在
if c.publisher != nil {
if err := c.publisher.Close(); err != nil {
c.logger.Error("failed to close publisher",
"error", err,
)
return err
}
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
2025-12-23 18:59:43 +08:00
}
c.logger.Info("persistence client closed successfully")
return nil
}
// QueryOperations 查询操作记录(支持分页、筛选、排序)
func (c *PersistenceClient) QueryOperations(ctx context.Context, req *OperationQueryRequest) (*OperationQueryResult, error) {
if c.manager == nil {
return nil, fmt.Errorf("persistence manager not initialized")
}
repo := c.manager.GetOperationRepo()
if repo == nil {
return nil, fmt.Errorf("operation repository not available")
}
return repo.Query(ctx, req)
}
// CountOperations 统计符合条件的操作记录数
func (c *PersistenceClient) CountOperations(ctx context.Context, req *OperationQueryRequest) (int64, error) {
if c.manager == nil {
return 0, fmt.Errorf("persistence manager not initialized")
}
repo := c.manager.GetOperationRepo()
if repo == nil {
return 0, fmt.Errorf("operation repository not available")
}
return repo.Count(ctx, req)
}
// GetOperationByID 根据 OpID 查询单条操作记录
func (c *PersistenceClient) GetOperationByID(ctx context.Context, opID string) (*model.Operation, TrustlogStatus, error) {
if c.manager == nil {
return nil, "", fmt.Errorf("persistence manager not initialized")
}
repo := c.manager.GetOperationRepo()
if repo == nil {
return nil, "", fmt.Errorf("operation repository not available")
}
return repo.FindByID(ctx, opID)
}