REST · Gin · Swagger — แผ่นเดียวจบ

สารบัญ

1. เวอร์ชันที่ทุกอย่างในหน้านี้รันผ่าน
2. REST — method กับความหมาย
3. Status code — เลือกตัวไหน
4. กฎตั้งชื่อ 7 ข้อ
5. query / body / header / path — ข้อมูลไปทางไหน
6. net/http — โครงที่ก็อปไปใช้ได้
7. net/http — ไวยากรณ์ pattern (Go 1.22+)
8. Gin — โครงที่ก็อปไปใช้ได้
9. Gin — Context ที่ใช้บ่อย
10. Gin — binding tag + ข้อความ error จริง
11. Gin — middleware & CORS
12. httptest — โครงเทสที่ก็อปไปใช้ได้
13. Swagger — คำสั่ง + annotation ครบชุด
14. Redis — สองคำสั่งที่เพิ่มจาก Day 7
15. Wongnok API spec
16. ตารางกับดักรวมทั้งวัน
17. ตารางแปล error / panic ที่เจอบ่อย
18. Environment Variables — Getenv/LookupEnv · แปลง type · วิธีตั้งค่า · 12-Factor
19. ตารางแปลง API ที่ออกแบบแย่ → RESTful

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

2 · REST — method กับความหมาย

idempotent = ยิงซ้ำกี่ครั้งผลสุดท้ายเหมือนยิงครั้งเดียว — ไม่ได้แปลว่า “ได้ status เดิม” · DELETE ครั้งแรกได้ 204 ครั้งที่สองได้ 404 ก็ยังถือว่า idempotent เพราะสถานะของ server เหมือนกัน

* PATCH idempotent หรือไม่ขึ้นกับว่าเขียนยังไง — {"stock": 5} idempotent แต่ {"stock": "+1"} ไม่

3 · Status code — เลือกตัวไหน

4 · กฎตั้งชื่อ 7 ข้อ

ข้อยกเว้นของกฎ 7 ที่ถูกต้อง — action ที่ HTTP method สื่อไม่ได้จริง ๆ ใส่ใน path ได้ (สไลด์หน้า 36 เขียนถูก): PATCH /users/123/suspend · PATCH /users/123/reset-password · POST /orders/123/cancel

Versioning

// stable
/api/v1/users
// เมื่อมี breaking change
/api/v2/users

breaking = ลบ field · เปลี่ยน type · เปลี่ยนความหมายของค่าเดิม · เปลี่ยน field ที่ required  |  ไม่ breaking = เพิ่ม field ใหม่ที่ optional · เพิ่ม endpoint ใหม่ · เพิ่มค่า enum ใหม่

5 · query / body / header / path — ข้อมูลไปทางไหน

Header สามตัวที่ต้องรู้จัก

6 · net/http — โครงที่ก็อปไปใช้ได้

package main

import (
    "encoding/json"
    "log"
    "net/http"
)

type User struct {
    ID   string `json:"id"`
    Name string `json:"name"`
}

func getUser(w http.ResponseWriter, r *http.Request) {
    id := r.PathValue("id")          // Go 1.22+

    // ลำดับนี้ห้ามสลับ: Header → WriteHeader → Encode
    w.Header().Set("Content-Type", "application/json; charset=utf-8")
    w.WriteHeader(http.StatusOK)
    json.NewEncoder(w).Encode(User{ID: id, Name: "Somchai"})
}

func main() {
    mux := http.NewServeMux()
    mux.HandleFunc("GET /health", func(w http.ResponseWriter, r *http.Request) {
        w.Write([]byte("ok"))
    })
    mux.HandleFunc("GET /users/{id}", getUser)

    log.Fatal(http.ListenAndServe(":8080", mux))
}

สิ่งที่ net/http ทำให้ฟรี

# ยิง POST ไปที่ route ที่ลงเป็น GET
$ curl -s -i -X POST http://127.0.0.1:8765/hello
HTTP/1.1 405 Method Not Allowed
Allow: GET, HEAD
Content-Type: text/plain; charset=utf-8
X-Content-Type-Options: nosniff

Method Not Allowed

405 พร้อม Allow header มาให้เอง — Gin ไม่ทำให้ (ดูหัวข้อ 9)

7 · net/http — ไวยากรณ์ pattern (Go 1.22+)

ลำดับความสำคัญ: pattern ที่เจาะจงกว่าชนะเสมอ ไม่เกี่ยวกับลำดับที่ลงทะเบียน — /users/me ชนะ /users/{id} · และ ServeMux ไม่ panic เมื่อลงทั้งสองอัน

ไวยากรณ์ที่พิมพ์ผิดแล้วพังเงียบ ๆ

pattern="get /hello"    // ลงทะเบียนผ่าน! แต่ GET จริงได้ 405 Allow: get
pattern="GET/hello"     // Go ตีเป็น host="GET" path="/hello" → 404 ทุกครั้ง เงียบสนิท
pattern="GET  /hello"   // เว้นวรรคเกิน → ใช้ได้ปกติ
pattern="GET hello"     // PANIC: parsing "GET hello": at offset 4: host/path missing /

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

package main

import (
    "net/http"
    "github.com/gin-gonic/gin"
)

func NewRouter() *gin.Engine {
    r := gin.Default()                // = New() + Logger() + Recovery()
    r.HandleMethodNotAllowed = true    // อยากได้ 405 ต้องเปิดเอง

    v1 := r.Group("/api/v1")
    {
        v1.GET("/users/:id", getUser)
        v1.POST("/users", createUser)
    }
    return r
}

func getUser(c *gin.Context) {
    c.JSON(http.StatusOK, gin.H{"id": c.Param("id")})
}

func main() { NewRouter().Run(":8080") }

9 · Gin — Context ที่ใช้บ่อย

Gin ต่างจาก net/http ตรงไหนจริง ๆ

10 · Gin — binding tag + ข้อความ error จริง

type CreateRecipeRequest struct {
    Name       string  `json:"name"       binding:"required"`
    Email      string  `json:"email"      binding:"required,email"`
    Level      int     `json:"level"      binding:"min=1,max=5"`
    Difficulty string  `json:"difficulty" binding:"oneof=easy medium hard"`
    Note       *string `json:"note"`   // pointer = แยก "ไม่ส่งมา" ออกจาก "ส่งค่าว่าง"
}

func create(c *gin.Context) {
    var req CreateRecipeRequest
    if err := c.ShouldBindJSON(&req); err != nil {   // ShouldBind เสมอ ไม่ใช่ Bind
        c.JSON(http.StatusBadRequest, gin.H{"message": err.Error()})
        return
    }
    c.JSON(http.StatusCreated, req)
}

ข้อความ error ที่ได้จริง

# ยิงเข้า struct CreateRecipeRequest ข้างบนตรง ๆ — ทุกเคสได้ HTTP 400

body={"name":"","email":"a@b.co","level":3,"difficulty":"easy"}
  Key: 'CreateRecipeRequest.Name' Error:Field validation for 'Name' failed on the 'required' tag

body={"name":"ผัดกะเพรา","email":"not-an-email","level":3,"difficulty":"easy"}
  Key: 'CreateRecipeRequest.Email' Error:Field validation for 'Email' failed on the 'email' tag

body={"name":"ผัดกะเพรา","email":"a@b.co","level":9,"difficulty":"extreme"}
  Key: 'CreateRecipeRequest.Level' Error:Field validation for 'Level' failed on the 'max' tag
  Key: 'CreateRecipeRequest.Difficulty' Error:Field validation for 'Difficulty' failed on the 'oneof' tag

สังเกตชื่อขึ้นต้น — Key: ใช้ชื่อ struct ใน Go (CreateRecipeRequest.Name) ไม่ใช่ชื่อใน json tag (name) · ข้อความนี้จึงไม่ควรส่งกลับไปให้ผู้ใช้ตรง ๆ เพราะมันเปิดเผยโครงสร้างภายในของโค้ดเรา

ผิดหลาย field พร้อมกัน → error ทุกอันต่อกันด้วย \n ในสตริงเดียว

11 · Gin — middleware & CORS

func RequireAuth() gin.HandlerFunc {
    return func(c *gin.Context) {
        if c.GetHeader("Authorization") == "" {
            c.AbortWithStatusJSON(http.StatusUnauthorized, gin.H{"message": "no token"})
            return
        }
        c.Set("userID", "u-123")
        c.Next()                 // ปล่อยให้ตัวถัดไปทำงาน
        // โค้ดตรงนี้รัน "ขากลับ" หลัง handler เสร็จแล้ว
    }
}

r.Use(RequireAuth())              // ทั้งเว็บ
admin := r.Group("/admin")
admin.Use(RequireAuth())          // เฉพาะกลุ่มนี้

CORS — ผลรันจริง

preflight = request OPTIONS ที่เบราว์เซอร์ยิงเองก่อน โดยที่โค้ดเราไม่ได้สั่ง เพื่อถามเซิร์ฟเวอร์ว่า “ขอส่ง method/header ชุดนี้ได้ไหม” ถ้าคำตอบไม่ผ่าน เบราว์เซอร์จะไม่ยิง request จริงเลย (ละเอียดใน บทเรียน 39)

# request จริง (มี Origin) กับ cors.Default()
$ curl -s -i -H "Origin: https://evil.example.com" http://127.0.0.1:39182/data
HTTP/1.1 200 OK
Access-Control-Allow-Origin: *

# preflight
$ curl -s -i -X OPTIONS -H "Origin: https://evil.example.com" \
    -H "Access-Control-Request-Method: POST" http://127.0.0.1:39182/data
HTTP/1.1 204 No Content
Access-Control-Allow-Headers: Origin,Content-Length,Content-Type
Access-Control-Allow-Methods: GET,POST,PUT,PATCH,DELETE,HEAD,OPTIONS
Access-Control-Allow-Origin: *
Access-Control-Max-Age: 43200

r.Use(cors.New(cors.Config{
    AllowOrigins: []string{"https://app.example.com"},
    AllowMethods: []string{"GET", "POST", "PUT", "DELETE"},
    AllowHeaders: []string{"Origin", "Content-Type", "Authorization"},
}))

CORS ไม่ใช่ระบบความปลอดภัยของ server — เป็นกฎที่เบราว์เซอร์บังคับตัวเอง curl และ Postman ไม่สนใจ CORS เลย ยิงได้ตลอด

12 · httptest — โครงเทสที่ก็อปไปใช้ได้

func TestGetUser(t *testing.T) {
    gin.SetMode(gin.TestMode)
    router := NewRouter()

    w := httptest.NewRecorder()
    req := httptest.NewRequest("GET", "/api/v1/users/1", nil)
    router.ServeHTTP(w, req)

    assert.Equal(t, 200, w.Code)
    assert.JSONEq(t, `{"id":"1"}`, w.Body.String())
    assert.Equal(t, "application/json; charset=utf-8", w.Header().Get("Content-Type"))
}

NewRecorder = ยิงเข้า router ในหน่วยความจำ ไม่เปิด port — ใช้ 99% ของเวลา  |  httptest.NewServer = เปิด server จริงบน port สุ่ม ใช้เมื่อต้องทดสอบตัว HTTP client ของเราเอง

13 · Swagger — คำสั่ง + annotation ครบชุด

ติดตั้ง

go install github.com/swaggo/swag/cmd/swag@latest
go get -u github.com/swaggo/gin-swagger
go get -u github.com/swaggo/files
go get github.com/swaggo/swag@latest        # ← สำคัญ ดูกล่องเตือนข้างล่าง

# wongnok/docs
docs/docs.go:169:2: unknown field LeftDelim in struct literal of type "github.com/swaggo/swag".Spec
docs/docs.go:170:2: unknown field RightDelim in struct literal of type "github.com/swaggo/swag".Spec
FAIL	wongnok/cmd/api [build failed]

General API Info — เขียนเหนือ func main

//	@title			Wongnok API
//	@version		1.0
//	@description	API สำหรับจัดการข้อมูลผู้ใช้
//	@host			localhost:8080
//	@BasePath		/api/v1
//	@schemes		http https

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

ระดับ endpoint

// FindByID godoc
//
//	@Summary		ดึงข้อมูล User รายคน
//	@Description	ค้นหา User จาก UUID แล้วคืนข้อมูลกลับมา
//	@Tags			users
//	@Produce		json
//	@Param			id	path		string	true	"User ID (UUID)"	format(uuid)
//	@Success		200	{object}	user.UserResponse
//	@Failure		404	{object}	httputil.ErrorResponse
//	@Security		BearerAuth
//	@Router			/users/{id} [get]
func (handler *Handler) FindByID(ctx *gin.Context) { /* … */ }

@Param มี 6 ช่อง: <ชื่อ> <path|query|header|body|formData> <type> <true|false> "<คำอธิบาย>" <attribute>

@Success/@Failure: <code> {object|array|string} <package>.<Struct> — ชื่อ type ต้องมี package นำหน้าเสมอ เขียน UserResponse เฉย ๆ swag หาไม่เจอ

ต่อเข้ากับ Gin

import (
    swaggerFiles "github.com/swaggo/files"
    ginSwagger   "github.com/swaggo/gin-swagger"
    _ "wongnok/docs"          // blank import — ไม่ใส่แล้วโหลด spec ไม่ขึ้น
)

router.GET("/swagger/*any", ginSwagger.WrapHandler(swaggerFiles.Handler))
// เปิดที่ localhost:8080/swagger/index.html

รัน swag init

# โครงที่ main.go อยู่ cmd/api/ ใช้แบบนี้ไม่ได้
swag init
#   → cannot parse source files .../main.go: no such file or directory
#   → ไม่มีโฟลเดอร์ docs/ เกิดขึ้นเลย

# ต้องชี้ไฟล์ด้วย -g
swag init -g cmd/api/main.go

ไฟล์ที่ได้: docs/docs.go (ตัวที่ blank import) · docs/swagger.json · docs/swagger.yaml
บรรทัด warning: failed to get package name in dir: ./ ขึ้นแม้ตอนสำเร็จ — ไม่เป็นไร

struct tag ที่มีผลกับเอกสาร

สามพฤติกรรมของ swag ที่ยืนยันด้วยผลรันจริง: Name *string → เอกสารขึ้นเป็น string ธรรมดา · json:"name,omitempty" → ใช้ชื่อ name · method อย่าง ToUser() ถูกมองข้าม swag สนใจแค่ field

เอา swagger.json ไปใช้ต่อ

• GitLab — commit docs/ เข้า repo (อย่าใส่ใน .gitignore) แล้วเปิดไฟล์ กด Display rendered file · ชื่อไฟล์ต้องมีคำว่า swagger หรือ openapi และนามสกุล .json/.yaml/.yml
• Postman — Import → File → swagger.json ได้ collection ครบทุก endpoint
• openapi-generator — openapi-generator generate -i swagger.json -g typescript-axios -o ./client

14 · Redis — สองคำสั่งที่เพิ่มจาก Day 7

เรื่อง Redis ที่เหลือทั้งหมดอยู่ใน บทเรียน 32 และ cheat sheet Day 7 แล้ว สไลด์ Day 8 มีของใหม่จริง ๆ แค่สองคำสั่งนี้

# SET พร้อมตั้งเวลาหมดอายุในคำสั่งเดียว (นิยมใช้สุด)
SET username "devpool" EX 60

# GETDEL — อ่านค่าแล้วลบทิ้งในคำสั่งเดียว (atomic)
GETDEL username

SET … EX 60 ดีกว่า SET แล้วตามด้วย EXPIRE เพราะ ถ้าโปรเซสตายระหว่างสองคำสั่ง key จะค้างอยู่ตลอดไป

15 · Wongnok API spec

กลุ่ม Auth ขัดกฎข้อ 1 และ 7 (เป็น verb และ GET ที่เปลี่ยน state) แต่มีเหตุผลรองรับ — OAuth redirect flow ต้องให้เบราว์เซอร์พาไปเอง ซึ่งทำได้แค่ GET · ดู บทเรียน 42

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

17 · ตารางแปล error / panic ที่เจอบ่อย

18 · Environment Variables — อ่านค่าคอนฟิกให้ไม่พังเงียบ

ทุกอย่างในหัวข้อนี้รันจริงบน Go 1.26.5 darwin/arm64 · ตัวแปรที่ใช้ทดสอบคือ LOG_LEVEL · โปรแกรมพิมพ์ค่าด้วย %q เครื่องหมายคำพูดในผลลัพธ์จึงเป็นของจริง

os.Getenv vs os.LookupEnv — สามกรณีที่ต่างกันจริง

# 1) ตั้งค่าปกติ
$ env LOG_LEVEL=DEBUG ./envtest
Getenv    = "DEBUG"
LookupEnv = "DEBUG", ok=true

# 2) ตั้งเป็นค่าว่าง — ไม่มีอะไรหลังเครื่องหมาย =
$ env LOG_LEVEL= ./envtest
Getenv    = ""
LookupEnv = "", ok=true

# 3) ไม่ได้ตั้งเลย
$ env -u LOG_LEVEL ./envtest
Getenv    = ""
LookupEnv = "", ok=false

ฝั่ง shell ก็แยกไม่ออกเหมือนกัน — echo $LOG_LEVEL และ [ -z "$LOG_LEVEL" ] ให้ผลเหมือนกันทั้งสองกรณี ต้องใช้ท่านี้ถึงจะเห็นความต่าง:

$ export LOG_LEVEL=""; printenv | grep -c '^LOG_LEVEL'
1                       # ตัวแปรมีอยู่จริง แค่ค่าว่าง

$ unset LOG_LEVEL;      printenv | grep -c '^LOG_LEVEL'
0                       # ไม่มีตัวแปรนี้แล้วจริง ๆ

# แบบสั้นในสคริปต์
$ [ -z "${LOG_LEVEL+x}" ] && echo 'UNSET'

แปลง type — env เป็น string เสมอ

func mustEnv(key string) string {
    v, ok := os.LookupEnv(key)
    if !ok {
        log.Fatalf("missing required env %s", key)   // ตายตั้งแต่ตอน start ดีกว่าพังตอนมีคนใช้
    }
    return v
}

func envInt(key string, def int) int {
    raw, ok := os.LookupEnv(key)
    if !ok || raw == "" {
        return def
    }
    n, err := strconv.Atoi(strings.TrimSpace(raw))   // TrimSpace: Atoi ไม่ตัดช่องว่างให้
    if err != nil {
        log.Fatalf("env %s=%q is not an int: %v", key, raw, err)
    }
    return n
}

strconv.Atoi — ผลรันจริงทุกเคส

strconv.ParseBool — รับได้ 12 ค่าเท่านั้น

โค้ดจริงของ Go 1.26.5 (src/internal/strconv/atob.go) เป็น switch เทียบสตริงตรง ๆ 12 case ไม่มี trim ไม่มี lowercase — นี่คือเหตุผลที่ TRUE ผ่านแต่ tRue ไม่ผ่าน

strconv.ParseBool("yes") -> v=false, err=strconv.ParseBool: parsing "yes": invalid syntax
strconv.ParseBool("")    -> v=false, err=strconv.ParseBool: parsing "": invalid syntax

จุดที่หลอกที่สุด ตอน error ParseBool คืน false ซึ่งหน้าตาเหมือน “ตั้งใจปิดฟีเจอร์” เป๊ะ ๆ · คนที่เขียน .env มาจาก YAML หรือ stack อื่น จะพิมพ์ FEATURE_X=yes แล้วงงว่าทำไมฟีเจอร์ไม่เปิด

time.ParseDuration — error message มีสามแบบ

TIMEOUT=30 ที่คนเขียนไฟล์คอนฟิกคิดว่า “สามสิบวินาที” พังทันทีด้วยข้อความ missing unit · ส่วนช่องว่างท้ายบรรทัดไปโผล่เป็น unknown unit "s " ซึ่งอ่านแล้วงงกว่ามาก — สังเกตช่องว่างในเครื่องหมายคำพูดให้ดี

วิธีตั้ง env — ห้าที่ที่ต้องรู้จัก

# assignment เปล่า ๆ ไม่มี export — shell เห็น แต่โปรแกรมไม่เห็น
$ APP_PORT=5555; echo "shell sees: $APP_PORT"; ./api
shell sees: 5555
APP_PORT  =                      ← ว่าง

# ใส่ export แล้วลูกถึงเห็น
$ export APP_PORT=5555; ./api
APP_PORT  = 5555

# inline ชนะ export — และไม่ค้างใน shell
$ export APP_PORT=8080; APP_PORT=7777 ./api; echo "shell still: $APP_PORT"
APP_PORT  = 7777
shell still: 8080

env ข้ามได้หลายทอดจริง — shell → go run → binary เป็นคนละ process กันทั้งหมด แต่ค่าวิ่งถึงครบ:

$ echo "this shell PID = $$"; APP_PORT=6262 go run .
this shell PID = 34148
APP_PORT = 6262
my PID = 34157  parent PID = 34151

Docker — ไม่สืบทอดอัตโนมัติ

$ docker run --rm -e LOG_LEVEL=INFO alpine printenv
PATH=/usr/local/sbin:/usr/local/bin:/usr/sbin:/usr/bin:/sbin:/bin
HOSTNAME=9666ec3f3209
LOG_LEVEL=INFO
HOME=/root

# -e ชื่อเปล่า ๆ = หยิบค่าจาก shell ปัจจุบัน
$ export LOG_LEVEL=FROM_HOST; docker run --rm -e LOG_LEVEL alpine printenv LOG_LEVEL
FROM_HOST

# --env-file vs -e : -e ชนะ
$ printf 'LOG_LEVEL=FROM_FILE\nAPP_PORT=3000\n' > app.env
$ docker run --rm --env-file app.env -e LOG_LEVEL=FROM_FLAG alpine printenv LOG_LEVEL
FROM_FLAG

$ export LOG_LEVEL=FROM_HOST
$ echo $LOG_LEVEL
FROM_HOST
$ docker run --rm alpine printenv LOG_LEVEL; echo exit=$?
exit=1                    # ไม่พิมพ์อะไรเลย

compose และ k8s — ไวยากรณ์อ้างอิง

สองบล็อกนี้เป็นไวยากรณ์สำหรับก็อปไปใช้ ไม่ใช่ผลรัน — ต่างจากบล็อกอื่นในหน้านี้

# docker-compose.yml
services:
  api:
    image: myapi:latest
    environment:
      LOG_LEVEL: INFO
      APP_PORT: "8080"
      POSTGRES_DSN: ${POSTGRES_DSN}   # หยิบจาก shell / .env ของ host
    env_file:
      - app.env

# k8s — ส่วน env ของ container
env:
  - name: LOG_LEVEL
    value: "INFO"

  - name: APP_PORT              # ค่าธรรมดา → ConfigMap
    valueFrom:
      configMapKeyRef:
        name: app-config
        key: APP_PORT

  - name: POSTGRES_DSN          # ความลับ → Secret
    valueFrom:
      secretKeyRef:
        name: app-secret
        key: POSTGRES_DSN

เส้นแบ่ง ConfigMap = ค่าที่เปิดให้ใครดูก็ได้ (log level, port, feature flag) · Secret = ค่าที่หลุดแล้วเดือดร้อน (DSN ที่มีรหัสผ่าน, API key, JWT secret) · ทั้งคู่จบลงที่ตัวแปร env ตัวเดียวกันในสายตาโปรแกรม — โค้ด Go เขียน os.LookupEnv("POSTGRES_DSN") เหมือนกันหมด ไม่ต้องรู้ว่ามาจากไหน

12-Factor — Factor III: Config

“เก็บ config ไว้ใน environment” · นิยามของ config ในที่นี้คือ ทุกอย่างที่ต่างกันระหว่าง deploy — dev, staging, production — เช่น DSN ของฐานข้อมูล, endpoint ของ service อื่น, credential, ชื่อโฮสต์ · ส่วนที่เหมือนกันทุก deploy เช่น routing table หรือชื่อ route ไม่ใช่ config

19 · ตารางแปลง API ที่ออกแบบแย่ → RESTful

ทั้งสี่คู่ลงทะเบียนบน Gin v1.12.0 จริงแล้วยิงเทียบกัน — คู่ที่ 1 กับ 4 ให้ผลลัพธ์เหมือนกันเป๊ะ เส้นแบ่งจึงไม่ได้อยู่ที่ “ทำงานได้ไหม” แต่อยู่ที่สามอย่างข้างล่างนี้

① เส้นที่ 3 — password ใน query โผล่ใน access log จริง

$ curl -s -X POST 'http://127.0.0.1:18080/createUser?name=Alice&password=123456'
$ grep -n '123456' gin-access.log
7:[GIN] 2026/08/21 - 13:01:28 | 200 |  54.083µs | 127.0.0.1 | POST "/createUser?name=Alice&password=123456"

# ฝั่งที่ถูก — ส่ง password ทาง body
$ curl -s -X POST 'http://127.0.0.1:18080/users' \
    -H 'Content-Type: application/json' -d '{"name":"Alice","password":"123456"}'
$ grep -n '123456' gin-access.log
7:[GIN] … POST "/createUser?name=Alice&password=123456"      ← เจอแค่บรรทัดเดิมบรรทัดเดียว

# บรรทัดที่ log ไว้ของ POST /users มีแค่นี้
8:[GIN] 2026/08/21 - 13:01:28 | 201 | 195.958µs | 127.0.0.1 | POST "/users"

gin.Logger() เขียน path + RawQuery ลง log ทุกครั้ง — รหัสผ่านจึงถูกบันทึกเป็น plaintext อ่านได้ตรง ๆ · ส่วน body ไม่ถูก log เลย ทั้งที่ server อ่านค่าได้ครบ · และนี่เพิ่งแค่ log ของ server เราเอง ยังไม่นับ proxy, CDN, browser history และ Referer ที่หัวข้อ 5 เตือนไว้

② เส้นที่ 2 — idempotency ไม่ได้ดูจาก status code

# ✔ DELETE /users/123 ยิงซ้ำ 3 ครั้ง
call 1 -> {"deleted":"123","remaining":1}                  | HTTP 200
call 2 -> {"error":"user not found","id":"123",…}          | HTTP 404
call 3 -> {"error":"user not found","id":"123",…}          | HTTP 404

# ✘ POST /deleteUser?id=123 ยิงซ้ำ 3 ครั้ง
call 1 -> {"deleted":"123","remaining":1}                  | HTTP 200
call 2 -> {"error":"user not found","id":"123",…}          | HTTP 404
call 3 -> {"error":"user not found","id":"123",…}          | HTTP 404

อีกจุดหนึ่ง: 404 ที่ได้ตอนยิงซ้ำ หน้าตาแยกไม่ออกจาก 404 ที่เกิดจากลบของที่ไม่เคยมี — DELETE /users/999 ก็ได้ 404 ตั้งแต่ครั้งแรก · API หลายเจ้าจึงเลือกตอบ 204 No Content ทุกครั้งแทน เพื่อให้ผลลัพธ์เหมือนกันจริง ๆ ทุกครั้ง

③ เส้นที่ 1 และ 4 — ดึงค่าจากคนละที่

GET /getUser?id=123      -> {"extracted_by":"c.Query(\"id\")",  "id":"123", …}
GET /users/123           -> {"extracted_by":"c.Param(\"id\")",  "id":"123", …}
GET /orders?status=paid  -> {"extracted_by":"c.Query(\"status\")","filter_status":"paid", …}
POST /users (JSON body)  -> {"extracted_by":"c.ShouldBindJSON (request body)","name":"Alice","password_len":6}

$ curl -s -w ' | HTTP %{http_code}\n' 'http://127.0.0.1:18080/orders'
{"filter_status":"","orders":[{"id":"o1","status":"paid"},{"id":"o2","status":"pending"},
 {"id":"o3","status":"paid"},{"id":"o4","status":"cancelled"}]} | HTTP 200

c.Param คืนค่าที่ URL-decode แล้ว — ส่ง /users/abc%20xyz เข้าไปได้ "abc xyz" (มีช่องว่างจริง)

อ้างอิง

• MDN — HTTP response status codes — คำนิยามทางการของทุก status
• MDN — CORS · Preflight request
• pkg.go.dev — net/http.ServeMux — ไวยากรณ์ pattern และกฎ precedence ฉบับทางการ
• pkg.go.dev — net/http/httptest
• Gin Documentation · pkg.go.dev
• go-playground/validator — รายการ binding tag ทั้งหมด
• gin-contrib/cors
• swaggo/swag — Declarative Comments Format — annotation ครบทุกตัว
• OpenAPI 2.0 (Swagger 2.0) Specification
• The Twelve-Factor App — III. Config — ต้นทางของหัวข้อ 18
• pkg.go.dev — os.Getenv / os.LookupEnv · strconv · time.ParseDuration
• RFC 9110 §9.2.2 — Idempotent Methods — นิยามทางการที่หัวข้อ 19 อ้างถึง
• Docker — docker run --env · Kubernetes — Define Environment Variables
• Cheat sheet Day 7 — Mockery · Testcontainers · Goose · Redis