前言

GoLang中結(jié)構(gòu)體的 JSON Tag 標(biāo)識（英文名backquote或backtick，反引號 ` 符號包裹的部分內(nèi)容）一直未明確看過完整規(guī)范和使用說明，存在模棱兩可，系統(tǒng)整理如下：

• JSON Tag標(biāo)簽的完整語法，包含哪些選項(xiàng)
• 不同選項(xiàng)（輸出名/-/omitempty/string）的作用及使用范圍
• 特殊注意事項(xiàng)補(bǔ)充

Json中Tag用法匯總

• JSON Tag標(biāo)簽格式為：json:"FieldName/-/可選,omitempty/可選,string/可選
• 多個選項(xiàng)之間使用 , 逗號分割
• FieldName選項(xiàng)：指定編碼后鍵名稱
  • 可為空，則使用Struct對應(yīng)字段名作為JSON輸出名
  • FieldName非空，則使用指定的FieldName作為JSON輸出名
  • -符號，輸出時忽略此字段；但要注意-,（多一個逗號結(jié)尾）時，輸出字段名為-的JSON字段，而不是忽略
• omitempty選項(xiàng)：忽略空值
  • 包含此選項(xiàng)，輸出時字段空值（零值+空值：false、0、nil指針、nil接口值，以及任何空數(shù)組、切片、map或字符串）則不輸出
• string選項(xiàng)：結(jié)果輸出為字符串
  • 字段結(jié)果輸出為字符串
  • 只適用于字符串、浮點(diǎn)、整數(shù)或布爾類型的字段
  • 這種額外的編碼有時在與 JavaScript 程序通信時使用
  • 要注意，如果字段值本身為string時，再次增加JSON的string標(biāo)簽選項(xiàng)，會導(dǎo)致多個引號的情況

// 示例代碼：https://go.dev/play/p/ApzFQttV_MB
package main

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

func main() {
?? ?type ColorGroup struct {
?? ??? ?Hello ? bool ? ? `json:"Hello,string"`
?? ??? ?world ? bool ? ? `json:"World,string"`
?? ??? ?ID ? ? ?int ? ? ?`json:"id,string"`
?? ??? ?Name ? ?string ? `json:"name,string"`
?? ??? ?Colors ?[]string `json:"ColorName,omitempty"`
?? ??? ?Colors1 []string `json:"ColorName1"`
?? ??? ?Colors2 []string `json:"ColorName2"`
?? ?}
?? ?group := ColorGroup{
?? ??? ?Hello: ? true,
?? ??? ?world: ? true,
?? ??? ?ID: ? ? ?1,
?? ??? ?Name: ? ?"Reds",
?? ??? ?Colors: ?[]string{"hello", "world"},
?? ??? ?Colors1: nil,
?? ??? ?Colors2: []string{},
?? ?}
?? ?b, err := json.Marshal(group)
?? ?if err != nil {
?? ??? ?fmt.Println("error:", err)
?? ?}
?? ?os.Stdout.Write(b)
}

// 輸出結(jié)果
//{"Hello":"true","id":"1","name":"\"Reds\"","ColorName":["hello","world"],"ColorName1":null,"ColorName2":[]}

其他注意：

• nil 指針、nil 接口、nil切片等nil類型值，進(jìn)行編碼后為 null JSON 對象
• 空切片、空數(shù)組編碼為 [] JSON 數(shù)組
• map 編碼為 {} JSON 對象
• 指針類型值編碼為指針?biāo)赶虻闹?，接口類型值編碼后為對應(yīng)類型的值

官方 Marshal 函數(shù)說明

func Marshal(v interface{}) ([]byte, error)

Marshal 返回變量 v 的 JSON 編碼后結(jié)果

Marshal 函數(shù)會遞歸的處理變量 v；如果一個值實(shí)現(xiàn)了Marshaler接口，并且不是一個nil指針，Marshal 調(diào)用其 MarshalJSON 方法來生成 JSON 數(shù)據(jù)。如果沒有 MarshalJSON 方法但實(shí)現(xiàn)了 encoding.TextMarshaler 方法，Marshal 調(diào)用 MarshalText 方法并將結(jié)果編碼為 JSON 字符串。nil 指針異常并不是嚴(yán)格意義上的必須，而是模仿了UnmarshalJSON行為中的一個類似的、必須的異常。

否則，Marshal使用以下與類型有關(guān)的默認(rèn)編碼：

• 布爾值被編碼為JSON布爾值
• 浮點(diǎn)、整數(shù)和數(shù)值類型值編碼為JSON數(shù)字
• 字符串值被編碼為JSON字符串，被強(qiáng)制為有效的UTF-8，用Unicode替換符文替換無效的字節(jié)。為了使JSON能夠安全地嵌入到HTML <script>標(biāo)簽中，字符串使用HTMLEscape進(jìn)行編碼，將”<”、”>”、”&”、”U+2028”和”U+2029”轉(zhuǎn)義為”\u003c”、”\u003e”、”\u0026”、”\u2028”、和”\u2029”。在使用編碼器時，可以通過調(diào)用SetEscapeHTML(false)禁用這種替換。
• 數(shù)組和分片的值會被編碼為JSON數(shù)組，但[]byte會被編碼為base64編碼的字符串，而nil切片會被編碼為null JSON對象值。
  • 數(shù)組、分片，編碼后為 JSON 數(shù)組
  • []byte空切片，編碼后為空數(shù)組 []
  • nil 切片，編碼后為 null
• 結(jié)構(gòu)體類型的值被編碼為JSON對象。每個導(dǎo)出的結(jié)構(gòu)字段都會成為對象的成員，使用字段名作為對象的鍵，除非字段因?yàn)橄旅娴脑虮皇÷?ul>
• 每個結(jié)構(gòu)字段的編碼都可通過存儲在結(jié)構(gòu)字段Tag標(biāo)簽的 “json” 鍵下的格式字符串來定制。格式字符串給出了字段的名稱，后面可能有一個用逗號分隔的選項(xiàng)列表。名稱可以是空的，以便指定選項(xiàng)而不覆蓋默認(rèn)的字段名
• “omitempty”選項(xiàng)，如果字段為空值，應(yīng)該從編碼中省略，定義為false、0、nil指針、nil接口值，以及任何空數(shù)組、切片、map或字符串
• 作為一種特殊情況，如果字段標(biāo)簽是”-“，字段總是被省略的。請注意，一個名稱為”-“的字段仍然可以使用標(biāo)簽”-,”來生成

結(jié)構(gòu)體字段Tag標(biāo)簽下 json 鍵對應(yīng)格式化字符串說明：

• 給出字段編碼后的名稱，后面可能有一組逗號分割的選項(xiàng)列表
• 字段名稱可以為空，用于在不覆蓋默認(rèn)字段名的情況下指定不同選項(xiàng)
• omitempty選項(xiàng)，字段為空值（false/0/nil指針/nil接口值/空數(shù)組/空切片/空map/空字符串）時則跳過編碼輸出
• 字段標(biāo)簽為-時，此字段總是被忽略；但要注意，名為-的字段出現(xiàn)在-,標(biāo)簽中時仍可以被生成

結(jié)構(gòu)體字段標(biāo)簽和對應(yīng)含義的一些例子：

// Field appears in JSON as key "myName".
// 該字段出現(xiàn)在JSON中時，名為"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.
// 該字段出現(xiàn)在JSON中時，名為"myName"，如為零值則輸出時忽略此字段
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.
// 該字段出現(xiàn)在JSON中時，名為"Field"，如為零值則輸出時忽略此字段
Field int `json:",omitempty"`

// Field is ignored by this package.
// 該字段當(dāng)前包輸出JSON時忽略
Field int `json:"-"`

// Field appears in JSON as key "-".
// 該字段出現(xiàn)在JSON中時，名為"-"
Field int `json:"-,"`

"string" 選項(xiàng)表示字段以 JSON 格式存儲在 JSON 編碼的字符串中。它只適用于字符串、浮點(diǎn)、整數(shù)或布爾類型的字段。這種額外的編碼有時在與JavaScript程序通信時使用。

Int64String int64 `json:",string"`

鍵名滿足以下條件時將被使用：非空字符串，僅由Unicode字母、數(shù)字和ASCII標(biāo)點(diǎn)符號（不包括引號、反斜杠和逗號）組成。

受下文所述的Go可見性規(guī)則的限制，匿名結(jié)構(gòu)字段通?？杀痪幋a，其內(nèi)部可導(dǎo)出的字段等價于外部結(jié)構(gòu)中的字段。匿名結(jié)構(gòu)體字段使用其JSON Tag標(biāo)簽中給出名稱，而不是匿名的。接口類型的匿名結(jié)構(gòu)字段的處理方式與將該類型作為其名稱相同，也不是匿名。

在決定對哪個字段進(jìn)行marshal或unmarshal時，Go中結(jié)構(gòu)體字段可見性規(guī)則進(jìn)行了調(diào)整。如果在同一級別有多個字段，并且該級別是嵌套最少的（且將是通常Go規(guī)則所選擇的嵌套級別），則適用以下額外規(guī)則：

1) 在這些字段中，如果有任何字段是JSON Tag標(biāo)記的，就只考慮有標(biāo)記的字段，即使有多個未標(biāo)記的字段，否則會發(fā)生沖突。

2) 如果只有一個字段（根據(jù)第一條規(guī)則標(biāo)記或不標(biāo)記），該字段被選中。

3) 否則有多個字段，都會被忽略；不會發(fā)生錯誤。

Go 1.1中新增了對匿名結(jié)構(gòu)字段的處理。在Go 1.1之前，匿名結(jié)構(gòu)字段被忽略。要在當(dāng)前版本和早期版本中強(qiáng)制忽略匿名結(jié)構(gòu)字段，請給該字段一個”-“的JSON標(biāo)簽。

Map的值被編碼為JSON對象。地圖的鍵類型必須是字符串、整數(shù)類型，或者實(shí)現(xiàn)了encoding.TextMarshaler接口。通過應(yīng)用以下規(guī)則對Map的鍵進(jìn)行排序并作為JSON對象的鍵使用，但要遵守上面為字符串值描述的UTF-8強(qiáng)制規(guī)則。

- 任何字符串類型的鍵都可以直接使用
- encoding.TextMarshalers 將被編碼
- 整數(shù)鍵被轉(zhuǎn)換為字符串

指針類型值被編碼為所指向的值，一個 nil 指針會被編碼為 null JSON值。

接口類型值編碼為接口中包含的值，一個 nil 接口值被編碼為 null JSON值。

通道（Channel）、復(fù)合類型（complex）和函數(shù)值（function）不能進(jìn)行JSON編碼，試圖對這樣的值進(jìn)行編碼會導(dǎo)致Marshal返回一個UnsupportedTypeError錯誤。
JSON不能代表循環(huán)嵌套的數(shù)據(jù)結(jié)構(gòu)，Marshal函數(shù)也將不處理它們。向Marshal傳遞循環(huán)結(jié)構(gòu)將導(dǎo)致一個錯誤。

參考

• encoding/json#Marshal
• struct json tag的使用及深入理解

總結(jié)

到此這篇關(guān)于GoLang中Json Tag用法的文章就介紹到這了,更多相關(guān)GoLang中Json Tag用法內(nèi)容請搜索腳本之家以前的文章或繼續(xù)瀏覽下面的相關(guān)文章希望大家以后多多支持腳本之家！

最新評論