原文鏈接:https://gopl-zh.github.io/ch4/ch4-05.html
JavaScript對象表示法(JSON)是一種用于發(fā)送和接收結(jié)構(gòu)化信息的標(biāo)準(zhǔn)協(xié)議。在類似的協(xié)議中,JSON并不是唯一的一個標(biāo)準(zhǔn)協(xié)議。 XML(§7.14)、ASN.1和Google的Protocol Buffers都是類似的協(xié)議,并且有各自的特色,但是由于簡潔性、可讀性和流行程度等原因,JSON是應(yīng)用最廣泛的一個。
Go語言對于這些標(biāo)準(zhǔn)格式的編碼和解碼都有良好的支持,由標(biāo)準(zhǔn)庫中的encoding/json、encoding/xml、encoding/asn1等包提供支持(譯注:Protocol Buffers的支持由 github.com/golang/protobuf 包提供),并且這類包都有著相似的API接口。本節(jié),我們將對重要的encoding/json包的用法做個概述。
JSON是對JavaScript中各種類型的值——字符串、數(shù)字、布爾值和對象——Unicode本文編碼。它可以用有效可讀的方式表示第三章的基礎(chǔ)數(shù)據(jù)類型和本章的數(shù)組、slice、結(jié)構(gòu)體和map等聚合數(shù)據(jù)類型。
基本的JSON類型有數(shù)字(十進制或科學(xué)記數(shù)法)、布爾值(true或false)、字符串,其中字符串是以雙引號包含的Unicode字符序列,支持和Go語言類似的反斜杠轉(zhuǎn)義特性,不過JSON使用的是\Uhhhh
轉(zhuǎn)義數(shù)字來表示一個UTF-16編碼(譯注:UTF-16和UTF-8一樣是一種變長的編碼,有些Unicode碼點較大的字符需要用4個字節(jié)表示;而且UTF-16還有大端和小端的問題),而不是Go語言的rune類型。
這些基礎(chǔ)類型可以通過JSON的數(shù)組和對象類型進行遞歸組合。一個JSON數(shù)組是一個有序的值序列,寫在一個方括號中并以逗號分隔;一個JSON數(shù)組可以用于編碼Go語言的數(shù)組和slice。一個JSON對象是一個字符串到值的映射,寫成一系列的name:value對形式,用花括號包含并以逗號分隔;JSON的對象類型可以用于編碼Go語言的map類型(key類型是字符串)和結(jié)構(gòu)體。例如:
boolean true
number -273.15
string "She said \"Hello, BF\""
array ["gold", "silver", "bronze"]
object {"year": 1980,
"event": "archery",
"medals": ["gold", "silver", "bronze"]}
考慮一個應(yīng)用程序,該程序負(fù)責(zé)收集各種電影評論并提供反饋功能。它的Movie數(shù)據(jù)類型和一個典型的表示電影的值列表如下所示。(在結(jié)構(gòu)體聲明中,Year和Color成員后面的字符串面值是結(jié)構(gòu)體成員Tag;我們稍后會解釋它的作用。)
gopl.io/ch4/movie
type Movie struct {
Title string
Year int `json:"released"`
Color bool `json:"color,omitempty"`
Actors []string
}
var movies = []Movie{
{Title: "Casablanca", Year: 1942, Color: false,
Actors: []string{"Humphrey Bogart", "Ingrid Bergman"}},
{Title: "Cool Hand Luke", Year: 1967, Color: true,
Actors: []string{"Paul Newman"}},
{Title: "Bullitt", Year: 1968, Color: true,
Actors: []string{"Steve McQueen", "Jacqueline Bisset"}},
// ...
}
這樣的數(shù)據(jù)結(jié)構(gòu)特別適合JSON格式,并且在兩者之間相互轉(zhuǎn)換也很容易。將一個Go語言中類似movies的結(jié)構(gòu)體slice轉(zhuǎn)為JSON的過程叫編組(marshaling)。編組通過調(diào)用json.Marshal函數(shù)完成:
data, err := json.Marshal(movies)
if err != nil {
log.Fatalf("JSON marshaling failed: %s", err)
}
fmt.Printf("%s\n", data)
Marshal函數(shù)返回一個編碼后的字節(jié)slice,包含很長的字符串,并且沒有空白縮進;我們將它折行以便于顯示:
[{"Title":"Casablanca","released":1942,"Actors":["Humphrey Bogart","Ingr
id Bergman"]},{"Title":"Cool Hand Luke","released":1967,"color":true,"Ac
tors":["Paul Newman"]},{"Title":"Bullitt","released":1968,"color":true,"
Actors":["Steve McQueen","Jacqueline Bisset"]}]
這種緊湊的表示形式雖然包含了全部的信息,但是很難閱讀。為了生成便于閱讀的格式,另一個json.MarshalIndent函數(shù)將產(chǎn)生整齊縮進的輸出。該函數(shù)有兩個額外的字符串參數(shù)用于表示每一行輸出的前綴和每一個層級的縮進:
data, err := json.MarshalIndent(movies, "", " ")
if err != nil {
log.Fatalf("JSON marshaling failed: %s", err)
}
fmt.Printf("%s\n", data)
上面的代碼將產(chǎn)生這樣的輸出(譯注:在最后一個成員或元素后面并沒有逗號分隔符):
[
{
"Title": "Casablanca",
"released": 1942,
"Actors": [
"Humphrey Bogart",
"Ingrid Bergman"
]
},
{
"Title": "Cool Hand Luke",
"released": 1967,
"color": true,
"Actors": [
"Paul Newman"
]
},
{
"Title": "Bullitt",
"released": 1968,
"color": true,
"Actors": [
"Steve McQueen",
"Jacqueline Bisset"
]
}
]
在編碼時,默認(rèn)使用Go語言結(jié)構(gòu)體的成員名字作為JSON的對象(通過reflect反射技術(shù),我們將在12.6節(jié)討論)。只有導(dǎo)出的結(jié)構(gòu)體成員才會被編碼,這也就是我們?yōu)槭裁催x擇用大寫字母開頭的成員名稱。
細心的讀者可能已經(jīng)注意到,其中Year名字的成員在編碼后變成了released,還有Color成員編碼后變成了小寫字母開頭的color。這是因為結(jié)構(gòu)體成員Tag所導(dǎo)致的。一個結(jié)構(gòu)體成員Tag是和在編譯階段關(guān)聯(lián)到該成員的元信息字符串:
Year int `json:"released"`
Color bool `json:"color,omitempty"`
結(jié)構(gòu)體的成員Tag可以是任意的字符串面值,但是通常是一系列用空格分隔的key:"value"鍵值對序列;因為值中含有雙引號字符,因此成員Tag一般用原生字符串面值的形式書寫。json開頭鍵名對應(yīng)的值用于控制encoding/json包的編碼和解碼的行為,并且encoding/...下面其它的包也遵循這個約定。成員Tag中json對應(yīng)值的第一部分用于指定JSON對象的名字,比如將Go語言中的TotalCount成員對應(yīng)到JSON中的total_count對象。Color成員的Tag還帶了一個額外的omitempty選項,表示當(dāng)Go語言結(jié)構(gòu)體成員為空或零值時不生成該JSON對象(這里false為零值)。果然,Casablanca是一個黑白電影,并沒有輸出Color成員。
編碼的逆操作是解碼,對應(yīng)將JSON數(shù)據(jù)解碼為Go語言的數(shù)據(jù)結(jié)構(gòu),Go語言中一般叫unmarshaling,通過json.Unmarshal函數(shù)完成。下面的代碼將JSON格式的電影數(shù)據(jù)解碼為一個結(jié)構(gòu)體slice,結(jié)構(gòu)體中只有Title成員。通過定義合適的Go語言數(shù)據(jù)結(jié)構(gòu),我們可以選擇性地解碼JSON中感興趣的成員。當(dāng)Unmarshal函數(shù)調(diào)用返回,slice將被只含有Title信息的值填充,其它JSON成員將被忽略。
var titles []struct{ Title string }
if err := json.Unmarshal(data, &titles); err != nil {
log.Fatalf("JSON unmarshaling failed: %s", err)
}
fmt.Println(titles) // "[{Casablanca} {Cool Hand Luke} {Bullitt}]"
許多web服務(wù)都提供JSON接口,通過HTTP接口發(fā)送JSON格式請求并返回JSON格式的信息。為了說明這一點,我們通過Github的issue查詢服務(wù)來演示類似的用法。首先,我們要定義合適的類型和常量:
gopl.io/ch4/github
// Package github provides a Go API for the GitHub issue tracker.
// See https://developer.github.com/v3/search/#search-issues.
package github
import "time"
const IssuesURL = "https://api.github.com/search/issues"
type IssuesSearchResult struct {
TotalCount int `json:"total_count"`
Items []*Issue
}
type Issue struct {
Number int
HTMLURL string `json:"html_url"`
Title string
State string
User *User
CreatedAt time.Time `json:"created_at"`
Body string // in Markdown format
}
type User struct {
Login string
HTMLURL string `json:"html_url"`
}
和前面一樣,即使對應(yīng)的JSON對象名是小寫字母,每個結(jié)構(gòu)體的成員名也是聲明為大寫字母開頭的。因為有些JSON成員名字和Go結(jié)構(gòu)體成員名字并不相同,因此需要Go語言結(jié)構(gòu)體成員Tag來指定對應(yīng)的JSON名字。同樣,在解碼的時候也需要做同樣的處理,GitHub服務(wù)返回的信息比我們定義的要多很多。
SearchIssues函數(shù)發(fā)出一個HTTP請求,然后解碼返回的JSON格式的結(jié)果。因為用戶提供的查詢條件可能包含類似?
和&
之類的特殊字符,為了避免對URL造成沖突,我們用url.QueryEscape來對查詢中的特殊字符進行轉(zhuǎn)義操作。
gopl.io/ch4/github
package github
import (
"encoding/json"
"fmt"
"net/http"
"net/url"
"strings"
)
// SearchIssues queries the GitHub issue tracker.
func SearchIssues(terms []string) (*IssuesSearchResult, error) {
q := url.QueryEscape(strings.Join(terms, " "))
resp, err := http.Get(IssuesURL + "?q=" + q)
if err != nil {
return nil, err
}
// We must close resp.Body on all execution paths.
// (Chapter 5 presents 'defer', which makes this simpler.)
if resp.StatusCode != http.StatusOK {
resp.Body.Close()
return nil, fmt.Errorf("search query failed: %s", resp.Status)
}
var result IssuesSearchResult
if err := json.NewDecoder(resp.Body).Decode(&result); err != nil {
resp.Body.Close()
return nil, err
}
resp.Body.Close()
return &result, nil
}
在早些的例子中,我們使用了json.Unmarshal函數(shù)來將JSON格式的字符串解碼為字節(jié)slice。但是這個例子中,我們使用了基于流式的解碼器json.Decoder,它可以從一個輸入流解碼JSON數(shù)據(jù),盡管這不是必須的。如您所料,還有一個針對輸出流的json.Encoder編碼對象。
我們調(diào)用Decode方法來填充變量。這里有多種方法可以格式化結(jié)構(gòu)。下面是最簡單的一種,以一個固定寬度打印每個issue,但是在下一節(jié)我們將看到如何利用模板來輸出復(fù)雜的格式。
gopl.io/ch4/issues
// Issues prints a table of GitHub issues matching the search terms.
package main
import (
"fmt"
"log"
"os"
"gopl.io/ch4/github"
)
func main() {
result, err := github.SearchIssues(os.Args[1:])
if err != nil {
log.Fatal(err)
}
fmt.Printf("%d issues:\n", result.TotalCount)
for _, item := range result.Items {
fmt.Printf("#%-5d %9.9s %.55s\n",
item.Number, item.User.Login, item.Title)
}
}
通過命令行參數(shù)指定檢索條件。下面的命令是查詢Go語言項目中和JSON解碼相關(guān)的問題,還有查詢返回的結(jié)果:
$ go build gopl.io/ch4/issues
$ ./issues repo:golang/go is:open json decoder
13 issues:
#5680 eaigner encoding/json: set key converter on en/decoder
#6050 gopherbot encoding/json: provide tokenizer
#8658 gopherbot encoding/json: use bufio
#8462 kortschak encoding/json: UnmarshalText confuses json.Unmarshal
#5901 rsc encoding/json: allow override type marshaling
#9812 klauspost encoding/json: string tag not symmetric
#7872 extempora encoding/json: Encoder internally buffers full output
#9650 cespare encoding/json: Decoding gives errPhase when unmarshalin
#6716 gopherbot encoding/json: include field name in unmarshal error me
#6901 lukescott encoding/json, encoding/xml: option to treat unknown fi
#6384 joeshaw encoding/json: encode precise floating point integers u
#6647 btracey x/tools/cmd/godoc: display type kind of each named type
#4237 gjemiller encoding/base64: URLEncoding padding is optional
GitHub的Web服務(wù)接口 https://developer.github.com/v3/ 包含了更多的特性。
練習(xí) 4.10: 修改issues程序,根據(jù)問題的時間進行分類,比如不到一個月的、不到一年的、超過一年。
練習(xí) 4.11: 編寫一個工具,允許用戶在命令行創(chuàng)建、讀取、更新和關(guān)閉GitHub上的issue,當(dāng)必要的時候自動打開用戶默認(rèn)的編輯器用于輸入文本信息。
練習(xí) 4.12: 流行的web漫畫服務(wù)xkcd也提供了JSON接口。例如,一個 https://xkcd.com/571/info.0.json 請求將返回一個很多人喜愛的571編號的詳細描述。下載每個鏈接(只下載一次)然后創(chuàng)建一個離線索引。編寫一個xkcd工具,使用這些離線索引,打印和命令行輸入的檢索詞相匹配的漫畫的URL。
練習(xí) 4.13: 使用開放電影數(shù)據(jù)庫的JSON服務(wù)接口,允許你檢索和下載 https://omdbapi.com/ 上電影的名字和對應(yīng)的海報圖像。編寫一個poster工具,通過命令行輸入的電影名字,下載對應(yīng)的海報。
更多建議: