GO Marshal用法及代碼示例

GO語言"encoding/json"包中"Marshal"函數的用法及代碼示例。

用法:

func Marshal(v any)([]byte, error)

Marshal 返回 v 的 JSON 編碼。

Marshal 遞歸地遍曆值 v。如果遇到的值實現了 Marshaler 接口並且不是 nil 指針，則 Marshal 調用其MarshalJSON 方法來生成 JSON。如果不存在 MarshalJSON 方法，但該值實現了編碼 TextMarshaler，則 Marshal 調用其 MarshalText 方法並將結果編碼為 JSON 字符串。 nil 指針異常不是絕對必要的，但在UnmarshalJSON 的行為中模仿了類似的必要異常

否則，Marshal 使用以下 type-dependent 默認編碼：

布爾值編碼為 JSON 布爾值。

浮點、整數和數字值編碼為 JSON 數字。

字符串值編碼為強製轉換為有效 UTF-8 的 JSON 字符串，用 Unicode 替換符文替換無效字節。為了讓 JSON 可以安全地嵌入 HTML <script> 標記，字符串使用 HTMLEscape 進行編碼，替換 "<"、">"、"&"、U+2028 和 U+2029 轉義為 "\u003c","\u003e"、"\u0026"、"\u2028" 和 "\u2029"。使用編碼器時，可以通過調用 SetEscapeHTML(false) 禁用此替換。

數組和切片值編碼為 JSON 數組，除了 []byte 編碼為 base64 編碼字符串，nil 切片編碼為空 JSON 值。

結構值編碼為 JSON 對象。每個導出的結構字段都成為對象的成員，使用字段名稱作為對象鍵，除非由於以下原因之一省略了該字段。

每個結構字段的編碼可以通過存儲在結構字段標簽中"json"鍵下的格式字符串進行自定義。格式字符串給出了字段的名稱，可能後跟以逗號分隔的選項列表。名稱可以為空，以便在不覆蓋默認字段名稱的情況下指定選項。

"omitempty" 選項指定如果字段具有空值(定義為 false、0、nil 指針、nil 接口值以及任何空數組、切片、映射或字符串)，則應從編碼中省略該字段。

作為一種特殊情況，如果字段標記為"-"，則始終省略該字段。請注意，名稱為"-" 的字段仍然可以使用標簽"-," 生成。

結構字段標簽及其含義示例：

// Field appears in JSON as key "myName".
Field int `json:"myName"`

// Field appears in JSON as key "myName" and
// the field is omitted from the object if its value is empty,
// as defined above.
Field int `json:"myName,omitempty"`

// Field appears in JSON as key "Field" (the default), but
// the field is skipped if empty.
// Note the leading comma.
Field int `json:",omitempty"`

// Field is ignored by this package.
Field int `json:"-"`

// Field appears in JSON as key "-".
Field int `json:"-,"`

"string" 選項表示字段以 JSON 格式存儲在 JSON-encoded 字符串中。它僅適用於字符串、浮點、整數或布爾類型的字段。在與JavaScript 程序通信時，有時會使用這種額外的編碼級別：

Int64String int64 `json:",string"`

如果鍵名是僅由 Unicode 字母、數字和 ASCII 標點符號組成的非空字符串，引號、反斜杠和逗號除外。

匿名結構字段通常被編組，就好像它們的內部導出字段是外部結構中的字段一樣，受製於下一段所述修改的通常的 Go 可見性規則。在其 JSON 標記中給出名稱的匿名結構字段被視為具有該名稱，而不是匿名的。接口類型的匿名結構字段被視為以該類型作為其名稱，而不是匿名的。

在決定編組或解組哪個字段時，針對 JSON 修改了結構字段的 Go 可見性規則。如果同一級別有多個字段，並且該級別嵌套最少(因此將是通常的 Go 規則選擇的嵌套級別)，則適用以下額外規則：

1) 在這些字段中，如果有 JSON-tagged，則僅考慮標記字段，即使有多個未標記字段否則會發生衝突。

2)如果恰好有一個字段(根據第一條規則標記或未標記)，則選擇該字段。

3) 否則有多個字段，全部忽略；沒有錯誤發生。

匿名結構字段的處理是 Go 1.1 中的新函數。在 Go 1.1 之前，匿名結構字段被忽略。要在當前版本和早期版本中強製忽略匿名結構字段，請為該字段提供 "-" 的 JSON 標記。

映射值編碼為 JSON 對象。映射的鍵類型必須是字符串、整數類型或實現編碼 TextMarshaler 映射鍵通過應用以下規則進行排序並用作 JSON 對象鍵，受上述字符串值說明的 UTF-8 強製：

- keys of any string type are used directly
- encoding.TextMarshalers are marshaled
- integer keys are converted to strings

指針值編碼為指向的值。 nil 指針編碼為空 JSON 值。

接口值編碼為接口中包含的值。一個 nil 接口值編碼為空 JSON 值。

通道、複數和函數值不能用 JSON 編碼。嘗試編碼這樣的值會導致 Marshal 返回 UnsupportedTypeError

JSON 不能表示循環數據結構並且 Marshal 不處理它們。將循環結構傳遞給 Marshal 將導致錯誤。

package main

import (
	"encoding/json"
	"fmt"
	"os"
)

func main() {
	type ColorGroup struct {
		ID     int
		Name   string
		Colors []string
	}
	group := ColorGroup{
		ID:     1,
		Name:   "Reds",
		Colors: []string{"Crimson", "Red", "Ruby", "Maroon"},
	}
	b, err := json.Marshal(group)
	if err != nil {
		fmt.Println("error:", err)
	}
	os.Stdout.Write(b)
}

{"ID":1,"Name":"Reds","Colors":["Crimson","Red","Ruby","Maroon"]}