Trong một dự án Apidog, các endpoint được quản lý theo cấu trúc phân cấp Module → Folder → Endpoints.
- Module đại diện cho các tệp OpenAPI độc lập, thường được nhóm theo lĩnh vực kinh doanh hoặc dịch vụ.
- Folder tổ chức các endpoint theo tính năng hoặc chức năng trong một module.
- Endpoint là các đặc tả OpenAPI hoặc định nghĩa API thực tế.
Hiểu rõ cấu trúc này là chìa khóa để tổ chức các API của bạn một cách hiệu quả.
Dưới đây là một ví dụ về cấu trúc phân cấp đơn giản:
Dự án Apidog
│
├── Module: Dịch vụ người dùng (phân chia theo lĩnh vực kinh doanh hoặc dịch vụ)
│ │
│ ├── Thư mục: Xác thực người dùng (danh mục tính năng)
│ │ │
│ │ ├── Endpoint: POST /login (Đăng nhập)
│ │ └── Endpoint: POST /register (Đăng ký)
│ │
│ └── Thư mục: Thông tin người dùng
│ │
│ └── Endpoint: GET /users/{id} (Lấy thông tin người dùng)
│
└── Module: Dịch vụ đơn hàng
│
├── Thư mục: Quản lý đơn hàng
│ │
│ ├── Endpoint: POST /orders (Tạo đơn hàng)
│ └── Endpoint: GET /orders/{id} (Lấy chi tiết đơn hàng)
│
└── Thư mục: Thanh toán
│
└── Endpoint: POST /payment/submit (Gửi thanh toán)Tìm hiểu về Module trong Apidog
Sau khi hiểu về cấu trúc phân cấp dự án, câu hỏi tiếp theo là: Mọi dự án có cần module không? Khi nào bạn nên tạo một module mới?
Khi bạn tạo một dự án mới, Apidog tự động tạo một module mặc định. Nếu dự án của bạn chỉ chứa một dịch vụ backend duy nhất hoặc một tập hợp nhỏ các endpoint, module mặc định này thường là đủ. Tuy nhiên, nếu bạn cần quản lý nhiều dịch vụ API riêng biệt, bạn có thể tạo một module riêng cho mỗi dịch vụ.
Ví dụ, một backend dự án có thể bao gồm các dịch vụ như Người dùng, Sản phẩm, Đơn hàng và Hậu cần—mỗi dịch vụ chịu trách nhiệm cho một miền cụ thể và thường được triển khai trên các URL dịch vụ khác nhau. Trong trường hợp này, nên tạo các module riêng lẻ cho các dịch vụ này để quản lý các endpoint của chúng một cách độc lập.
Bạn có thể tạo một module bằng cách nhấp vào nút + phía trên cây thư mục và chọn Module.
Sau khi được tạo, nó sẽ xuất hiện trong cây dự án bên trái cùng với các module khác, với không gian riêng để chứa các thư mục và endpoint. Bạn có thể tự do thêm endpoint và thư mục trong mỗi module.
Các module độc lập với nhau, mỗi module có các endpoint, schema, component và biến module riêng. Tuy nhiên, các schema có thể được tham chiếu chéo giữa các module. Ngoài ra, các cài đặt cấp dự án như biến môi trường, kết nối cơ sở dữ liệu và các script chung đều có thể truy cập được bởi tất cả các module.
Mỗi module tương ứng với một tệp đặc tả OpenAPI hoàn chỉnh. Khi xuất dự án của bạn, các tệp OpenAPI được tạo theo từng module.
Tìm hiểu về Folder trong một Module
Sau khi tạo các module của mình, bước tiếp theo là lập kế hoạch cách cấu trúc các endpoint bên trong chúng.
Mọi module đều bắt đầu với một thư mục gốc chứa tất cả các thư mục con và endpoint.
Bạn có thể tạo các thư mục trực tiếp dưới thư mục gốc hoặc lồng chúng vào các thư mục hiện có khác.
Khi thiết kế cấu trúc thư mục, hãy xem xét độ phức tạp của module. Đối với một module chỉ có một vài endpoint, một thư mục đơn cấp đơn giản được tổ chức theo chức năng thường là đủ. Nhưng đối với các module phức tạp hơn, tốt hơn là nên tạo các thư mục đa cấp, có cấu trúc tốt để giữ mọi thứ được tổ chức và dễ điều hướng.
Ví dụ, trong một module Dịch vụ người dùng, bạn có thể có các thư mục cấp cao nhất như:
- Xác thực người dùng (cho các endpoint đăng nhập, đăng ký, đặt lại mật khẩu)
- Thông tin người dùng
- Kiểm soát truy cập
Nếu một thư mục trở nên quá lớn hoặc độc lập về mặt logic, bạn có thể chuyển đổi nó thành một module độc lập.
Nhấp vào biểu tượng ... bên cạnh tên thư mục và chọn ...More > Convert to a new Module. Điều này giúp giữ cho cấu trúc dự án của bạn được tổ chức tốt khi nó mở rộng.
Quản lý Môi trường & Cấu hình cho một Module
Ngoài các endpoint có cấu trúc, mỗi module thường tương ứng với một địa chỉ dịch vụ hoặc môi trường triển khai khác nhau. Bạn có thể dễ dàng cấu hình chúng trong Quản lý Môi trường.
Trong cài đặt quản lý môi trường, Base URL của mỗi module có thể được cấu hình riêng. Ví dụ, trong một Môi trường thử nghiệm:
- Dịch vụ người dùng →
http://user-service:8001 - Dịch vụ đơn hàng →
http://order-service:8002
Khi chuyển đổi môi trường, Apidog tự động cập nhật Base URL của mỗi module. Ví dụ, khi chuyển môi trường phát triển sang môi trường thử nghiệm, Base URL của module dịch vụ người dùng sẽ thay đổi từ http://localhost:8001 thành http://user-service:8001, và Base URL của module dịch vụ đơn hàng sẽ thay đổi từ http://localhost:8002 thành http://order-service:8002.
Các biến môi trường được chia sẻ trên tất cả các module và hoạt động tốt nhất để lưu trữ các cài đặt khác nhau giữa các môi trường. Ngược lại, các biến module là duy nhất cho mỗi module — ví dụ: khóa API hoặc token riêng của chúng — và có thể được sử dụng trong bất kỳ endpoint nào trong module đó.
Quản lý và Tái sử dụng Schema
Quản lý schema hiệu quả giúp tránh trùng lặp và đảm bảo tính nhất quán giữa các module.
Mỗi module có phần quản lý schema riêng, nơi bạn có thể định nghĩa và duy trì các cấu trúc dữ liệu liên quan đến nghiệp vụ. Các schema này có thể được tái sử dụng trong module hoặc được tham chiếu bởi các module khác.
Ví dụ, module Dịch vụ người dùng định nghĩa các schema liên quan đến người dùng. Module Dịch vụ đơn hàng định nghĩa các schema liên quan đến đơn hàng. Nếu Dịch vụ đơn hàng cần tham chiếu thông tin người dùng, nó có thể đơn giản tái sử dụng schema của Dịch vụ người dùng—không cần tạo lại.
Từ Postman sang Apidog: Tổ chức các Collection & Endpoint đã nhập
Nếu nhóm của bạn trước đây đã sử dụng Postman, bạn có thể dễ dàng di chuyển các collection và endpoint hiện có sang Apidog.
Trong quá trình nhập:
- Mỗi Postman Collection trở thành một Module.
- Cấu trúc thư mục được tự động ánh xạ.
- Các endpoint và schema được giữ nguyên.
Điều này cho phép bạn giữ cấu trúc API quen thuộc của mình trong khi tận dụng hệ thống module của Apidog.
Kết luận
Bằng cách định nghĩa rõ ràng các module, tổ chức các thư mục và tái sử dụng các schema, bạn có thể giữ cho các dự án Apidog của mình gọn gàng, có khả năng mở rộng và dễ dàng cộng tác.
Thiết kế module của Apidog giúp các nhóm làm việc nhanh hơn, tránh nhầm lẫn và quản lý các API phức tạp hiệu quả hơn — từ thiết kế đến tài liệu và thử nghiệm.