模組二：型別、資料與介面 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 程式中也看得見。

2.2 slice 與 map

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

slice 和 map 是 Go 最常用的集合型別。slice 表達有順序的資料列表，map 表達 key-value 查詢表。理解它們的行為，是寫出可靠 Go 程式的基本功。

本章目標

學完本章後，你將能夠：

建立與操作 slice
理解 slice 的長度、容量與 append
建立與操作 map
判斷何時使用 slice，何時使用 map
避免 nil slice、nil map 與共享底層資料的常見問題

【觀察】slice 表達有順序的資料

slice 是 Go 中用來表示有順序元素列表的集合型別。以下範例建立一個 []string，並依照索引順序走訪：

1names := []string{"Alice", "Bob", "Carol"}
2
3for i, name := range names {
4    fmt.Println(i, name)
5}

slice 的常見操作是讀取元素、取得長度、用 append 增加元素：

1names = append(names, "Dave")
2first := names[0]
3count := len(names)

append 的核心規則是：它會回傳 append 後的 slice，呼叫端必須接回結果。len(names) 取得元素數量；append 可能重用原底層 array，也可能配置新底層 array：

1names = append(names, "Eve")

【判讀】slice 是對底層 array 的視窗

slice 的核心模型是「指向底層 array 的視窗」，不是 array 本身。它比較像一個描述底層 array 區段的 header，包含：

1pointer -> 底層 array
2len     -> 目前看得到幾個元素
3cap     -> 從起點到底層 array 結尾還有多少容量

長度與容量分別描述「目前元素數」與「不重新配置時還能擴張多少」。以下範例可以觀察 len 和 cap 的變化：

1items := make([]int, 0, 3)
2fmt.Println(len(items), cap(items)) // 0 3
3
4items = append(items, 10)
5fmt.Println(len(items), cap(items)) // 1 3

append 超過容量時，Go 可能會配置新的底層 array：

1items = append(items, 20, 30, 40)
2fmt.Println(len(items), cap(items))

這就是 append 必須接回原變數的原因：append 後的 slice 可能已經指向新的底層資料。

【策略】用 slice 保存順序，用 map 做查詢

選擇集合型別的核心規則是：在意順序用 slice，需要 key-value 查詢用 map。如果你在意資料順序，用 slice：

1tasks := []string{"read", "write", "test"}

如果你要用 key 快速查資料，用 map：

1scores := map[string]int{
2    "Alice": 90,
3    "Bob":   85,
4}

讀取 map：

1score, ok := scores["Alice"]
2if ok {
3    fmt.Println(score)
4}

map 讀取的核心規則是：需要分辨「不存在」和「零值」時，必須使用 value, ok。key 不存在時，map 會回傳 value type 的零值：

1score := scores["Unknown"] // 0

如果不檢查 ok，你無法分辨「不存在」和「存在但分數是 0」。

【執行】nil slice 與 nil map 的差異

nil slice 和 nil map 的核心差異是：nil slice 可以 append，nil map 不能寫入。nil slice 可以 append：

1var names []string
2names = append(names, "Alice")

nil map 不能直接寫入：

1var scores map[string]int
2scores["Alice"] = 90 // panic

map 寫入前必須先初始化：

1scores := make(map[string]int)
2scores["Alice"] = 90

或用 literal：

1scores := map[string]int{
2    "Alice": 90,
3}

slice 和 map 的常見組合

用 slice 保存輸出順序

map 的迭代順序不保證穩定；如果輸出順序重要，必須額外用 slice 保存或排序 key：

1for name, score := range scores {
2    fmt.Println(name, score)
3}

先整理 key：

1names := make([]string, 0, len(scores))
2for name := range scores {
3    names = append(names, name)
4}
5sort.Strings(names)
6
7for _, name := range names {
8    fmt.Println(name, scores[name])
9}

用 map 當 set

Go 沒有內建 set；需要集合語義時，常用 map[string]struct{} 表示「某個 key 是否存在」：

1seen := make(map[string]struct{})
2seen["Alice"] = struct{}{}
3
4if _, ok := seen["Alice"]; ok {
5    fmt.Println("already seen")
6}

如果想更直觀，也可以用 map[string]bool：

1seen := map[string]bool{
2    "Alice": true,
3}

設計檢查

檢查一：接住 append 回傳值

1append(names, "Alice") // 編譯錯誤：append 結果未使用

正確做法：

1names = append(names, "Alice")

檢查二：寫入前初始化 map

1var m map[string]int
2m["x"] = 1 // panic

正確做法：

1m := make(map[string]int)
2m["x"] = 1

檢查三：需要順序時先排序 key

map 的順序不能拿來做穩定輸出、測試 snapshot 或 UI 排序。需要順序就額外維護 slice。

2.3 interface：用行為定義依賴

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

Go 的 interface 描述的是行為，不是繼承關係。你不需要在 concrete type 上宣告「我實作了某個 interface」；只要方法集合符合，Go 就視為實作。

本章目標

學完本章後，你將能夠：

理解 implicit interface 的設計精神
寫出小而精準的 interface
避免把 concrete type 暴露給不需要的呼叫者
用 interface 改善測試與依賴邊界

【觀察】interface 只描述需要的行為

interface 的核心規則是：只描述呼叫者需要的行為，不描述實作者的完整身份。假設有一個函式要把訊息寫到某個目的地；它不需要知道目的地是檔案、記憶體 buffer，還是網路連線，只需要知道對方能 Write。

1type Writer interface {
2 Write(p []byte) (n int, err error)
3}
4
5func WriteMessage(w Writer, message string) error {
6 _, err := w.Write([]byte(message))
7 return err
8}

這個 interface 很小，只描述一個行為：寫入 bytes。

【判讀】Go interface 是由使用者定義的需求

在 Go 裡，interface 常由「使用者」定義，而不是由「實作者」定義。

這和很多語言不同。你不需要在某個型別上寫：

1// Go 不需要這種宣告
2type File implements Writer

implicit interface 的核心規則是：只要型別有相同方法，就符合 interface，不需要顯式宣告實作關係。

1type MemoryWriter struct {
2 data []byte
3}
4
5func (m *MemoryWriter) Write(p []byte) (int, error) {
6 m.data = append(m.data, p...)
7 return len(p), nil
8}

MemoryWriter 沒有提到 Writer，但它已經符合 Writer。

【策略】interface 越小，依賴越清楚

小 interface 的核心規則是：interface 應由使用端需要的最小行為組成。Go 常見的好 interface 很小：

 1type Reader interface {
 2 Read(p []byte) (n int, err error)
 3}
 4
 5type Writer interface {
 6 Write(p []byte) (n int, err error)
 7}
 8
 9type Closer interface {
10 Close() error
11}

小 interface 的好處是：

呼叫者只依賴自己真正需要的行為
測試替身容易寫
concrete type 可以在不同情境中被重用
未來改內部結構時，外部影響較小

反例是把太多方法塞進一個 interface：

1type UserService interface {
2 CreateUser(User) error
3 UpdateUser(User) error
4 DeleteUser(string) error
5 FindUser(string) (User, error)
6 ListUsers() ([]User, error)
7 ExportUsers() ([]byte, error)
8}

如果某個函式只需要查詢 user，卻依賴整個 UserService，它就知道太多了。

【執行】為查詢需求設計小介面

依賴邊界的核心規則是：使用端只依賴自己需要的方法。假設一個 HTTP handler 只需要查詢使用者名稱：

 1type UserLookup interface {
 2 FindName(userID string) (string, bool)
 3}
 4
 5type Handler struct {
 6 users UserLookup
 7}
 8
 9func NewHandler(users UserLookup) *Handler {
10 return &Handler{users: users}
11}

這個 handler 不知道 user 是存在 map、資料庫、檔案，還是測試假物件裡。它只知道自己需要 FindName。

測試時可以寫一個很小的 fake：

1type fakeUsers map[string]string
2
3func (f fakeUsers) FindName(userID string) (string, bool) {
4 name, ok := f[userID]
5 return name, ok
6}

這就是 Go interface 最實用的地方：它讓依賴變小，讓測試變簡單。

何時先保留 concrete type

interface 的使用邊界是：替換需求或測試替身需求清楚時，再抽出小介面。以下情境通常適合先保留 concrete type：

只有一個 concrete type，而且沒有測試替身需求
interface 只是完整複製 concrete type 的所有方法
你還不確定呼叫者真正需要哪些行為

Go 的常見做法是：先寫 concrete type，等使用端出現明確需求，再抽小 interface。

2.4 常數與 typed string

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

常數讓程式中的固定值有名稱。typed string 則讓一組字串值形成語意邊界，避免任意字串到處流動。

本章目標

學完本章後，你將能夠：

用 const 定義固定值
理解 untyped constant 與 typed constant 的差異
用 typed string 表達狀態與事件類型
集中管理協定字串與 log message

【觀察】字串散落會增加維護成本

協定字串的核心問題是：同一個語意若以裸字串散落在程式中，拼字、修改與合法值判斷都會變成隱性成本。以下是裸字串散落的典型樣子：

1if status == "active" {
2 // ...
3}
4
5if eventType == "user.created" {
6 // ...
7}
8
9log.Println("user created")

短期看起來很直接，但問題是：

拼字錯誤不容易被發現
修改字串時要全專案搜尋
無法從型別看出哪些值是合法的
不同概念可能共用同一種 string

常數可以先解決命名與集中管理問題。

【判讀】const 是把意圖寫進名稱

const 的核心用途是把固定值的意圖寫進名稱。Go 的常數宣告如下：

1const DefaultPort = 8080
2const EventUserCreated = "user.created"

使用常數後，呼叫端讀到的是語意：

1if eventType == EventUserCreated {
2 // ...
3}

這比直接看到 "user.created" 更清楚，因為名稱說明了這個字串在系統中的角色。

【策略】用 typed string 區分概念

typed string 的核心用途是用型別區分不同語意的字串。當多組資料底層都是字串，但語意不同，可以定義不同型別：

1type TaskStatus string
2
3const (
4 TaskStatusPending TaskStatus = "pending"
5 TaskStatusRunning TaskStatus = "running"
6 TaskStatusDone TaskStatus = "done"
7 TaskStatusFailed TaskStatus = "failed"
8)

函式簽名可以明確要求 TaskStatus：

1func CanRetry(status TaskStatus) bool {
2 return status == TaskStatusFailed
3}

這不會讓 Go 變成 enum 語言，但能讓 API 更清楚。讀者看到 TaskStatus，就知道這不是任意字串。

【執行】事件類型與 action 常數

事件類型的核心規則是：同一組事件值應集中在同一個 typed string 型別下。事件驅動程式常需要管理事件類型：

1type EventType string
2
3const (
4 EventUserCreated EventType = "user.created"
5 EventUserUpdated EventType = "user.updated"
6 EventUserDeleted EventType = "user.deleted"
7)

API action 也可以用同樣方式：

1type Action string
2
3const (
4 ActionSubscribe Action = "subscribe"
5 ActionUnsubscribe Action = "unsubscribe"
6 ActionPing Action = "ping"
7)

處理時，switch 會變得可讀：

 1func HandleAction(action Action) error {
 2 switch action {
 3 case ActionSubscribe:
 4 return nil
 5 case ActionUnsubscribe:
 6 return nil
 7 case ActionPing:
 8 return nil
 9 default:
10 return fmt.Errorf("unknown action: %s", action)
11 }
12}

log message 也適合集中

log message 的核心規則是：會被 grep、監控或文件引用的訊息應保持穩定。這類 message 可以用常數集中：

1const (
2 LogServerStarted = "server started"
3 LogEventDropped = "event dropped"
4 LogInvalidAction = "invalid action"
5)

這樣做的價值是讓 log 訊號穩定。當 log 是除錯入口時，穩定字串就是系統 contract 的一部分。

常見取捨

不必把所有字串都變常數

只出現一次、沒有協定意義、不需要搜尋的文字，可以直接寫在原處。過度常數化會讓讀者一直跳檔案。

常數名稱要說明清楚概念

如果常數名稱只是重複值本身，幫助不大：

1const StringActive = "active" // 不佳

比較好的名稱要說明概念：

1const TaskStatusActive TaskStatus = "active"

2.5 指標與資料複製邊界

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

Go 的指標讓函式可以操作原本的資料，而不是資料複本。這很有效率，也很危險：當多個地方共享同一份資料時，你需要明確決定誰可以修改，誰只能讀取。

本章目標

學完本章後，你將能夠：

理解值傳遞與指標傳遞的差異
判斷何時使用 pointer
理解 slice、map 本身已經帶有共享底層資料的特性
用 copy 保護資料邊界

【觀察】Go 預設是值傳遞

值傳遞的核心規則是：函式收到的是參數值的複本，修改複本不會改到呼叫端原值。以下範例中，Rename 修改的是複本：

 1type User struct {
 2 Name string
 3}
 4
 5func Rename(u User) {
 6 u.Name = "Bob"
 7}
 8
 9func main() {
10 user := User{Name: "Alice"}
11 Rename(user)
12 fmt.Println(user.Name) // Alice
13}

Rename 修改的是複本，不是 main 裡的 user。

指標傳遞的核心規則是：函式收到原值位址，因此可以修改呼叫端原值。如果想修改原本的值，就要傳指標：

1func Rename(u *User) {
2 u.Name = "Bob"
3}
4
5func main() {
6 user := User{Name: "Alice"}
7 Rename(&user)
8 fmt.Println(user.Name) // Bob
9}

&user 取得位址，*User 表示指向 User 的指標。

【判讀】pointer 表示共享修改權

pointer 的核心語意是共享修改權，不只是效能工具。它表示被呼叫者可能看到或修改原本那份資料。

適合使用 pointer 的情境：

情境	原因
方法需要修改 receiver	例如 `Counter.Inc()`
struct 很大，複製成本高	避免每次呼叫都複製大量資料
需要表示 optional object	`nil` 可表示不存在
多個方法共享同一份狀態	例如 repository、server、cache

不適合濫用 pointer 的情境：

小型不可變資料，例如 time.Time 常直接值傳遞
只是為了「看起來像物件導向」
不希望呼叫者能修改內部資料

【策略】slice 和 map 要特別小心

slice 和 map 的核心風險是：即使參數不是 pointer，也會共享底層資料。

slice 共享底層陣列

slice 參數會複製 slice header，但 header 指向同一個底層 array；因此函式內修改元素，外面會看見。

1func Modify(items []string) {
2 items[0] = "changed"
3}
4
5func main() {
6 names := []string{"Alice", "Bob"}
7 Modify(names)
8 fmt.Println(names[0]) // changed
9}

map 本身就是 reference-like

map 傳入函式後，函式可以修改同一份 map。這是很多共享狀態 bug 的來源。

1func Modify(m map[string]int) {
2 m["count"] = 10
3}
4
5func main() {
6 values := map[string]int{"count": 1}
7 Modify(values)
8 fmt.Println(values["count"]) // 10
9}

【執行】回傳資料時建立 copy 邊界

copy 邊界的核心規則是：不希望外部修改內部狀態時，不要直接回傳內部 map、slice 或 pointer。假設 UserRepository 內部保存一組使用者：

1type User struct {
2 ID string
3 Name string
4}
5
6type UserRepository struct {
7 users map[string]User
8}

直接回傳 map 會把內部狀態暴露給呼叫者：

1func (r *UserRepository) Users() map[string]User {
2 return r.users
3}

呼叫者就可以繞過 UserRepository 修改內部資料：

1users := repo.Users()
2users["1"] = User{ID: "1", Name: "Changed"}

安全做法是回傳複製：

1func (r *UserRepository) Users() map[string]User {
2 result := make(map[string]User, len(r.users))
3 for id, user := range r.users {
4 result[id] = user
5 }
6 return result
7}

回傳 slice 時也要複製 slice：

1func (r *UserRepository) ListUsers() []User {
2 result := make([]User, 0, len(r.users))
3 for _, user := range r.users {
4 result = append(result, user)
5 }
6 return result
7}

這樣呼叫者可以自由排序、append 或修改回傳資料，不會影響 repository 內部狀態。

深層複製與淺層複製

深層複製的核心規則是：struct 裡面若含 slice、map 或 pointer，只複製 struct 本身仍會共享內部資料。以下 Profile 包含 slice：

1type Profile struct {
2 Name string
3 Tags []string
4}

淺層複製：

1copyProfile := profile

copyProfile.Tags 和 profile.Tags 仍然指向同一個底層 array。若要保護邊界，需要複製 slice：

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 與依賴組裝；如果你要先回看語言教材，可以讀：

2.7 generics 入門：型別參數與約束

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

generics 的核心用途是讓重複的型別安全邏輯可以被抽出來。Go 的泛型適合資料結構、集合 helper、測試工具與少量演算法；一般 application flow 仍應優先使用具體型別與小介面。

預計補充內容

這些型別系統邊界會在下列章節展開：

Go 入門：interface：用行為定義依賴：先看 interface 與具體型別的邊界，才能判斷什麼情況值得引入 generics。
Go 入門：table-driven test：泛型 helper 常常是給測試工具用的，這裡會看到它怎麼支撐重複案例。
Go 進階：資料結構與 allocation 壓力：當泛型影響配置與熱路徑時，才需要往 runtime 成本那層看。

與 Backend 教材的分工

本章只處理 Go 型別系統。資料庫 row mapping、serialization schema 或外部 protocol code generation 會放在 Backend 或實戰章節中討論。

和 Go 教材的關係

這一章承接的是集合操作、型別約束與泛型應用；如果你要先回看語言教材，可以讀：