Struct on Tarragon

2.1 struct 與 JSON tag

Wed, 22 Apr 2026 00:00:00 +0000

Go 的 struct 用來描述資料形狀：有哪些欄位、欄位是什麼型別、哪些資料應該放在一起。當資料需要存成 JSON 或透過 API 傳輸時，JSON tag 會把 Go 的欄位命名對應到外部格式。

本章目標

學完本章後，你將能夠：

定義可序列化成 JSON 的 struct
理解 omitempty 的 API 語義
分辨內部欄位命名與外部 JSON 命名
看懂設定檔、API request 與事件資料模型

【觀察】struct 用欄位集合定義資料形狀

struct 的核心規則是：每個欄位都用名稱和型別描述一部分資料。以下範例用 struct 定義一份應用設定：

1type Config struct {
2 AppName string `json:"appName"`
3 Port int `json:"port"`
4 Debug bool `json:"debug"`
5}

這段程式同時回答兩個問題：Go 程式內用哪些欄位處理設定，以及 JSON 檔案裡的欄位名稱是什麼。

【判讀】JSON tag 是外部資料格式 contract

JSON tag 的核心規則是：Go 欄位名稱服務程式碼可見性，JSON 欄位名稱服務外部資料格式。AppName 對應 appName 是兩個命名慣例的交界：

層次	命名	原因
Go struct 欄位	`AppName`	exported 欄位必須大寫開頭
JSON payload	`appName`	JSON 與 API 常用 camelCase

omitempty 宣告「這個欄位在某些資料情境中不是必要資料」。它是可選欄位的語義標記；欄位為零值時，JSON 序列化會跳過輸出。

【策略】先用資料語意決定欄位是否必要

設計 JSON 資料時，先分辨欄位角色：

欄位角色	tag 策略
每筆資料都需要	不加 `omitempty`
只有部分情境需要	加 `omitempty`
內部使用，不輸出 JSON	使用 `json:"-"`
外部名稱需要穩定	明確寫 tag，不依賴預設

這樣資料 contract 會比「把 struct 全部輸出」更清楚。

【執行】事件資料建模

事件資料模型的核心規則是：事件本身必備欄位不使用 omitempty，事件內容可依類型使用可選欄位。UserEvent 表示一筆使用者行為事件，可以來自檔案、HTTP API 或 message queue：

1type UserEvent struct {
2 UserID string `json:"userId"`
3 Type string `json:"type"`
4 Timestamp time.Time `json:"timestamp"`
5 Source string `json:"source"`
6 Payload Payload `json:"payload"`
7}

這個 struct 的欄位都沒有 omitempty，表示它是事件流中的完整資料單位。相比之下，Payload 可以依事件類型使用 omitempty，因為不同事件只會填入部分欄位。

巢狀 struct

巢狀 struct 的核心規則是：資料本身有層次時，Go 型別也應保留同樣層次。以下設定把 server 相關欄位集中到 ServerConfig：

 1type ServerConfig struct {
 2 Host string `json:"host"`
 3 Port int `json:"port"`
 4}
 5
 6type Config struct {
 7 AppName string `json:"appName"`
 8 Debug bool `json:"debug"`
 9 Server ServerConfig `json:"server"`
10}

對應 JSON：

1{
2 "appName": "notify",
3 "debug": true,
4 "server": {
5 "host": "localhost",
6 "port": 8080
7 }
8}

這樣的設計讓資料層次在 Go 程式中也看得見。

3.4 encoding/json：資料交換

Wed, 22 Apr 2026 00:00:00 +0000

encoding/json 是 Go 標準庫中負責 JSON 編碼與解碼的 package。它的核心用途是把 Go struct 轉成 JSON，或把 JSON 轉回 Go struct，讓程式能和設定檔、HTTP API、message queue 等外部格式交換資料。

本章目標

學完本章後，你將能夠：

用 json.Unmarshal 解析 JSON bytes
用 json.Marshal 輸出 JSON bytes
用 json.NewDecoder 解析 stream
用 json.NewEncoder 寫出 response
正確處理 JSON 解析錯誤

【觀察】JSON 解碼是外部資料進入 Go 型別的邊界

JSON 解碼的核心規則是：外部資料必須先進入明確的 Go struct，後續程式才應依賴型別欄位。以下範例把設定檔 JSON 解析成 Config：

 1type Config struct {
 2 AppName string `json:"appName"`
 3 Port int `json:"port"`
 4 Debug bool `json:"debug"`
 5}
 6
 7func LoadConfig(data []byte) (Config, error) {
 8 var cfg Config
 9 if err := json.Unmarshal(data, &cfg); err != nil {
10 return Config{}, fmt.Errorf("parse config JSON: %w", err)
11 }
12 return cfg, nil
13}

json.Unmarshal 需要接收 pointer，因為它要把解析結果寫入 cfg。若傳入 cfg 而不是 &cfg，解碼結果無法寫回呼叫端變數。

【判讀】JSON tag 是解碼與編碼的欄位對照表

JSON tag 的核心規則是：Go 欄位名稱和 JSON 欄位名稱可以不同，但必須在 struct tag 中明確對應。

1type User struct {
2 ID string `json:"id"`
3 Name string `json:"name"`
4 CreatedAt string `json:"createdAt"`
5}

這個 struct 對應的 JSON 是：

1{
2 "id": "u_1",
3 "name": "Alice",
4 "createdAt": "2026-04-22T10:00:00Z"
5}

Go 欄位必須 exported，encoding/json 才能讀寫。小寫開頭欄位是 unexported，JSON package 不會填入。

【策略】bytes 用 Marshal/Unmarshal，stream 用 Encoder/Decoder

JSON API 選擇的核心規則是：資料已經在記憶體中用 Marshal / Unmarshal，資料來自 stream 用 Encoder / Decoder。

情境	適合 API
`[]byte` 解析成 struct	`json.Unmarshal`
struct 轉成 `[]byte`	`json.Marshal`
從 `io.Reader` 讀 JSON	`json.NewDecoder`
寫 JSON 到 `io.Writer`	`json.NewEncoder`

HTTP request body 是 stream，適合用 decoder：

1func decodeCreateUser(r *http.Request) (CreateUserRequest, error) {
2 var req CreateUserRequest
3 if err := json.NewDecoder(r.Body).Decode(&req); err != nil {
4 return CreateUserRequest{}, fmt.Errorf("decode request JSON: %w", err)
5 }
6 return req, nil
7}

HTTP response writer 也是 stream，適合用 encoder：

1func writeJSON(w http.ResponseWriter, status int, data any) {
2 w.Header().Set("Content-Type", "application/json")
3 w.WriteHeader(status)
4 _ = json.NewEncoder(w).Encode(data)
5}

【執行】在 HTTP handler 中處理 JSON

HTTP JSON handler 的核心規則是：解析錯誤屬於 client input 問題，通常回 400；內部處理錯誤屬於 server 問題，通常回 500。

 1type CreateUserRequest struct {
 2 Name string `json:"name"`
 3}
 4
 5type CreateUserResponse struct {
 6 ID string `json:"id"`
 7 Name string `json:"name"`
 8}
 9
10func handleCreateUser(w http.ResponseWriter, r *http.Request) {
11 var req CreateUserRequest
12 if err := json.NewDecoder(r.Body).Decode(&req); err != nil {
13 writeJSON(w, http.StatusBadRequest, map[string]string{
14 "error": "invalid JSON",
15 })
16 return
17 }
18
19 if req.Name == "" {
20 writeJSON(w, http.StatusBadRequest, map[string]string{
21 "error": "name is required",
22 })
23 return
24 }
25
26 resp := CreateUserResponse{
27 ID: "u_1",
28 Name: req.Name,
29 }
30 writeJSON(w, http.StatusCreated, resp)
31}

這個 handler 把 JSON 邊界處理清楚：先解碼，再驗證，再執行核心邏輯，最後輸出 JSON。

1.6 函式、方法與 receiver

Wed, 22 Apr 2026 00:00:00 +0000

Go 沒有 class，但有函式、struct 與方法。方法只是帶有 receiver 的函式；receiver 讓函式和某個型別形成關聯，進而表達「這個行為屬於這個資料」。

本章目標

學完本章後，你將能夠：

區分普通函式與方法
理解 receiver 的語法與語義
判斷何時使用 pointer receiver
用建構函式集中初始化規則

【觀察】普通函式不屬於特定值

普通函式的核心規則是：它不綁定特定型別，只接收參數並回傳結果。以下函式只負責把名稱正規化：

1func NormalizeName(name string) string {
2 return strings.TrimSpace(strings.ToLower(name))
3}

呼叫方式：

1name := NormalizeName(" Alice ")

這種函式適合描述純粹轉換：輸入什麼，輸出什麼，不需要修改某個物件的內部狀態。

【判讀】方法是帶 receiver 的函式

方法的核心規則是：函式若需要以某個型別作為操作對象，就用 receiver 綁到該型別。行為和某個型別密切相關時，可以寫成方法：

 1type Counter struct {
 2 value int
 3}
 4
 5func (c *Counter) Inc() {
 6 c.value++
 7}
 8
 9func (c Counter) Value() int {
10 return c.value
11}

(c *Counter) 和 (c Counter) 就是 receiver。它放在 func 和方法名稱之間，表示這個函式是 Counter 的方法。receiver 只表示「這個函式以這個型別作為操作對象」，不代表繼承關係 — Go 沒有類別繼承，方法只是綁定到型別的函式。

呼叫方式：

1var c Counter
2c.Inc()
3fmt.Println(c.Value())

Go 會讓方法呼叫看起來像物件操作，但本質仍然是函式呼叫。

【策略】用是否修改狀態選擇 receiver

receiver 選擇的核心規則是：要修改原值用 pointer receiver，不修改且型別小可以用 value receiver。receiver 有兩種常見形式：

receiver	適用情境
value receiver	不修改原值，型別小，複製成本低
pointer receiver	需要修改原值，或型別較大，避免複製

例如 Value() 不修改 Counter，可以用 value receiver：

1func (c Counter) Value() int {
2 return c.value
3}

Inc() 需要修改原本的 counter，所以使用 pointer receiver：

1func (c *Counter) Inc() {
2 c.value++
3}

如果你不確定，先問一個問題：這個方法是否要改變 receiver 的狀態？答案是 yes，通常就用 pointer receiver。

【執行】用建構函式集中初始化

建構函式的核心用途是集中初始化規則。Go 沒有 constructor 關鍵字，但慣例會用 NewTypeName 建立需要初始化的型別：

 1type Cache struct {
 2 items map[string]string
 3}
 4
 5func NewCache() *Cache {
 6 return &Cache{
 7 items: make(map[string]string),
 8 }
 9}
10
11func (c *Cache) Set(key, value string) {
12 c.items[key] = value
13}
14
15func (c *Cache) Get(key string) (string, bool) {
16 value, ok := c.items[key]
17 return value, ok
18}

使用方式：

1cache := NewCache()
2cache.Set("theme", "dark")
3value, ok := cache.Get("theme")

這裡 NewCache() 的價值是保證 items 一定被初始化。呼叫者不需要知道 Cache 內部有 map，也不需要記得手動 make。

函式還是方法？

函式與方法的選擇規則是：純轉換用函式，依賴型別狀態用方法，需要初始化保證用 NewTypeName。可以用這張表判斷：

問題	選擇
只是轉換資料？	普通函式
行為依賴某個型別的狀態？	方法
需要保證初始化規則？	`NewTypeName` 建構函式
需要符合 interface？	方法

範例：

1func ParsePort(raw string) (int, error) {
2 // 純資料轉換，適合普通函式
3}
4
5func (s *Server) Start() error {
6 // 啟動 Server，適合方法
7}

2.6 struct embedding 與組合式設計

Wed, 22 Apr 2026 00:00:00 +0000

struct embedding 的核心用途是組合既有能力。它可以讓欄位與方法被提升到外層型別，但設計重點仍然是清楚表達責任，而不是模擬繼承階層。

預計補充內容

這些組合邊界會在下列章節展開：

Go 入門：組合優先：小介面與明確依賴：先理解 Go 為什麼偏好組合，才能判斷 embedding 是在表達能力，還是在模仿繼承。
Go 入門：interface：用行為定義依賴：這裡會把 embedding 和 interface 的責任分開，避免欄位提升變成隱性耦合。
Go 進階：composition root 與依賴組裝：當組合開始影響 wiring 時，就要看依賴是在哪一層被建立的。

與其他章節的關係

本章承接組合優先：小介面與明確依賴與 interface：用行為定義依賴，後續會連到 composition root 與依賴組裝。

和 Go 教材的關係

這一章承接的是組合、interface 與依賴組裝；如果你要先回看語言教材，可以讀：