คำถามที่พบบ่อยเรื่องการทำงานเป็นทีม: contract, config และ fixture

สรุปสั้น ๆ: ตกลงสิ่งเหล่านี้ครั้งเดียวในข้อตกลงของทีม — envelope แบบ {"data":…,"meta":…} ที่ใช้ HTTP status code, สไตล์การตั้งชื่อเดียวทั้งเว็บไซต์, timestamp แบบ RFC 3339 ที่มีเขตเวลา และ enum แบบ string — แล้วพัฒนา API ใหม่ทุกตัวบน contract เดียวกันโดยเพิ่มฟิลด์เท่านั้น ไม่เปลี่ยนหรือลบฟิลด์เดิม

คำถามเหล่านี้ไม่มีคำตอบที่ถูกเพียงคำตอบเดียว แต่ทีมต้องมีคำตอบเดียว — ไม่เช่นนั้น API ใหม่ทุกตัวจะเริ่มเถียงเรื่องเดิมอีกครั้ง

1. Contract ของ API

API ควรคืนข้อมูลโครงสร้างแบบไหน?

รูปแบบที่พบบ่อยสามแบบ แต่ละแบบมีต้นทุน:

สำหรับ API ธุรกิจภายใน แนะนำ "envelope แบบ resource + HTTP status code ที่บอกผลลัพธ์":

复制{
  "data": [{ "id": "1", "name": "示例" }],
  "meta": { "total": 128, "page": 2, "pageSize": 20 }
}

สำหรับ error ให้ใช้ HTTP status code ร่วมกับ body ของ error ที่มีโครงสร้าง แทนการซ้อน code อีกชั้น:

复制{
  "error": {
    "type": "validation_failed",
    "message": "请求参数校验失败",
    "details": [
      { "path": "/email", "reason": "格式不正确" }
    ]
  }
}

จุดสำคัญ: HTTP status code บอกความสำเร็จหรือความล้มเหลวอยู่แล้ว ดังนั้น business code จึงซ้ำซ้อน เมื่อสองระบบอยู่ร่วมกัน ความไม่สอดคล้องอย่าง "201 แต่ code เป็น 500" แทบจะหลีกเลี่ยงไม่ได้

เลี่ยง array เปล่า เมื่อระดับบนสุดเป็น array คุณแนบ pagination, total หรือ cursor ไม่ได้ และการเพิ่มทีหลังหมายถึงต้องแก้ฝั่งผู้เรียกทุกตัว

ชื่อฟิลด์ควรใช้ snake_case หรือ camelCase?

เลือกอย่างใดอย่างหนึ่ง ใช้ทั้งเว็บไซต์ และอย่าปนกันภายในเอกสาร JSON หนึ่งฉบับ

เกณฑ์:

1. ใครเป็นผู้ใช้ JSON นี้: ถ้า frontend เป็นหลักให้ camelCase ถ้า data pipeline และบริการ Python เป็นหลักให้ snake_case;
2. มันแมปกับคอลัมน์ฐานข้อมูลโดยตรงไหม: snake_case ประหยัดชั้นแปลงเมื่อส่งโครงสร้างตารางตรง ๆ;
3. ความต่อเนื่องของระบบเดิม: คงสิ่งที่ API เดิมใช้ไว้ ความสม่ำเสมอสำคัญกว่าความถูกต้อง

ถ้าจำเป็นต้องแปลงจริง ๆ ให้ทำที่ขอบ (gateway หรือชั้น request ของ frontend) ไม่ใช่กระจายการเรียก toCamelCase ทั่วโค้ดธุรกิจ

ฟิลด์เวลาควรใช้รูปแบบไหน?

ใช้ string แบบ RFC 3339 / ISO 8601 ที่มี offset ของเขตเวลา:

复制{
  "createdAt": "2026-10-30T11:37:57+08:00",
  "updatedAt": "2026-10-30T03:37:57Z"
}

จุดสำคัญ:

• ต้องมีเขตเวลา: 2026-10-30 11:37:57 ที่ไม่มีเขตเวลาจะพังในสถานการณ์ข้ามเขตเวลาอย่างแน่นอน;
• ใช้ Z หรือ offset อย่างสม่ำเสมอ: ทั้งสองถูกต้อง แต่ห้ามปนกันภายใน API หนึ่งตัว;
• เลี่ยง numeric timestamp: ไม่ว่าจะเป็นวินาทีหรือมิลลิวินาที และจะนับ leap second ด้วยหรือไม่ ทุกทีมต้องตีความใหม่เอง เมื่อต้องกระชับ ให้ใช้จำนวนเต็มมิลลิวินาที แต่ระบุหน่วยให้ชัดในเอกสาร

แนะนำชื่อฟิลด์ที่ลงท้ายด้วย At เช่น createdAt / updatedAt / deletedAt จะเห็นได้ทันทีว่าค่านั้นเป็นจุดในเวลา ไม่ใช่ช่วงเวลา สำหรับช่วงเวลาใช้ timeoutMs, ttlSeconds — ใส่หน่วยไว้ในชื่อ

ค่า null ควรเป็น null หรือละเว้นฟิลด์?

ขึ้นกับว่า "ฟิลด์นี้มีความหมายหรือไม่":

กรณีที่สามคือกรณีที่ถูกละเลยบ่อยที่สุด ในคำขอ PATCH:

复制{ "nickname": null }

อันนี้หมายถึง "ล้างชื่อเล่น" ส่วนการไม่ใส่ nickname ใน request body หมายถึง "อย่าแตะชื่อเล่น" ถ้าคุณถือทั้งสองอย่างเป็น "ล้างค่า" ผู้ใช้ที่แก้ email ก็จะลบชื่อเล่นของตัวเองไปด้วย

ย้ำอีกครั้ง: อย่าใช้ undefined มันไม่ใช่ค่า JSON ที่ถูกต้อง และ JSON.stringify จะตัด key ออกทั้งหมด พฤติกรรมจึงตรงกับ "ละเว้น" ขณะที่โค้ดดูเหมือน "ส่งค่าว่างเข้ามาชัดเจน"

ฟิลด์ boolean ควรตั้งชื่ออย่างไร?

ใช้คำนำหน้า is / has / can / should และเลี่ยงการปฏิเสธ

复制{
  "isActive": true,
  "hasPassword": false,
  "canEdit": true
}

บทเรียนสามข้อ:

1. ห้ามใช้การปฏิเสธ: isDisabled: false บังคับให้ผู้อ่านต้องกลับค่าหนึ่งครั้ง; isEnabled: true ตรงกว่า การปฏิเสธซ้อน (isNotDisabled) เป็นหายนะ;
2. อย่าใช้ตัวเลขแทน boolean: "enabled": 1 ทำให้ผู้ใช้ทุกคนต้องเขียน === 1 หนึ่งครั้ง;
3. อย่าใช้ string: "enable": "true" เป็น truthy ใน JavaScript และ if (data.enable) ก็เป็นจริงกับ "false" ด้วย; bug แบบนี้ตามรอยยากมาก

ฟิลด์ enum ควรใช้ตัวเลขหรือ string?

ใช้ string เว้นแต่มีข้อจำกัดเรื่องพื้นที่จัดเก็บหรือแบนด์วิดท์ชัดเจน

复制{ "status": "active" }

เทียบกับ { "status": 1 } string ชนะเพราะ:

• log, ไฟล์ packet capture และฐานข้อมูลอ่านได้ตรง ๆ โดยไม่ต้องเปิดตารางแมป;
• การเพิ่มค่า enum ไม่เปลี่ยนความหมายของค่าที่มีอยู่ (การแทรกค่าใน enum แบบตัวเลขจะเลื่อนทุกอย่าง);
• frontend ไม่ต้องดูแลแมป 1 → 'active' ให้ตรงกัน

ต้นทุนคือไบต์ที่เพิ่มขึ้นเล็กน้อย ซึ่งแทบไม่มีความหมายหลังบีบอัด

แนวปฏิบัติคู่กัน: ใช้ตัวพิมพ์เล็ก + ขีดล่างสำหรับค่า enum แบบ string (pending_review) และจำกัดด้วย enum ใน Schema เพื่อให้ค่าที่ไม่ถูกต้องถูกปฏิเสธในขั้น validation

2. Configuration และ fixture

config ควรเป็น JSON, YAML หรือ TOML?

เลือกตามวัตถุประสงค์ ไม่ใช่ตามความชอบ:

ข้อผิดพลาดที่พบบ่อยในทีมคือเก็บ config ธุรกิจเป็น YAML — การแปลงชนิดโดยนัยของ YAML (1.0 กลายเป็น number, NO กลายเป็น boolean, 2026-10-30 กลายเป็น date) ให้ผลต่างกันในแต่ละ parser

ถ้า config ต้องถูกตรวจอย่างเข้มงวดด้วยโปรแกรม ให้เลือก JSON + Schema และอธิบาย comment ผ่านฟิลด์ _comment หรือเอกสารแยก

ควรจัดระเบียบ fixture สำหรับทดสอบอย่างไร?

จัดตาม "baseline หนึ่งชุด + diff น้อยที่สุด" ไม่ใช่คัดลอก JSON ก้อนใหญ่สำหรับทุกกรณีทดสอบ

复制fixtures/
├─ users/
│  ├─ base.json              # object ผู้ใช้พื้นฐาน
│  ├─ no-email.json          # ขาดเฉพาะ email
│  └─ invalid-age.json       # เฉพาะ age ที่นอกช่วง
└─ fixtures.ts               # ฟังก์ชันช่วยโหลดและ merge แบบตื้น

复制import baseUser from './users/base.json';

export function makeUser(overrides: Partial<User> = {}): User {
  return { ...baseUser, ...overrides };
}

ด้วยวิธีนี้กรณีทดสอบใหม่เขียนแค่ฟิลด์ที่ต่าง และการเปลี่ยนฟิลด์ใน baseline จะอัปเดตทุกกรณีโดยอัตโนมัติ

กฎสามข้อ:

1. fixture ต้องผ่าน Schema validation: fixture baseline เองก็ควรเป็นข้อมูลที่ถูกต้อง;
2. อย่าส่งข้อมูลจริงจาก production ออกมา: เบอร์โทร, เลขบัตรประชาชน และที่อยู่ล้วนเป็นข้อมูลส่วนบุคคล;
3. fixture ควรอยู่ใน version control แต่ต้องเล็ก: ไฟล์เดียวที่เกินหลายสิบ KB สมควรถูกตัดหรือสร้างขึ้นมาใหม่

จะลด merge conflict ในไฟล์ JSON ได้อย่างไร?

JSON ขัดแย้งกันง่าย: formatter จะจัดรูปแบบใหม่ทั้งไฟล์ในครั้งเดียว สองคนที่แต่ละคนแก้คนละบรรทัดจึงขัดกันทั้งไฟล์

กลยุทธ์สี่ข้อ:

1. รวมรูปแบบให้เป็นหนึ่งเดียวและใส่ใน .editorconfig: การย่อหน้า, การขึ้นบรรทัดใหม่ และบรรทัดใหม่ท้ายไฟล์ที่สม่ำเสมอช่วยเลี่ยง diff ที่ไม่เกี่ยวกัน;
2. เรียง key: ตกลงลำดับตัวอักษร เพื่อให้ฟิลด์ใหม่ไม่ชนกับจุดแทรกของคนอื่น;
3. แยกไฟล์: แบ่ง config.json ก้อนใหญ่เป็นหลายไฟล์ตามโดเมน พื้นที่ขัดแย้งก็เล็กลงเอง;
4. เลี่ยง commit แบบ "จัดรูปแบบใหม่ทั้งหมด": แยกการจัดรูปแบบกับการเปลี่ยนธุรกิจเป็นสอง commit เพื่อให้ review อ่านได้

ถ้าทีมใช้ lock file (pnpm-lock.yaml, package-lock.json) อย่า merge ด้วยมือ ให้สร้างใหม่แทน:

复制git checkout --theirs pnpm-lock.yaml
pnpm install

จะรักษาความเข้ากันได้ระหว่างเวอร์ชันได้อย่างไร?

หลักการคือ "เพิ่ม ไม่เปลี่ยน ไม่ลบ"

กลไกสนับสนุน:

• ผู้ใช้ฝั่งปลายทางอ่านแบบ "ผ่อนปรน": เพิกเฉยฟิลด์ที่ไม่รู้จักและให้ค่าเริ่มต้นกับฟิลด์ที่หายไป;
• เซิร์ฟเวอร์เก็บฟิลด์เก่าไว้ระยะหนึ่งและคืน header Deprecation ใน response เป็นคำใบ้;
• ใน Schema อย่าทำเครื่องหมายฟิลด์ใหม่เป็น required และติดแท็กฟิลด์ที่เลิกใช้ด้วย deprecated: true

จะตรวจสอบ contract ใน CI ได้อย่างไร?

ถือ Schema เป็นส่วนหนึ่งของโค้ดและตรวจทุก commit

复制# ตรวจข้อมูลตัวอย่างกับ Schema (ใช้ ajv-cli)
npx ajv-cli validate -s schemas/user.json -d "fixtures/users/*.json" --strict=false

รันสามอย่างใน CI:

1. ความถูกต้องของ Schema เอง: การประกาศ $schema ถูกต้องหรือไม่ และ $ref resolve ได้หรือไม่;
2. fixture ตรงกับ Schema หรือไม่: ยืนยันว่าข้อมูลทดสอบไม่คลาดเคลื่อน;
3. contract เข้ากันได้ย้อนหลังหรือไม่: เทียบกับเวอร์ชันก่อนหน้าและตรวจฟิลด์ที่ถูกลบหรือชนิดที่เปลี่ยน

ข้อที่สามต้องมีเครื่องมือสนับสนุน (เช่น openapi-diff หรือ json-schema-diff) ถ้าไม่มีอย่างน้อยให้ใช้สคริปต์เทียบการเปลี่ยนแปลงใน array required และชุด key ใน properties

3. สรุปเร็ว