ในโปรเจกต์ Apidog, จุดเชื่อมต่อ (endpoints) จะถูกจัดการในโครงสร้างแบบลำดับชั้นของ Module → Folder → Endpoints
- Modules (โมดูล) แสดงถึงไฟล์ OpenAPI ที่เป็นอิสระ ซึ่งมักจะจัดกลุ่มตามโดเมนธุรกิจหรือบริการ
- Folders (โฟลเดอร์) จัดระเบียบจุดเชื่อมต่อตามคุณสมบัติหรือฟังก์ชันภายในโมดูล
- Endpoints (จุดเชื่อมต่อ) คือข้อมูลจำเพาะของ OpenAPI หรือคำจำกัดความของ API ที่แท้จริง
การทำความเข้าใจโครงสร้างนี้เป็นกุญแจสำคัญในการจัดระเบียบ API ของคุณอย่างมีประสิทธิภาพ
นี่คือตัวอย่างโครงสร้างลำดับชั้นอย่างง่าย:
Apidog Project
│
├── Module: User Service (แบ่งตามโดเมนธุรกิจหรือบริการ)
│ │
│ ├── Folder: User Authentication (หมวดหมู่คุณสมบัติ)
│ │ │
│ │ ├── Endpoint: POST /login (เข้าสู่ระบบ)
│ │ └── Endpoint: POST /register (ลงทะเบียน)
│ │
│ └── Folder: User Info (ข้อมูลผู้ใช้)
│ │
│ └── Endpoint: GET /users/{id} (รับข้อมูลผู้ใช้)
│
└── Module: Order Service (บริการคำสั่งซื้อ)
│
├── Folder: Order Management (การจัดการคำสั่งซื้อ)
│ │
│ ├── Endpoint: POST /orders (สร้างคำสั่งซื้อ)
│ └── Endpoint: GET /orders/{id} (รับรายละเอียดคำสั่งซื้อ)
│
└── Folder: Payment (การชำระเงิน)
│
└── Endpoint: POST /payment/submit (ส่งการชำระเงิน)ทำความเข้าใจ Modules ใน Apidog
หลังจากทำความเข้าใจลำดับชั้นของโปรเจกต์แล้ว คำถามถัดไปคือ: ทุกโปรเจกต์จำเป็นต้องมีโมดูลหรือไม่? คุณควรสร้างโมดูลใหม่เมื่อใด?
เมื่อคุณสร้างโปรเจกต์ใหม่ Apidog จะสร้างโมดูลเริ่มต้นให้โดยอัตโนมัติ หากโปรเจกต์ของคุณมีเพียงบริการแบ็คเอนด์เดียวหรือมีจุดเชื่อมต่อจำนวนน้อย โมดูลเริ่มต้นนี้มักจะเพียงพอ อย่างไรก็ตาม หากคุณต้องการจัดการบริการ API ที่แตกต่างกันหลายรายการ คุณสามารถสร้างโมดูลแยกต่างหากสำหรับแต่ละบริการได้
ตัวอย่างเช่น แบ็คเอนด์ของโปรเจกต์อาจรวมถึงบริการต่างๆ เช่น User, Product, Order และ Logistics ซึ่งแต่ละบริการรับผิดชอบโดเมนเฉพาะและมักจะถูกปรับใช้บน URL บริการที่แตกต่างกัน ในกรณีนี้ ขอแนะนำให้สร้างโมดูลแต่ละรายการสำหรับบริการเหล่านี้เพื่อจัดการจุดเชื่อมต่อของตนเองอย่างอิสระ
คุณสามารถสร้างโมดูลได้โดยคลิกปุ่ม + เหนือโครงสร้างโฟลเดอร์และเลือก Module
เมื่อสร้างแล้ว โมดูลจะปรากฏในโครงสร้างโปรเจกต์ด้านซ้ายพร้อมกับโมดูลอื่นๆ โดยมีพื้นที่สำหรับโฟลเดอร์และจุดเชื่อมต่อของตนเอง คุณสามารถเพิ่มจุดเชื่อมต่อและโฟลเดอร์ภายในแต่ละโมดูลได้อย่างอิสระ
โมดูลต่างๆ เป็นอิสระจากกัน โดยแต่ละโมดูลมีจุดเชื่อมต่อ, สคีมา, ส่วนประกอบ และตัวแปรโมดูลของตนเอง อย่างไรก็ตาม สคีมาสามารถอ้างอิงข้ามโมดูลได้ นอกจากนี้ การตั้งค่าระดับโปรเจกต์ เช่น ตัวแปรสภาพแวดล้อม, การเชื่อมต่อฐานข้อมูล และสคริปต์ทั่วไป สามารถเข้าถึงได้โดยทุกโมดูล
แต่ละโมดูลจะสอดคล้องกับไฟล์ข้อมูลจำเพาะ OpenAPI ที่สมบูรณ์ เมื่อส่งออกโปรเจกต์ของคุณ ไฟล์ OpenAPI จะถูกสร้างขึ้นต่อโมดูล
ทำความเข้าใจ Folders ภายในโมดูล
หลังจากสร้างโมดูลของคุณแล้ว ขั้นตอนต่อไปคือการวางแผนวิธีจัดโครงสร้างจุดเชื่อมต่อภายในโมดูลเหล่านั้น
ทุกโมดูลเริ่มต้นด้วย root folder (โฟลเดอร์หลัก) ที่เก็บโฟลเดอร์ย่อยและจุดเชื่อมต่อทั้งหมด
คุณสามารถสร้างโฟลเดอร์โดยตรงภายใต้โฟลเดอร์หลัก หรือซ้อนโฟลเดอร์เหล่านั้นภายในโฟลเดอร์อื่นที่มีอยู่แล้วได้
เมื่อออกแบบโครงสร้างโฟลเดอร์ ให้พิจารณาว่าโมดูลนั้นซับซ้อนเพียงใด สำหรับโมดูลที่มีจุดเชื่อมต่อเพียงไม่กี่จุด โฟลเดอร์ระดับเดียวที่จัดระเบียบตามฟังก์ชันมักจะเพียงพอ แต่สำหรับโมดูลที่ซับซ้อนมากขึ้น การสร้างโฟลเดอร์หลายระดับที่มีโครงสร้างดีจะดีกว่าเพื่อให้ทุกอย่างเป็นระเบียบและง่ายต่อการนำทาง
ตัวอย่างเช่น ในโมดูล User Service คุณอาจมีโฟลเดอร์ระดับบนสุด เช่น:
- User Authentication (สำหรับการเข้าสู่ระบบ, การลงทะเบียน, จุดเชื่อมต่อการรีเซ็ตรหัสผ่าน)
- User Info (ข้อมูลผู้ใช้)
- Access Control (การควบคุมการเข้าถึง)
หากโฟลเดอร์ใดโฟลเดอร์หนึ่งมีขนาดใหญ่เกินไปหรือเป็นอิสระทางตรรกะ คุณสามารถแปลงเป็นโมดูลแบบสแตนด์อโลนได้
คลิกไอคอน ... ถัดจากชื่อโฟลเดอร์และเลือก ...More > Convert to a new Module สิ่งนี้ช่วยให้โครงสร้างโปรเจกต์ของคุณเป็นระเบียบเมื่อมีการขยายขนาด
การจัดการสภาพแวดล้อม & การกำหนดค่าสำหรับโมดูล
นอกเหนือจากจุดเชื่อมต่อที่มีโครงสร้างแล้ว แต่ละโมดูลมักจะสอดคล้องกับที่อยู่บริการหรือสภาพแวดล้อมการปรับใช้ที่แตกต่างกัน คุณสามารถกำหนดค่าสิ่งเหล่านี้ได้อย่างง่ายดายในการจัดการสภาพแวดล้อม
ในการตั้งค่าการจัดการสภาพแวดล้อม Base URL ของแต่ละโมดูลสามารถกำหนดค่าแยกกันได้ ตัวอย่างเช่น ใน Test Environment (สภาพแวดล้อมการทดสอบ):
- User Service →
http://user-service:8001 - Order Service →
http://order-service:8002
เมื่อเปลี่ยนสภาพแวดล้อม Apidog จะอัปเดต Base URL ของแต่ละโมดูลโดยอัตโนมัติ ตัวอย่างเช่น เมื่อเปลี่ยนสภาพแวดล้อมการพัฒนาไปเป็นสภาพแวดล้อมการทดสอบ Base URL ของโมดูลบริการผู้ใช้จะเปลี่ยนจาก http://localhost:8001 เป็น http://user-service:8001 และ Base URL ของโมดูลบริการคำสั่งซื้อจะเปลี่ยนจาก http://localhost:8002 เป็น http://order-service:8002
ตัวแปรสภาพแวดล้อมจะถูกแชร์ข้ามทุกโมดูลและทำงานได้ดีที่สุดสำหรับการจัดเก็บการตั้งค่าที่แตกต่างกันระหว่างสภาพแวดล้อม ในทางตรงกันข้าม ตัวแปรโมดูลจะมีเอกลักษณ์เฉพาะสำหรับแต่ละโมดูล เช่น คีย์ API หรือโทเค็นของตนเอง และสามารถใช้ในจุดเชื่อมต่อใดก็ได้ภายในโมดูลนั้น
การจัดการและการนำสคีมากลับมาใช้ใหม่
การจัดการสคีมาอย่างมีประสิทธิภาพช่วยหลีกเลี่ยงการซ้ำซ้อนและรับประกันความสอดคล้องในทุกโมดูล
แต่ละโมดูลมีส่วนการจัดการสคีมาของตนเอง ซึ่งคุณสามารถกำหนดและดูแลโครงสร้างข้อมูลที่เกี่ยวข้องกับธุรกิจได้ สคีมาเหล่านี้สามารถนำกลับมาใช้ใหม่ภายในโมดูลหรืออ้างอิงโดยโมดูลอื่นได้
ตัวอย่างเช่น โมดูล User Service กำหนดสคีมาที่เกี่ยวข้องกับผู้ใช้ โมดูล Order Service กำหนดสคีมาที่เกี่ยวข้องกับคำสั่งซื้อ หาก Order Service ต้องการอ้างอิงข้อมูลผู้ใช้ ก็สามารถนำสคีมาของ User Service กลับมาใช้ใหม่ได้โดยไม่จำเป็นต้องสร้างใหม่
จาก Postman สู่ Apidog: การจัดระเบียบ Collections & Endpoints ที่นำเข้า
หากทีมของคุณเคยใช้ Postman มาก่อน คุณสามารถ ย้าย collections และ endpoints ที่มีอยู่ไปยัง Apidog ได้อย่างง่ายดาย
ระหว่างการนำเข้า:
- แต่ละ Postman Collection จะกลายเป็น Module
- โครงสร้างโฟลเดอร์จะถูกแมปโดยอัตโนมัติ
- Endpoints และสคีมาจะถูกเก็บรักษาไว้
สิ่งนี้ช่วยให้คุณสามารถคงโครงสร้าง API ที่คุ้นเคยไว้ได้ ในขณะที่ใช้ประโยชน์จากระบบโมดูลาร์ของ Apidog
บทสรุป
ด้วยการกำหนด modules ที่ชัดเจน, การจัดระเบียบ folders และการนำ schemas กลับมาใช้ใหม่ คุณสามารถทำให้โปรเจกต์ Apidog ของคุณสะอาด, ปรับขนาดได้ และทำงานร่วมกันได้ง่าย
การออกแบบโมดูลาร์ของ Apidog ช่วยให้ทีมทำงานได้เร็วขึ้น, หลีกเลี่ยงความสับสน และจัดการ API ที่ซับซ้อนได้อย่างมีประสิทธิภาพมากขึ้น — ตั้งแต่การออกแบบไปจนถึงเอกสารและการทดสอบ