差分包

diff 包提供了用于生成、比较和可视化预期值与实际值之间差异的工具。该包专为测试场景设计，但也可在需要差异可视化的任何上下文中使用。

特性

• 使用 go-cmp 进行泛型类型比较
• 支持字符串基于统一差分格式的对比
• 提供字符级别的详细文本比较功能
• 支持丰富的颜色和空白区域可视化输出
• 可处理多种 Go 类型，包括结构体、映射和基础类型
• 通过反射实现复杂类型的比较

模块架构

该包按以下模块组织：

1. 核心差异逻辑（diff.go）：主要接口和特定类型差异生成
2. 统一差分（udiff.go）：统一差分解析与格式化实现
3. 输出增强（enrich.go）：用于提升差异输出的颜色与格式
4. 类型与值格式化（convoluted.go）：负责 Go 类型和值的格式化比较
5. 测试工具（testing.go）：适用于测试场景的功能实现

使用示例

基本比较

package main

import (
    "fmt"
    "github.com/walteh/cloudstack-mcp/pkg/diff"
)

func main() {
    expected := "Hello, World!"
    actual := "Hello, Universe!"

    // 生成两个字符串之间的差异
    result := diff.TypedDiff(expected, actual)

    // 打印差异结果
    fmt.Println(result)
}

测试中的使用

package mypackage_test

import (
    "testing"
    "github.com/walteh/cloudstack-mcp/pkg/diff"
)

func TestSomething(t *testing.T) {
    expected := map[string]int{"a": 1, "b": 2}
    actual := map[string]int{"a": 1, "b": 3}

    // 比较值并根据不匹配的结果进行测试失败
    diff.RequireEqual(t, expected, actual)
}

复杂类型比较

package mypackage_test

import (
    "reflect"
    "testing"
    "github.com/walteh/cloudstack-mcp/pkg/diff"
)

type MyStruct struct {
    Name string
    Age  int
    private string
}

func TestStructComparison(t *testing.T) {
    s1 := MyStruct{Name: "Alice", Age: 30, private: "secret"}
    s2 := MyStruct{Name: "Alice", Age: 31, private: "secret"}

    // 比较包含未导出字段的结构体
    diff.RequireEqual(t, s1, s2, diff.WithUnexportedType[MyStruct]())
}

字符级别差异对比

package main

import (
    "fmt"
    "github.com/walteh/cloudstack-mcp/pkg/diff"
)

func main() {
    str1 := "Hello"
    str2 := "World"

    // 对比两个字符串的字符差异
    diff.Show(str1, str2)
}

扩展点

该包设计允许用户通过实现以下接口或添加选项来自定义行为：

• 实现 diff.Comparator 接口以自定义比较逻辑。
• 使用 diff.WithOptions 方法来配置特定的差异生成参数。

最佳实践

1. 选择合适的比较方法：

   • 对于简单值使用 TypedDiff。
   • 对于复杂结构体使用 RequireEqual 并结合选项处理未导出字段。

2. 处理未导出字段时：

   // 使用 WithUnexportedType 选项显式比较私有字段
   diff.RequireEqual(t, a, b, diff.WithUnexportedType[type](...))
   

3. 自定义比较逻辑时：

   type MyComparator struct{}
   
   func (MyComparator) Compare(a, b interface{}) string {
       // 自定义比较实现
   }
   
   // 注册自定义比较器
   diff.Register(diff.KeyType(reflect.TypeOf(a)), &MyComparator{})
   

旧版本兼容性

尽管推荐使用新方法，但包仍支持以下旧函数以确保向后兼容：

• diff.Show()
• diff.DiffString()

这些旧函数已逐步弃用，建议在新项目中优先采用最新接口。