query · body · header — ส่งข้อมูลเข้าไปทางไหน

package main

import "github.com/gin-gonic/gin"

func main() {
    r := gin.Default()          // r = router: ตัวจับคู่ "method + path" เข้ากับ handler

    r.GET("/ping", func(c *gin.Context) {   // handler = ฟังก์ชันที่ถูกเรียกเมื่อมี request ตรงกับ route นี้
        c.JSON(200, gin.H{"ok": true})     // c = Context: กล่องที่มีทั้ง request ขาเข้าและ response ขาออก
    })

    r.Run("127.0.0.1:8080")      // เปิดรับ request ค้างไว้ จนกว่าจะกด Ctrl+C
}

1 · หนึ่ง request มีสี่ช่อง ไม่ใช่ช่องเดียว

ตอนคุณกดปุ่มในเว็บ สิ่งที่วิ่งออกไปคือข้อความธรรมดาก้อนหนึ่ง ที่มีรูปแบบตายตัว หน้าตาแบบนี้เป๊ะ ๆ:

POST /recipes?draft=true HTTP/1.1        ← บรรทัดแรก: method + path + query
Host: api.example.com                    ┐
Authorization: Bearer abc123             │ header — บอกว่า "ใครขอ / ขอแบบไหน"
Content-Type: application/json           ┘
                                         ← บรรทัดว่าง = เส้นแบ่งหัวกับตัว
{"title":"ต้มยำกุ้ง","minutes":30}        ← body — เนื้อข้อมูล

อ่านจากบนลงล่างแล้วจะเห็นว่า ทั้งสี่ช่องอยู่คนละที่กันทางกายภาพ:

ทีนี้ประเด็นที่ทำให้มือใหม่เสียเวลาเป็นชั่วโมง: server ไม่ได้เอาสี่ช่องนี้มากองรวมกันแล้วให้คุณค้นทีเดียว ฟังก์ชันอ่าน query อ่านได้เฉพาะ query · ฟังก์ชันอ่าน body อ่านได้เฉพาะ body
ถ้าส่งผิดช่อง คุณจะไม่ได้ error — คุณจะได้ค่าว่าง ซึ่งอ่านยากกว่ามาก

2 · พิสูจน์ว่ามันแยกกันจริง

ผมเขียน handler (ฟังก์ชันที่ทำงานเมื่อ request วิ่งมาถึง route นี้) ตัวเดียว ที่พยายามอ่านคำว่า sort จากทุกช่องพร้อมกัน แล้วยิงเข้าไปสองรอบ — รอบแรกส่ง sort=name ทาง body รอบสองส่งทาง query ทั้งที่ค่าเหมือนกันเป๊ะ:

r.POST("/probe", func(c *gin.Context) {
    q  := c.Query("sort")      // อ่านจาก query string
    pf := c.PostForm("sort")   // อ่านจาก body แบบ form
    raw, _ := io.ReadAll(c.Request.Body)
    c.JSON(200, gin.H{
        "Query_sort": q, "PostForm_sort": pf,
        "GetHeader_ct": c.GetHeader("Content-Type"),
        "rawBody_after": string(raw),
    })
})

# รอบ 1 — sort อยู่ใน body ติดป้าย Content-Type: application/x-www-form-urlencoded
#          (= รูปแบบ body ที่หน้าตาเหมือน query string คือ key=value คั่นด้วย & แบบที่ฟอร์ม HTML ส่งมา)
POST /probe            body: sort=name

# รอบ 2 — sort อยู่ใน query
POST /probe?sort=name  body: (ว่าง)

=== 1) ช่องทางแยกกันไหม: ส่ง sort=name ผ่าน body แบบ form ===
POST   /probe            -> 200 {"GetHeader_ct":"application/x-www-form-urlencoded",
                                 "PostForm_sort":"name","Query_sort":"","rawBody_after":""}
=== 1b) ส่ง sort=name ผ่าน query ===
POST   /probe?sort=name  -> 200 {"GetHeader_ct":"",
                                 "PostForm_sort":"","Query_sort":"name","rawBody_after":""}

3 · คำถามสามข้อ ตัดสินให้จบว่าข้อมูลชิ้นนี้ไปช่องไหน

หัวใจของบทนี้ไม่ใช่ชื่อฟังก์ชันของ Gin แต่คือการตัดสินใจ เวลามีข้อมูลชิ้นใหม่โผล่มาในสเปก ("อยากค้นตามความยากง่ายด้วย") ให้เดินไล่คำถามจากบนลงล่าง เจอ "ใช่" ข้อไหนก่อนก็จบที่ข้อนั้น:

ข้อมูลหนึ่งชิ้นมาถึงมือคุณ
   │
   ├─ 1. มันระบุว่า "resource ไหน" ไหม? ─────── ใช่ ─▶ path    /recipes/42
   │      ถ้าไม่มีมัน server ไม่รู้จะทำกับอะไร
   │
   ├─ 2. มันกรอง / เรียง / แบ่งหน้า ไหม? ────── ใช่ ─▶ query   ?sort=name&limit=10
   │      ตัดออกก็ยังตอบได้ แค่ได้ผลกว้างกว่าเดิม
   │
   ├─ 3. มันคือเนื้อข้อมูลที่จะบันทึก ไหม? ───── ใช่ ─▶ body    {"title":"ต้มยำกุ้ง"}
   │      ของใหม่ที่ server ยังไม่มี / ของที่จะถูกแก้
   │
   └─ 4. มันเป็น metadata ของการเชื่อมต่อ ไหม? ─ ใช่ ─▶ header  Authorization: Bearer …
          ไม่ใช่ข้อมูลของ resource แต่บอกว่า "ใครขอ / ขอมาแบบไหน / อยากได้กลับแบบไหน"

ลองเดินคำถามกับสเปกจริงของ Day 8 (เว็บรวมสูตรอาหาร) ดู:

4 · query — ตัวกรอง ไม่ใช่ตัวระบุ

ฝั่ง Gin อ่าน query ได้สามแบบ และสามแบบนี้ไม่ได้ต่างกันแค่ความสวย ผมรันทั้งสามตัวกับสามสถานการณ์: ส่งค่ามา · ไม่ส่งเลย · ส่ง key มาแต่ค่าว่าง
handler ที่ใช้เรียกทั้งสามตัวกับคีย์ q แล้วตอบกลับเป็น JSON — c.Query("q") → ช่อง Query · c.DefaultQuery("q","x") → ช่อง DefaultQuery · c.GetQuery("q") คืนสองค่า → ช่อง GetQuery_val กับ GetQuery_ok

# ค่า default ที่ใส่ไว้คือ "x" — ผลรันจริง (body ที่ handler ตอบกลับ)
GET /search?q=go
  {"DefaultQuery":"go","GetQuery_ok":true,"GetQuery_val":"go","Query":"go","Query_len":2}
GET /search
  {"DefaultQuery":"x","GetQuery_ok":false,"GetQuery_val":"","Query":"","Query_len":0}
GET /search?q=
  {"DefaultQuery":"","GetQuery_ok":true,"GetQuery_val":"","Query":"","Query_len":0}

บรรทัดที่สองกับสามคือหัวใจ — "ไม่ส่งมาเลย" กับ "ส่งมาแต่ว่าง" ไม่ใช่เรื่องเดียวกัน
c.Query ได้ "" เท่ากันทั้งคู่ แยกไม่ออก · c.DefaultQuery("q","x") ก็แยกไม่ออกในทางที่อันตรายกว่า: พอ client ส่ง ?q= มา ค่า default ไม่ทำงาน (ได้ "" ไม่ใช่ "x")
มีแต่ c.GetQuery ที่คืนตัวที่สองเป็น ok — ตัวเดียวที่แยกสองกรณีนี้ออกจากกันได้

อีกสองพฤติกรรมที่ต้องรู้ก่อนไปเจอเองตอนดึกสองยาม — ผมรันทั้งคู่:

// คีย์ซ้ำได้ และ Query() คืนแค่ตัวแรก
GET /multi?tag=go&tag=web&tag=api
  -> {"Query":"go", "QueryArray":["go","web","api"]}

// query แยกตัวพิมพ์เล็กใหญ่ แต่ header ไม่แยก
GET /case?sort=name&Sort=NAME   (ส่ง header  Authorization: Bearer abc123)
  -> {"header_AUTHORIZATION":"Bearer abc123","header_Authorization":"Bearer abc123",
      "header_authorization":"Bearer abc123","query_Sort":"NAME","query_sort":"name"}

query: sort กับ Sort คือคนละคีย์กันจริง ๆ — พิมพ์ผิดตัวเดียวคือหาย
header: เรียกด้วยตัวพิมพ์แบบไหนก็ได้ค่าเดียวกัน เพราะสเปก HTTP บอกว่าชื่อ header ไม่แยกเล็กใหญ่ และ Go แปลงชื่อให้เป็นรูปมาตรฐานให้เอง
สองบรรทัดนี้คือเหตุผลว่าทำไม c.GetHeader("authorization") ใช้ได้ แต่ c.Query("Sort") ทำให้ฟีเจอร์เรียงลำดับเงียบไปทั้งฟีเจอร์

5 · ผูก query ทั้งชุดเป็น struct — และ tag ที่คนใส่ผิดกันทุกคน

พอ query มีสี่ห้าตัว การเรียก c.Query ทีละตัวแล้ว strconv.Atoi เองจะเริ่มเละ Gin ให้ผูกทั้งชุดเข้า struct ได้ด้วย ShouldBindQuery — แต่มันอ่าน tag ชื่อ form ไม่ใช่ json

type ListQuery struct {
    Sort  string `form:"sort,default=created_at" binding:"omitempty,oneof=created_at name rating"`
    Limit int    `form:"limit,default=20" binding:"min=1,max=100"`
    Page  int    `form:"page,default=1" binding:"min=1"`
}

r.GET("/recipes", func(c *gin.Context) {
    var q ListQuery
    if err := c.ShouldBindQuery(&q); err != nil {
        c.JSON(400, gin.H{"error": err.Error()})
        return
    }
    c.JSON(200, gin.H{"sort": q.Sort, "limit": q.Limit, "page": q.Page})
})

อ่าน tag แถวแรกทีละท่อน: form:"sort" = ไปหยิบ query ชื่อ sort · default=created_at = ถ้าไม่ส่งมาให้ใช้ค่านี้แทน (อยู่ใน tag form) · binding:"..." = กฎตรวจค่าหลังหยิบมาแล้ว โดย omitempty แปลว่า "ว่างได้ ถ้าว่างก็ข้ามกฎที่เหลือไป" ส่วน oneof= คือรายชื่อค่าที่ยอมรับ

ผลรันจริงทั้งห้าเคส:

GET /recipes?sort=name&limit=10&page=2  -> 200 {"limit":10,"page":2,"sort":"name"}
GET /recipes                            -> 200 {"limit":20,"page":1,"sort":"created_at"}
GET /recipes?limit=1000                 -> 400 {"error":"Key: 'ListQuery.Limit' Error:Field validation for 'Limit' failed on the 'max' tag"}
GET /recipes?sort=price                 -> 400 {"error":"Key: 'ListQuery.Sort' Error:Field validation for 'Sort' failed on the 'oneof' tag"}
GET /recipes?limit=abc                  -> 400 {"error":"strconv.ParseInt: parsing \"abc\": invalid syntax"}

สามอย่างที่ได้มาฟรีจาก struct เดียว: ค่า default (default=20), แปลงชนิดให้ (query เป็นสตริงเสมอ แต่ q.Limit เป็น int แล้ว), และ กันค่าประหลาด — ?limit=1000 ถูกปฏิเสธตั้งแต่ประตู ไม่ทันได้ไปถาม database ว่า "ขอ 1000 แถว"

6 · body — เนื้อข้อมูลที่จะบันทึก

body คือช่องเดียวที่ยาวได้ไม่จำกัดในทางปฏิบัติ และเป็นช่องเดียวที่ไม่ปรากฏใน URL มันจึงเป็นที่ของ "ของใหม่ที่จะถูกเก็บ" — คู่กับ method ที่แปลว่าเขียน: POST / PUT / PATCH

POST /recipes                      // สร้างของใหม่ — body คือของทั้งชิ้น
Content-Type: application/json
{"title":"ต้มยำกุ้ง","minutes":30,"difficulty":"medium"}

PUT /recipes/42                    // แทนที่ทั้งชิ้น — path บอกว่าชิ้นไหน, body บอกว่าเป็นอะไร
{"title":"ต้มยำกุ้งน้ำข้น","minutes":35,"difficulty":"medium"}

PATCH /recipes/42                  // แก้บางส่วน — body มีเฉพาะ field ที่จะแก้
{"minutes":35}

สังเกตว่า PUT /recipes/42 ใช้สองช่องพร้อมกัน — 42 อยู่ใน path (ระบุตัว) ส่วนเนื้อหาอยู่ใน body (เนื้อข้อมูล)
คนใหม่มักเผลอยัด id ลงไปใน body ด้วย แล้วเกิดคำถามที่ตอบไม่ได้: ถ้า PUT /recipes/42 แต่ body เขียน {"id":99,...} จะเชื่อใคร? ให้ path เป็นเจ้าของคำตอบเสมอ แล้ว id ใน body ก็ไม่ต้องมีตั้งแต่แรก

POST /recipes/search
{"id":42,
 "q":"ต้มยำ",
 "sort":"rating",
 "limit":10}

GET /recipes/42

GET /recipes
    ?q=ต้มยำ
    &sort=rating
    &limit=10

7 · header — metadata ของการเชื่อมต่อ

ไม้บรรทัดของ header คือ: มันจะยังจริงอยู่ไหมถ้าเปลี่ยนไปเรียก endpoint อื่น (endpoint = คู่ "method + path" หนึ่งคู่ เช่น GET /recipes คือ endpoint หนึ่ง)
token ของฉัน — จริงอยู่ทุก endpoint · "ฉันส่ง JSON" — จริงทุกครั้งที่ฉันส่ง JSON · แต่ "เรียงตามคะแนน" จริงเฉพาะกับ GET /recipes เท่านั้น → อันหลังคือ query ไม่ใช่ header

คู่ที่คนสลับกันบ่อยที่สุดคือ Content-Type กับ Accept
อยู่ใน request เหมือนกันแต่คนละเรื่อง: Content-Type พูดถึงของที่แนบไปกับ request นี้ ส่วน Accept พูดถึงของที่อยากได้กลับมา
เวลาส่ง GET ที่ไม่มี body การใส่ Content-Type จึงไม่มีความหมายอะไรเลย — ไม่มีของให้ติดป้าย

8 · กับดักตัวจริง — อย่าส่ง token หรือ password ทาง query

ถึงหัวข้อที่ผมอยากให้จำมากที่สุดของบท มันไม่ใช่เรื่องความสวยงามของ API แต่เป็นเรื่องที่ทำให้บริษัทต้อง revoke token ทั้งระบบ (= ยกเลิกบัตรผ่านของทุกคนแล้วออกใหม่)
ผมเปิด server จริงด้วย gin.Default() ซึ่งมี Logger ติดมาให้ตามค่า default
Logger คือตัวที่พิมพ์ access log ออกมาหนึ่งบรรทัดต่อหนึ่ง request (เวลา · status · path ที่ถูกเรียก)
จากนั้นผมยิงเข้าไปสามครั้ง แต่ละครั้งส่งความลับคนละช่องกัน:

$ curl "http://127.0.0.1:18135/orders?token=SECRET-abc123&sort=name"

$ curl -H "Authorization: Bearer SECRET-abc123" \
       "http://127.0.0.1:18135/orders?sort=name"

$ curl -X POST -H "Content-Type: application/json" \
       -d '{"password":"p@ssw0rd"}' "http://127.0.0.1:18135/login"

[GIN] 2026/08/20 - 22:04:34 | 200 | 104.125µs |       127.0.0.1 | GET      "/orders?token=SECRET-abc123&sort=name"
[GIN] 2026/08/20 - 22:04:34 | 200 |  111.75µs |       127.0.0.1 | GET      "/orders?sort=name"
[GIN] 2026/08/20 - 22:04:34 | 200 |  74.25µs |       127.0.0.1 | POST     "/login"

มาตรฐาน OAuth 2.0 Bearer Token (RFC 6750 — ข้อตกลงกลางว่าจะส่ง "บัตรผ่าน" ของผู้ใช้กันยังไง) เองก็นิยามวิธีส่ง token ทาง query ไว้จริง แต่กำกับไว้ว่า ไม่ควรใช้ และให้เหตุผลตรงกับที่เราเพิ่งเห็น — URL ที่มี token มีโอกาสสูงมากที่จะถูกจดลง log
สรุปเป็นกฎที่ใช้ได้ตลอดชีวิต: อะไรที่หลุดแล้วต้องรีเซ็ต — ห้ามอยู่ใน URL (token, password, OTP, เลขบัตร, เลขบัตรประชาชน) ให้ไป header หรือ body เท่านั้น

9 · GET ที่มี body — ทำได้ แต่ห้ามพึ่ง

คำถามที่ต้องมีคนถามเสมอ: "ถ้าเงื่อนไขค้นหาซับซ้อนมาก ส่ง GET พร้อม body JSON เลยได้ไหม"
ทางเทคนิค — ได้ ผมรัน server จริงแล้วยิงด้วย curl ตรง ๆ handler อ่าน body ออกครบ:

$ curl -X GET -H "Content-Type: application/json" -d '{"sort":"name"}' http://127.0.0.1:18136/echo
{"body":"{\"sort\":\"name\"}","bodyLen":15,"method":"GET"}

$ curl http://127.0.0.1:18136/echo
{"body":"","bodyLen":0,"method":"GET"}

แต่ "รันบนเครื่องตัวเองแล้วได้" กับ "ใช้ได้จริงบนอินเทอร์เน็ต" คนละเรื่องกัน
สเปก HTTP (RFC 9110) บอกไว้ว่า body ที่ติดมากับ GET ไม่มีความหมายที่นิยามไว้ และ server มีสิทธิ์ปฏิเสธ request แบบนั้นได้ — ซึ่งแปลว่าทุกตัวที่อยู่ระหว่างทาง (proxy, CDN, gateway, API client library, เครื่องมือทดสอบ) มีสิทธิ์ตัด body ทิ้งอย่างถูกต้องตามสเปก

10 · สรุปเป็นตารางเดียว

แถวสุดท้ายมีตัวเดียวที่ต้องระวัง: query เท่านั้นที่แยกตัวพิมพ์เล็กใหญ่
ผมยิง {"TITLE":"ต้มยำ"} เข้า struct ที่ติด json:"title" แล้วได้ 200 {"title":"ต้มยำ"} — เข้า field ปกติ เพราะ encoding/json ของ Go เทียบชื่อแบบไม่สนตัวพิมพ์ให้อยู่แล้ว
แต่ ?Sort=name กับ ?sort=name คือคนละคีย์จริง ๆ ตามที่รันให้ดูในหัวข้อ 4

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

GET /recipes?limit=1000  -> 400 {"error":"Key: 'ListQuery.Limit' Error:Field validation for 'Limit' failed on the 'max' tag"}
GET /recipes?limit=abc   -> 400 {"error":"strconv.ParseInt: parsing \"abc\": invalid syntax"}

อ้างอิง

• RFC 9110 §9.3.1 — GET — สเปกบอกเองว่า body ที่ติดมากับ GET ไม่มีความหมายที่นิยามไว้ และ server ปฏิเสธได้
• RFC 9110 §5.1 — Field Names — ที่มาของ "ชื่อ header ไม่แยกตัวพิมพ์เล็กใหญ่"
• RFC 6750 §2.3 — URI Query Parameter — วิธีส่ง token ทาง query มีนิยามอยู่จริง แต่กำกับว่า SHOULD NOT ใช้ เพราะ URL มักถูกจดลง log
• pkg.go.dev — Context.GetQuery · DefaultQuery · QueryArray
• pkg.go.dev — ShouldBindQuery · ShouldBindUri — ตัวไหนอ่าน tag อะไร
• pkg.go.dev — http.Header.Get — อธิบายว่าทำไมตัวพิมพ์ของชื่อ header ไม่สำคัญ
• pkg.go.dev — validator/v10 — ที่มาของ tag oneof, min, max ที่ใช้ในบทนี้
• MDN — Accept · Content-Type — เส้นแบ่งระหว่าง "ของที่ส่งไป" กับ "ของที่อยากได้กลับ"