วิธีจัดการ Environment และตัวแปรลับใน Apidog (Dev, Staging, Prod)

ทุกทีม API ล้วนเจออุปสรรคเดียวกัน คำขอแรกที่คุณสร้างจะชี้ไปยังเซิร์ฟเวอร์เดียว โดยมีโทเค็นเดียวที่วางอยู่ในส่วนหัว จากนั้นมีสภาพแวดล้อม Staging ตามมา แล้วก็ Production ทันใดนั้นคุณก็ต้องแก้ไข URL ด้วยมือทุกครั้งก่อนการรัน และมีคนทดสอบ endpoint สำหรับลบกับระบบ Production เนื่องจาก base URL เก่าเกินไป ตัวแปรสภาพแวดล้อมของ API มีอยู่เพื่อขจัดความผิดพลาดประเภทนี้ทั้งหมด และ Apidog ได้สร้างสิ่งเหล่านี้ให้เป็นส่วนหลักของผลิตภัณฑ์ แทนที่จะเป็นส่วนเสริม

คำแนะนำนี้จะแสดงวิธีตั้งค่าสภาพแวดล้อม Dev, Staging และ Prod ใน Apidog จัดเก็บโทเค็นและ API key เป็นตัวแปรแทนที่จะเป็นสตริงที่เขียนตายตัว รักษาข้อมูลลับจริงให้อยู่นอกระบบคลาวด์ด้วยค่าในเครื่อง และส่งผ่านสภาพแวดล้อมไปยัง CI ผ่าน Apidog CLI หากคุณต้องการภาพรวมที่กว้างขึ้นว่า ไคลเอนต์ API ที่มีการจัดการสภาพแวดล้อมและข้อมูลลับ ควรจัดการอะไรบ้าง เราได้กล่าวถึงเรื่องนั้นแยกต่างหากแล้ว ในที่นี้เราจะเน้นการปฏิบัติจริง

ทำไม URL และโทเค็นที่เขียนตายตัวถึงใช้งานไม่ได้เมื่อมีสภาพแวดล้อมที่สอง

เมื่อมีสภาพแวดล้อมเดียว การเขียนโค้ดตายตัวก็ใช้งานได้ดี https://api.acmepay.dev อยู่ในทุกคำขอ โทเค็นของคุณอยู่ในทุกส่วนหัว Authorization และยังไม่มีปัญหาอะไร

ปัญหาจะเริ่มต้นขึ้นเมื่อมีสภาพแวดล้อมที่สองปรากฏขึ้น:

ทุกคำขอต้องแก้ไขเพื่อกำหนดเป้าหมายใหม่ ห้าสิบ endpoint ที่ชี้ไปที่ dev หมายถึงการแก้ไข URL ห้าสิบครั้งเพื่อทดสอบ staging จากนั้นอีกห้าสิบครั้งเพื่อสลับกลับ คุณจะต้องพลาดบางอย่าง
โทเค็นรั่วไหลข้ามขอบเขต API key ของระบบ production ที่วางลงใน request body จะถูกบันทึกพร้อมกับโปรเจกต์ แชร์กับทีม และส่งออกไปพร้อมกับคอลเลกชัน ระเบียบวิธี Twelve-Factor App ชี้แจงเรื่องนี้อย่างตรงไปตรงมา: การกำหนดค่าจะแตกต่างกันไประหว่างการ deploy แต่โค้ดไม่ต่างกัน ดังนั้นการกำหนดค่าจึงไม่ควรอยู่ใน artifact ที่คุณแชร์
การรันจะหยุดไม่สามารถทำซ้ำได้ เมื่อ URL และข้อมูลรับรองอยู่ในแต่ละคำขอ การ "รัน smoke tests กับ staging" จะกลายเป็นการค้นหาและแทนที่ด้วยตนเอง แทนที่จะเป็นการสลับด้วยคลิกเดียว

วิธีแก้ปัญหานี้เป็นที่รู้จักกันมานานและได้รับการพิสูจน์แล้ว: แยกนิยามของคำขอ (เมธอด, พาธ, บอดี้, การยืนยัน) ออกจากบริบทการ deploy (base URL, ข้อมูลรับรอง, ID เฉพาะสภาพแวดล้อม) คำขอจะคงเหมือนกันทุกที่ มีเพียงบริบทเท่านั้นที่เปลี่ยนแปลงไป

Apidog สร้างแบบจำลองสภาพแวดล้อมและตัวแปรอย่างไร

Apidog แบ่งปัญหาออกเป็นสองส่วนที่ทำงานร่วมกัน

**สภาพแวดล้อม (environment)** คือบริบทที่มีชื่อ เช่น Dev, Staging หรือ Prod แต่ละสภาพแวดล้อมมี base URL ของตัวเอง (เซิร์ฟเวอร์ที่คำขอจะถูกส่งไป) และชุดค่าตัวแปรของตัวเอง เมื่อสลับสภาพแวดล้อม ทุกคำขอในโปรเจกต์จะถูกกำหนดเป้าหมายใหม่พร้อมกัน ดังที่ เอกสารการจัดการสภาพแวดล้อม อธิบายไว้

**ตัวแปร (variable)** คือตัวยึดตำแหน่งที่มีชื่อที่คุณอ้างถึงเป็น {{variable_name}} ได้ทุกที่ที่มีค่า: URL, query params, headers, request bodies และ scripts ณ รันไทม์ Apidog จะแก้ไขตัวยึดตำแหน่งนั้นตามสภาพแวดล้อมที่ใช้งานอยู่และขอบเขตอื่นๆ ที่เกี่ยวข้อง

ขอบเขตของตัวแปรและลำดับความสำคัญ

Apidog แก้ไขตัวแปรผ่านขอบเขตห้าแบบ จากลำดับความสำคัญต่ำสุดไปสูงสุด: global, module, environment, data และ local

ขอบเขต	อยู่ที่ไหน	การใช้งานทั่วไป
Global	ทั้งโปรเจกต์, ทุกสภาพแวดล้อม	ค่าคงที่ เช่น `{{api_version}}`
Module	โมดูลเดียวของโปรเจกต์	การตั้งค่าต่อบริการในโปรเจกต์ไมโครเซอร์วิส
Environment	เฉพาะสภาพแวดล้อมที่ใช้งานอยู่	`{{base_url}}`, `{{auth_token}}`, `{{merchant_id}}`
Data	ไฟล์ CSV/JSON ภายนอกในการทดสอบ	อินพุตการทดสอบทีละแถว
Local (ชั่วคราว)	หนึ่งคำขอหรือการทดสอบ แล้วหายไป	โทเค็นที่ดึงออกมากลางสถานการณ์

ลำดับความสำคัญมีความสำคัญในทางปฏิบัติ กำหนด {{auth_token}} เป็นค่าสำรองแบบ global แล้วมันจะทำงานได้ทุกที่ แต่ทันทีที่สภาพแวดล้อม Staging ของคุณกำหนด {{auth_token}} ของตัวเอง ค่าของสภาพแวดล้อมจะชนะเมื่อ Staging ทำงานอยู่ นั่นคือสิ่งที่คุณต้องการ: ค่าเริ่มต้นที่ใช้ร่วมกันอยู่ด้านล่าง และการแทนที่เฉพาะสภาพแวดล้อมอยู่ด้านบน สำหรับการเจาะลึกแต่ละขอบเขต โปรดดูคำแนะนำของเราเกี่ยวกับ การควบคุมตัวแปรใน Apidog

พฤติกรรมหนึ่งที่ทำให้คนสับสนคือ: ตัวแปร local ถูกออกแบบมาให้เป็นแบบชั่วคราว ตั้งค่าในสคริปต์แล้วมันจะหายไปเมื่อการรันเสร็จสิ้น นี่เป็นคุณสมบัติสำหรับค่าชั่วคราวภายในสถานการณ์ทดสอบ และเป็นข้อผิดพลาดในแบบจำลองความคิดของคุณหากคุณคาดหวังว่ามันจะคงอยู่ สิ่งที่คุณต้องการในวันพรุ่งนี้ควรอยู่ในตัวแปรสภาพแวดล้อมหรือตัวแปร global

ตั้งค่า dev, staging และ prod ใน Apidog

นี่คือขั้นตอนการทำงานสำหรับ API การชำระเงินที่มีการ deploy สามแบบ

1. สร้างสามสภาพแวดล้อม

เปิดการจัดการสภาพแวดล้อมจากมุมขวาบนของโปรเจกต์ และสร้างสภาพแวดล้อมใหม่สำหรับการ deploy แต่ละครั้ง ตั้งชื่อและ base URL ให้แต่ละรายการดังนี้:

Dev → https://api-dev.acmepay.dev
Staging → https://api-staging.acmepay.dev
Prod → https://api.acmepay.com

เก็บ base URL โดยมีคำนำหน้าโปรโตคอลและไม่มีเครื่องหมายทับท้าย เพื่อให้พาธสามารถรวมกันได้อย่างเรียบร้อย

2. กำหนดชื่อตัวแปรเดียวกันในแต่ละสภาพแวดล้อม

ความสอดคล้องกันคือเคล็ดลับทั้งหมด ทุกสภาพแวดล้อมกำหนดชื่อตัวแปรเดียวกันแต่มีค่าต่างกัน:

ตัวแปร	Dev	Staging	Prod
`{{auth_token}}`	dev token	staging token	prod token
`{{merchant_id}}`	`mrc_test_449`	`mrc_stg_449`	`mrc_live_8821`
`{{webhook_secret}}`	dev secret	staging secret	prod secret

3. อ้างอิงตัวแปรในคำขอ ไม่ใช่ค่าดิบ

คำขอสร้างการเรียกเก็บเงินจะมีลักษณะเช่นนี้ในทุกที่:

POST /v1/charges
Authorization: Bearer {{auth_token}}

{
  "merchant_id": "{{merchant_id}}",
  "amount": 1999,
  "currency": "usd"
}

base URL ไม่ปรากฏเลย; Apidog จะเพิ่ม base URL ของสภาพแวดล้อมที่ใช้งานอยู่โดยอัตโนมัติ ไม่มีสิ่งใดในนิยามของคำขอที่ระบุชื่อสภาพแวดล้อม ซึ่งทำให้มันพกพาได้

4. สลับด้วยตัวเลือก

ตัวเลือกสภาพแวดล้อมจะอยู่ที่มุมขวาบนของหน้าต่าง Apidog เลือก Staging แล้วทุกคำขอ สถานการณ์ทดสอบ และสคริปต์ในโปรเจกต์จะถูกแก้ไขตาม base URL ของ staging และค่าตัวแปรของ staging ไม่มีการแก้ไข ไม่มีการค้นหาและแทนที่ หากคุณกำลังพิจารณาว่าควรมีอะไรอยู่ใน tier การ deploy ใด การเปรียบเทียบ sandbox กับ test environments ของเราจะครอบคลุมว่าทีมมักจะแบ่งพวกมันอย่างไร

มาจาก Postman? สภาพแวดล้อมที่มีอยู่ของคุณจะถูกถ่ายโอน คู่มือการย้ายข้อมูลจาก Postman จะแนะนำการนำเข้า collections และ environments ด้วยไม่กี่คลิก รวมถึงค่าตัวแปรด้วย

เก็บข้อมูลลับไว้ในเครื่อง: ค่าที่ใช้ร่วมกัน vs ค่าในเครื่อง

นี่คือส่วนที่ทีมส่วนใหญ่ทำผิดพลาด และเป็นส่วนที่การออกแบบของ Apidog มีประโยชน์

ทุกสภาพแวดล้อมและตัวแปร global ใน Apidog สามารถเก็บค่าได้สองค่า ตามที่ระบุไว้ใน เอกสารอ้างอิงตัวแปร:

**ค่าที่ใช้ร่วมกัน (Shared value)**: ซิงค์กับเซิร์ฟเวอร์ของ Apidog และมองเห็นได้โดยทุกคนในโปรเจกต์
**ค่าในเครื่อง (Local value)**: จัดเก็บเฉพาะในแคชของไคลเอนต์ของคุณบนเครื่องของคุณเท่านั้น ไม่เคยซิงค์กับคลาวด์และเพื่อนร่วมทีมไม่สามารถมองเห็นได้

เมื่อทั้งสองค่ามีอยู่ ไคลเอนต์ของคุณจะใช้ค่าในเครื่อง ดังนั้นรูปแบบที่ปลอดภัยสำหรับข้อมูลลับจึงง่ายมาก:

สร้างตัวแปร เช่น {{auth_token}} ในแต่ละสภาพแวดล้อม
ปล่อยค่าที่ใช้ร่วมกันให้ว่างเปล่า หรือตั้งค่าเป็นตัวยึดตำแหน่ง เช่น SET_LOCALLY
ใส่โทเค็นจริงในค่าในเครื่องบนเครื่องของคุณเอง

โครงสร้างตัวแปรจะซิงค์กับทีม แต่ข้อมูลลับจะไม่ซิงค์ วิศวกรแต่ละคนใส่ข้อมูลรับรองของตนเองเพียงครั้งเดียว และทุกคำขอที่แชร์จะทำงานให้พวกเขาได้ทันที นี่สอดคล้องกับ OWASP Secrets Management Cheat Sheet: กำหนดขอบเขตข้อมูลลับอย่างเข้มงวด แชร์ผ่านช่องทางที่ควบคุมได้ และเก็บไว้ให้ห่างจากสิ่งใดๆ ที่จะถูกทำซ้ำอย่างกว้างขวาง

มีข้อควรระวังสองประการที่ควรรู้ ค่าในเครื่องจะอยู่ในแคชของไคลเอนต์ ดังนั้นการล้างแคชของ Apidog จะลบค่าเหล่านั้น และการย้ายไปยังแล็ปท็อปเครื่องใหม่หมายถึงการป้อนค่าเหล่านั้นใหม่ จัดสรรเวลาห้านาทีสำหรับเรื่องนั้น ไม่ใช่ห้าชั่วโมงของการทบทวนเหตุการณ์เพราะ prod key ถูกซิงค์ไปยังคนสิบสองคน

คุณยังสามารถทำเครื่องหมายสภาพแวดล้อมทั้งหมดว่าเป็นส่วนตัวแทนที่จะเป็นแบบแชร์ก็ได้ สภาพแวดล้อม Prod ที่มองเห็นได้เฉพาะสองคนที่ deploy เท่านั้น นับเป็นการตั้งค่าที่ถูกต้อง และยังทำงานร่วมกับค่าในเครื่องเพื่อการป้องกันในเชิงลึกอีกด้วย

ใช้สภาพแวดล้อมในสถานการณ์ทดสอบและ CI

สภาพแวดล้อมจะถูกนำไปใช้ในสถานการณ์ทดสอบของ Apidog โดยตรง สร้างสถานการณ์หนึ่งครั้ง (สร้างการเรียกเก็บเงิน, ตรวจสอบสถานะ, ยืนยันการชำระเงิน) จากนั้นเลือกสภาพแวดล้อมที่จะรันเมื่อถึงเวลาดำเนินการ สถานการณ์เดียวกันนี้จะกลายเป็น smoke test สำหรับ dev ของคุณ และชุดทดสอบ regression สำหรับ staging ของคุณ

สคริปต์อ่านและเขียนในขอบเขตเดียวกัน post-processor ที่ดึงโทเค็นใหม่จากการตอบกลับการเข้าสู่ระบบมีลักษณะดังนี้:

const body = pm.response.json();
pm.environment.set("auth_token", body.access_token);

คำขอต่อมาในสถานการณ์จะแก้ไข {{auth_token}} เป็นค่าที่ถูกดึงมา สำหรับรูปแบบเช่นการดึง request params เข้าไปในสคริปต์ โปรดดูที่ การดึง request params ใน pre/post-request scripts

สำหรับ CI นั้น Apidog CLI จะรับสภาพแวดล้อมเป็น flag:

apidog run --access-token $APIDOG_ACCESS_TOKEN \
  -t 637132 \
  -e 358171 \
  --env-var "auth_token=$STAGING_API_TOKEN"

-e เลือกสภาพแวดล้อมด้วย ID โปรดทราบว่า CLI จะแก้ไขค่าที่ใช้ร่วมกัน ไม่ใช่ค่าในเครื่องของคุณ ซึ่งเป็นพฤติกรรมที่ถูกต้อง: ข้อมูลลับส่วนตัวของคุณไม่ควรเข้าถึงได้จาก build agent อยู่แล้ว ให้แทรกข้อมูลรับรองจริง ณ รันไทม์แทน ด้วยการใช้ --env-var และ --global-var เพื่อแทนที่ในรูปแบบ key=value หรือ --variables เพื่อโหลดทั้งไฟล์ จัดเก็บข้อมูลลับจริงในที่เก็บข้อมูลลับของผู้ให้บริการ CI ของคุณ (GitHub Actions secrets, GitLab CI variables) และส่งผ่านพวกมันไป pipeline จะไม่มีโทเค็นในรูปแบบข้อความธรรมดา และการเปลี่ยนข้อมูลรับรองหมายถึงการอัปเดต CI secret เพียงตัวเดียว

เวิร์กโฟลว์ของทีมที่เกิดขึ้นจากสิ่งนี้

เมื่อรวมกันแล้ว การแบ่งงานก็ชัดเจน:

**ที่ใช้ร่วมกัน, ซิงค์แล้ว**: ชื่อสภาพแวดล้อม, base URL, ชื่อตัวแปร, ค่าตัวแปรที่ใช้ร่วมกันแบบ placeholder, สถานการณ์ทดสอบ
**ส่วนตัว, ในเครื่อง**: โทเค็นและคีย์ของวิศวกรแต่ละคนเป็นค่าในเครื่อง
**CI เป็นเจ้าของ**: ข้อมูลรับรอง pipeline ในที่เก็บข้อมูลลับของ CI, ถูกแทรกผ่าน CLI flags

เพื่อนร่วมทีมคนใหม่เข้าร่วม เปิดโปรเจกต์ และเห็นสามสภาพแวดล้อมที่สร้างไว้พร้อมใช้งาน โดยมีตัวแปรทุกตัวที่ตั้งชื่อและจัดทำเอกสารไว้ พวกเขาคัดลอกโทเค็น dev ของตนเองลงในช่องค่าในเครื่องเพียงช่องเดียวแล้วเริ่มทำงาน ไม่มีใครส่ง DM prod key ไม่มีใครดูแลหน้า wiki "current staging URL" ที่ล้าสมัย

ข้อผิดพลาดทั่วไปที่ควรหลีกเลี่ยง

การคอมมิตโทเค็นจริงเข้าไปในค่าที่ใช้ร่วมกัน เป็นข้อผิดพลาดที่พบได้บ่อยที่สุด หากข้อมูลลับต้องส่งถึงเพื่อนร่วมทีม ควรผ่าน password manager หรือ vault ไม่ใช่ผ่านตัวแปรที่ซิงค์ ตรวจสอบค่าที่ใช้ร่วมกันของคุณสักครั้ง; สิ่งใดก็ตามที่ดูเหมือนข้อมูลรับรองที่ใช้งานจริงควรย้ายไปยังค่าในเครื่องและทำการหมุนเวียน
การลืมว่าสภาพแวดล้อมใดกำลังทำงานอยู่ ความเคยชินทำให้ส่งคำขอก่อนที่ตาจะตรวจสอบตัวเลือก ทำให้การดำเนินการที่ก่อให้เกิดความเสียหายยากต่อการทำผิดพลาด: ทำให้ Prod เป็นส่วนตัวสำหรับคนจำนวนน้อยลง และให้ตัวแปรเฉพาะ prod มีชื่อที่แตกต่างกัน หรือมีค่าที่ใช้ร่วมกันเป็น placeholder เพื่อให้การรันในสภาพแวดล้อมที่ผิดพลาดล้มเหลวอย่างชัดเจนเมื่อมีการยืนยันตัวตน แทนที่จะสำเร็จอย่างเงียบๆ
คาดหวังว่าตัวแปรชั่วคราวจะคงอยู่ ตัวแปรในขอบเขต local ที่ตั้งค่าไว้ระหว่างการรันจะหายไปเมื่อการรันสิ้นสุดลง เลื่อนขั้นสิ่งใดๆ ที่ต้องการให้คงอยู่ไปยังขอบเขตสภาพแวดล้อมอย่างชัดเจนในสคริปต์ของคุณ
ชื่อตัวแปรที่แตกต่างกันในแต่ละสภาพแวดล้อม หาก dev เรียกมันว่า {{token}} และ staging เรียกมันว่า {{auth_token}} การสลับสภาพแวดล้อมจะทำให้คำขอของคุณเสียไปครึ่งหนึ่ง ใช้ชื่อเดียวกันทุกที่ มีเพียงค่าเท่านั้นที่แตกต่างกัน
สภาพแวดล้อมเดียวขนาดใหญ่สำหรับทุกสิ่ง หากคุณยัด dev_base_url และ prod_base_url เข้าไปในสภาพแวดล้อมเดียว คุณกำลังสร้างปัญหาการเขียนโค้ดตายตัวขึ้นมาใหม่ด้วยขั้นตอนที่เพิ่มขึ้น หนึ่งสภาพแวดล้อมต่อหนึ่งบริบทการ deploy

พร้อมที่จะตั้งค่านี้แล้วหรือยัง? ดาวน์โหลด Apidog ฟรี สร้างสามสภาพแวดล้อมของคุณ และย้ายโทเค็นแรกของคุณไปเป็นค่าในเครื่อง ใช้เวลาประมาณสิบนาทีสำหรับโปรเจกต์ที่มีอยู่แล้ว

คำถามที่พบบ่อย (FAQ)

จะเก็บข้อมูลลับไม่ให้เข้าไปในโปรเจกต์ Apidog ที่แชร์ได้อย่างไร?

จัดเก็บเป็นค่าในเครื่อง (local values) ทุกตัวแปรมีค่าที่ใช้ร่วมกัน (ซิงค์กับทีม) และค่าในเครื่อง (แคชบนเครื่องของคุณเท่านั้น) ปล่อยค่าที่ใช้ร่วมกันให้เป็นตัวยึดตำแหน่ง และเก็บโทเค็นจริงไว้ในเครื่อง เพื่อความเป็นส่วนตัวเพิ่มเติม ให้ทำเครื่องหมายสภาพแวดล้อมที่ละเอียดอ่อน เช่น Prod เป็นส่วนตัว เพื่อให้มีเพียงบุคคลที่เฉพาะเจาะจงเท่านั้นที่มองเห็น

ตัวแปร global กับ environment ต่างกันอย่างไร?

ตัวแปร global ใช้ได้กับทั้งโปรเจกต์ไม่ว่าสภาพแวดล้อมใดจะทำงานอยู่ ใช้สำหรับค่าที่ไม่เปลี่ยนแปลงระหว่างการ deploy เช่น สตริงเวอร์ชัน API ตัวแปรสภาพแวดล้อมเป็นของสภาพแวดล้อมเดียวและจะมีผลเหนือตัวแปร global เมื่อทั้งสองกำหนดชื่อเดียวกัน คู่มือตัวแปร ของเราจะอธิบายทั้งห้าขอบเขต รวมถึง module, data และ local

ทำไมการทดสอบของฉันจึงผ่านใน Apidog client แต่ล้มเหลวใน CI?

โดยปกติเป็นเพราะไคลเอนต์แก้ไขค่าในเครื่อง ในขณะที่ CLI แก้ไขค่าที่ใช้ร่วมกัน หากโทเค็นของคุณมีอยู่ในค่าในเครื่องเท่านั้น CLI จะเห็นตัวแปรที่ว่างเปล่าหรือเป็นตัวยึดตำแหน่ง ส่งผ่านข้อมูลรับรองอย่างชัดเจนใน pipeline ด้วย --env-var "auth_token=$YOUR_CI_SECRET" เพื่อให้ CI จัดหาข้อมูลลับของตนเองที่รันไทม์

ฉันสามารถย้ายสภาพแวดล้อม Postman ไปยัง Apidog ได้หรือไม่?

ได้ Apidog สามารถนำเข้า Postman collections และ environments ได้โดยตรง โดยคงชื่อตัวแปรและค่าไว้ไม่เปลี่ยนแปลง ดังนั้นการอ้างอิง {{base_url}} ของคุณจะยังคงทำงานได้หลังจากการย้ายข้อมูล ตรวจสอบค่าที่นำเข้าหลังจากนั้นและย้ายข้อมูลรับรองจริงใดๆ ไปยังค่าในเครื่อง เนื่องจาก Postman export สามารถมีข้อมูลลับในรูปแบบข้อความธรรมดาได้