function_regression_tests

Domain Event 功能回归测试

📋 概述

本目录包含 jxt-core/sdk/pkg/domain/event 包的功能回归测试，确保领域事件基础设施的核心功能在代码变更后保持稳定。

📊 测试统计

• 总测试用例数: 73 ✅
• 测试覆盖率: 87.0% ✅
• 测试文件数: 6
• 测试助手: 1
• 测试状态: 全部通过 ✅

🎯 测试目标

• ✅ 验证 BaseDomainEvent 和 EnterpriseDomainEvent 的核心功能
• ✅ 验证 Payload 序列化/反序列化助手的正确性
• ✅ 验证一致性校验机制的可靠性
• ✅ 验证并发场景下的线程安全性
• ✅ 验证真实业务场景的集成流程

📁 测试文件结构

function_regression_tests/
├── README.md                          # 本文档
├── test_helper.go                     # 测试辅助工具
├── base_domain_event_test.go          # BaseDomainEvent 功能测试
├── enterprise_domain_event_test.go    # EnterpriseDomainEvent 功能测试
├── payload_helper_test.go             # Payload 处理助手测试
├── validation_test.go                 # 一致性校验测试
└── integration_test.go                # 集成测试

🧪 测试分类

1. BaseDomainEvent 测试 (base_domain_event_test.go)

测试用例数: 15

核心测试场景:

• ✅ 事件创建和基本字段验证
• ✅ UUIDv7 格式和唯一性验证
• ✅ UUIDv7 时序性验证
• ✅ 并发创建事件的线程安全性
• ✅ 不同类型聚合根ID的支持
• ✅ Getter 方法的正确性
• ✅ 接口实现验证
• ✅ nil Payload 处理
• ✅ 空字符串处理
• ✅ 不同类型 Payload 支持
• ✅ 版本字段验证
• ✅ 时间精度验证
• ✅ 多个事件的独立性

关键测试:

// 测试 UUIDv7 时序性
TestBaseDomainEvent_UUIDTimeOrdering

// 测试并发创建（10,000 个事件）
TestBaseDomainEvent_ConcurrentCreation

// 测试不同类型的聚合根ID
TestBaseDomainEvent_AggregateIDTypes

2. EnterpriseDomainEvent 测试 (enterprise_domain_event_test.go)

测试用例数: 14

核心测试场景:

• ✅ 企业级事件创建和字段验证
• ✅ 默认租户ID ("*") 验证
• ✅ 租户ID 设置和获取
• ✅ 多租户场景验证
• ✅ CorrelationId（业务关联ID）
• ✅ CausationId（因果事件ID）
• ✅ TraceId（分布式追踪ID）
• ✅ 所有可观测性字段的集成
• ✅ 事件因果链验证
• ✅ 接口实现验证
• ✅ 继承方法验证
• ✅ 并发字段访问
• ✅ 空可观测性字段处理
• ✅ 完整工作流验证
• ✅ 字段独立性验证

关键测试:

// 测试事件因果链
TestEnterpriseDomainEvent_EventCausationChain

// 测试多租户场景
TestEnterpriseDomainEvent_MultiTenantScenario

// 测试完整工作流
TestEnterpriseDomainEvent_CompleteWorkflow

3. Payload 处理助手测试 (payload_helper_test.go)

测试用例数: 18

核心测试场景:

• ✅ 结构体到结构体的反序列化
• ✅ 直接类型匹配优化
• ✅ 复杂嵌套结构处理
• ✅ nil Payload 错误处理
• ✅ 企业级事件 Payload 处理
• ✅ 不同类型转换
• ✅ 字符串 Payload
• ✅ 数字 Payload
• ✅ 数组 Payload
• ✅ 指针 Payload
• ✅ Payload 序列化
• ✅ nil Payload 序列化
• ✅ 复杂 Payload 序列化
• ✅ Payload 序列化/反序列化往返
• ✅ 多次反序列化一致性
• ✅ 空结构体处理
• ✅ JSON 标签支持
• ✅ 类型安全验证

关键测试:

// 测试复杂嵌套结构
TestUnmarshalPayload_ComplexNestedStructure

// 测试 Payload 往返
TestPayloadRoundTrip

// 测试类型安全
TestUnmarshalPayload_TypeSafety

4. 一致性校验测试 (validation_test.go)

测试用例数: 17

核心测试场景:

• ✅ 基础事件一致性校验成功
• ✅ 企业级事件一致性校验成功
• ✅ nil Envelope 错误处理
• ✅ nil Event 错误处理
• ✅ EventType 不匹配检测
• ✅ AggregateID 不匹配检测
• ✅ TenantID 不匹配检测
• ✅ 基础事件与 TenantID 的处理
• ✅ 空 TenantID 处理
• ✅ 默认 TenantID ("*") 处理
• ✅ 多个字段不匹配检测
• ✅ 完整工作流验证
• ✅ 大小写敏感性
• ✅ 空格差异检测
• ✅ 空字符串处理
• ✅ 特殊字符支持
• ✅ 长字符串支持

关键测试:

// 测试 EventType 不匹配
TestValidateConsistency_EventTypeMismatch

// 测试 TenantID 不匹配
TestValidateConsistency_TenantIDMismatch

// 测试完整工作流
TestValidateConsistency_CompleteWorkflow

5. 集成测试 (integration_test.go)

测试用例数: 9

核心测试场景:

• ✅ 完整事件生命周期
• ✅ 事件因果链集成
• ✅ 多租户事件处理
• ✅ 并发事件创建和验证（1000 个事件）
• ✅ Payload 序列化往返集成
• ✅ 事件版本控制
• ✅ 事件时序性
• ✅ 错误处理集成
• ✅ 真实场景：订单处理流程

关键测试:

// 测试完整事件生命周期
TestIntegration_CompleteEventLifecycle

// 测试并发创建和验证（1000 个事件）
TestIntegration_ConcurrentEventCreationAndValidation

// 测试真实场景：订单处理
TestIntegration_RealWorldScenario_OrderProcessing

🚀 运行测试

运行所有测试

cd jxt-core/tests/domain/event/function_regression_tests
go test -v

运行特定测试文件

# 只运行 BaseDomainEvent 测试
go test -v -run TestBaseDomainEvent

# 只运行 EnterpriseDomainEvent 测试
go test -v -run TestEnterpriseDomainEvent

# 只运行 Payload 助手测试
go test -v -run TestUnmarshalPayload

# 只运行一致性校验测试
go test -v -run TestValidateConsistency

# 只运行集成测试
go test -v -run TestIntegration

运行特定测试用例

# 运行 UUIDv7 时序性测试
go test -v -run TestBaseDomainEvent_UUIDTimeOrdering

# 运行并发创建测试
go test -v -run TestBaseDomainEvent_ConcurrentCreation

# 运行事件因果链测试
go test -v -run TestEnterpriseDomainEvent_EventCausationChain

生成测试覆盖率报告

# 生成覆盖率报告
go test -cover

# 生成详细覆盖率报告
go test -coverprofile=coverage.out
go tool cover -html=coverage.out -o coverage.html

# 查看覆盖率详情
go tool cover -func=coverage.out

运行性能测试

# 运行并发测试（压力测试）
go test -v -run TestBaseDomainEvent_ConcurrentCreation
go test -v -run TestIntegration_ConcurrentEventCreationAndValidation

📊 测试统计

✅ 测试覆盖的关键功能

1. UUIDv7 支持

• ✅ UUID 格式验证
• ✅ UUID 唯一性（测试 1000+ 个事件）
• ✅ UUID 时序性（保证递增）
• ✅ 并发生成安全性（10,000 个并发事件）

2. 多租户支持

• ✅ 默认租户 ("*")
• ✅ 租户隔离
• ✅ 多租户事件处理
• ✅ 租户一致性校验

3. 可观测性支持

• ✅ CorrelationId（业务流程追踪）
• ✅ CausationId（事件因果链）
• ✅ TraceId（分布式追踪）
• ✅ 完整的可观测性集成

4. Payload 处理

• ✅ 泛型反序列化
• ✅ 类型安全
• ✅ 复杂嵌套结构
• ✅ 序列化/反序列化往返
• ✅ 多种数据类型支持

5. 一致性校验

• ✅ EventType 一致性
• ✅ AggregateID 一致性
• ✅ TenantID 一致性
• ✅ 清晰的错误信息
• ✅ 边界情况处理

6. 并发安全

• ✅ 并发事件创建（10,000 个事件）
• ✅ 并发字段访问
• ✅ 并发序列化/反序列化
• ✅ 并发一致性校验

🎯 测试最佳实践

1. 使用 TestHelper

helper := NewTestHelper(t)

// 创建事件
event := helper.CreateBaseDomainEvent("Test.Event", "test-123", "Test", payload)

// 断言
helper.AssertNoError(err, "Should succeed")
helper.AssertEqual(expected, actual, "Should match")

2. 测试命名规范

// 格式：Test<Component>_<Scenario>
TestBaseDomainEvent_Creation
TestEnterpriseDomainEvent_MultiTenantScenario
TestUnmarshalPayload_ComplexNestedStructure
TestValidateConsistency_EventTypeMismatch
TestIntegration_CompleteEventLifecycle

3. 测试组织

• 每个测试文件专注于一个组件
• 每个测试用例专注于一个场景
• 使用清晰的注释说明测试目的
• 使用有意义的测试数据

4. 错误处理测试

// 测试错误场景
result, err := jxtevent.UnmarshalPayload[TestPayload](event)
helper.AssertError(err, "Should return error")
helper.AssertErrorContains(err, "expected message", "Error should contain message")

🔍 故障排查

测试失败

1. 查看详细输出:

   go test -v -run <TestName>
   

2. 检查错误信息: 测试使用清晰的错误消息，指出具体失败原因

3. 运行单个测试: 隔离问题

   go test -v -run TestBaseDomainEvent_Creation
   

性能问题

1. 运行性能分析:

   go test -cpuprofile=cpu.prof -memprofile=mem.prof
   go tool pprof cpu.prof
   

2. 检查并发测试: 并发测试可能需要更多时间

📝 添加新测试

1. 选择合适的测试文件

• 基础事件功能 → base_domain_event_test.go
• 企业级功能 → enterprise_domain_event_test.go
• Payload 处理 → payload_helper_test.go
• 一致性校验 → validation_test.go
• 集成场景 → integration_test.go

2. 编写测试用例

func TestNewFeature_Scenario(t *testing.T) {
    helper := NewTestHelper(t)
    
    // 准备测试数据
    // ...
    
    // 执行测试
    // ...
    
    // 验证结果
    helper.AssertEqual(expected, actual, "Should match")
}

3. 运行测试验证

go test -v -run TestNewFeature_Scenario

🎉 测试成功标准

• ✅ 所有 73 个测试用例通过
• ✅ 测试覆盖率 > 80%
• ✅ 无并发竞争条件
• ✅ 无内存泄漏
• ✅ 性能符合预期

⚠️ 重要说明

Go 1.24 Map 兼容性问题

在 Go 1.24 中，由于新的 map 实现，jsoniter 在序列化 map[string]interface{} 时可能会在并发场景下崩溃。

解决方案:

• ✅ 所有测试使用具体的结构体类型而非 map[string]interface{}
• ✅ 推荐在生产代码中也使用结构体类型的 Payload
• ✅ 如果必须使用 map，避免在并发环境中序列化

示例:

// ❌ 不推荐（Go 1.24 并发场景可能崩溃）
payload := map[string]interface{}{
    "key": "value",
}

// ✅ 推荐
type MyPayload struct {
    Key string `json:"key"`
}
payload := MyPayload{Key: "value"}

📚 相关文档

• Domain Event Package README
• Domain Event Implementation Report
• Migration Plan

🔄 持续集成

建议在 CI/CD 流程中运行这些测试：

# .github/workflows/test.yml
- name: Run Domain Event Tests
  run: |
    cd jxt-core/tests/domain/event/function_regression_tests
    go test -v -cover

最后更新: 2025-10-25
维护者: Architecture Team
状态: ✅ 活跃维护