模組三：標準庫實戰 on Tarragon

3.1 fmt、strings 與基本文字處理

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

文字處理的核心規則是：格式化輸出交給 fmt，字串查找、裁切、替換與組合交給 strings。本章將用 CLI 輸出、設定值清理與簡單 parser 建立標準庫文字處理基礎。

`fmt` 負責格式化

fmt 的核心責任是把資料轉成可閱讀的文字。它可以輸出到標準輸出，也可以把格式化結果組成字串，常用於 CLI 訊息、錯誤訊息與簡單除錯。

1name := "worker"
2count := 3
3
4fmt.Printf("%s handled %d jobs\n", name, count)
5message := fmt.Sprintf("%s handled %d jobs", name, count)
6
7fmt.Println(message)

Printf 會直接輸出，Sprintf 會回傳字串。這個差異很重要：函式內部如果只是要建立訊息，通常應該用 Sprintf 回傳字串，而不是直接印出。

格式動詞描述輸出形狀

格式動詞的核心作用是告訴 fmt 如何呈現資料。常見動詞包括 %s 表示字串，%d 表示十進位整數，%v 表示一般值，%+v 顯示 struct 欄位名稱，%#v 顯示更接近 Go 語法的表示。

 1type User struct {
 2 ID int
 3 Name string
 4}
 5
 6user := User{ID: 7, Name: "alice"}
 7
 8fmt.Printf("%v\n", user) // {7 alice}
 9fmt.Printf("%+v\n", user) // {ID:7 Name:alice}
10fmt.Printf("%#v\n", user) // main.User{ID:7, Name:"alice"}

%v 適合一般輸出，%+v 適合快速檢查 struct 欄位，%#v 適合除錯或理解實際型別。正式 log 通常應該使用結構化 log，而不是把所有資料塞進格式化字串。

錯誤訊息要包含可行動資訊

錯誤訊息的核心原則是描述失敗的操作與關鍵資料。fmt.Errorf 可以建立帶格式的 error，也可以用 %w 包裝原始錯誤，保留錯誤鏈。

1func loadUser(id string) error {
2 if id == "" {
3 return fmt.Errorf("load user: id is required")
4 }
5
6 return nil
7}

錯誤訊息是給工程師定位問題的線索。像 "failed" 這類訊息太籠統，讀者無法知道是哪個操作失敗。

1if err := saveConfig(path, config); err != nil {
2 return fmt.Errorf("save config %q: %w", path, err)
3}

這裡的訊息包含操作 save config、目標 path 與原始錯誤。呼叫端可以顯示完整錯誤，也可以用 errors.Is 或 errors.As 檢查被包裝的錯誤。

`strings` 負責字串操作

strings 的核心責任是提供不需要正規表示式的常見字串操作。裁切空白、檢查前後綴、切割、替換、大小寫轉換，都應該先考慮 strings。

1raw := " api,worker,admin "
2raw = strings.TrimSpace(raw)
3
4parts := strings.Split(raw, ",")
5for _, part := range parts {
6 fmt.Println(strings.TrimSpace(part))
7}

這段程式先移除整體前後空白，再用逗號切割，最後清理每個片段。這種處理很常見於環境變數、設定檔與簡單文字輸入。

查找與判斷應該直接表達意圖

字串判斷的核心原則是使用最貼近意圖的函式。檢查包含關係用 Contains，檢查開頭用 HasPrefix，檢查結尾用 HasSuffix。

1path := "/api/users"
2
3if strings.HasPrefix(path, "/api/") {
4 fmt.Println("api route")
5}
6
7if strings.Contains(path, "users") {
8 fmt.Println("user resource")
9}

用 Index 判斷是否存在也是可行的，但意圖比較間接。

1if strings.Index(path, "/api/") == 0 {
2 fmt.Println("api route")
3}

這段程式需要讀者理解 Index 回傳 0 表示出現在開頭；HasPrefix 則直接說出規則。入門階段應優先選擇語意清楚的 API。

組合字串要看資料量

組合少量字串時，+ 與 fmt.Sprintf 通常足夠；大量或迴圈內組合字串時，strings.Builder 更適合。核心判斷是：資料量小時重視可讀性，資料量大時避免反覆建立中間字串。

1name := "alice"
2message := "hello, " + name
3fmt.Println(message)

少量字串串接很直覺，不需要過度設計。當你在迴圈中累積文字，strings.Builder 能更明確地表達「正在逐步建構一段文字」。

1var builder strings.Builder
2
3for _, name := range []string{"alice", "bob", "carol"} {
4 builder.WriteString("- ")
5 builder.WriteString(name)
6 builder.WriteString("\n")
7}
8
9fmt.Print(builder.String())

strings.Builder 不是每次組字串都必須使用。若資料量小、流程簡單，普通串接往往更好讀。

簡單 parser 可以先用標準庫

簡單文字解析的核心策略是先用清楚的步驟切割資料，再逐步驗證格式。只有當格式本身複雜到難以維護時，才需要引入 parser 或正規表示式。

 1func parsePair(input string) (string, string, error) {
 2 parts := strings.SplitN(input, "=", 2)
 3 if len(parts) != 2 {
 4 return "", "", fmt.Errorf("parse pair %q: missing =", input)
 5 }
 6
 7 key := strings.TrimSpace(parts[0])
 8 value := strings.TrimSpace(parts[1])
 9 if key == "" {
10 return "", "", fmt.Errorf("parse pair %q: empty key", input)
11 }
12
13 return key, value, nil
14}

SplitN 限制最多切成兩段，避免 value 裡再次出現 = 時被過度切割。這個例子也先處理格式錯誤，再回傳正常結果，讓流程保持清楚。

3.2 time：時間與 duration

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

時間處理的核心規則是：時間點使用 time.Time，時間長度使用 time.Duration。本章將說明 now、parse、format、duration、timer 與 ticker 的基本用法。

`time.Time` 表示時間點

time.Time 的核心意義是一個具體時間點。它可以代表現在、某個解析出來的時間、資料庫中的時間戳，或 API 回傳的建立時間。

1now := time.Now()
2fmt.Println(now)

time.Now() 會取得目前時間。它很方便，但也會讓測試變得不穩定；需要可測試的邏輯時，通常會把時間來源包成參數或介面。

1func isExpired(now time.Time, deadline time.Time) bool {
2 return now.After(deadline)
3}

這個函式不自己呼叫 time.Now()，而是由呼叫端傳入現在時間。測試時就能提供固定時間點，避免測試結果受執行時間影響。

`time.Duration` 表示時間長度

time.Duration 的核心意義是一段時間長度，不是某個時間點。它常用於 timeout、interval、重試等待與效能測量。

1timeout := 5 * time.Second
2interval := 200 * time.Millisecond
3
4fmt.Println(timeout)
5fmt.Println(interval)

time.Second、time.Millisecond 這些常數本身是 Duration，可以用乘法組出可讀的時間長度。這比直接寫奈秒數清楚很多。

1// 可讀性差：
2timeout := time.Duration(5000000000)
3
4// 可讀性好：
5timeout := 5 * time.Second

直接寫數字會讓讀者無法立即看出單位。Go 的時間 API 以奈秒為底層單位，但程式碼應該使用明確單位表達意圖。

時間加減要區分時間點與長度

時間運算的核心規則是：時間點加上 duration 會得到另一個時間點，兩個時間點相減會得到 duration。

1start := time.Now()
2deadline := start.Add(30 * time.Second)
3elapsed := time.Since(start)
4
5fmt.Println(deadline)
6fmt.Println(elapsed)

Add 適合計算截止時間，Since 適合計算從某個時間點到現在經過多久。time.Until(deadline) 則可以計算距離某個未來時間還有多久。

1remaining := time.Until(deadline)
2if remaining <= 0 {
3 fmt.Println("expired")
4}

這些 API 讓程式直接表達時間語意，而不是把時間轉成數字後自行相減。

parse 與 format 使用 layout

Go 時間格式化的核心規則是使用固定參考時間 2006-01-02 15:04:05 作為 layout。layout 用這個參考時間的各個部分代表輸出形狀。

1now := time.Date(2026, 4, 22, 9, 30, 0, 0, time.UTC)
2
3fmt.Println(now.Format("2006-01-02"))
4fmt.Println(now.Format("2006-01-02 15:04:05"))

如果你想輸出年月日，就在 layout 裡寫 2006-01-02；如果想輸出 24 小時制時間，就寫 15:04:05。這和許多語言使用 YYYY-MM-DD 的方式不同，是 Go 時間 API 最容易混淆的地方。

解析時間也使用同一套 layout。

1input := "2026-04-22 09:30:00"
2
3createdAt, err := time.Parse("2006-01-02 15:04:05", input)
4if err != nil {
5 return err
6}
7
8fmt.Println(createdAt)

time.Parse 預設會以 UTC 解讀不含時區的時間。若資料代表某個本地時區，應使用 time.ParseInLocation。

timer 表示一次性的未來事件

time.Timer 的核心用途是在一段時間後發出一次訊號。它常用於 timeout、延遲執行與 select 控制。

1timer := time.NewTimer(2 * time.Second)
2defer timer.Stop()
3
4select {
5case <-timer.C:
6 fmt.Println("timeout")
7}

timer.C 是一個 channel，到時間後會收到一個時間值。若 timer 可能提前不再使用，應呼叫 Stop 釋放資源。

在很多簡單情境中，time.After 更短。

1select {
2case <-time.After(2 * time.Second):
3 fmt.Println("timeout")
4}

time.After 適合一次性的簡單 timeout；在高頻迴圈或需要取消、重設的情境中，time.NewTimer 通常比較適合。

ticker 表示週期性事件

time.Ticker 的核心用途是固定間隔發出訊號。它常用於定期清理、輪詢、健康檢查與背景工作。

1ticker := time.NewTicker(1 * time.Second)
2defer ticker.Stop()
3
4for i := 0; i < 3; i++ {
5 <-ticker.C
6 fmt.Println("tick")
7}

ticker.C 每隔指定 duration 會收到一次訊號。只要不再使用 ticker，就應呼叫 Stop，避免背景資源持續運作。

週期性工作要有明確的退出條件。實務上常搭配 context.Context。

 1func run(ctx context.Context) {
 2 ticker := time.NewTicker(1 * time.Second)
 3 defer ticker.Stop()
 4
 5 for {
 6 select {
 7 case <-ctx.Done():
 8 return
 9 case <-ticker.C:
10 fmt.Println("work")
11 }
12 }
13}

這段程式每秒執行一次工作，直到 context 被取消。時間控制與生命週期控制分開後，程式會比較容易測試與關閉。

小結

下一章會進入 os 與 io，說明檔案、輸入輸出與 streaming API 的共同抽象。

3.3 os/io：檔案與輸入輸出

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

Go I/O 的核心規則是：資料來源抽象成 io.Reader，資料目的地抽象成 io.Writer。本章將從檔案讀寫開始，建立 os、io 與 streaming API 的基本模型。

檔案操作從 `os` 開始

os package 的核心責任是處理作業系統層級的資源，例如檔案、目錄、環境變數與 process 相關資訊。入門階段最常用的是讀檔、寫檔與建立檔案。

1data, err := os.ReadFile("config.json")
2if err != nil {
3 return err
4}
5
6fmt.Println(string(data))

os.ReadFile 會一次把整個檔案讀進記憶體，適合設定檔、小型文字檔與測試資料。若檔案可能很大，就應改用 streaming 方式逐步讀取。

寫入小檔案也可以使用 os.WriteFile。

1data := []byte("name=demo\n")
2
3if err := os.WriteFile("app.env", data, 0644); err != nil {
4 return err
5}

最後的 0644 是檔案權限。它表示檔案擁有者可讀寫，其他人可讀。權限是 Unix 檔案權限慣例。

開啟檔案後要關閉

檔案是作業系統資源，開啟後應在不使用時關閉。Go 常用 defer file.Close() 放在成功開啟檔案後，確保函式結束時釋放資源。

 1file, err := os.Open("data.txt")
 2if err != nil {
 3 return err
 4}
 5defer file.Close()
 6
 7data, err := io.ReadAll(file)
 8if err != nil {
 9 return err
10}
11
12fmt.Println(string(data))

defer 應該放在確認 err == nil 之後，因為開啟失敗時 file 可能是 nil。這是 Go I/O 程式很重要的基本順序：先檢查錯誤，再使用資源。

`io.Reader` 表示可讀來源

io.Reader 的核心意義是「可以讀出 bytes 的來源」。檔案、網路連線、HTTP request body、字串 reader 都可以是 reader。

1func countBytes(r io.Reader) (int, error) {
2 data, err := io.ReadAll(r)
3 if err != nil {
4 return 0, err
5 }
6
7 return len(data), nil
8}

這個函式不關心資料來自檔案、記憶體或網路，只要求呼叫端提供一個 io.Reader。這就是 Go 介面設計的典型風格：用小介面描述能力，而不是描述具體來源。

1count, err := countBytes(strings.NewReader("hello"))
2if err != nil {
3 return err
4}
5
6fmt.Println(count)

strings.NewReader 可以把字串包成 reader，常用於測試與範例。因為函式依賴 io.Reader，測試時不需要真的建立檔案。

`io.Writer` 表示可寫目的地

io.Writer 的核心意義是「可以接收 bytes 的目的地」。檔案、網路連線、HTTP response、記憶體 buffer 都可以是 writer。

1func writeGreeting(w io.Writer, name string) error {
2 _, err := fmt.Fprintf(w, "hello, %s\n", name)
3 return err
4}

這個函式不決定輸出位置，只決定輸出內容。呼叫端可以把內容寫到標準輸出、檔案或 buffer。

1var buffer bytes.Buffer
2
3if err := writeGreeting(&buffer, "alice"); err != nil {
4 return err
5}
6
7fmt.Println(buffer.String())

bytes.Buffer 同時實作 reader 與 writer，適合用來累積輸出或測試寫入結果。

streaming 適合大資料或長連線

streaming 的核心策略是分段處理資料，而不是一次把全部資料載入記憶體。當檔案很大、資料來自網路，或你只需要逐步轉送資料時，streaming 會比 ReadAll 更適合。

 1func copyFile(dstPath string, srcPath string) error {
 2 src, err := os.Open(srcPath)
 3 if err != nil {
 4 return err
 5 }
 6 defer src.Close()
 7
 8 dst, err := os.Create(dstPath)
 9 if err != nil {
10 return err
11 }
12 defer dst.Close()
13
14 _, err = io.Copy(dst, src)
15 return err
16}

io.Copy 從 reader 讀資料並寫到 writer。這段程式沒有手動配置完整檔案大小的 byte slice，因此可以處理比記憶體更大的檔案。

`bufio.Scanner` 適合逐行讀取

逐行處理文字的核心工具是 bufio.Scanner。它會把 reader 切成一個個 token，預設 token 是一行文字。

1func printLines(r io.Reader) error {
2 scanner := bufio.NewScanner(r)
3 for scanner.Scan() {
4 fmt.Println(scanner.Text())
5 }
6
7 return scanner.Err()
8}

scanner.Scan() 每次成功讀到一行就回傳 true，讀完或遇到錯誤時回傳 false。迴圈結束後要檢查 scanner.Err()，因為讀取錯誤不會在迴圈內直接回傳。

Scanner 適合一般文字行，但它有預設 token 大小限制。若要處理非常長的行或大型二進位資料，應改用 bufio.Reader 或其他 streaming API。

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。

3.5 net/http 與 handler 設計

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

Go 的 net/http 把 HTTP endpoint 簡化成一個核心模型：handler 接收 request，然後寫出 response。後端服務可以有複雜的資料庫、queue、背景工作或即時連線，但 HTTP 入口本身應該先保持清楚。

handler 是 HTTP 邊界

HTTP handler 的核心責任是處理協定邊界。它應該讀取 request、驗證輸入、呼叫內部邏輯，最後寫出 status code、header 與 body。

 1func handleHealth(w http.ResponseWriter, r *http.Request) {
 2    if r.Method != http.MethodGet {
 3        http.Error(w, "method not allowed", http.StatusMethodNotAllowed)
 4        return
 5    }
 6
 7    w.Header().Set("Content-Type", "application/json")
 8    w.WriteHeader(http.StatusOK)
 9    fmt.Fprint(w, `{"status":"ok"}`)
10}

這個 handler 只處理健康檢查：確認 HTTP method，設定回應格式，寫出 JSON。它沒有讀取資料庫，也沒有啟動背景工作，因為健康檢查的責任就是讓呼叫者知道服務是否能回應。

handler 可以呼叫內部服務，但不應該把所有業務規則都塞在 HTTP 層。HTTP 層越薄，測試越容易，未來改成 CLI、queue consumer 或其他入口時也比較不會重寫核心邏輯。

`http.HandlerFunc` 是函式轉接器

http.HandlerFunc 的核心意義是讓普通函式符合 http.Handler 介面。只要函式形狀是 func(http.ResponseWriter, *http.Request)，就能成為 HTTP handler。

1func hello(w http.ResponseWriter, r *http.Request) {
2    fmt.Fprint(w, "hello")
3}
4
5func main() {
6    http.HandleFunc("/hello", hello)
7    http.ListenAndServe(":8080", nil)
8}

http.HandleFunc 會把 hello 轉成 handler 並註冊到預設 mux。小範例可以這樣寫，但實際應用通常會建立自己的 ServeMux，避免全域註冊讓測試與組裝變得不清楚。

1func newRouter() http.Handler {
2    mux := http.NewServeMux()
3    mux.HandleFunc("/health", handleHealth)
4    mux.HandleFunc("/users", handleUsers)
5    return mux
6}

回傳 http.Handler 可以隱藏路由實作，呼叫端只需要知道這是一個可被 server 使用的 handler。

`ServeMux` 負責路由分派

ServeMux 的核心責任是把 request path 對應到 handler。標準庫的 http.NewServeMux 足以建立許多小型服務與教學範例。

 1func main() {
 2    mux := http.NewServeMux()
 3    mux.HandleFunc("GET /health", handleHealth)
 4    mux.HandleFunc("POST /users", handleCreateUser)
 5
 6    server := &http.Server{
 7        Addr:    ":8080",
 8        Handler: mux,
 9    }
10
11    if err := server.ListenAndServe(); err != nil {
12        log.Fatal(err)
13    }
14}

新版 Go 的 ServeMux 支援在 pattern 裡寫 HTTP method，例如 GET /health。這能讓 method 與 path 在註冊處一起呈現。

若你的專案需要 middleware group、path parameter 或更完整的路由功能，可以使用第三方 router。入門階段先理解標準庫模型，會更容易看懂任何 router 的抽象。

request 讀取要有明確限制

讀取 request 的核心原則是只接受你預期的內容。handler 應該檢查 method、content type、body 大小與 JSON 格式，避免把任意輸入直接交給內部邏輯。

 1type createUserRequest struct {
 2    Name  string `json:"name"`
 3    Email string `json:"email"`
 4}
 5
 6func handleCreateUser(w http.ResponseWriter, r *http.Request) {
 7    if r.Method != http.MethodPost {
 8        http.Error(w, "method not allowed", http.StatusMethodNotAllowed)
 9        return
10    }
11
12    defer r.Body.Close()
13    r.Body = http.MaxBytesReader(w, r.Body, 1<<20)
14
15    var req createUserRequest
16    if err := json.NewDecoder(r.Body).Decode(&req); err != nil {
17        http.Error(w, "invalid json", http.StatusBadRequest)
18        return
19    }
20
21    if req.Email == "" {
22        http.Error(w, "email is required", http.StatusBadRequest)
23        return
24    }
25
26    w.WriteHeader(http.StatusCreated)
27}

http.MaxBytesReader 限制 body 大小，避免大型輸入消耗過多記憶體。json.Decoder 解析 body，失敗時回傳 400 Bad Request。欄位驗證通過後，handler 才進入真正的建立流程。

這段範例省略了資料儲存，因為本章重點是 HTTP 邊界。實務上通常會把建立使用者的規則放到 service 函式，handler 只負責轉換 request 與 response。

response 要先決定狀態碼

寫 response 的核心規則是先決定 status code，再寫 header 與 body。只要 body 開始寫出，Go 就會送出預設或目前設定的 status code。

1func writeJSON(w http.ResponseWriter, status int, value any) {
2    w.Header().Set("Content-Type", "application/json")
3    w.WriteHeader(status)
4
5    if err := json.NewEncoder(w).Encode(value); err != nil {
6        // response 已經開始寫出，這裡通常只能記錄錯誤。
7        log.Printf("write json response: %v", err)
8    }
9}

WriteHeader 應該在 Encode 之前呼叫。若先寫 body，再呼叫 WriteHeader，狀態碼可能已經固定為 200 OK。

1writeJSON(w, http.StatusCreated, map[string]string{
2    "id": "user_123",
3})

小型範例可以直接在 handler 裡寫 response；當多個 handler 都要輸出 JSON 時，抽出 writeJSON 這類 helper 可以減少重複。

handler 可以依賴介面

handler 依賴介面的核心好處是測試與替換更容易。HTTP 層不需要知道資料來自資料庫、記憶體或遠端 API，只需要知道它可以呼叫某個能力。

 1type UserCreator interface {
 2    CreateUser(ctx context.Context, name string, email string) (string, error)
 3}
 4
 5type UserHandler struct {
 6    creator UserCreator
 7}
 8
 9func (h UserHandler) Create(w http.ResponseWriter, r *http.Request) {
10    // 解析與驗證 request 後：
11    id, err := h.creator.CreateUser(r.Context(), "alice", "alice@example.com")
12    if err != nil {
13        http.Error(w, "create user", http.StatusInternalServerError)
14        return
15    }
16
17    writeJSON(w, http.StatusCreated, map[string]string{"id": id})
18}

這裡的 UserHandler 不知道使用者如何被建立，只知道有一個 UserCreator。測試時可以提供假的 creator，正式環境再接上真正實作。

介面不需要一開始就為所有東西建立。當 handler 真的需要隔離外部依賴，或測試需要替換依賴時，再抽出小介面會更自然。

小結

下一章會回到 logging，說明如何用 slog 讓服務輸出可搜尋、可關聯的結構化資訊。

3.6 log/slog：結構化日誌

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

log/slog 是 Go 標準庫提供的結構化日誌 package。它的核心用途是把 log 寫成「訊息 + key-value 欄位」，讓人類能讀，也讓工具能搜尋、過濾與聚合。

本章目標

學完本章後，你將能夠：

建立 text 或 JSON logger
使用 log level 區分訊號重要性
用 key-value 欄位保存可查詢資訊
設計穩定的 log 欄位名稱
避免把所有資訊塞進自由文字

【觀察】結構化日誌把資訊放進欄位

結構化日誌的核心規則是：穩定資訊放欄位，敘述文字只描述事件。以下範例記錄一筆 user 建立事件：

1logger := slog.New(slog.NewJSONHandler(os.Stdout, nil))
2
3logger.Info(
4 "user created",
5 "userID", "u_1",
6 "email", "alice@example.com",
7)

JSON handler 會輸出類似：

1{
2 "time": "2026-04-22T10:00:00Z",
3 "level": "INFO",
4 "msg": "user created",
5 "userID": "u_1",
6 "email": "alice@example.com"
7}

這比 fmt.Printf("user u_1 alice@example.com created") 更容易被查詢。

【判讀】level 表示事件嚴重度

log level 的核心規則是：level 表示事件需要多少注意力，不表示程式碼所在位置。

level	適用情境
Debug	開發或診斷細節
Info	正常但重要的狀態變化
Warn	可恢復但需要注意的異常
Error	操作失敗或需要處理的錯誤

範例：

1logger.Debug("cache miss", "key", key)
2logger.Info("server started", "addr", addr)
3logger.Warn("queue full", "dropped", count)
4logger.Error("write file failed", "path", path, "error", err)

Error log 應該包含 error 欄位，讓讀者知道失敗原因。

【策略】欄位名稱要穩定

log 欄位設計的核心規則是：同一個概念使用同一個欄位名稱，不要在不同地方混用別名。

概念	建議欄位
使用者 ID	`userID`
request ID	`requestID`
工作 ID	`jobID`
元件名稱	`component`
錯誤	`error`

不要這樣混用：

1logger.Info("job queued", "id", job.ID)
2logger.Info("job started", "job_id", job.ID)
3logger.Info("job done", "jobID", job.ID)

應該統一：

1logger.Info("job queued", "jobID", job.ID)
2logger.Info("job started", "jobID", job.ID)
3logger.Info("job done", "jobID", job.ID)

欄位穩定後，grep、log query、dashboard 才能可靠。

【執行】建立帶預設欄位的 logger

預設欄位的核心規則是：每筆 log 都需要的上下文，應該掛在 logger 上，而不是每次手動重複。

 1base := slog.New(slog.NewJSONHandler(os.Stdout, &slog.HandlerOptions{
 2 Level: slog.LevelInfo,
 3}))
 4
 5logger := base.With(
 6 "component", "worker",
 7 "version", "1.0.0",
 8)
 9
10logger.Info("job started", "jobID", "j_1")
11logger.Info("job finished", "jobID", "j_1")

With 會回傳帶有固定欄位的新 logger。這適合 component、version、requestID 這類上下文。

設計檢查

把所有資訊塞進 msg

不佳：

1logger.Info("job j_1 for user u_1 started")

較佳：

1logger.Info("job started", "jobID", "j_1", "userID", "u_1")

第二種寫法可以直接查 jobID=j_1 或 userID=u_1。

欄位名稱不穩定

欄位名稱不穩定會讓查詢失效。選定 userID 就一路使用 userID，不要混用 uid、user_id、user。

忽略敏感資訊

log 會被保存與轉發。密碼、token、完整信用卡號等敏感資訊不應寫入 log。

延伸閱讀

本章只介紹標準庫 log/slog 的基本用法。服務開始有 domain event、state repository 或查詢需求時，可以接著閱讀如何新增結構化記錄欄位；進入生產操作後，再閱讀 Go 進階：結構化日誌欄位設計與 Observability pipeline、metrics 與 tracing。

3.7 context：取消、逾時與生命週期

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

context.Context 是 Go 用來傳遞取消訊號、逾時與 request-scoped 資訊的標準機制。它的核心用途是讓一串呼叫知道「這件工作是否應該停止」。

本章目標

學完本章後，你將能夠：

理解 context 的取消語義
使用 context.WithCancel
使用 context.WithTimeout
在 goroutine 和函式呼叫鏈中傳遞 context
避免把 context 當成一般資料容器

【觀察】context 表示工作生命週期

context 的核心規則是：被取消的 context 代表這件工作不應繼續進行。長時間工作應定期檢查 ctx.Done()：

 1func Run(ctx context.Context) error {
 2 for {
 3 select {
 4 case <-ctx.Done():
 5 return ctx.Err()
 6 default:
 7 doOneStep()
 8 }
 9 }
10}

ctx.Done() 是一個 channel。當 context 被取消或逾時，這個 channel 會被關閉。

【判讀】取消是由上層傳給下層

context 的方向規則是：上層建立 context，下層接收 context；下層不應保存 context，也不應自行決定整個系統的生命週期。

1func main() {
2 ctx, cancel := context.WithCancel(context.Background())
3 defer cancel()
4
5 go worker(ctx)
6
7 waitForSignal()
8 cancel()
9}

context.Background() 是根 context。context.WithCancel 回傳子 context 和 cancel 函式。當 cancel() 被呼叫，所有使用該 context 的下層工作都會收到停止訊號。

【策略】逾時用 WithTimeout，主動停止用 WithCancel

context 建立方式的核心規則是：不知道何時停止但需要手動停止，用 WithCancel；有明確時間限制，用 WithTimeout。

1ctx, cancel := context.WithTimeout(context.Background(), 2*time.Second)
2defer cancel()
3
4if err := fetchData(ctx); err != nil {
5 return err
6}

下層函式應該接收 context：

 1func fetchData(ctx context.Context) error {
 2 req, err := http.NewRequestWithContext(ctx, http.MethodGet, "https://example.com", nil)
 3 if err != nil {
 4 return err
 5 }
 6
 7 resp, err := http.DefaultClient.Do(req)
 8 if err != nil {
 9 return err
10 }
11 defer resp.Body.Close()
12 return nil
13}

當 timeout 到達，HTTP request 會被取消。

【執行】讓背景 goroutine 有序退出

背景 goroutine 的核心規則是：啟動時接收 context，迴圈中用 select 同時等待工作與取消訊號。

 1func worker(ctx context.Context, jobs <-chan Job) {
 2 for {
 3 select {
 4 case <-ctx.Done():
 5 return
 6 case job, ok := <-jobs:
 7 if !ok {
 8 return
 9 }
10 handleJob(job)
11 }
12 }
13}

這個 worker 有兩種退出路徑：

退出原因	對應 case
上層取消	`<-ctx.Done()`
job channel 關閉	`ok == false`

這比讓 goroutine 無限跑更安全，也比較容易測試。

設計檢查

把 context 存進 struct

context 的生命週期屬於單次操作，不應長期存在 struct 裡。通常把 context 作為函式第一個參數：

1func (s *Service) Do(ctx context.Context, input Input) error

忘記呼叫 cancel

WithCancel、WithTimeout、WithDeadline 回傳的 cancel 應該被呼叫，釋放相關資源：

1ctx, cancel := context.WithTimeout(parent, time.Second)
2defer cancel()

用 context 傳一般參數

context value 適合 request-scoped metadata，例如 request ID。一般業務參數應放在函式參數或 struct 裡。

3.8 defer 與資源清理

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

defer 的核心用途是把資源清理放在取得資源的附近。檔案、鎖、response body、temporary resource 與測試 cleanup 都適合用 defer 表達「離開這個 scope 前要完成的事」。

預計補充內容

這些資源清理邊界會在下列章節展開：

Go 進階：select loop 的生命週期設計：長生命週期的 goroutine 會怎麼收尾，和 defer 的 scope 觀念直接相關。
Go 進階：graceful shutdown 與 signal handling：當 process 要停下來時，defer 常常是 cleanup 的最後一道保險。
Go 入門：testing 基礎：測試裡的資源回收與 t.Cleanup，會比單純 close 更能說清楚責任。

與 Go 進階的關係

本章建立基本資源清理語感。長時間 worker、WebSocket pump 與 graceful shutdown 會在 Go 進階：select loop 的生命週期設計與 graceful shutdown 與 signal handling 中延伸。

和 Go 教材的關係

這一章承接的是資源生命週期、goroutine 停止與 shutdown；如果你要先回看語言教材，可以讀：

3.9 flag、os/env 與設定邊界

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

設定讀取的核心責任是把外部字串轉成程式內部的 typed config。環境變數、命令列 flag、設定檔與預設值都只是輸入來源；application 應依賴已驗證的 config struct。

預計補充內容

這些設定邊界會在下列章節展開：

Go 進階：composition root 與依賴組裝：設定讀取的真正用途，是在啟動層把外部輸入轉成可驗證的依賴。
Go 入門：從入口程式看應用啟動流程：先看主程式怎麼啟動，才知道設定應該在哪裡完成驗證。
Backend：部署平台與網路入口：像 secret manager、ConfigMap 與 rollout 這類平台責任應該留給 Backend。

與 Backend 教材的分工

本章只處理 Go 程式內的設定邊界。secret manager、Kubernetes ConfigMap、container environment、遠端動態設定與部署平台 rollout 會放在 Backend：部署平台與網路入口。

和 Go 教材的關係

這一章承接的是入口流程與 composition root；如果你要先回看語言教材，可以讀：

3.10 標準庫如何支撐服務型 Go

Thu, 23 Apr 2026 00:00:00 +0000

Go 標準庫的服務價值在於它直接提供 HTTP、timeout、取消、日誌與資源管理的基本能力。這一章把前面學過的工具串成服務底座，讓讀者理解標準庫如何支撐後端程式，而不只是個別 API 的使用方式。

本章目標

學完本章後，你將能夠：

看出標準庫為什麼是 Go 服務的底座
把 context、net/http、log/slog、defer 與 time 串成一個服務模型
理解為什麼這些工具會讓服務更可維護
把標準庫能力轉成實際服務邊界
知道何時標準庫已足夠，何時才需要外部框架

【觀察】標準庫本身就能做服務

Go 的標準庫已經包含服務程式需要的主要基礎能力。net/http 可以直接建立服務，context 可以控制取消與 timeout，log/slog 可以支援結構化日誌，defer 可以整理資源釋放，time 可以處理期限與排程。

這些能力拼在一起，就是一個後端服務最基本的底盤。

【判讀】context 是服務生命週期的中心

在服務型 Go 裡，context 是請求、取消與 deadline 的共同語言。當 handler、worker、DB、Redis 都接受 context 時，整個流程就能在同一個生命週期邊界內運作；缺少 context 的長時間流程會讓取消與逾時難以傳遞。

【判讀】net/http 讓入口保持簡單

net/http 的 handler 模型很薄，這是優點。它讓你能快速建立路由、驗證 request、回傳 response，而不需要先學一大套框架約定。對服務型 Go 來說，這種簡單性會直接降低協作成本。

【策略】log 與 defer 讓邊界更完整

log/slog 提供結構化日誌，讓高併發服務的診斷更容易；defer 則讓 close、unlock、cancel 等收尾操作更安全。這兩個工具都是 Go 在長時間運行服務中很重要的可靠性支撐。

小結

標準庫是 Go 成為服務語言的核心原因之一。當你把 context、net/http、log/slog、defer 與 time 看成一組工具時，就更容易理解 Go 為什麼適合做後端服務。

模組三：標準庫實戰 on Tarragon

3.1 fmt、strings 與基本文字處理

fmt 負責格式化

格式動詞描述輸出形狀

錯誤訊息要包含可行動資訊

strings 負責字串操作

查找與判斷應該直接表達意圖

組合字串要看資料量

簡單 parser 可以先用標準庫

3.2 time：時間與 duration

time.Time 表示時間點

time.Duration 表示時間長度

時間加減要區分時間點與長度

parse 與 format 使用 layout

timer 表示一次性的未來事件

ticker 表示週期性事件

小結

3.3 os/io：檔案與輸入輸出

檔案操作從 os 開始

開啟檔案後要關閉

io.Reader 表示可讀來源

io.Writer 表示可寫目的地

streaming 適合大資料或長連線

bufio.Scanner 適合逐行讀取

3.4 encoding/json：資料交換

本章目標

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

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

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

【執行】在 HTTP handler 中處理 JSON

3.5 net/http 與 handler 設計

handler 是 HTTP 邊界

http.HandlerFunc 是函式轉接器

ServeMux 負責路由分派

request 讀取要有明確限制

response 要先決定狀態碼

handler 可以依賴介面

小結

3.6 log/slog：結構化日誌

本章目標

【觀察】結構化日誌把資訊放進欄位

【判讀】level 表示事件嚴重度

【策略】欄位名稱要穩定

【執行】建立帶預設欄位的 logger

設計檢查

把所有資訊塞進 msg

欄位名稱不穩定

忽略敏感資訊

延伸閱讀

3.7 context：取消、逾時與生命週期

本章目標

【觀察】context 表示工作生命週期

【判讀】取消是由上層傳給下層

【策略】逾時用 WithTimeout，主動停止用 WithCancel

【執行】讓背景 goroutine 有序退出

設計檢查

把 context 存進 struct

忘記呼叫 cancel

用 context 傳一般參數

3.8 defer 與資源清理

預計補充內容

與 Go 進階的關係

和 Go 教材的關係

3.9 flag、os/env 與設定邊界

預計補充內容

與 Backend 教材的分工

和 Go 教材的關係

3.10 標準庫如何支撐服務型 Go

本章目標

【觀察】標準庫本身就能做服務

【判讀】context 是服務生命週期的中心

【判讀】net/http 讓入口保持簡單

【策略】log 與 defer 讓邊界更完整

小結

`fmt` 負責格式化

`strings` 負責字串操作

`time.Time` 表示時間點

`time.Duration` 表示時間長度

檔案操作從 `os` 開始

`io.Reader` 表示可讀來源

`io.Writer` 表示可寫目的地

`bufio.Scanner` 適合逐行讀取

`http.HandlerFunc` 是函式轉接器

`ServeMux` 負責路由分派