caarlos0/env — ประกาศ config เป็น struct ครั้งเดียว

go version go1.26.5 darwin/arm64
github.com/caarlos0/env/v11 v11.4.1

1 · ทวนโจทย์ที่บทเรียน 44 ค้างไว้ — แล้วนับบรรทัดกันจริง ๆ

บทเรียน 44 พิสูจน์ไว้ห้าข้อว่าการโปรย os.Getenv ไปทั่วโค้ดพังยังไง: พิมพ์ชื่อผิดไม่มีใครเตือน · ต้องแปลง type เองทุกที่ · default กระจัดกระจาย · ไม่มีที่ไหนบอกว่าแอปต้องการ config อะไรบ้าง · และมันระเบิดกลางทางแทนที่จะตายตอน start
ท้ายบทนั้นสรุปสิ่งที่อยากได้ไว้เป็นประโยคเดียว — ประกาศครั้งเดียว แล้วให้ library ทำที่เหลือ วันนี้เราจะได้ของชิ้นนั้นแล้ว

นี่คือของจริงที่ผมนับ — ก๊อปทั้งก้อนไปวางเป็นไฟล์ internal/configmanual/manual.go แล้ว go build ผ่าน · go vet เงียบ
ต้องเป็นคนละโฟลเดอร์กับโค้ดในหัวข้อ 2 นะ — สองก้อนนี้ประกาศ type Config ชื่อเดียวกัน ถ้าวางไว้ package เดียวกันจะได้ Config redeclared in this block ทันที
ส่วนบล็อก import หกบรรทัดที่เห็นข้างล่างนี้ ไม่ได้นับรวมใน 39 บรรทัด ตามที่กล่องข้างบนบอกไว้ — 39 นับเฉพาะ type Config (6) กับ func LoadManual (33)

package configmanual

import (
	"fmt"
	"os"
	"strconv"
	"time"
)

type Config struct {
	AppPort         int
	ShutdownTimeout time.Duration
	LogLevel        string
	PostgresDSN     string
}

func LoadManual() (Config, error) {
	var cfg Config

	portStr, ok := os.LookupEnv("APP_PORT")
	if !ok || portStr == "" {
		portStr = "8080"
	}
	port, err := strconv.Atoi(portStr)
	if err != nil {
		return cfg, fmt.Errorf("APP_PORT: %w", err)
	}
	cfg.AppPort = port

	toStr, ok := os.LookupEnv("APP_SHUTDOWN_TIMEOUT")
	if !ok || toStr == "" {
		toStr = "10s"
	}
	to, err := time.ParseDuration(toStr)
	if err != nil {
		return cfg, fmt.Errorf("APP_SHUTDOWN_TIMEOUT: %w", err)
	}
	cfg.ShutdownTimeout = to

	lvl, ok := os.LookupEnv("LOG_LEVEL")
	if !ok || lvl == "" {
		lvl = "DEBUG"
	}
	cfg.LogLevel = lvl

	cfg.PostgresDSN = os.Getenv("POSTGRES_DSN")

	return cfg, nil
}

อ่านแล้วจะเห็นว่ามันไม่ได้ยาก — มันแค่ยาว ซ้ำ และน่าเบื่อ
สังเกตว่า config 4 ตัวใช้ if err != nil ไปแล้วสองก้อน ถ้ามี 15 ตัวจะเป็นยังไง และบรรทัดที่คนขี้เกียจเขียนที่สุดคือบรรทัดเช็ก error — พอเผลอเขียน _ ไปตัวหนึ่ง คุณก็ได้กับดักทั้งหมดของบทเรียน 44 กลับมาทันที

2 · โค้ดทั้งหมดที่ต้องเขียน

นี่คือโค้ดจากสไลด์หน้า 9 ทั้งดุ้น — ผมก๊อปมาวางแล้ว go build ผ่าน และ go vet เงียบสนิท ไฟล์นี้คือ internal/config/config.go ตามโครง internal/ ของ บทเรียน 27
สังเกต import ให้ดี — สไลด์เขียนไว้บรรทัดเดียวคือ import "github.com/caarlos0/env/v11" ซึ่งคอมไพล์ไม่ผ่าน เพราะ field ShutdownTimeout ใช้ time.Duration ต้องเติม "time" เข้าไปด้วย ผมเลยเขียนเป็นบล็อกให้ครบตั้งแต่ตรงนี้ (ถ้าไม่เติม จะได้ cfgtest/config.go:7:18: undefined: time ซึ่งไม่ได้บอกเลยว่าต้องไปเติม import):

package config

import (
	"time"

	"github.com/caarlos0/env/v11"
)

type Config struct {
	AppPort         int           `env:"APP_PORT" envDefault:"8080"`
	ShutdownTimeout time.Duration `env:"APP_SHUTDOWN_TIMEOUT" envDefault:"10s"`
	LogLevel        string        `env:"LOG_LEVEL" envDefault:"DEBUG"`
	PostgresDSN     string        `env:"POSTGRES_DSN"`
}

func Load() (Config, error) {
	return env.ParseAs[Config]()
}

// `env:"APP_PORT" envDefualt:"8080"`   ← สะกดผิดหนึ่งตัว
$ go build ./...    # เงียบ
$ go vet ./...      # เงียบ
$ go run .
[typo] main.Typo{AppPort:0, Timeout:10000000000} err=<nil>

รันจริงสองรอบ รอบแรกไม่ตั้ง env เลย รอบสองตั้งครบ (พิมพ์ด้วย %#v จึงเห็นชื่อ field)
ตอนทดลองผมย้าย Config มาไว้ใน package main ไฟล์เดียวจบ %#v เลยพิมพ์ว่า main.Config — ถ้าวางไว้ใน internal/config จริงตามโค้ดข้างบน จะขึ้นเป็น config.Config แทน (ผมรันเทียบมาแล้วทั้งสองแบบ ค่าที่ได้เหมือนกันเป๊ะ ต่างแค่ชื่อ package ที่ type ถูกประกาศไว้):

$ go run .
cfg=main.Config{AppPort:8080, ShutdownTimeout:10000000000, LogLevel:"DEBUG", PostgresDSN:""}
err=<nil>

$ APP_PORT=9999 APP_SHUTDOWN_TIMEOUT=1m30s LOG_LEVEL=INFO \
    POSTGRES_DSN="postgres://u:p@localhost:5432/db" go run .
cfg=main.Config{AppPort:9999, ShutdownTimeout:90000000000, LogLevel:"INFO", PostgresDSN:"postgres://u:p@localhost:5432/db"}
err=<nil>

สรุปเป็นตารางเทียบตามที่สไลด์ให้ไว้ ทุกช่องฝั่งซ้ายมาจากโค้ดในหัวข้อ 1 ที่ผมนับบรรทัดจริง:

3 · struct tag ทั้ง 4 ตัว

สไลด์หน้า 10 ให้มาสี่ตัว ผมทดสอบมาครบทุกตัวแล้ว:

envSeparator — ยังใช้ได้กับ slice ของชนิดอื่นด้วย

type Sep struct {
	DefaultSep []string `env:"HOSTS"`                        // ไม่ใส่ separator
	CustomSep  []string `env:"ORIGINS" envSeparator:";"`
	IntsSep    []int    `env:"PORTS" envSeparator:"|"`       // slice ของ int
	SepDefault []string `env:"TAGS" envDefault:"a,b,c"`      // default ก็ถูก split
}

$ HOSTS="a.com,b.com,c.com" ORIGINS="x.io;y.io" PORTS="1|2|3" go run .
[Sep] main.Sep{DefaultSep:[]string{"a.com", "b.com", "c.com"},
      CustomSep:[]string{"x.io", "y.io"},
      IntsSep:[]int{1, 2, 3},
      SepDefault:[]string{"a", "b", "c"}} err=<nil>

สามเรื่องที่ได้จากผลนี้: ไม่ใส่ envSeparator ก็ได้ comma เป็นค่าเริ่มต้น · ใช้กับ []int ได้ ไม่ใช่แค่ []string (มันแยกแล้วแปลงทีละชิ้น) · และ envDefault ก็โดน split ด้วยตัวคั่นเดียวกัน — TAGS ที่ไม่ได้ตั้ง ได้ []string{"a","b","c"} ไม่ใช่สตริงเดียวว่า "a,b,c"

envPrefix — สำหรับ struct ซ้อน struct

type DB struct {
	Host string `env:"HOST"`
	Port int    `env:"PORT" envDefault:"5432"`
}
type Redis struct { Host string `env:"HOST"` }

type Nested struct {
	Primary DB    `envPrefix:"DB_"`
	Cache   Redis `envPrefix:"REDIS_"`
	NoPfx   DB                        // ← ไม่ใส่ prefix เลย
}

$ DB_HOST="pg.local" DB_PORT=6543 REDIS_HOST="redis.local" HOST="bare.local" go run .
[Nested] main.Nested{Primary:main.DB{Host:"pg.local", Port:6543},
         Cache:main.Redis{Host:"redis.local"},
         NoPfx:main.DB{Host:"bare.local", Port:5432}} err=<nil>

ประโยชน์ของมันชัดมาก: DB ตัวเดียวเอาไปใช้ซ้ำได้ทั้ง primary และ replica แค่เปลี่ยน prefix — ไม่ต้องเขียน struct ซ้ำสองรอบเพื่อเปลี่ยนชื่อ env

4 · option ต่อท้ายใน env tag

ทั้งสี่ตัวนี้เขียนต่อท้ายชื่อ env ในอัญประกาศเดียวกัน คั่นด้วยจุลภาค คือ env:"NAME,option" ไม่ใช่ tag แยกใหม่ — ตรงนี้คนพิมพ์ผิดกันบ่อย

,notEmpty กับ ,unset — ผลรันจริง

// `env:"NE_VAR,notEmpty"` แล้วสั่ง os.Setenv("NE_VAR", "")
[notEmpty empty] err=env: environment variable "NE_VAR" should not be empty

// `env:"U_VAR,unset"` แล้วสั่ง os.Setenv("U_VAR", "temp-value")
[unset] parsed="temp-value" err=<nil> ; after parse LookupEnv -> value="" exists=false

,unset มีประโยชน์กับค่าลับ: ค่าเข้า struct ครบแล้ว แต่มันหายไปจาก environment ทันที — process ลูกที่คุณ spawn ทีหลัง (เช่นเรียก exec.Command) จะไม่เห็นรหัสผ่านนั้นอีก

type File struct {
	V string `env:"F_VAR,file"`
}

// เขียนไฟล์ชั่วคราวที่มีเนื้อว่า  s3cr3t-from-file\n   (มี \n ปิดท้าย)
// แล้ว os.Setenv("F_VAR", ชื่อไฟล์นั้น)

[file ok] value="s3cr3t-from-file\n" err=<nil>

[file missing path] err=env: could not load content of file "/definitely/not/here.txt" from variable F_VAR: open /definitely/not/here.txt: no such file or directory

5 · กับดักที่สไลด์เตือนเอง — ,required คู่กับ envDefault

มุมล่างขวาของสไลด์หน้า 10 มีกล่องแดงเขียนว่า: "ระวัง — ,required ใส่คู่กับ envDefault แล้ว envDefault ชนะเสมอ required จะไม่มีผลเลย"
ผมไปพิสูจน์มาแล้ว ทั้งด้วยการรันและด้วยการเปิดซอร์สอ่าน — สไลด์พูดถูกทุกตัวอักษร

type A struct {
	Both string `env:"MYVAR,required" envDefault:"fallback"`
}
type B struct {
	OnlyRequired string `env:"MYVAR2,required"`        // ไม่มี envDefault
}
type C struct {
	BothNotEmpty string `env:"MYVAR3,notEmpty" envDefault:"fallback3"`
}

$ go run .
=== ไม่ตั้ง env เลย ===
[A required+envDefault] value="fallback" err=<nil>
[B required only]       value=""          err=env: required environment variable "MYVAR2" is not set
[C notEmpty+envDefault] value="fallback3" err=<nil>

$ MYVAR2= go run .
=== ตั้ง MYVAR2 เป็นค่าว่าง (MYVAR2=) ===
[A required+envDefault] value="fallback" err=<nil>
[B required only]       value=""         err=<nil>      // ← ผ่านฉลุย!
[C notEmpty+envDefault] value="fallback3" err=<nil>

เหตุผลไม่ได้อยู่ในเวทมนตร์ที่ไหน — มันอยู่ในซอร์สของ env.go เอง สองจุด ผมเปิดของ v11.4.1 มาให้ดู:

// env.go บรรทัด 613 — เงื่อนไขที่ตัดสินว่า required จะ error ไหม
if fieldParams.Required && !exists && fieldParams.OwnKey != "" {
	return "", newVarIsNotSetError(fieldParams.Key)
}

if fieldParams.NotEmpty && val == "" {   // บรรทัด 617

// env.go บรรทัด 648 — ฟังก์ชันที่ตัดสินว่า exists กับ val เป็นอะไร
func getOr(key, defaultValue string, defExists bool, envs map[string]string) (val string, exists, isDefault bool) {
	value, exists := envs[key]
	switch {
	case (!exists || key == "") && defExists:
		return defaultValue, true, true      // ← ไม่มี env แต่มี default → บอกว่า "มีอยู่"
	case exists && value == "" && defExists:
		return defaultValue, true, true      // ← env ว่าง แต่มี default → ก็ยังบอกว่า "มีอยู่"
	case !exists:
		return "", false, false
	}
	return value, true, false
}

6 · type ที่รองรับ — และคำว่า "zero dependency"

สไลด์หน้า 9 ลิสต์ type ที่รองรับไว้ ผมเขียน struct ที่มีครบทุกตัวแล้วรันทีเดียว — ผ่านหมด:

TextUnmarshaler คือกุญแจของทั้งหมดนี้

encoding.TextUnmarshaler คือ interface ของ standard library ที่มีเมธอดเดียว: UnmarshalText([]byte) error
แปลว่า "ชนิดนี้รู้วิธีสร้างตัวเองจากข้อความ" — ใครก็ตามที่เขียนเมธอดนี้ให้ type ของตัวเอง จะใช้กับ caarlos0/env ได้ทันทีโดย library ไม่ต้องรู้จักคุณมาก่อน

type LogLevel struct{ v string }

func (l *LogLevel) UnmarshalText(b []byte) error {
	s := strings.ToUpper(string(b))
	switch s {
	case "DEBUG", "INFO", "WARN", "ERROR":
		l.v = s
		return nil
	}
	return fmt.Errorf("unknown log level %q", s)
}

$ LVL=info LVLP=warn go run .
Lvl=main.LogLevel{v:"INFO"} LvlP=&{WARN}       # ส่ง info เข้าไป ได้ INFO ออกมา

$ LVL=verbose go run .
ERR: env: parse error on field "Lvl" of type "main.LogLevel": unknown log level "VERBOSE"

สังเกตข้อความ error ให้ดี — ข้อความที่คุณเขียนเองใน UnmarshalText ถูกยกมาใส่ในข้อความของ library ทั้งดุ้น พร้อมชื่อ field และชนิด
นี่คือวิธีทำ validation ระดับ "ค่านี้ต้องเป็นหนึ่งในสี่ค่านี้เท่านั้น" ตั้งแต่ตอน parse โดยไม่ต้องรอ validator (ซึ่งเป็นเรื่องของ บทเรียน 47)

// แบบ 1 — ลายเซ็นผิด (รับ string แทน []byte) → library ฟ้องให้ ดีมาก
err=env: no parser found for field "W" of type "main.Wrong"

// แบบ 2 — ลืมใส่ * หน้า receiver:  func (l ValRecv) UnmarshalText(...)
$ go vet ./...      # เงียบ
$ V_VAR=warn go run .
V=main.ValRecv{v:""} err=<nil>      // ← ค่าหายไปเฉย ๆ ไม่มี error

D=0s (time.Duration)
LOC=UTC (*time.Location)          # ← ตัวนี้ไม่เป็น nil!
UP=<nil> (*url.URL)
PI=<nil>
SL=[]string(nil)
M=map[string]int(nil)
Lvl=main.LogLevel{v:""} LvlP=<nil>
T=0001-01-01 00:00:00 +0000 UTC (time.Time)

zero dependency — ผมไปตรวจมาแล้ว และมันจริงยิ่งกว่าที่สไลด์บอก

กล่องเขียวล่างสุดของสไลด์หน้า 9 เขียนว่า "zero dependency — ไลบรารีนี้ไม่พึ่ง package นอกเลยสักตัว"
วิธีตรวจคือเปิด go.mod ของมันดูว่ามีบล็อก require ไหม:

$ cat ~/go/pkg/mod/github.com/caarlos0/env/v11@v11.4.1/go.mod
module github.com/caarlos0/env/v11

// v11.0.1 accidentally introduced a breaking change regarding the behavior of nil pointers.
// You can now chose to auto-initialize them by setting the `init` tag option.
retract v11.0.1

// v11.2.0 accidentally introduced a breaking change regarding the behavior of nil slices of complex types.
retract v11.2.0

// v11.3.0 merges OS environment variables with environments set with Options instead of overriding them.
retract v11.3.0

go 1.18

$ wc -c ~/go/pkg/mod/github.com/caarlos0/env/v11@v11.4.1/go.sum
       0 /Users/tuwanon/go/pkg/mod/github.com/caarlos0/env/v11@v11.4.1/go.sum
# ได้ 0 byte — ไฟล์ว่างเปล่า ไม่มี checksum ของ dependency ให้เก็บเลย
# (path หลังเลข 0 คือ path ของเครื่องผม ของคุณจะเป็นชื่อ user ตัวเอง)

ไม่มีบรรทัด require แม้แต่บรรทัดเดียว และ go.sum ขนาด 0 byte
ที่แรงกว่านั้น: ผมเปิด env_test.go (ไฟล์ test ขนาด 62KB) ดู import ทั้งหมด — มีแค่ encoding/base64, encoding/json, errors, fmt, net/http, net/url, os, path/filepath, reflect, runtime, strconv, strings, testing, time — standard library ล้วน ไม่มีแม้แต่ testify

7 · แปลง type ไม่ได้ — error หน้าตาเป็นยังไง

type Config struct {
	AppPort         int           `env:"APP_PORT" envDefault:"8080"`
	ShutdownTimeout time.Duration `env:"APP_SHUTDOWN_TIMEOUT" envDefault:"10s"`
	LogLevel        string        `env:"LOG_LEVEL" envDefault:"DEBUG"`
	PostgresDSN     string        `env:"POSTGRES_DSN"`
}

// แล้วรัน:  APP_PORT=abc go run .

$ APP_PORT=abc go run .
cfg=main.Config{AppPort:0, ShutdownTimeout:10000000000, LogLevel:"DEBUG", PostgresDSN:""}
err=env: parse error on field "AppPort" of type "int": strconv.ParseInt: parsing "abc": invalid syntax

$ go run .        // net.Listen("tcp", ":0")
listening on [::]:59055      // ← ระบบแจกพอร์ตสุ่มให้ ไม่มี error สักตัว

อีกเคสที่มือใหม่พลาดบ่อยมาก — ลืมใส่หน่วยให้ time.Duration:

$ APP_SHUTDOWN_TIMEOUT=10 go run .
cfg=main.Config{AppPort:8080, ShutdownTimeout:0, LogLevel:"DEBUG", PostgresDSN:""}
err=env: parse error on field "ShutdownTimeout" of type "time.Duration": unable to parse duration: time: missing unit in duration "10"

เขียน 10 คิดว่าเป็น "10 วินาที" — ต้องเขียน 10s
สังเกตว่าข้อความ error ก้อนนี้ห่อกันสามชั้น: env: (ของ library) → parse error on field "ShutdownTimeout" (ชื่อ field ที่พัง) → time: missing unit (ข้อความจาก time.ParseDuration ของ standard library ซึ่งเป็นตัวเดียวกับที่บทเรียน 44 เจอ)
ทั้งสามชั้นบอกคนละอย่างที่จำเป็นทั้งหมด: ใครฟ้อง · field ไหน · เพราะอะไร

ผิดหลายจุดพร้อมกัน — env.AggregateError

ถ้าเขียนเองด้วย os.Getenv แบบหัวข้อ 1 พอเจอ error แรกก็ return ทันที คุณจะแก้ทีละตัว รันใหม่ทีละรอบ
caarlos0/env ทำคนละแบบ — ผมทดสอบด้วย struct ที่ผิดพร้อมกันสามจุด:

type Multi struct {
	A string `env:"M_A,required"`   // ไม่ตั้ง
	B string `env:"M_B,required"`   // ไม่ตั้ง
	C int    `env:"M_C"`            // ตั้งเป็น notanint
}

$ M_C=notanint go run .
[multi errors] err=env: required environment variable "M_A" is not set; required environment variable "M_B" is not set; parse error on field "C" of type "int": strconv.ParseInt: parsing "notanint": invalid syntax

    type=env.AggregateError
    inner[0] env.VarIsNotSetError: required environment variable "M_A" is not set
    inner[1] env.VarIsNotSetError: required environment variable "M_B" is not set
    inner[2] env.ParseError: parse error on field "C" of type "int": strconv.ParseInt: parsing "notanint": invalid syntax

8 · สรุปสิ่งที่บทนี้ปิดไป และสิ่งที่ยังค้าง

ทดสอบความเข้าใจ

# ไม่ตั้งเลย
err=env: required environment variable "MYVAR2" is not set
    → ข้างในเป็น env.VarIsNotSetError

# ตั้งเป็นค่าว่าง — MYVAR2= go run .
err=<nil>          # ผ่าน! นี่คือช่องโหว่

err=env: environment variable "NE_VAR" should not be empty
    → ข้างในเป็น env.EmptyVarError

อ้างอิง

• github.com/caarlos0/env — README ตัวจริง · อ่านหัวข้อ "Caveats" ให้ครบ เพราะมันลิสต์พฤติกรรมที่คนคาดไม่ถึงไว้หลายข้อ
• pkg.go.dev — caarlos0/env/v11 — ดูรายชื่อ error type ให้ครบ — ในซอร์ส v11.4.1 มีชื่อที่ลงท้ายด้วย Error ทั้งหมด 11 ชื่อ สี่ตัวที่เจอบ่อยคือ (VarIsNotSetError, EmptyVarError, ParseError, LoadFileContentError) และ AggregateError ที่ห่อทั้งหมดไว้
• pkg.go.dev — encoding.TextUnmarshaler — interface เมธอดเดียวที่ทำให้ type ของคุณเข้ากับ library นี้ได้ (และกับ encoding/json ด้วย)
• pkg.go.dev — time.ParseDuration — ตัวที่ทำงานอยู่เบื้องหลัง time.Duration field · ไม่มีหน่วย d สำหรับวัน อยากได้ 1 วันต้องเขียน 24h
• pkg.go.dev — reflect — กลไกที่ library ใช้ส่อง struct tag ตอนรัน · อ่านเพื่อเข้าใจว่าทำไม tag ที่พิมพ์ผิดถึงเงียบสนิท
• Go Modules Reference — retract — คำสั่งที่เจอใน go.mod ของ library นี้สามบรรทัด อธิบายว่าผู้เขียนถอนเวอร์ชันที่มีปัญหายังไง
• บทเรียน 44 — Configuration & Environment Variables — โจทย์ทั้งหมดที่บทนี้มาตอบ · ถ้ายังไม่ชัดว่า "ค่าว่าง" กับ "ไม่ได้ตั้ง" ต่างกันยังไง ให้กลับไปอ่านหัวข้อ 4 ของบทนั้นก่อน
• The Twelve-Factor App — III. Config — ต้นทางของแนวคิด "config อยู่ใน environment"