Config · .env · Validate · JWT · OAuth · Keycloak — แผ่นเดียวจบ

go version go1.26.5 darwin/arm64

github.com/caarlos0/env/v11             v11.4.1
github.com/joho/godotenv                v1.5.1
github.com/go-playground/validator/v10  v10.30.3
github.com/golang-jwt/jwt/v5            v5.3.1
golang.org/x/oauth2                     v0.36.0
github.com/coreos/go-oidc/v3            v3.20.0
gorm.io/gorm                            v1.31.2
gorm.io/driver/postgres                 v1.6.2
goose                                   v3.27.3
quay.io/keycloak/keycloak:26.7          # tag นี้ชี้ไปที่ 26.7.2
postgres:16-alpine                      # PostgreSQL 16.15 บน colima

สารบัญ

1. เวอร์ชันที่ทุกอย่างในหน้านี้รันผ่าน
2. caarlos0/env — struct tag · option · type ที่รองรับ
3. caarlos0/env — กับดัก
4. godotenv — autoload vs Load vs Overload
5. .env — รูปแบบไฟล์ + .gitignore
6. validator/v10 — tag · error จริง · errors.Join · Humanize
7. โครง internal/config ที่ก็อปไปใช้ได้
8. ท่อลำเลียงค่าทั้งเส้น
9. JWT — โครงสร้าง · golang-jwt/v5 · error ทุกเคส
10. OAuth 2.0 — ตัวละคร 4 ตัว + Authorization Code Grant
11. Keycloak — compose · endpoint · components
12. flow /login /callback /exchange /logout
13. goose + ตาราง users
14. ตารางกับดักรวมทั้งวัน
15. ตารางแปล error / panic ที่เจอบ่อย

1 · เวอร์ชันที่ทุกอย่างในหน้านี้รันผ่าน

$ cat $(go env GOMODCACHE)/github.com/caarlos0/env/v11@v11.4.1/go.mod
module github.com/caarlos0/env/v11
// (มีแต่ retract 3 บรรทัด กับ go 1.18 — ไม่มี require เลยสักบรรทัด)
go 1.18

$ ls -l .../env/v11@v11.4.1/go.sum
--- go.sum: 0B (ไฟล์ว่างเปล่า) ---

2 · caarlos0/env — struct tag · option · type ที่รองรับ

โครงพื้นฐาน

import "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"`
}

cfg, err := env.ParseAs[Config]()

--- run 1: no env set (defaults) ---
cfg=main.Config{AppPort:8080, ShutdownTimeout:10000000000, LogLevel:"DEBUG", PostgresDSN:""}
err=<nil>
AppPort type=int value=8080
ShutdownTimeout type=time.Duration value=10s ms=10000
--- run 2: env set ---
cfg=main.Config{AppPort:9999, ShutdownTimeout:90000000000, LogLevel:"INFO", PostgresDSN:"postgres://u:p@localhost:5432/db"}
err=<nil>
AppPort type=int value=9999
ShutdownTimeout type=time.Duration value=1m30s ms=90000

PostgresDSN ไม่มี envDefault และไม่ได้ตั้ง env → ได้ "" เงียบ ๆ ไม่ error เพราะไม่ได้ใส่ ,required

struct tag ทั้ง 4 ตัว

$ 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 ใช้ได้กับ slice ของ type อื่นด้วย ไม่ใช่แค่ []string (ทดสอบ []int ผ่าน) · และ envDefault ก็ถูก split ด้วย separator เดียวกัน (SepDefault มาจาก envDefault:"a,b,c" ทั้งที่ไม่ได้ตั้ง env TAGS เลย)

$ 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>

NoPfx เป็น struct ซ้อนที่ไม่ได้ใส่ envPrefix — มันอ่าน HOST เปล่า ๆ · มีหลาย struct ซ้อนแล้วลืมใส่ prefix เมื่อไหร่ ทั้งคู่จะไปแย่ง key เดียวกัน

option ท้าย tag — เขียนต่อหลังชื่อ key คั่นด้วย ,

// ,unset — ค่าเข้า struct ครบ แต่หลังจากนั้น env หายไปจริง
[unset] parsed="temp-value" err=<nil> ; after parse LookupEnv -> value="" exists=false

,unset เหมาะกับ secret ที่ไม่อยากให้ process ลูกเห็นต่อ — โปรแกรมเราอ่านไปแล้ว ใครที่ fork ต่อจากเราจะไม่เห็นอีก

$ # ไฟล์มีเนื้อว่า "s3cr3t-from-file\n"
[file ok] value="s3cr3t-from-file\n" err=<nil>

type ที่รองรับ — รันครบทุกตัวแล้ว

$ I8=-12 I64=9223372036854775807 U16=65535 U64=18446744073709551615 F32=3.14 F64=2.718281828 \
  B=true S=hello D=1h30m LOC=Asia/Bangkok U="https://api.example.com:8443/v1/users?q=1" \
  UP="postgres://user@db:5432/app" PI=42 PS=ptrval SL="a,b,c" SLD="1s,2m,3h" \
  M="a:1,b:2" MS="k1:v1,k2:v2" LVL=info LVLP=warn T="2026-08-22T10:30:00Z" go run .

I8=-12 I64=9223372036854775807 U16=65535 U64=18446744073709551615
F32=3.14 F64=2.718281828 B=true S="hello"
D=1h30m0s (time.Duration)
LOC=Asia/Bangkok (*time.Location)
U=url.URL{Scheme:"https", Opaque:"", User:(*url.Userinfo)(nil), Host:"api.example.com:8443",
  Path:"/v1/users", Fragment:"", RawQuery:"q=1", RawPath:"", RawFragment:"",
  ForceQuery:false, OmitHost:false}
UP=postgres://user@db:5432/app (*url.URL)
PI=0x5de58d7140d0 deref=42
PS deref="ptrval"
SL=[]string{"a", "b", "c"}
SLD=[]time.Duration{1000000000, 120000000000, 10800000000000}
M=map[string]int{"a":1, "b":2}
MS=map[string]string{"k1":"v1", "k2":"v2"}
Lvl=main.LogLevel{v:"INFO"} LvlP=&{WARN}
T=2026-08-22 10:30:00 +0000 UTC (time.Time)

time.Time ใช้ได้ทั้งที่ README ไม่ได้ list ไว้ — เพราะมันเป็น encoding.TextUnmarshaler อยู่แล้ว · นี่คือเหตุผลว่าทำไม TextUnmarshaler สำคัญ: เขียนเมธอดเดียวแล้ว type ของเราใช้กับ env ได้ทันที

// custom type ที่คืน error → env ห่อให้เป็น parse error
$ LVL=verbose go run .
ERR: env: parse error on field "Lvl" of type "main.LogLevel": unknown log level "VERBOSE"

D=0s (time.Duration)
LOC=UTC (*time.Location)          ← ไม่ใช่ nil!
UP=<nil> (*url.URL)
PI=nil
PS=nil
SL=[]string(nil)
M=map[string]int(nil)             ← nil map: เขียนลงไปจะ panic
T=0001-01-01 00:00:00 +0000 UTC (time.Time)

3 · caarlos0/env — กับดัก

① ,required คู่กับ envDefault = required ไม่มีผลเลย

type A struct { Both        string `env:"MYVAR,required" envDefault:"fallback"` }
type B struct { OnlyRequired string `env:"MYVAR2,required"` }

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

A มี required แต่ได้ default ไปเงียบ ๆ err=<nil> · B ที่มี required เปล่า ๆ error ตามคาด · เหตุผลอยู่ในซอร์ส env.go ฟังก์ชัน getOr (env.go:648-660 ของ v11.4.1):

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   // ← บรรทัด 651-652 · คืน exists=true
	case exists && value == "" && defExists:
		return defaultValue, true, true   // ← ตั้งเป็นค่าว่างก็ยังได้ default

พอ exists เป็น true เสมอเมื่อมี envDefault เงื่อนไขที่ env.go:613

if fieldParams.Required && !exists && fieldParams.OwnKey != "" {

ก็ไม่มีวันเป็นจริง

② ,notEmpty คู่กับ envDefault ก็โดนกลบเหมือนกันเป๊ะ

type C struct { BothNotEmpty string `env:"MYVAR3,notEmpty" envDefault:"fallback3"` }

=== ไม่ตั้ง env เลย ===
[C notEmpty+envDefault] value="fallback3" err=<nil>
=== ตั้ง MYVAR3 ว่าง (MYVAR3=) ===
[C notEmpty+envDefault] value="fallback3" err=<nil>

ตั้งเป็นค่าว่างก็ยังได้ default (มี case exists && value == "" && defExists ใน getOr อีกอัน) · กฎที่จำง่ายที่สุด: ใส่ envDefault เมื่อไหร่ required และ notEmpty ตายทันที

$ MYVAR2= go run .            # ตั้งเป็นสตริงว่าง
[B required only]       value="" err=<nil>

③ แปลง type ไม่ได้ — struct ไม่ได้ว่างทั้งก้อน

$ APP_PORT=abc go run t1.go
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
AppPort type=int value=0
ShutdownTimeout type=time.Duration value=10s ms=10000

สังเกตให้ดี: field ที่พังได้ zero value ส่วน field อื่นถูกเติมครบตามปกติ (ShutdownTimeout=10s, LogLevel=DEBUG) · ใครลืมเช็ค err จะได้ AppPort=0 ไปใช้ต่อ แล้ว server จะ bind พอร์ตสุ่ม

④ time.Duration ที่ลืมใส่หน่วย

$ APP_SHUTDOWN_TIMEOUT=10 go run t1.go
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 คิดว่าเป็นวินาที — ต้องเขียน 10s · มือใหม่พลาดตรงนี้บ่อยที่สุดในบทนี้

⑤ error หลายจุดพร้อมกัน — env.AggregateError ไม่ fail fast

$ M_C=notanint go run .     # struct มี M_A,required · M_B,required · M_C int
[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

4 · godotenv — autoload vs Load vs Overload

วิธีที่ 1 — autoload (สั้นที่สุด)

import _ "github.com/joho/godotenv/autoload"
// จบ — ไม่ต้องเรียกอะไรอีกเลย os.Getenv ได้ค่าจาก .env ทันที

--- run 1: autoload, no shell env ---
APP_NAME="from-dotenv"
PORT="9999"

ทั้ง package autoload มีแค่ 15 บรรทัด และส่วนที่ทำงานจริงคือ:

import "github.com/joho/godotenv"

func init() {
	godotenv.Load()
}

ไม่รับค่า error กลับมาเลย — ทิ้งทั้งดุ้น · จำบรรทัดนี้ไว้ เดี๋ยวจะได้เห็นราคาของมัน

// พิสูจน์ว่าค่ามาถึงก่อน main จริง (ไม่ใช่แค่อ่านซอร์สเดา)
1) package-level var init: GOOD=set-by-dotenv
2) main package init(): GOOD = set-by-dotenv
3) main(): GOOD = set-by-dotenv

ค่ามาแล้วตั้งแต่ตอน package-level var init ซึ่งเกิดก่อนทุกอย่างของ main

วิธีที่ 2 — เรียก godotenv.Load() เอง

func main() {
	if err := godotenv.Load(); err != nil {
		slog.Debug("no .env file", "err", err)
	}
	cfg, err := env.ParseAs[Config]()
	// ...
}

=== with .env ===
after Load, raw os.Getenv PORT="8081"
ParseAs err=<nil> cfg={AppName:svc-from-dotenv Port:8081}

Load vs Overload

$ APP_NAME=from-shell go run . load
before: APP_NAME="from-shell"
err=<nil>
after(load): APP_NAME="from-shell"          ← shell ชนะ

$ APP_NAME=from-shell go run . overload
before: APP_NAME="from-shell"
err=<nil>
after(overload): APP_NAME="from-dotenv"     ← .env ชนะ

ซอร์สเขียนไว้ตรง ๆ — godotenv.go:50 ว่า “It's important to note that it WILL NOT OVERRIDE an env variable that already exists” ส่วน godotenv.go:73 ว่า “this WILL OVERRIDE an env variable that already exists”

ไม่มีไฟล์ .env เลย

$ # วิธีที่ 2 — จับ error ได้
err (%v)   = open .env: no such file or directory
err type   = *fs.PathError
os.ErrNotExist? = true
program still running, did not panic
exit code: 0

อยากแยก “ไม่มีไฟล์” (ปกติบน prod) ออกจาก “ไฟล์พัง” (ต้องดัง) ใช้ errors.Is(err, os.ErrNotExist) ได้เลย ดีกว่า slog.Debug เฉย ๆ

ใครทำอะไร — godotenv vs caarlos0/env

5 · .env — รูปแบบไฟล์ที่รองรับ + สิ่งที่ต้องใส่ .gitignore

# d2.env
BCD=SURPRISE
P1="a$BCD"        → "aSURPRISE"   ถูกแทนค่า
P3="p@ss$W0RD"    → "p@ss"       $W0RD ไม่มีค่า จึงถูกแทนด้วยค่าว่าง
P4="a${BCD}x"     → "aSURPRISEx"

# dollar.env — ชื่อพิมพ์เล็ก ไม่โดนอะไรเลย
bcd=SURPRISE
PASS="a$bcd"      → "a$bcd"      รอด เพราะ bcd เป็นตัวพิมพ์เล็ก

ไฟล์ .env พัง — เกิดอะไรขึ้น

# bad1.env
GOOD=1
this line has no equals sign
AFTER=2

  err  = unexpected character "\n" in variable name near "this line has no equals sign\nAFTER=2\n"
  Load err = unexpected character "\n" in variable name near "this line has no equals sign\nAFTER=2\n"
  GOOD after Load = ""
  AFTER after Load = ""

# bad3.env — quote ไม่ปิด
GOOD=1
UNCLOSED="oops
AFTER=2

  err  = unterminated quoted value "oops
  Load err = unterminated quoted value "oops
  GOOD after Load = ""
  AFTER after Load = ""

=== bad2.env ===        # มีบรรทัด 123INVALID=x
  err  = <nil>
  123INVALID => "x"
=== bad4.env ===        # มีบรรทัด =novalue (ไม่มีชื่อ key)
  err  = <nil>
   => "novalue"
  GOOD after Load = "1"

ราคาของ autoload ที่ต้องรู้

$ # .env พัง (บรรทัดไม่มี =) + import _ autoload อย่างเดียว
main package init() runs; GOOD =
main(): GOOD="" AFTER=""
no error was ever surfaced
exit code: 0

.env ถูกหาจาก current working directory ไม่ใช่ที่ตั้งของ binary

=== run binary from project root (where .env lives) ===
cwd=/var/folders/.../p8       WHERE="root-dotenv"
=== run same binary from sub/ (no .env there) ===
cwd=/var/folders/.../p8/sub   WHERE=""

binary ตัวเดียวกันเป๊ะ ผลต่างกันเพราะ cwd ต่างกัน · ยืนยันจากซอร์ส godotenv.go:179 ที่ return []string{".env"} ซึ่งเป็น path สัมพัทธ์ · จุดนี้กัดคนตอนขึ้น Docker / systemd บ่อยมาก

สิ่งที่ต้องใส่ .gitignore

# .gitignore
.env
.env.*
!.env.example

# .env.example — ก็อปเป็น .env แล้วเติมค่าจริงเอง
APP_NAME=wongnok
APP_ENV=development
APP_PORT=8080
APP_SHUTDOWN_TIMEOUT=10s
LOG_LEVEL=info
LOG_FORMAT=json
POSTGRES_DSN=postgres://user:pass@localhost:5432/wongnok?sslmode=disable

6 · validator/v10 — tag · error จริง · errors.Join · Humanize

import "github.com/go-playground/validator/v10"

// ตัวเดียวทั้ง package — validator แคชข้อมูล struct ไว้ข้างใน
var validate = validator.New(validator.WithRequiredStructEnabled())

err := validate.Struct(cfg)

tag ที่ใช้บ่อย

ข้อความ error จริง — คืนครบทุก field พร้อมกัน

=== err.Error() ===
Key: 'App.Name' Error:Field validation for 'Name' failed on the 'required' tag
Key: 'App.Port' Error:Field validation for 'Port' failed on the 'lte' tag
Key: 'App.Env' Error:Field validation for 'Env' failed on the 'oneof' tag
Key: 'App.Host' Error:Field validation for 'Host' failed on the 'hostname|ip' tag
Key: 'App.Timeout' Error:Field validation for 'Timeout' failed on the 'gte' tag
=== count ===
len: 5

รูปแบบเป๊ะทุกช่องว่าง — มีช่องว่างหลัง Key: แต่ไม่มีหลัง Error: · ห้าบรรทัดนี้คั่นด้วย \n ที่ ValidationErrors.Error() ใส่ให้เอง ไม่ได้มาจาก errors.Join

oneof กับ hostname|ip — ผลจริงทีละค่า

---- oneofci=Dev Staging PROD ----
oneofci "dev"    -> <nil>
oneofci "DEV"    -> <nil>
oneofci "prod"   -> <nil>
oneofci "PrOd"   -> <nil>
oneofci "qa"     -> Key: 'C.Env' Error:Field validation for 'Env' failed on the 'oneofci' tag

hostname|ip "localhost"          -> <nil>
hostname|ip "api.example.com"    -> <nil>
hostname|ip "127.0.0.1"          -> <nil>
hostname|ip "::1"                -> <nil>
hostname|ip "192.168.1.300"      -> Key: 'H.Host' Error:Field validation for 'Host' failed on the 'hostname|ip' tag
hostname|ip "not a host!"        -> Key: 'H.Host' Error:Field validation for 'Host' failed on the 'hostname|ip' tag
hostname|ip ""                   -> Key: 'H.Host' Error:Field validation for 'Host' failed on the 'hostname|ip' tag
hostname|ip "db_server"          -> Key: 'H.Host' Error:Field validation for 'Host' failed on the 'hostname|ip' tag
hostname|ip "example.com:5432"   -> Key: 'H.Host' Error:Field validation for 'Host' failed on the 'hostname|ip' tag

// Env string `validate:"oneof=dev,staging,prod"`   ← ผิด
before Struct()
panic: Undefined validation function 'staging' on field 'Env'

goroutine 1 [running]:
github.com/go-playground/validator/v10.(*Validate).parseFieldTagsRecursive(...)
	.../validator/v10@v10.30.3/cache.go:311 +0x9e4
github.com/go-playground/validator/v10.(*Validate).extractStructCache(...)
	.../cache.go:156 +0x454
github.com/go-playground/validator/v10.(*Validate).Struct(...)
	.../validator_instance.go:347
exit status 2

--- gte=1 (ไม่มีหน่วย) ---
gte=1 with 1ns  -> <nil>
gte=1 with 0    -> Key: 'A.T' Error:Field validation for 'T' failed on the 'gte' tag
gte=1 with 500ms-> <nil>          ← ผ่านฉลุย

--- gte=1s,lte=30s (มีหน่วย) ---
0s     -> Key: 'B.T' Error:Field validation for 'T' failed on the 'gte' tag
1s     -> <nil>
15s    -> <nil>
31s    -> Key: 'B.T' Error:Field validation for 'T' failed on the 'lte' tag

WithRequiredStructEnabled() ต่างยังไง

--- nested struct (ไม่ใช่ pointer) ---
plain  / zero nested struct  -> <nil>
opt    / zero nested struct  -> Key: 'Cfg.DB' Error:Field validation for 'DB' failed on the 'required' tag
plain  / filled nested       -> <nil>
opt    / filled nested       -> <nil>
--- pointer nested, nil ---
plain -> Key: 'Cfg2.DB' Error:Field validation for 'DB' failed on the 'required' tag
opt   -> Key: 'Cfg2.DB' Error:Field validation for 'DB' failed on the 'required' tag

ต่างกันจุดเดียวเป๊ะ: required บน nested struct ที่ไม่ใช่ pointer · ไม่ใส่ option = tag นั้นถูกเมิน · ใส่ option = zero struct ตก · ส่วน *DB (pointer) ไม่เกี่ยว ตกทั้งสองแบบอยู่แล้ว · doc comment ในซอร์สเขียนว่า “WithRequiredStructEnabled enables required tag on non-pointer structs to be applied instead of ignored.”

แกะ error ทีละ field

var ve validator.ValidationErrors
if errors.As(err, &ve) {
	for _, fe := range ve {
		fmt.Println(fe.Namespace(), fe.Field(), fe.Tag(), fe.Param(), fe.Value())
	}
}

errors.As -> true len: 4
Namespace="Cfg.Name"    Field="Name"    Tag="required" Param=""      Kind=string Type=string        Value=""
Namespace="Cfg.Env"     Field="Env"     Tag="oneof"    Param="dev prod" Kind=string Type=string     Value="qa"
Namespace="Cfg.Timeout" Field="Timeout" Tag="gte"      Param="1s"    Kind=int64  Type=time.Duration Value=100000000
Namespace="Cfg.DB.Port" Field="Port"    Tag="lte"      Param="65535" Kind=int    Type=int           Value=99999

// รันจริง — validator v10.30.3 + go1.26.5 · fe.Value() ของ field Timeout
dynamic type = time.Duration
%v     -> 100ms
%s     -> 100ms
Sprint -> 100ms
%#v    -> 100000000
%d     -> 100000000

errors.Join — คั่นด้วยอะไรกันแน่

Error() = "alpha\nbeta\ngamma"
contains \n: 16
errors.Is(j,b) -> true
Unwrap() []error len: 3
errors.Join with nils: true true

// ยัด ValidationErrors เข้า Join แล้วยังดึงกลับมาได้
errors.As through Join -> true 4
jv.Error() = "config load failed\nKey: 'Cfg.Name' Error:Field validation for 'Name' failed on the 'required' tag\nKey: 'Cfg.Env' Error:...

Humanize — แปลง error ก้อนใหญ่ให้คนอ่านรู้เรื่อง

// internal/config/humanize.go
func Humanize(err error) string {
	var joined interface{ Unwrap() []error }
	errs := []error{err}
	if errors.As(err, &joined) {
		errs = joined.Unwrap()
	}

	lines := []string{"invalid configuration:"}
	for _, e := range errs {
		var ve validator.ValidationErrors
		if errors.As(e, &ve) {
			for _, fe := range ve {
				lines = append(lines, fmt.Sprintf("  - %s: ผิดกฎ %q", fe.Namespace(), fe.Tag()))
			}
			continue
		}
		lines = append(lines, "  - "+e.Error())
	}
	return strings.Join(lines, "\n")
}

$ env APP_PORT=99999 LOG_LEVEL=BANANA POSTGRES_DSN= go run ./cmd/api
FATAL load configuration:
invalid configuration:
  - App.Port: ผิดกฎ "lte"
  - Logging.Level: ผิดกฎ "oneofci"
  - Database.PostgresDSN: ผิดกฎ "required"
exit status 1

ลำดับบรรทัดคาดเดาได้เสมอ — errors.Join เรียงตามลำดับที่เราใส่ (App → Logging → Database) และในแต่ละ struct เรียงตามลำดับ field

$ env APP_PORT=abc ./api
time=2026-08-22T10:15:12.112+07:00 level=ERROR msg="load configuration"
invalid configuration:
  - parse error on field "Port" of type "int": strconv.ParseInt: parsing "abc": invalid syntax

BenchmarkSingleton-10      	 8658763	       120.6 ns/op	      48 B/op	       1 allocs/op
BenchmarkNewEachTime-10    	  140612	      8638 ns/op	   16229 B/op	     224 allocs/op
// Apple M4, go1.26.5

7 · โครง internal/config ที่ก็อปไปใช้ได้

config.go

package config

import (
	"errors"
	"fmt"

	"github.com/caarlos0/env/v11"
	"github.com/go-playground/validator/v10"
)

// ใช้ตัวเดียวทั้ง package — validator แคชข้อมูล struct ไว้ข้างใน
var validate = validator.New(validator.WithRequiredStructEnabled())

type Config struct {
	App      App
	Logging  Logging
	Database Database
}

func Load() (Config, error) {
	cfg, err := env.ParseAs[Config]()
	if err != nil {
		return Config{}, fmt.Errorf("parse environment: %w", err)
	}

	// ไม่ wrap ด้วย fmt.Errorf — errors.Join จัดบรรทัดไว้แล้ว
	if err := cfg.Validate(); err != nil {
		return Config{}, err
	}

	return cfg, nil
}

// รวม error ของ "ทุก section" มาแสดงทีเดียว
// เพิ่ม Redis? สร้าง redis.go + เติม 1 บรรทัดตรงนี้
func (cfg Config) Validate() error {
	return errors.Join(
		cfg.App.Validate(),
		cfg.Logging.Validate(),
		cfg.Database.Validate(),
	)
}

$ go build ./...
internal/config/app.go:1:1: expected 'package', found 'type'

# เติม package config แล้วยังไม่พอ
$ go build ./...
internal/config/app.go:7:18: undefined: time
internal/config/app.go:10:45: undefined: fmt

app.go

type App struct {
	Name            string        `env:"APP_NAME" envDefault:"wongnok" validate:"required"`
	Env             string        `env:"APP_ENV" envDefault:"development" validate:"required,oneof=development staging production"`
	Port            int           `env:"APP_PORT" envDefault:"8080" validate:"gte=1,lte=65535"`
	ShutdownTimeout time.Duration `env:"APP_SHUTDOWN_TIMEOUT" envDefault:"10s" validate:"required"`
}

func (app App) Addr() string       { return fmt.Sprintf(":%d", app.Port) }
func (app App) IsProduction() bool { return app.Env == "production" }

func (app App) Validate() error { return validate.Struct(app) }

logging.go

type Logging struct {
	Level  string `env:"LOG_LEVEL" envDefault:"info" validate:"required,oneofci=debug info warn error"`
	Format string `env:"LOG_FORMAT" envDefault:"json" validate:"required,oneofci=json text"`
}

func (logging Logging) Validate() error { return validate.Struct(logging) }

Level ต้องใช้ oneofci ไม่ใช่ oneof — ไม่งั้น tag ที่โผล่ใน error จะเป็น 'oneof' แล้วข้อความจะไม่ตรงกับที่หัวข้อ 6 โชว์ไว้

database.go

type Database struct {
	PostgresDSN     string        `env:"POSTGRES_DSN" validate:"required"`
	MaxOpenConns    int           `env:"DB_MAX_OPEN_CONNS" envDefault:"25" validate:"gte=1,lte=500"`
	MaxIdleConns    int           `env:"DB_MAX_IDLE_CONNS" envDefault:"25" validate:"gte=1,lte=500"`
	ConnMaxLifetime time.Duration `env:"DB_CONN_MAX_LIFETIME" envDefault:"5m" validate:"required,gt=0"`
}

func (database Database) Validate() error { return validate.Struct(database) }

if database.ConnMaxLifetime <= 0 {
	return errors.New("DB_CONN_MAX_LIFETIME must be greater than 0")
}

########## [ก่อน refactor] DB_CONN_MAX_LIFETIME=-5s
Validate : FAILED ->
DB_CONN_MAX_LIFETIME must be greater than 0
########## [หลัง refactor] DB_CONN_MAX_LIFETIME=-5s
Validate : OK                              ← ค่าติดลบผ่านฉลุย

config_test.go — เทสต์ config โดยไม่ต้องมี .env

func TestLoad_Defaults(t *testing.T) {
	t.Setenv("POSTGRES_DSN", "postgres://u:p@localhost:5432/db")
	// t.Setenv คืนค่า env เดิมให้อัตโนมัติเมื่อจบเทสต์
	cfg, err := config.Load()
	// ...
}

$ go test ./internal/config/ -v
=== RUN   TestLoad_Defaults
--- PASS: TestLoad_Defaults (0.00s)
=== RUN   TestLoad_ThreeErrorsAtOnce
--- PASS: TestLoad_ThreeErrorsAtOnce (0.00s)
=== RUN   TestLoad_ReturnsZeroValueOnError
--- PASS: TestLoad_ReturnsZeroValueOnError (0.00s)
PASS
ok  	wongnok/api/internal/config	0.572s

ทำไม Load() คืน Config ไม่ใช่ *Config

sizeof(config.Config) = 120 bytes
sizeof(*config.Config) = 8 bytes
[value ] err != nil? true | cfgVal.App.Port = 0 | cfgVal.App.Addr() = ":0"
[ptr   ] err != nil? true | cfgPtr == nil? true
[ptr   ] panic ตอนอ่าน cfgPtr.App.Port: runtime error: invalid memory address or nil pointer dereference

ก่อนเรียก              : Port=8080 Addr=":8080"
หลัง handlerA(value)   : Port=8080 Addr=":8080"
หลัง handlerB(pointer) : Port=1 Addr=":1"  <-- validate ผ่านไปแล้ว แต่ค่าเปลี่ยนได้

Load() ถูกเรียกครั้งเดียวตอน start — 120 bytes ไม่ใช่เรื่อง · เหตุผลที่หนักแน่นกว่าคือแถวกลาง: ค่าที่ผ่าน validate แล้วต้อง valid ตลอดอายุโปรแกรม

8 · ท่อลำเลียงค่าทั้งเส้น

พิสูจน์ว่าด่าน 2 ปล่อยผ่านจริง แล้วด่าน 3 รับช่วง

$ env POSTGRES_DSN="postgres://u:p@localhost:5432/db" APP_PORT=99999 go run ./cmd/probe
ParseAs  : OK -> App.Port=99999 App.Env="development" Log.Level="info" Shutdown=10s DSN="postgres://u:p@localhost:5432/db"
Validate : FAILED ->
Key: 'App.Port' Error:Field validation for 'Port' failed on the 'lte' tag

$ env POSTGRES_DSN= go run ./cmd/probe
ParseAs  : OK -> App.Port=8080 ... DSN=""
Validate : FAILED ->
Key: 'Database.PostgresDSN' Error:Field validation for 'PostgresDSN' failed on the 'required' tag

$ env POSTGRES_DSN="..." APP_ENV=prodction go run ./cmd/probe
ParseAs  : OK -> App.Env="prodction" ...
Validate : FAILED ->
Key: 'App.Env' Error:Field validation for 'Env' failed on the 'oneof' tag

$ env POSTGRES_DSN="..." LOG_LEVEL=BANANA go run ./cmd/probe
ParseAs  : OK -> Log.Level="BANANA" ...
Validate : FAILED ->
Key: 'Logging.Level' Error:Field validation for 'Level' failed on the 'oneofci' tag

$ env POSTGRES_DSN="..." APP_SHUTDOWN_TIMEOUT=0s go run ./cmd/probe
ParseAs  : OK -> Shutdown=0s ...
Validate : FAILED ->
Key: 'App.ShutdownTimeout' Error:Field validation for 'ShutdownTimeout' failed on the 'required' tag

ห้าเคสนี้ ParseAs ผ่านหมด — พิมพ์ prodction ตกตัว u ก็ยังเป็น string ที่ถูกต้องในสายตา env · ตัวที่จับได้คือ validator ล้วน ๆ

ตายตั้งแต่ start ไม่ใช่ตอน request แรก

$ env APP_PORT=99999 LOG_LEVEL=BANANA POSTGRES_DSN= ./api & sleep 2
--- ps เช็คว่า process ยังอยู่ไหม ---
process ตายไปแล้ว
--- lsof :8080 ---
(ไม่มี process ไหน listen :8080)
--- curl /healthz ---
http_code=000
curl exit=7
EXIT_CODE=1

พิสูจน์ครบสามชั้น: process ตาย · ไม่มีอะไร bind :8080 · curl ต่อไม่ติด (exit 7 = Failed to connect) · exit code จริงคือ 1

$ # config ถูกต้อง — เดินจนสุดสาย
--- curl /healthz ---
ok
http_code=200
--- stderr ของ server ---
{"time":"2026-08-22T10:13:43.048067+07:00","level":"INFO","msg":"configuration loaded","app":"wongnok","env":"development","addr":":8080"}
{"time":"2026-08-22T10:13:43.084594+07:00","level":"INFO","msg":"database connected"}
{"time":"2026-08-22T10:13:43.085393+07:00","level":"INFO","msg":"server starting","addr":":8080"}

ลำดับใน run() ที่ทำให้ได้ log แบบนี้: logger ชั่วคราว (slog TextHandler) → godotenv.Load() → config.Load() → logger ตัวจริงที่สร้างจาก cfg.Logging (เลยกลายเป็น JSON ตั้งแต่บรรทัดแรก) → gorm.Open + SetMaxOpenConns/SetMaxIdleConns/SetConnMaxLifetime + Ping → ListenAndServe

9 · JWT — โครงสร้าง · golang-jwt/v5 · error ทุกเคส

สามส่วน คั่นด้วยจุด

$ echo 'eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9' | tr '_-' '/+' | base64 -d
{"alg":"HS256","typ":"JWT"}

# payload — ไม่ต้องมี secret เลย
{"sub":"1234567890","name":"John Doe","admin":true,"iat":1516239022}

# ทำซ้ำด้วย Go: jwt.NewParser().ParseUnverified (ไม่ส่ง secret เข้าไป)
err=<nil>
alg=HS256 typ=JWT
claims=map[admin:true iat:1.516239022e+09 name:John Doe sub:1234567890]
จำนวนส่วนของ token=3

$ echo 'eyJzdWIiOiIxMjM0NTY3ODkwIiwibmFtZSI6IkpvaG4gRG9lIiwiYWRtaW4iOnRydWUsImlhdCI6MTUxNjIzOTAyMn0' | tr '_-' '/+' | base64 -d
{"sub":"1234567890","name":"John Doe","admin":true,"iat":151623902     ← ขาด 2 ตัวท้าย ไม่มี error ด้วย

$ python3 -c "import base64,sys;print(base64.urlsafe_b64decode(sys.argv[1]+'='*(-len(sys.argv[1])%4)).decode())" <segment>
{"sub":"1234567890","name":"John Doe","admin":true,"iat":1516239022}

your-256-bit-secret                      reGQzG3OKdoIMWLDKOZ4TICJit3EW69cQE72E2CfzRE  no
secret                                   39jkN-bckg4fbZQEb0xHIxzYL9qI_g4c4WyzEYNHZok  no
a-string-secret-at-least-256-bits-long   KMUFsIDTnFmyG3nMiGM6H9FNFUROf3wh7SmqJp-QV30  MATCH
target:                                  KMUFsIDTnFmyG3nMiGM6H9FNFUROf3wh7SmqJp-QV30

# ยืนยันซ้ำด้วย jwt/v5
secret="your-256-bit-secret"                    -> FAIL: token signature is invalid: signature is invalid
secret="a-string-secret-at-least-256-bits-long" -> OK (signature ผ่าน)

โครงที่ก็อปไปใช้ได้

import (
	"time"                              // ขาดไม่ได้ — โค้ดข้างล่างใช้ time.Now()

	"github.com/golang-jwt/jwt/v5"      // v5.3.1
)

secret := []byte("a-string-secret-at-least-256-bits-long")

// ---------- สร้าง ----------
claims := jwt.MapClaims{
	"sub":  "42",
	"name": "somchai",
	"role": "admin",
	"iat":  time.Now().Unix(),
	"exp":  time.Now().Add(time.Hour).Unix(),   // ต้องใส่เอง! ดูกล่องเตือน
}
token, err := jwt.NewWithClaims(jwt.SigningMethodHS256, claims).SignedString(secret)

// ---------- ตรวจ ----------
tok, err := jwt.Parse(token,
	func(t *jwt.Token) (any, error) { return secret, nil },
	// algorithm confusion = attacker สลับ alg ใน header ให้เราหยิบ "คีย์ผิดประเภท" ไปตรวจ (ดูท้ายหัวข้อ)
	jwt.WithValidMethods([]string{"HS256"}),   // กัน algorithm confusion
	jwt.WithExpirationRequired(),                 // บังคับว่าต้องมี exp
)

=== 3) สร้าง JWT เอง (HS256) ===
token = eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJleHAiOjE3ODczNzE5MjUsImlhdCI6MTc4NzM2ODMyNSwibmFtZSI6InNvbWNoYWkiLCJyb2xlIjoiYWRtaW4iLCJzdWIiOiI0MiJ9.MTGaDfheYUXIvMe-j3oO8iTOvdgRPLaizc0cHV_ybEQ
len   = 185 byte

--- 3b) parse กลับ + verify ---
OK  valid=true claims=map[exp:1.787371925e+09 iat:1.787368325e+09 name:somchai role:admin sub:42]

error จริงของทุกเคส

token ไม่มี exp เลย (default)                        err = <nil>
token ไม่มี exp + WithExpirationRequired()           err = token has invalid claims: token is missing required claim: exp claim is required

alg=none ทะลุได้จริงไหม

evil token = eyJhbGciOiJub25lIiwidHlwIjoiSldUIn0.eyJyb2xlIjoiYWRtaW4iLCJzdWIiOiI0MiJ9.

A) มี WithValidMethods([HS256]) -> err = token signature is invalid: signing method none is invalid
B) ไม่มี WithValidMethods       -> err = token signature is invalid: token is unverifiable: 'none' signature type is not allowed
C) keyfunc คืน UnsafeAllowNoneSignatureType -> err = <nil>      ← ทะลุ!
D) ยกระดับ user เป็น admin ผ่าน alg=none -> err = token signature is invalid: token is unverifiable: 'none' signature type is not allowed  valid = false

// algorithm confusion: attacker เอา RSA public key (ที่เปิดเผยอยู่แล้ว) มาเซ็นแบบ HS256
attacker เซ็น HS256 ด้วย public key: err=<nil>
A) ไม่มี WithValidMethods    -> err = token signature is invalid: key is of invalid type: HMAC verify expects []byte
B) มี WithValidMethods([RS256]) -> err = token signature is invalid: signing method HS256 is invalid

เคส A รอดเพราะ type ไม่ match โดยบังเอิญ ไม่ใช่เพราะมันเช็ค alg — ถ้า keyfunc คืน []byte ตอนไหนก็ทะลุ · เคส B กันแบบตั้งใจ · ใส่ WithValidMethods เสมอ

Basic Auth vs JWT — ทำไมถึงย้าย

$ # ยิง 3 ครั้ง — header ตัวเดิมเป๊ะทุกครั้ง
[server] GET /foods  Authorization: "Basic c29tY2hhaTpwQHNzdzByZA=="
[server] r.BasicAuth() -> user="somchai" pass="p@ssw0rd" ok=true

$ # decode กลับได้ทันทีโดยไม่ต้องมี key
somchai:p@ssw0rd

$ # ยิงด้วยรหัสผิด
[server] GET /foods  Authorization: "Basic c29tY2hhaTp3cm9uZw=="
[server] r.BasicAuth() -> user="somchai" pass="wrong" ok=true

ราคาที่จ่าย — JWT ใหญ่กว่า session id มาก

header ที่ส่งจริง Authorization: Bearer <typical> = 247 byte
header ที่ส่งจริง Cookie: sid=<hex>              = 44 byte

ถ้ามี 1000 request: fat JWT กินแบนด์วิดท์ขาขึ้นเพิ่ม 521000 byte เทียบ session

fat JWT บวมเพราะ claims เยอะ แล้ว ชื่อไทยยิ่งแพงกว่าชื่ออังกฤษ ~4 เท่าต่อตัวอักษร — ภาษาไทยเป็น UTF-8 ตัวละ 3 byte แล้ว base64 ขยายอีก ×4/3 กลายเป็นตัวละ 4 byte ใน token · อย่ายัด permission ทั้งชุดลง token

json.Marshal -> {"name":"สมชาย ใจดี"}   len: 39 byte
มี \u escape ไหม: false
payload ที่ decode กลับจาก token: {"exp":…,"name":"สมชาย ใจดี","permissions":[…],…}
"สมชาย ใจดี" = 10 rune · 28 byte (UTF-8) · base64url แล้ว 38 byte

Swagger — บอก Swagger UI ว่ามีช่องใส่ token

// @securityDefinitions.apikey	BearerAuth
// @in							header
// @name						Authorization
// @description				ใส่ค่าเป็น "Bearer {token}"

=== securityDefinitions ที่ได้จริง (swag v1.16.4) ===
{
  "BearerAuth": {
    "description": "ใส่ค่าเป็น \"Bearer {token}\"",
    "type": "apiKey",
    "name": "Authorization",
    "in": "header"
  }
}
--- security ระดับ endpoint ---
[ { "BearerAuth": [] } ]
--- swagger version --- 2.0

swag v1 ออก Swagger 2.0 ซึ่งไม่มี type: http / scheme: bearer — จึงต้องใช้ apiKey และผู้ใช้ต้องพิมพ์คำว่า Bearer นำหน้าเองในช่อง Authorize · รายละเอียด annotation ครบชุดอยู่ที่ บทเรียน 41

10 · OAuth 2.0 — ตัวละคร 4 ตัว + Authorization Code Grant

OAuth 2.0 คือ framework สำหรับ มอบสิทธิ์แบบจำกัดขอบเขต (delegated authorization) — ให้แอปหนึ่งทำอะไรบางอย่างแทนเราได้ โดยไม่ต้องบอกรหัสผ่านของเราให้มันรู้

Authorization Code Grant — 8 ขั้น

ขั้น 2  App สุ่ม code_verifier แล้วส่ง code_challenge = BASE64URL(SHA256(code_verifier)) ไปกับ request
ขั้น 5  App ส่ง code + code_verifier ตัวจริง (แทน client_secret) ไปแลก token
        Auth Server แฮชแล้วเทียบกับ code_challenge ที่จำไว้ — ไม่ตรงก็ไม่ให้ token

โค้ด OIDC ฝั่ง Go — compile และรันจริงแล้ว

import (
	"github.com/coreos/go-oidc/v3/oidc"   // v3.20.0
	"golang.org/x/oauth2"                 // v0.36.0
)

provider, err := oidc.NewProvider(ctx, issuerURL)   // อ่าน discovery ให้เอง

conf := &oauth2.Config{
	ClientID:     clientID,
	ClientSecret: clientSecret,
	Endpoint:     provider.Endpoint(),                 // ไม่ต้อง hardcode URL
	RedirectURL:  "http://localhost:8080/auth/callback",
	Scopes:       []string{oidc.ScopeOpenID, "profile", "email"},
}

// ขั้น 2
url := conf.AuthCodeURL(state)

// ขั้น 5-6
tok, err := conf.Exchange(ctx, code)

// id_token ไม่ได้อยู่ใน tok.AccessToken — ต้องดึงแยก
rawIDToken, ok := tok.Extra("id_token").(string)

verifier := provider.Verifier(&oidc.Config{ClientID: clientID})
idToken, err := verifier.Verify(ctx, rawIDToken)
var claims struct {
	Email             string `json:"email"`
	PreferredUsername string `json:"preferred_username"`
}
err = idToken.Claims(&claims)

$ go build ./... ; go vet ./...
BUILD_EXIT=0
VET_EXIT=0

$ go run ./cmd/probe      # ยิง issuer จริง (Google) ไม่ใช่แค่ compile
AuthURL  = https://accounts.google.com/o/oauth2/v2/auth
TokenURL = https://oauth2.googleapis.com/token
AuthCodeURL = https://accounts.google.com/o/oauth2/v2/auth?client_id=my-client-id&redirect_uri=http%3A%2F%2Flocalhost%3A8080%2Fauth%2Fcallback&response_type=code&scope=openid+profile+email&state=state-abc123
Verify(ขยะ) ERROR = oidc: malformed jwt: go-jose/go-jose: compact JWS format must have three parts

11 · Keycloak — compose · endpoint · components

Keycloak คือ Authorization Server แบบ open source ที่เรารันเองได้ — ทำหน้าที่เก็บผู้ใช้ · แสดงหน้า login · ออก token · ปิด session ให้เรา โดยที่เราไม่ต้องเขียนระบบเก็บรหัสผ่านเอง

compose.yml

services:
  keycloak:
    image: quay.io/keycloak/keycloak:26.7
    container_name: wongnok-keycloak
    restart: always
    command: ["start-dev", "--import-realm"]
    environment:
      KC_BOOTSTRAP_ADMIN_USERNAME: admin
      KC_BOOTSTRAP_ADMIN_PASSWORD: admin
      # ฉบับ Post ลบ KC_HOSTNAME: localhost ออกแล้ว
      KC_HOSTNAME_STRICT: "false"
      KC_HTTP_ENABLED: "true"
    ports:
      - "8081:8080"
    volumes:
      # เก็บข้อมูลของ embedded database ไว้
      - wongnok-keycloak-data:/opt/keycloak/data

# ← บล็อกนี้ขาดไม่ได้ ไม่งั้น compose จะบอกว่า volume undefined
volumes:
  wongnok-keycloak-data:

$ docker-compose up -d
 Image quay.io/keycloak/keycloak:26.7 Pulled
 Network kc_default Created
 Volume kc_wongnok-keycloak-data Created
 Container wongnok-keycloak Created
 Container wongnok-keycloak Started

$ # รอจน ready
READY after ~4s (HTTP 200)

$ docker logs wongnok-keycloak | tail
2026-08-22 03:13:34,745 INFO  [org.keycloak.services] (main) KC-SERVICES0077: Created temporary admin user with username admin
2026-08-22 03:13:34,883 INFO  [io.quarkus] (main) Keycloak 26.7.2 on JVM (powered by Quarkus 3.33.3.1) started in 5.582s. Listening on: http://0.0.0.0:8080

$ docker logs wongnok-keycloak | head -20
2026-08-22 03:13:30,102 INFO  [org.keycloak.url.HostnameV2ProviderFactory] (main) If hostname is specified, hostname-strict is effectively ignored

$ docker logs wongnok-keycloak 2>&1 | grep -i -E "import|realm"
2026-08-22 03:13:34,071 INFO  [org.keycloak.services] (main) KC-SERVICES0050: Initializing master realm
# ← ไม่มีบรรทัด import สักบรรทัด

endpoint สำคัญ — จาก OIDC discovery

ศัพท์ที่โผล่ใน URL ก่อนจะถูกอธิบายเต็ม ๆ ในหัวข้อย่อยถัดไป: realm = พื้นที่แยกอิสระของแต่ละโปรเจกต์ (user/client/role ไม่ปนข้าม realm) · master คือ realm ที่ Keycloak สร้างให้เองตอน start — ของจริงเราจะสร้าง realm ชื่อ wongnok แยกออกมา ไม่ใช้ master ทำงาน

$ curl -s http://localhost:8081/realms/master/.well-known/openid-configuration

grant_types_supported = ["authorization_code", "client_credentials", "implicit", "password",
  "refresh_token", "urn:ietf:params:oauth:grant-type:device_code",
  "urn:ietf:params:oauth:grant-type:jwt-bearer", "urn:ietf:params:oauth:grant-type:token-exchange",
  "urn:ietf:params:oauth:grant-type:uma-ticket", "urn:openid:params:grant-type:ciba"]
response_types_supported = ["code", "none", "id_token", "token", "id_token token",
  "code id_token", "code token", "code id_token token"]

components — ของสี่อย่างที่ต้องรู้จัก

Group → Role ทำงานจริง — พิสูจน์ด้วย token

== 3. map role recipe:write -> group chefs ==   HTTP 204
== 4. put user chef1 into group chefs ==        HTTP 204

== 5a. DIRECT realm roles of chef1 ==
['default-roles-wongnok']                       ← ไม่เคยผูก recipe:write กับ user เลย
== 5b. COMPOSITE/effective realm roles of chef1 ==
['default-roles-wongnok', 'offline_access', 'recipe:write', 'uma_authorization']
== 5c. groups of chef1 ==
['/chefs']

== access_token payload AFTER group->role ==
  "azp": "wongnok-api",
  "preferred_username": "chef1",
  "realm_access": { "roles": ["default-roles-wongnok", "recipe:write", "offline_access", "uma_authorization"] }

role โผล่ใน realm_access.roles (realm role) ไม่ใช่ resource_access — หาผิดที่แล้วจะงงว่าทำไมไม่เห็น

claim ที่ Keycloak ใส่มาใน access_token

{
  "exp": …, "iat": 1787368445,
  "jti": "onrtro:f1adacbf-bd71-072f-c8c8-b8a6d666cc03",
  "iss": "http://localhost:8081/realms/wongnok",
  "aud": "account",
  "sub": "5da7f595-196f-44a6-8dfd-64306ce734d6",
  "typ": "Bearer",
  "azp": "wongnok-api",
  "sid": "grEBoqUUX084tjH4AEFbI5aJ",
  "acr": "1",
  "allowed-origins": ["http://localhost:8080"],
  "realm_access": { "roles": ["default-roles-wongnok", "offline_access", "uma_authorization"] },
  "resource_access": { "account": { "roles": ["manage-account", "manage-account-links", "view-profile"] } },
  "scope": "openid profile email",
  "email_verified": true,
  "name": "Chef One",
  "preferred_username": "chef1",
  "given_name": "Chef", "family_name": "One",
  "email": "chef1@wongnok.dev"
}

อายุ token ค่าเริ่มต้นของ 26.7

expires_in         = 300     # access_token — 5 นาที
refresh_expires_in = 1800    # refresh_token — 30 นาที
token_type         = Bearer
scope              = openid profile email

access_token  len 1346   refresh_token len 694   id_token len 1037

ไม่ใช่ 1 ชั่วโมงตามที่หลายคนจำ · ถ้าอยากได้ token มาเทสต์เร็ว ๆ ต้องเปิด directAccessGrantsEnabled: true ที่ client ก่อนถึงจะใช้ password grant ได้

verify ด้วย public key อย่างเดียว — ไม่ต้องแชร์ secret

$ curl -s http://localhost:8081/realms/wongnok/protocol/openid-connect/certs
number of keys = 2
{'kid': 'wyvKSfqZdLBxEgiFH8uLjDWqHbA_HNNaoo7eusbO...', 'kty': 'RSA', 'alg': 'RS256', 'use': 'sig', ...}
{'kid': 'Mf4wHVuGfb9hhl_aZu4jyayOm94BXmiUsDX413Re...', 'kty': 'RSA', 'alg': 'RSA-OAEP', 'use': 'enc', ...}

$ # Go stdlib ล้วน: ดึง JWKS → match kid → ประกอบ rsa.PublicKey → VerifyPKCS1v15
token header kid = wyvKSfqZdLBxEgiFH8uLjDWqHbA_HNNaoo7eusbOGF4  alg = RS256
matched JWKS key: kid = wyvKSfqZdLBxEgiFH8uLjDWqHbA_HNNaoo7eusbOGF4 use = sig alg = RS256
public key modulus bits = 2048  exponent = 65537
VERIFY OK  -> signature valid using ONLY the public key from jwks_uri (no client_secret used)
tampered token correctly REJECTED: crypto/rsa: verification error

== JWT header of access_token ==
{ "alg": "RS256", "typ": "JWT", "kid": "wyvKSfqZdLBxEgiFH8uLjDWqHbA_HNNaoo7eusbOGF4" }
== refresh_token header ==
{ "alg": "HS512", "typ": "JWT", "kid": "b2ffdb37-5e0e-4ae7-b420-370b9638d5b1" }

เลิกใช้แล้วเก็บกวาด

$ docker-compose down -v
 Container wongnok-keycloak Removed
 Volume kc_wongnok-keycloak-data Removed
 Network kc_default Removed

$ # image ยังคาไว้ ถ้าอยากลบ
$ docker rmi quay.io/keycloak/keycloak:26.7

12 · flow /login /callback /exchange /logout

ทำไม /callback ไม่คืน token ตรง ๆ แต่คืน ticket

13 · goose + ตาราง users

DSN — ตัวที่ถูกต้อง กับตัวที่มีปัญหา

$ # ฝั่ง Go ไม่พังเลย — สาม parser ให้ผลตรงกันหมด
=== DSN: postgres://postgres:Pe@devp00l@localhost:5432?database=wongnok
  net/url.Parse  -> user="postgres" password="Pe@devp00l" host="localhost:5432" rawquery="database=wongnok"
  pgx ParseConfig-> host="localhost" port=5432 user="postgres" password="Pe@devp00l" database="wongnok"
  lib/pq ParseURL-> "database='wongnok' host='localhost' password='Pe@devp00l' port='5432' user='postgres'"

$ goose up
2026/08/22 10:11:57 OK   20260822031131_create_users.sql (12.99ms)
2026/08/22 10:11:57 goose: successfully migrated database to version: 20260822031131

$ # ลงฐานไหน? เช็คทั้งสองฐาน
=== tables in DB 'postgres' ===   Did not find any relations.
=== tables in DB 'wongnok' ===
 public | goose_db_version | table | postgres
 public | users            | table | postgres

$ psql "postgres://postgres:Pe@devp00l@localhost:5432/wongnok" -c "select current_database()"
psql: error: could not translate host name "devp00l@localhost" to address: Name does not resolve

$ psql "postgres://postgres:Pe@devp00l@localhost:5432?database=wongnok" -c "select current_database()"
psql: error: invalid URI query parameter: "database"

$ psql "postgres://postgres:Pe%40devp00l@localhost:5432/wongnok" -c "select current_database()"
 current_database
------------------
 wongnok
(1 row)

คำสั่ง goose ที่ใช้จริง

# .env — goose CLI อ่านไฟล์นี้ให้เอง (flag -env ค่าเริ่มต้นคือ .env)
GOOSE_DRIVER=postgres
GOOSE_DBSTRING=postgres://postgres:Pe%40devp00l@localhost:5432/wongnok?sslmode=disable
GOOSE_MIGRATION_DIR=migrations

$ # ไฟล์ที่ goose create สร้างมาให้
-- +goose Up
SELECT 'up SQL query';

-- +goose Down
SELECT 'down SQL query';

migration ของตาราง users

-- +goose Up
CREATE TABLE users (
    id                 UUID PRIMARY KEY,
    email              VARCHAR(255) NOT NULL,
    name               VARCHAR(255),
    bio                TEXT,
    uid                VARCHAR(255) NOT NULL,
    image_url          TEXT,
    preferred_username VARCHAR(255),
    last_signed_in_at  TIMESTAMPTZ,
    created_at         TIMESTAMPTZ NOT NULL DEFAULT now(),
    updated_at         TIMESTAMPTZ NOT NULL DEFAULT now(),
    deleted_at         TIMESTAMPTZ
);

CREATE INDEX        idx_users_email      ON users (email);
CREATE UNIQUE INDEX idx_users_uid        ON users (uid);
CREATE INDEX        idx_users_deleted_at ON users (deleted_at);

-- +goose Down
DROP TABLE users;

$ psql -U postgres -d wongnok -c '\d users'
                              Table "public.users"
     Column       |           Type           | Collation | Nullable | Default
--------------------+--------------------------+-----------+----------+---------
 id                 | uuid                     |           | not null |
 email              | character varying(255)   |           | not null |
 name               | character varying(255)   |           |          |
 bio                | text                     |           |          |
 uid                | character varying(255)   |           | not null |
 image_url          | text                     |           |          |
 preferred_username | character varying(255)   |           |          |
 last_signed_in_at  | timestamp with time zone |           |          |
 created_at         | timestamp with time zone |           | not null | now()
 updated_at         | timestamp with time zone |           | not null | now()
 deleted_at         | timestamp with time zone |           |          |
Indexes:
    "users_pkey" PRIMARY KEY, btree (id)
    "idx_users_deleted_at" btree (deleted_at)
    "idx_users_email" btree (email)
    "idx_users_uid" UNIQUE, btree (uid)

soft delete ของ GORM ทำงานยังไง

type User struct {
	ID        uuid.UUID      `gorm:"type:uuid;primaryKey"`
	DeletedAt gorm.DeletedAt `gorm:"index:idx_users_deleted_at"`
	// ชนิดต้องเป็น gorm.DeletedAt เท่านั้น — *time.Time ใช้ไม่ได้
}

1) Create OK, id = bae1dc16-8585-4f91-bbe6-d30160e7dbdd
2) db.Delete() -> DeletedAt.Valid = true
3) Count() ปกติ (ถูกกรอง deleted_at IS NULL) = 0
4) Unscoped().Count() (นับแถวที่ soft delete ด้วย) = 1

INSERT 0 1
UPDATE 1                       # soft delete
     uid      | soft_deleted
--------------+--------------
 oidc-sub-123 | t
INSERT ...
ERROR:  duplicate key value violates unique constraint "idx_users_uid"
DETAIL:  Key (uid)=(oidc-sub-123) already exists.

5) สมัครใหม่ uid เดิม -> err = ERROR: duplicate key value violates unique constraint "idx_users_uid" (SQLSTATE 23505)
6) FirstOrCreate      -> err = ERROR: duplicate key value violates unique constraint "idx_users_uid" (SQLSTATE 23505)

DROP INDEX idx_users_uid;
CREATE UNIQUE INDEX idx_users_uid ON users (uid) WHERE deleted_at IS NULL;

DROP INDEX
CREATE INDEX
INSERT 0 1
     uid      | active
--------------+--------
 oidc-sub-123 | f
 oidc-sub-123 | t
(2 rows)
ERROR:  duplicate key value violates unique constraint "idx_users_uid"   # ยังกัน uid ซ้ำในแถวที่ active

รอบแรก:
Create โดยไม่เซ็ต ID -> err=<nil>, id=00000000-0000-0000-0000-000000000000

รอบสอง (uid ต่างกัน):
Create โดยไม่เซ็ต ID -> err=ERROR: duplicate key value violates unique constraint "users_pkey" (SQLSTATE 23505)

แถวในตาราง:
                  id                  |    uid
--------------------------------------+-----------
 00000000-0000-0000-0000-000000000000 | no-id-set

อ่าน goose status ให้ถูก

$ goose status                              # หลัง up
    Applied At                  Migration
    =======================================
    Sat Aug 22 03:11:57 2026 -- 20260822031131_create_users.sql

$ goose down ; goose status
    Applied At                  Migration
    =======================================
    Pending                  -- 20260822031131_create_users.sql

หัวตาราง Applied At / Migration กับเส้น ==== goose พิมพ์มาให้ทุกครั้งที่เรียก status ไม่ว่าจะ pending หรือ applied · และ goose ใส่ prefix วันเวลา (2026/08/22 11:48:24 ) นำหน้า ทุกบรรทัดที่มันพิมพ์ รวมถึง create · status · version เหมือนบล็อก goose up ข้างบน — บล็อก status นี้กับตารางคำสั่งข้างบนตัด prefix ออกให้พอดีความกว้าง ของจริงบนเครื่องจะมีติดมาด้วยเสมอ

$ psql -c 'select * from goose_db_version;' -c 'show timezone;' ; date
 id |   version_id   | is_applied |           tstamp
----+----------------+------------+----------------------------
  1 |              0 | t          | 2026-08-22 03:11:46.240423
  3 | 20260822031131 | t          | 2026-08-22 03:14:26.155434
(2 rows)

 TimeZone
----------
 UTC

local now:
Sat Aug 22 10:15:38 +07 2026

14 · ตารางกับดักรวมทั้งวัน

15 · ตารางแปล error / panic ที่เจอบ่อยของวันนี้

อ้างอิง

• caarlos0/env — README มีรายการ tag/option/type ครบ · pkg.go.dev
• joho/godotenv — โดยเฉพาะ godotenv.go และ parser.go ที่หัวข้อ 4–5 อ้างถึง
• go-playground/validator — รายการ validate tag ทั้งหมด · pkg.go.dev
• pkg.go.dev — errors.Join · errors.As
• The Twelve-Factor App — III. Config — ต้นทางของแนวคิด “config อยู่ใน environment”
• golang-jwt/jwt — pkg.go.dev v5 · รายการ Parser option ทั้งหมด
• RFC 7519 — JSON Web Token (JWT) · jwt.io — เครื่องมือ decode
• RFC 6749 — The OAuth 2.0 Authorization Framework — นิยามตัวละคร 4 ตัวและ grant ทุกแบบ
• OpenID Connect Core 1.0 · coreos/go-oidc · golang.org/x/oauth2
• Keycloak Documentation · Running Keycloak in a container · Hostname configuration
• pressly/goose · GORM — Soft Delete
• PostgreSQL — Partial Indexes — ที่มาของทางแก้ในหัวข้อ 13
• Cheat sheet Day 8 — REST · Gin · Swagger · Environment Variables พื้นฐาน
• Cheat sheet Day 7 — Mockery · Testcontainers · Goose · Redis