Cloudstack MCP

🚀 差分包

差分包提供了用於生成、比較和可視化預期值與實際值之間差異的工具。該工具專為測試場景設計，但也可在需要差異可視化的任何場景中使用。

🚀 快速開始

差分包藉助 go-cmp 實現泛型類型比較，支持字符串基於統一差分格式的對比，還能提供字符級別的詳細文本比較功能。它可處理多種 Go 類型，包括結構體、映射和基礎類型，通過反射實現複雜類型的比較。

✨ 主要特性

• 使用 go-cmp 進行泛型類型比較
• 支持字符串基於統一差分格式的對比
• 提供字符級別的詳細文本比較功能
• 支持豐富的顏色和空白區域可視化輸出
• 可處理多種 Go 類型，包括結構體、映射和基礎類型
• 通過反射實現複雜類型的比較

📚 詳細文檔

模塊架構

該包按以下模塊組織：

1. 核心差異邏輯（diff.go）：主要接口和特定類型差異生成
2. 統一差分（udiff.go）：統一差分解析與格式化實現
3. 輸出增強（enrich.go）：用於提升差異輸出的顏色與格式
4. 類型與值格式化（convoluted.go）：負責 Go 類型和值的格式化比較
5. 測試工具（testing.go）：適用於測試場景的功能實現

擴展點

該包設計允許用戶通過實現以下接口或添加選項來自定義行為：

• 實現 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()

這些舊函數已逐步棄用，建議在新項目中優先採用最新接口。

💻 使用示例

基礎用法

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)
}