Apidog: Cách trả về dữ liệu Mock có điều kiện bằng Quy tắc tùy chỉnh và Script Mock

Smart mock cung cấp API giả trong vài giây. Công cụ đọc lược đồ điểm cuối và tạo dữ liệu hợp lý như email, dấu thời gian hoặc tên người dùng. Với phần lớn công việc frontend, Smart mock đủ để bạn tiếp tục phát triển mà không cần chờ backend.

Dùng thử Apidog ngay hôm nay

Tuy nhiên, Smart mock chỉ trả về một cấu trúc cho mỗi điểm cuối. Khi cần phân nhánh theo yêu cầu — chẳng hạn /login trả về 200 cho người dùng hợp lệ và 401 cho các trường hợp khác, hoặc /orders/{id} trả về các trạng thái đơn hàng khác nhau — bạn cần mock có điều kiện.

Apidog giải quyết trường hợp này bằng hai tính năng:

• Mock expectations: phản hồi dựa trên điều kiện.
• Mock scripts: JavaScript cho logic tính toán mà điều kiện không thể biểu diễn.

Nếu bạn mới bắt đầu, hãy xem tổng quan về mocking API. Công cụ được sử dụng trong bài là Apidog, dựa trên quy trình contract-first mà OpenAPI Initiative tài liệu hóa.

Conditional mocking thực sự có nghĩa là gì?

Mock có điều kiện là một quy tắc:

Nếu yêu cầu trông như thế này, hãy trả về phản hồi như thế kia.

Trong Apidog, bạn có hai lớp cấu hình.

1. Tùy chỉnh cấp trường trong schema
   
   Gán giá trị cố định hoặc dùng Faker.js để sinh dữ liệu động. Cách này kiểm soát giá trị từng trường nhưng không phân nhánh phản hồi theo yêu cầu.

2. Mock expectations cho toàn bộ phản hồi
   
   Mỗi expectation có thể có:

   • Tên quy tắc
   • Điều kiện khớp yêu cầu
   • Response body
   • HTTP status code
   • Response headers
   • Response delay

Expectation không có điều kiện hoạt động như quy tắc bắt tất cả. Expectation có điều kiện chỉ trả về phản hồi khi yêu cầu khớp.

Các giá trị động cấp trường trước

Trước khi tạo nhánh phản hồi, hãy xem cách tạo dữ liệu động trong schema. Bất kỳ trường chuỗi nào cũng có thể dùng biểu thức Faker.js theo cú pháp:

{{$category.method}}

Ví dụ:

{
  "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')}}"
}

Bạn có thể truyền tham số cho phương thức Faker.js, nối văn bản tĩnh với biểu thức động, hoặc cấu hình locale để dữ liệu phù hợp với khu vực. Xem tài liệu tham khảo Faker.js trong Apidog để biết thêm các phương thức hỗ trợ.

Smart mock tạo dữ liệu động, nhưng không phân nhánh theo request. Để làm điều đó, hãy dùng mock expectations.

Hướng dẫn: POST /login trả về 200 hoặc 401

Giả sử điểm cuối POST /login nhận JSON:

{
  "username": "[e-mail]",
  "password": "whatever"
}

Mục tiêu:

• [e-mail] nhận 200 và token.
• Các username khác nhận 401.

1. Mở tab cấu hình mock

Tùy chế độ làm việc:

• Trong DEBUG, mở điểm cuối rồi chọn tab Mock.

• Trong DESIGN, mở điểm cuối rồi chọn tab Advanced mock.

Cả hai đều dẫn đến danh sách expectation. Nếu chưa có ứng dụng, hãy tải Apidog, sau đó tạo hoặc import điểm cuối /login.

2. Tạo expectation thành công

Nhấn New expectation và cấu hình:

• Expectation name: login-success
• Condition type: request body parameter
• Name / JSON path: username
• Condition value: [e-mail]

Với body JSON lồng nhau, dùng đường dẫn dấu chấm, ví dụ:

user.email

Đặt Response data:

{
  "token": "mock-jwt-{{$string.uuid}}",
  "user": {
    "id": 4821,
    "username": "[e-mail]",
    "role": "member"
  }
}

Lưu expectation. HTTP status mặc định là 200, nên không cần thay đổi thêm.

3. Tạo expectation thất bại

Tạo expectation thứ hai:

• Expectation name: login-failure
• Không thêm điều kiện.

Expectation này sẽ trở thành quy tắc bắt tất cả. Đặt Response data:

{
  "error": "invalid_credentials",
  "message": "Username or password is incorrect."
}

Mở tab More và đặt:

• HTTP Status Code: 401

Bạn cũng có thể đặt tại đây:

• Response delay theo mili giây
• Response headers tùy chỉnh

Ví dụ, thêm độ trễ 400ms để kiểm tra trạng thái loading trên frontend.

4. Sắp xếp expectation đúng thứ tự

Apidog kiểm tra expectation từ trên xuống dưới. Quy tắc khớp đầu tiên sẽ thắng.

Sắp xếp như sau:

1. login-success
2. login-failure

Nếu đặt login-failure ở trên, quy tắc không điều kiện sẽ khớp mọi request và login-success sẽ không bao giờ chạy.

Kiểm tra bằng curl:

# known user -> 200 with a token
curl -X POST https://<your-mock-host>/login \
  -H "Content-Type: application/json" \
  -d '{"username":"[e-mail]","password":"whatever"}'

# anyone else -> 401
curl -X POST https://<your-mock-host>/login \
  -H "Content-Type: application/json" \
  -d '{"username":"[e-mail]","password":"whatever"}'

Hướng dẫn: phản hồi khác nhau cho /orders/{id}

Bạn cũng có thể phân nhánh theo path parameter. Ví dụ:

• /orders/5001 trả về đơn hàng đã giao.
• /orders/5002 trả về đơn hàng đã hủy.
• Mọi ID khác trả về đơn hàng đang chờ xử lý.

Expectation order-shipped

Thêm điều kiện:

• Path parameter: id
• Giá trị: 5001

Response body:

{
  "id": 5001,
  "status": "shipped",
  "total": 129.9,
  "trackingNumber": "1Z{{$string.alphanumeric(length=16)}}",
  "shippedAt": "{{$date.recent(days=3,format='yyyy-MM-dd')}}"
}

Expectation order-cancelled

Thêm điều kiện:

• Path parameter: id
• Giá trị: 5002

Response body:

{
  "id": 5002,
  "status": "cancelled",
  "total": 0,
  "cancelledAt": "{{$date.recent(days=1,format='yyyy-MM-dd')}}",
  "refundIssued": true
}

Thêm fallback cho các ID khác

Tạo expectation cuối cùng không có điều kiện để trả về một đơn hàng đang chờ xử lý. Luôn đặt quy tắc này ở cuối danh sách.

Bạn cũng có thể kết hợp điều kiện. Ví dụ, thêm cả:

• Path parameter id=5001
• Header X-Test-Mode=admin

Nhiều điều kiện được kết hợp bằng logic AND, nghĩa là tất cả điều kiện phải khớp.

Apidog hỗ trợ điều kiện dựa trên:

• Request body JSON
• Path parameter
• Query parameter
• Header
• Cookie
• Địa chỉ IP

Buộc các trạng thái lỗi theo yêu cầu

Bạn không cần làm hỏng backend để kiểm tra xử lý lỗi của frontend.

Ví dụ: tạo một expectation trả về 500 khi client gửi header sau:

X-Mock-Scenario: server-error

Đặt response body:

{
  "error": "internal_error",
  "requestId": "{{$string.uuid}}",
  "message": "Something went wrong on our end. Please retry."
}

Trong tab More, đặt:

HTTP Status Code: 500

Frontend có thể kích hoạt lỗi bằng request như sau:

curl https://<your-mock-host>/orders/5001 \
  -H "X-Mock-Scenario: server-error"

Bạn có thể áp dụng cùng kỹ thuật cho:

• 404 Not Found
• 429 Too Many Requests
• 503 Service Unavailable

Với 429, hãy thêm header Retry-After trong tab More để kiểm tra retry logic.

Nếu muốn xác thực các response này bằng kiểm thử tự động, hãy xem hướng dẫn về xác nhận API.

Mỗi expectation có thể được bật hoặc tắt độc lập cho mock cục bộ và mock đám mây. Điều này hữu ích khi bạn muốn giữ quy tắc 500 trong local mock nhưng không muốn đồng đội gặp lỗi đó trên cloud mock.

Khi các quy tắc không đủ: Mock Script

Mock expectations phù hợp với các nhánh cố định. Nhưng nếu response cần được tính toán từ request, hãy dùng Mock Script.

Mock Script là JavaScript chạy trên phản hồi Smart mock. Nó nằm ở cuối tab Mock và cần được bật bằng công tắc.

Các biến toàn cục có sẵn:

• $$.mockRequest

  • getParam(key)
  • headers
  • cookies
  • body
  • formdata
  • urlencoded

• $$.mockResponse

  • setBody()
  • setCode()
  • setDelay()
  • json()
  • headers
  • code

Ví dụ: tính tổng đơn hàng từ các item trong request body và đọc currency từ header.

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))
});

Ví dụ request:

{
  "items": [
    { "price": 19.99, "quantity": 2 },
    { "price": 5, "quantity": 3 }
  ]
}

Mock Script có thể tính toán subtotal, tax và total thay vì bạn phải tạo sẵn mọi tổ hợp response.

Để mở rộng logic JavaScript, hãy tham khảo MDN JavaScript.

Quy tắc quan trọng: Mock Script không chạy cùng expectation

Mock Script chỉ hoạt động với Smart mock.

Nó không áp dụng cho:

• Mock expectations
• Response examples

Nếu một expectation khớp request, Mock Script sẽ không chạy. Vì vậy, chọn một phương pháp cho mỗi điểm cuối:

Nhu cầu	Nên dùng
Response cố định theo điều kiện	Mock expectations
Response được tính toán từ request	Mock Script với Smart mock
Dữ liệu động từ schema	Smart mock

Thứ tự ưu tiên của mock

Với mỗi mock request, Apidog xử lý theo thứ tự sau:

1. Kiểm tra mock expectations từ trên xuống dưới.
2. Nếu có expectation mà tất cả điều kiện đều khớp, Apidog trả về response của expectation đó.
3. Nếu không expectation nào khớp, Apidog dùng Mock Method Priority trong:

   Project Settings → Feature Settings → Mock Settings

1. Ở bước fallback này, Smart mock tạo response từ schema; Mock Script cũng chỉ chạy ở lớp này.

Mô hình nên dùng:

Quy tắc cụ thể → Quy tắc ít cụ thể hơn → Fallback không điều kiện → Smart mock

Đặt expectation cụ thể ở đầu, expectation bắt tất cả ở cuối, và để Smart mock xử lý các trường hợp còn lại. Xem thêm các trường hợp sử dụng mocking API để chọn đúng phương pháp cho từng tình huống.

Những điều cần biết trước khi triển khai

Trước khi gỡ lỗi expectation không hoạt động, kiểm tra các giới hạn sau:

• Điều kiện tham số không hỗ trợ {{variables}}.
• Biến project và environment của Apidog không khả dụng trong mock expectations.
• Điều kiện request body chỉ hỗ trợ JSON, không hỗ trợ XML.
• Với JSON body, trường tên điều kiện phải dùng JSON path, ví dụ user.email.
• Định dạng điều kiện phải khớp đặc tả API. Điểm cuối form-data phải dùng vị trí form-data, không phải JSON.
• Mock Script không có hàm logging.
• Đối tượng pm không khả dụng trong Mock Script.
• Biến Apidog không thể dùng bên trong Mock Script.

Giữ Mock Script độc lập và tránh phụ thuộc vào biến môi trường.

Tự động hóa quy trình với Apidog CLI

Mocking trong Apidog là tính năng GUI và cloud. Không có lệnh CLI để khởi động mock server đang chạy.

Tuy nhiên, Apidog CLI giúp quản lý tài nguyên mà mock được xây dựng từ đó.

Mock response phụ thuộc vào endpoint schema. Khi contract thay đổi, hãy cập nhật endpoint và schema trong project để Smart mock luôn tạo response đúng với API hiện tại.

Sau khi mock giúp frontend phát triển độc lập, bạn có thể chạy test scenario trong CI để xác thực backend thực tế:

apidog run -t <scenario_id> -e <env_id> -r cli

Lệnh này chạy test scenario và báo cáo kết quả. Mock, schema và kiểm thử có thể cùng dựa trên một nguồn contract.

Xem thêm:

• Hướng dẫn cài đặt Apidog CLI
• Apidog CLI trong GitHub Actions

Câu hỏi thường gặp

Tại sao expectation bị bỏ qua dù điều kiện có vẻ đúng?

Thường do hai nguyên nhân:

1. Sai thứ tự expectation: một quy tắc không điều kiện nằm phía trên quy tắc cụ thể.
2. Sai định dạng điều kiện: JSON body cần JSON path; form-data phải dùng vị trí form-data.

Hãy kiểm tra lại tổng quan về mocking API nếu cần xem lại cấu hình cơ bản.

Tôi có thể dùng Mock Script và mock expectation trên cùng response không?

Không. Mock Script chỉ chạy với Smart mock. Khi expectation khớp, script sẽ bị bỏ qua.

Làm cách nào trả về 401 hoặc 500 mà không ảnh hưởng response 200 mặc định?

Tạo expectation riêng với điều kiện do client kiểm soát, chẳng hạn header X-Mock-Scenario. Sau đó đặt HTTP status trong tab More. Khi header không có hoặc không khớp, response mặc định vẫn là 200.

Điều kiện có dùng được biến môi trường không?

Không. {{variable}} không khả dụng trong mock expectations, và điều kiện không hỗ trợ {{variables}}. Dùng giá trị cố định trong điều kiện.

Điều gì xảy ra nếu không expectation nào khớp?

Apidog quay về Mock Method Priority trong:

Project Settings → Feature Settings → Mock Settings

Tại đó, Smart mock tạo response từ schema. Nếu cần fallback cụ thể, thêm expectation không điều kiện ở cuối danh sách.

Tóm tắt

Dùng Smart mock khi bạn cần dữ liệu động nhanh từ schema. Dùng mock expectations khi response cần phân nhánh theo request:

• 200 cho người dùng hợp lệ, 401 cho các trường hợp khác
• Response đơn hàng khác nhau theo id
• 500, 404, 429 hoặc 503 theo header hoặc query parameter

Chỉ dùng Mock Script khi cần tính toán response từ dữ liệu request. Luôn nhớ: expectation được kiểm tra trước, từ trên xuống dưới; Smart mock chỉ là fallback khi không expectation nào khớp.

Tải Apidog để tạo mock có điều kiện đầu tiên của bạn.