Smart mock cung cấp cho bạn một API giả trong vài giây. Nó đọc lược đồ điểm cuối của bạn và trả về dữ liệu hợp lý: một email trông thật, một dấu thời gian hợp lý, một cái tên không phải là xJ8kQ. Đối với hầu hết các công việc frontend, điều đó là đủ để giúp bạn tiếp tục.
Sau đó, bạn gặp phải trường hợp mà Smart mock không thể giải quyết. Bạn muốn /login trả về 200 cho một người dùng đã biết và 401 trong các trường hợp khác. Bạn muốn /orders/{id} trả về một đơn hàng đã được giao cho một ID và một đơn hàng đã hủy cho một ID khác. Bạn muốn buộc trả về 500 theo yêu cầu để xử lý lỗi của bạn được thực hiện trước khi gặp môi trường sản xuất. Smart mock chỉ trả về một cấu trúc cho mỗi điểm cuối, vì vậy nó không thể phân nhánh dựa trên yêu cầu. Đó là khoảng trống mà hướng dẫn này sẽ lấp đầy.
Apidog giải quyết vấn đề này với hai tính năng: mock expectations (kỳ vọng mock) cho các phản hồi có điều kiện dựa trên quy tắc, và mock scripts (tập lệnh mock) cho logic mà các quy tắc không thể diễn tả. Hướng dẫn này sẽ trình bày cả hai với các ví dụ cụ thể, và giải thích thứ tự ưu tiên để các quy tắc tùy chỉnh của bạn luôn vượt trội hơn Smart mock. Nếu bạn mới làm quen với những điều cơ bản, tổng quan về mocking API là một phần khởi động tốt, và Apidog là công cụ chúng ta sẽ sử dụng xuyên suốt. OpenAPI Initiative tài liệu hóa quy trình làm việc contract-first (hợp đồng trước) giúp tất cả những điều này trở nên khả thi.
Conditional mocking thực sự có nghĩa là gì
Một mock có điều kiện là một quy tắc: khi yêu cầu đến trông giống thế này, hãy trả về thế kia. Apidog xây dựng các quy tắc này từ hai lớp.
Lớp đầu tiên là tùy chỉnh cấp trường bên trong lược đồ điểm cuối. Bạn gán một trường vào một giá trị cố định, hoặc bạn đính kèm một biểu thức Faker.js động để nó thay đổi theo mỗi cuộc gọi. Điều đó kiểm soát nội dung của một trường, nhưng nó vẫn trả về một dạng phản hồi cho điểm cuối.
Lớp thứ hai là kỳ vọng mock phản hồi đầy đủ. Một kỳ vọng là một quy tắc được đặt tên với các điều kiện tùy chọn và thân phản hồi, mã trạng thái và tiêu đề riêng. Một kỳ vọng không có điều kiện sẽ trả về dữ liệu cố định mà không có điều kiện. Một kỳ vọng có điều kiện sẽ trả về dữ liệu của nó chỉ khi yêu cầu khớp. Xếp chồng một vài cái này và bạn sẽ có được sự phân nhánh thực sự: phản hồi B khi yêu cầu khớp với điều kiện A, một thân lỗi khi thiếu tiêu đề, một tải trọng khác cho mỗi tham số đường dẫn.
Lớp thứ hai đó giúp trạng thái lỗi theo yêu cầu và các thân yêu cầu riêng lẻ trở nên khả thi. Phần còn lại của hướng dẫn này sẽ tập trung vào đó.
Các giá trị động cấp trường trước
Trước khi phân nhánh, việc xem xét cách một trường đơn lẻ nhận giá trị của nó sẽ hữu ích, vì các phản hồi có điều kiện của bạn sẽ tái sử dụng cùng một cú pháp.
Bên trong lược đồ của một điểm cuối, bất kỳ trường chuỗi nào cũng có thể chứa một biểu thức Faker.js được viết dưới dạng {{$category.method}}. Apidog giải quyết nó mới trên mỗi cuộc gọi mock, sử dụng các kiểu trường mà định nghĩa JSON Schema của bạn đã khai báo.
{
"id": "{{$number.int(min=1000,max=9999)}}",
"customer": "{{$person.fullName}}",
"email": "{{$internet.email}}",
"product": "{{$commerce.productName}}",
"shippingAddress": "{{$location.streetAddress}}, {{$location.city}}",
"orderedAt": "{{$date.between(from='2024-01-01',to='2024-12-31',format='yyyy-MM-dd')}}"
}
Các phương thức có tham số hoạt động, vì vậy {{$number.int(min=1000,max=9999)}} giới hạn giá trị và {{$date.between(...)}} cố định một phạm vi và định dạng. Bạn có thể nối văn bản tĩnh và nhiều biểu thức trong một trường, đó là cách địa chỉ trên được xây dựng. Nếu bạn cần dữ liệu cụ thể theo vùng, Apidog hỗ trợ các mock locale có thể tùy chỉnh để tên, địa chỉ và số điện thoại của bạn phù hợp với một ngôn ngữ hoặc quốc gia cụ thể. Tài liệu tham khảo Faker.js trong Apidog bao gồm toàn bộ danh mục phương thức.
Đây là lãnh địa của Smart mock. Nó động, nhưng không có điều kiện. Để phân nhánh dựa trên yêu cầu, bạn chuyển sang các kỳ vọng.
Hướng dẫn: một điểm cuối đăng nhập trả về 200 hoặc 401
Trường hợp điển hình: POST /login nhận một thân JSON với username và password. Một người dùng đã biết sẽ nhận được 200 cùng với một token. Tất cả những người khác sẽ nhận được 401.
Mở đúng tab
Nơi bạn cấu hình điều này phụ thuộc vào chế độ làm việc của bạn:
- Trong chế độ DEBUG (Yêu cầu trước), mở điểm cuối và nhấp vào tab Mock.
- Trong chế độ DESIGN (Thiết kế trước), mở điểm cuối và nhấp vào tab Advanced mock.
Cả hai đều dẫn đến danh sách kỳ vọng tương tự. Nếu bạn muốn làm theo và chưa có ứng dụng, hãy Tải xuống Apidog và nhập hoặc tạo một điểm cuối /login trước.
Thêm kỳ vọng thành công
Nhấp vào New expectation. Đặt cho nó một tên kỳ vọng như login-success. Bây giờ hãy thêm một điều kiện. Vì username nằm trong phần thân yêu cầu JSON, bạn khớp nó như một tham số thân yêu cầu: đặt đường dẫn JSON của thuộc tính mục tiêu, username, vào trường tên và đặt điều kiện bằng alice@example.com.
Các điều kiện tham số thân yêu cầu chỉ dành cho JSON, và chúng được khớp thông qua đường dẫn JSON trong trường tên, vì vậy các thuộc tính lồng nhau sử dụng đường dẫn dấu chấm như user.email. Điền vào Dữ liệu phản hồi với payload thành công:
{
"token": "mock-jwt-{{$string.uuid}}",
"user": {
"id": 4821,
"username": "alice@example.com",
"role": "member"
}
}
Lưu. Mã trạng thái HTTP mặc định là 200, vì vậy bạn không cần phải thay đổi bất cứ điều gì khác cho trường hợp thành công.
Thêm kỳ vọng thất bại
Nhấp vào New expectation một lần nữa. Đặt tên là login-failure và để trống các điều kiện của nó để nó hoạt động như một quy tắc bắt tất cả. Đặt Dữ liệu phản hồi của nó thành thân lỗi:
{
"error": "invalid_credentials",
"message": "Username or password is incorrect."
}
Cái này cần một trạng thái không mặc định. Mở tab More của kỳ vọng và đặt Mã trạng thái HTTP thành 401. Khi bạn ở đó, hãy lưu ý rằng tab More cũng là nơi bạn đặt Độ trễ phản hồi theo mili giây (mặc định 0) và bất kỳ tiêu đề phản hồi tùy chỉnh nào. Độ trễ 400ms là một cách đơn giản để đảm bảo biểu tượng tải của bạn thực sự hiển thị.
Thứ tự quan trọng
Các kỳ vọng được đánh giá từ trên xuống dưới, và cái khớp đầu tiên sẽ thắng. Vì vậy, login-success phải nằm trên login-failure. Một yêu cầu với username bằng alice@example.com sẽ khớp với quy tắc đầu tiên và trả về token. Bất cứ thứ gì khác sẽ rơi vào quy tắc thất bại không điều kiện và nhận 401. Nếu bạn đảo ngược thứ tự, quy tắc không điều kiện sẽ khớp với mọi thứ và trường hợp thành công của bạn sẽ không bao giờ được kích hoạt.
Sao chép URL mock từ điểm cuối và kiểm tra cả hai đường dẫn:
# known user -> 200 with a token
curl -X POST https://<your-mock-host>/login \
-H "Content-Type: application/json" \
-d '{"username":"alice@example.com","password":"whatever"}'
# anyone else -> 401
curl -X POST https://<your-mock-host>/login \
-H "Content-Type: application/json" \
-d '{"username":"stranger@example.com","password":"whatever"}'
Hướng dẫn: Các thân phản hồi khác nhau cho /orders/{id} theo trạng thái
Trường hợp phổ biến thứ hai phân nhánh dựa trên một tham số đường dẫn. Bạn muốn /orders/{id} trả về một đơn hàng đã giao cho một ID và một đơn hàng đã hủy cho một ID khác, để giao diện người dùng của bạn có thể hiển thị mọi trạng thái mà không cần backend trực tiếp.
Tạo một kỳ vọng cho mỗi trạng thái. Đối với mỗi kỳ vọng, hãy thêm một điều kiện trên tham số đường dẫn id, sau đó điền vào Dữ liệu phản hồi tương ứng.
Kỳ vọng order-shipped, điều kiện: tham số đường dẫn id bằng 5001.
{
"id": 5001,
"status": "shipped",
"total": 129.90,
"trackingNumber": "1Z{{$string.alphanumeric(length=16)}}",
"shippedAt": "{{$date.recent(days=3,format='yyyy-MM-dd')}}"
}
Kỳ vọng order-cancelled, điều kiện: tham số đường dẫn id bằng 5002.
{
"id": 5002,
"status": "cancelled",
"total": 0,
"cancelledAt": "{{$date.recent(days=1,format='yyyy-MM-dd')}}",
"refundIssued": true
}
Thêm một kỳ vọng cuối cùng không có điều kiện mà trả về một đơn hàng đang chờ xử lý chung, để bất kỳ ID nào khác vẫn nhận được phản hồi hợp lệ thay vì bỏ qua. Sắp xếp các quy tắc cụ thể phía trên quy tắc bắt tất cả, lưu lại, và bạn có một mock hiển thị mọi trạng thái đơn hàng theo yêu cầu. Việc kết hợp các điều kiện cũng hoạt động: thêm một điều kiện tiêu đề cùng với điều kiện đường dẫn và cả hai phải đúng, vì Apidog kết hợp nhiều điều kiện với logic AND (một giao điểm của các điều kiện, theo thuật ngữ của tài liệu).
Các điều kiện không chỉ giới hạn ở thân và đường dẫn. Bạn có thể khớp theo tham số truy vấn, tham số tiêu đề, tham số cookie, và thậm chí cả địa chỉ IP, điều này cho phép bạn hạn chế một phản hồi cho các máy khách cụ thể trong quá trình kiểm tra.
Buộc các trạng thái lỗi theo yêu cầu
Bạn không cần một backend bị hỏng để kiểm tra các phản hồi bị lỗi. Một kỳ vọng cộng với tab More cung cấp cho bạn bất kỳ trạng thái nào bạn muốn.
Để buộc một 500, hãy thêm một kỳ vọng mà điều kiện của nó là thứ bạn kiểm soát từ phía client, chẳng hạn một tiêu đề X-Mock-Scenario bằng server-error. Đặt Dữ liệu phản hồi của nó thành một thân lỗi thực tế và Mã trạng thái HTTP của nó thành 500 trong tab More.
{
"error": "internal_error",
"requestId": "{{$string.uuid}}",
"message": "Something went wrong on our end. Please retry."
}
Bây giờ điểm cuối tương tự sẽ phục vụ một 200 thông thường theo mặc định và một 500 bất cứ khi nào bạn gửi tiêu đề đó. Hãy làm tương tự cho 404, 429 (với tiêu đề Retry-After được đặt trong tab More), hoặc 503. Xử lý lỗi frontend của bạn cuối cùng đã có thứ để bắt. Nếu bạn xác nhận các phản hồi này trong các kiểm tra tự động, hướng dẫn về xác nhận API sẽ kết hợp tốt với thiết lập này.
Một chi tiết cho các dự án chia sẻ: mỗi kỳ vọng có thể được bật hoặc tắt độc lập cho môi trường mock cục bộ và đám mây từ danh sách kỳ vọng. Vì vậy, bạn có thể giữ một quy tắc 500 hoạt động cục bộ trong khi tắt nó trong mock đám mây mà đồng đội của bạn truy cập.
Khi các quy tắc không đủ: tập lệnh mock
Các kỳ vọng mang tính khai báo. Chúng khớp và trả về, nhưng chúng không thể tính toán. Khi bạn cần một trường được dẫn xuất từ yêu cầu, tổng được tính từ các mục hàng, hoặc một thân phản hồi thay đổi hình dạng dựa trên nhiều đầu vào cùng một lúc, bạn sẽ tìm đến một tập lệnh mock.
Một tập lệnh mock là JavaScript chạy chống lại phản hồi mock. Nó nằm trong phần Mock Script ở cuối tab Mock và được bật bằng một công tắc. Tập lệnh hiển thị hai biến toàn cục:
$$.mockRequest: đọc yêu cầu đến thông quagetParam(key), cộng thêmheaders,cookies,body,formdatavàurlencoded.$$.mockResponse: định hình phản hồi đi ra thông quasetBody(),setCode(),setDelay(),json(), và các thuộc tínhheadersvàcode.
Đây là một tập lệnh tính tổng đơn hàng từ các mặt hàng đã đăng và phản hồi lại tiêu đề tiền tệ của người gọi:
const body = $$.mockRequest.body;
const items = body.items || [];
const subtotal = items.reduce((sum, item) => {
return sum + item.price * item.quantity;
}, 0);
const currency = $$.mockRequest.headers["x-currency"] || "USD";
$$.mockResponse.setCode(201);
$$.mockResponse.setBody({
orderId: Math.floor(Math.random() * 90000) + 10000,
currency: currency,
subtotal: subtotal,
tax: Number((subtotal * 0.08).toFixed(2)),
total: Number((subtotal * 1.08).toFixed(2))
});
Luồng là: Smart mock tạo ra một phản hồi ban đầu, tập lệnh của bạn đọc $$.mockRequest và $$.mockResponse hiện tại, áp dụng logic của nó, gọi $$.mockResponse.setBody() (và setCode, setDelay, hoặc headers nếu cần), và công cụ trả về kết quả cuối cùng. Tài liệu tham khảo MDN JavaScript là một người bạn đồng hành vững chắc nếu bạn muốn phát triển logic hơn nữa với các phương thức mảng hoặc tính toán ngày tháng.
Một quy tắc khiến mọi người gặp khó khăn
Tập lệnh mock chỉ hoạt động với Smart mock. Chúng không áp dụng cho các kỳ vọng mock hoặc ví dụ phản hồi. Đây là điều quan trọng nhất cần ghi nhớ: bạn không thể kết hợp một tập lệnh mock với một phản hồi dựa trên kỳ vọng. Nếu một kỳ vọng khớp với yêu cầu, tập lệnh sẽ không bao giờ chạy. Vì vậy, hãy chọn một phương pháp cho mỗi điểm cuối. Sử dụng các kỳ vọng khi bạn phân nhánh dựa trên các điều kiện cố định và trả về các thân phản hồi đã định sẵn. Sử dụng một tập lệnh mock khi bạn cần đầu ra được tính toán từ cơ sở được tạo bởi Smart mock.
Cách thứ tự ưu tiên được giải quyết
Tóm lại, đây là thứ tự Apidog thực hiện cho bất kỳ yêu cầu mock nào:
- Nó kiểm tra các kỳ vọng của bạn, từ trên xuống dưới. Kỳ vọng đầu tiên mà tất cả các điều kiện khớp sẽ thắng, và phản hồi của nó được trả về. Đây là lý do tại sao các quy tắc tùy chỉnh vượt trội hơn Smart mock: một kỳ vọng khớp sẽ bỏ qua mọi thứ bên dưới nó.
- Nếu không có kỳ vọng nào khớp, Apidog sẽ quay về Ưu tiên phương thức Mock mà bạn đã đặt trong Project Settings - Feature Settings - Mock Settings. Đó là cấp độ mà Smart mock (và bất kỳ tập lệnh mock nào gắn liền với nó) tạo ra phản hồi.
Mô hình tinh thần rất đơn giản: các quy tắc cụ thể trước, dữ liệu được tạo ra sau. Sắp xếp các kỳ vọng của bạn từ cụ thể nhất đến ít cụ thể nhất, giữ một quy tắc bắt tất cả không điều kiện ở cuối nếu bạn muốn đảm bảo khớp, và để Smart mock xử lý mọi thứ khác. Để tìm hiểu sâu hơn về thời điểm nên dựa vào mỗi lớp, hướng dẫn các trường hợp sử dụng mocking API sẽ ánh xạ các tình huống phổ biến với các tính năng.
Những điều cần biết trước khi triển khai
Một vài hạn chế sẽ giúp bạn tránh một phiên gỡ lỗi khó hiểu:
- Các điều kiện tham số không hỗ trợ
{{variables}}. Các biến dự án và môi trường Apidog không khả dụng bên trong các kỳ vọng mock, vì vậy hãy đặt các giá trị cố định trong điều kiện của bạn. - Các điều kiện tham số thân yêu cầu chỉ dành cho JSON, không phải XML, và phải được khớp thông qua đường dẫn JSON trong trường tên.
- Định dạng thân yêu cầu trong một điều kiện phải khớp với thông số kỹ thuật API. Một điểm cuối form-data phải được mock với vị trí form-data, không phải JSON.
- Bên trong các tập lệnh mock không có hàm ghi log, đối tượng
pmkhông khả dụng (đó là một môi trường thực thi khác so với các tập lệnh kiểm thử), và các biến Apidog không thể được sử dụng. Hãy giữ logic tập lệnh độc lập.
Không có tính năng nào trong số này bị giới hạn theo gói trong tài liệu. Sự khác biệt duy nhất giữa cục bộ và đám mây là về chức năng: công tắc bật/tắt độc lập cho mỗi môi trường được mô tả trước đó, chứ không phải là một bức tường phí.
Tự động hóa quy trình làm việc với Apidog CLI
Mocking trong Apidog là một khả năng GUI và đám mây. Công cụ mock phục vụ các điểm cuối của bạn từ các URL mock cục bộ và đám mây, và không có lệnh CLI nào khởi động một máy chủ mock đang chạy. Điều mà Apidog CLI bổ sung là khả năng kiểm soát các tài nguyên mà các mock đó được xây dựng từ đó.
Các phản hồi mock được tạo từ lược đồ điểm cuối, vì vậy độ chính xác của mock của bạn theo dõi độ chính xác của đặc tả của bạn. CLI, và các tác nhân mã hóa AI điều khiển nó (Cursor, Claude Code, Trae, Codex), có thể tạo và cập nhật các điểm cuối và lược đồ trong dự án của bạn. Thay đổi hợp đồng trong mã, đồng bộ hóa nó, và đầu ra mock vẫn chính xác mà không cần ai mở lại ứng dụng.
Khi mock đã giải tỏa công việc frontend, các kịch bản kiểm thử của cùng dự án sẽ chạy không giao diện trong CI để xác thực backend thực tế so với hợp đồng mà mock đã mô tả:
apidog run -t <scenario_id> -e <env_id> -r cli
Lệnh đơn giản đó thực thi các kịch bản kiểm thử của bạn và báo cáo kết quả, để mock và quá trình xác minh chia sẻ một nguồn thông tin duy nhất. Hướng dẫn cài đặt Apidog CLI bao gồm thiết lập, và Apidog CLI trong GitHub Actions hướng dẫn cách tích hợp nó vào một pipeline.
Câu hỏi thường gặp
Tại sao kỳ vọng của tôi bị bỏ qua mặc dù điều kiện có vẻ đúng? Gần như luôn là do thứ tự hoặc không khớp định dạng. Các kỳ vọng được đánh giá từ trên xuống dưới và cái khớp đầu tiên sẽ thắng, vì vậy một quy tắc không điều kiện rộng lớn nằm phía trên một quy tắc cụ thể sẽ nuốt yêu cầu. Cũng cần xác nhận định dạng thân yêu cầu khớp với đặc tả (đường dẫn JSON cho thân JSON, vị trí form-data cho điểm cuối form). Tổng quan về mocking API bao gồm các kiến thức cơ bản về thiết lập nếu bạn muốn kiểm tra lại.
Tôi có thể sử dụng một tập lệnh mock và một kỳ vọng mock trên cùng một phản hồi không? Không. Tập lệnh mock chỉ chạy với Smart mock. Chúng bị bỏ qua bởi các kỳ vọng mock và các ví dụ phản hồi. Nếu một kỳ vọng khớp, tập lệnh sẽ không bao giờ thực thi, vì vậy hãy chọn một cách tiếp cận cho mỗi điểm cuối: các kỳ vọng cho phân nhánh dựa trên quy tắc, các tập lệnh cho đầu ra được tính toán.
Làm cách nào để trả về 401 hoặc 500 mà không làm hỏng 200 mặc định? Thêm một kỳ vọng riêng biệt với một điều kiện mà bạn kiểm soát từ phía client (một tiêu đề hoạt động tốt), sau đó mở tab More của nó và đặt Mã trạng thái HTTP. Phản hồi mặc định vẫn là 200; lỗi chỉ được kích hoạt khi điều kiện khớp.
Các điều kiện có thể sử dụng biến môi trường của tôi không? Không. Các giá trị {{variable}} của Apidog không khả dụng bên trong các kỳ vọng mock, và các điều kiện tham số không hỗ trợ {{variables}}. Hãy sử dụng các giá trị cố định trong các điều kiện.
Điều gì xảy ra khi không có kỳ vọng nào khớp? Apidog sẽ quay về ưu tiên phương thức Mock trong Project Settings - Feature Settings - Mock Settings, nơi Smart mock tạo ra một phản hồi từ lược đồ của bạn. Thêm một kỳ vọng bắt tất cả không điều kiện là cách để đảm bảo một phương án dự phòng cụ thể thay thế.
Tóm tắt
Smart mock xử lý các trường hợp phổ biến, và các kỳ vọng mock xử lý mọi thứ có điều kiện nếu: 200 cho người dùng đã biết và 401 trong các trường hợp khác, một thân đơn hàng khác cho mỗi trạng thái, một 500 theo yêu cầu. Chỉ sử dụng tập lệnh mock khi bạn cần đầu ra được tính toán mà các quy tắc không thể diễn tả, và hãy nhớ rằng nó chỉ chạy với Smart mock. Hãy ghi nhớ thứ tự ưu tiên (các kỳ vọng cụ thể trước, dữ liệu được tạo ra sau) và các mock của bạn sẽ phân nhánh chính xác như cách các API thực tế hoạt động. Tải xuống Apidog để xây dựng mock có điều kiện đầu tiên của bạn, miễn phí, không yêu cầu thẻ tín dụng.