Bạn cần một API giả để xây dựng. Có thể backend chưa sẵn sàng, hoặc dịch vụ bên thứ ba bị giới hạn tốc độ truy cập, hoặc bạn chỉ muốn các thử nghiệm của mình chạy mà không cần truy cập máy chủ thật. Câu trả lời thông thường là một mock. Vấn đề là làm thế nào để bạn thiết lập một mock.
Bạn có thể nhấp qua giao diện người dùng (GUI) để định nghĩa các route và phản hồi có sẵn. Điều đó tốt cho một lần. Nhưng một mock bạn tự xây dựng bằng tay trong một ứng dụng desktop thì khó tái tạo, khó quản lý phiên bản, và không thể được tái tạo tự động bởi CI hoặc một tác nhân mã hóa AI. Một mock bạn định nghĩa từ dòng lệnh thì khác. Nó là một lệnh trong một script, một bước trong một pipeline, một dòng mà một tác nhân có thể chạy. Những gì bạn gõ, máy cũng có thể gõ.
Hướng dẫn này bao gồm hai cách. Thứ nhất, cách mã nguồn mở chung: các máy chủ mock nhị phân đơn lẻ mà bạn chạy trực tiếp từ một tệp, để một spec hoặc một tệp JSON trở thành một endpoint trực tiếp chỉ với một lệnh. Sau đó là cách CLI của Apidog, hoạt động khác và đáng để tìm hiểu theo cách riêng của nó. Nếu bạn muốn có cái nhìn tổng quan về các tùy chọn trước, tổng hợp của chúng tôi về các công cụ mock API tốt nhất và hướng dẫn các công cụ mock API REST đều cung cấp cho bạn cái nhìn rộng hơn.
button
Cách chung: chạy máy chủ mock từ một tệp
Mock CLI cổ điển là một tệp nhị phân nhỏ mà bạn trỏ vào một tệp. Cung cấp cho nó một spec hoặc một tệp dữ liệu, và nó sẽ phục vụ một endpoint HTTP thực trên một cổng cục bộ. Không có dự án, không cần đăng nhập, không cần tài khoản. Các công cụ này chỉ làm một việc: biến một tệp thành một API giả mà bạn có thể gọi. Ba công cụ dưới đây bao gồm hầu hết mọi trường hợp.
Prism: phục vụ một spec OpenAPI
Nếu bạn đã có một tệp OpenAPI, Prism của Stoplight là công cụ mock yêu cầu ít nỗ lực nhất mà bạn có thể chạy. Nó đọc các paths, ví dụ và schema của bạn, sau đó phục vụ các phản hồi phù hợp với hợp đồng.
npx @stoplight/prism-cli mock ./openapi.yaml
Lệnh đó khởi động một máy chủ trên http://127.0.0.1:4010 với mọi hoạt động trong spec của bạn được kết nối. Prism trả về example mà bạn đã định nghĩa cho một phản hồi, hoặc tạo một phản hồi ngẫu nhiên hợp lệ từ schema nếu bạn không định nghĩa. Nó cũng xác thực các yêu cầu đến so với spec, vì vậy một lời gọi bị sai cấu trúc sẽ nhận được mã 422 thích hợp thay vì được thông qua một cách im lặng. Hãy gọi nó để kiểm tra xem nó có hoạt động không:
curl http://127.0.0.1:4010/orders/123
Prism không trạng thái (stateless), vì vậy một yêu cầu POST không duy trì bất cứ điều gì. Đó là điểm mấu chốt khi bạn muốn mock giữ đúng hợp đồng. Để cài đặt toàn cục, hãy chạy npm install -g @stoplight/prism-cli và bỏ npx.
Mockoon CLI: chạy một tệp dữ liệu không có giao diện
Mockoon CLI chạy một mock từ một tệp dữ liệu, có thể là tệp bạn đã xuất từ ứng dụng desktop Mockoon miễn phí hoặc một spec OpenAPI đơn giản. Ứng dụng desktop cho phép bạn xây dựng các route một cách trực quan; CLI chạy cùng môi trường đó mà không có giao diện trong CI hoặc trên một máy chủ.
npx @mockoon/cli start --data ./env.json
Trỏ --data vào một tệp môi trường Mockoon hoặc một tệp OpenAPI JSON/YAML và nó sẽ phục vụ ngay lập tức, mặc định ở cổng 3000. Thêm --port để thay đổi nó. Nếu tệp dữ liệu đến từ một phiên bản Mockoon cũ hơn, CLI sẽ di chuyển nó trong bộ nhớ mà không chạm vào tệp gốc. Cài đặt nó toàn cục với npm install -g @mockoon/cli để có lệnh mockoon-cli liên tục. Đây là một lựa chọn tốt khi bạn muốn các route phong phú hơn, được điều chỉnh thủ công hơn so với một spec đơn thuần cung cấp và vẫn muốn chúng chạy mà không cần giao diện người dùng. Một máy chủ mock nhẹ cho API RESTful thường thuộc trường hợp này.
json-server: tạo API REST giả từ JSON
Khi bạn chưa có spec, json-server là cách nhanh nhất. Bạn viết một tệp JSON đơn giản mô tả dữ liệu của mình, và nó sẽ xây dựng một API REST đầy đủ xung quanh nó.
npx json-server db.json
Với một db.json chứa một mảng posts, nó sẽ phục vụ http://localhost:3000/posts với các phương thức GET, POST, PUT, PATCH và DELETE thực sự. Một yêu cầu POST thực sự thêm một bản ghi và ghi lại vào tệp, vì vậy bạn có hành vi trạng thái miễn phí, điều mà Prism không cung cấp. Bạn cũng có thể lọc, sắp xếp và phân trang thông qua các tham số truy vấn. Cài đặt toàn cục với npm install -g json-server nếu bạn muốn nó luôn có trong PATH của mình.
Đó là cách mở. Mỗi công cụ là một tệp nhị phân đơn lẻ, chạy từ một tệp và không cần gì khác. Đánh đổi là mỗi công cụ đều là một hòn đảo riêng biệt. Mock tồn tại tách biệt với thiết kế thực, các thử nghiệm và tài liệu của bạn, và bạn phải tự giữ các tệp và các quy trình đang chạy đồng bộ. Nếu bạn cần khớp yêu cầu chính xác hoặc phát lại, MockServer và WireMock đi sâu hơn, với cái giá phải trả là một môi trường chạy Java.
Cách CLI của Apidog: nhập spec, script các kỳ vọng
Apidog mock theo cách khác, và việc hiểu đúng điều này sẽ giúp bạn tránh nhầm lẫn. CLI apidog không khởi động máy chủ mock cục bộ từ một tệp. Không có lệnh apidog mock ./openapi.yaml. Thay vào đó, Apidog lưu trữ mock cho bạn, và CLI là cách bạn cung cấp cho nó một spec và script các phản hồi tùy chỉnh.
Một lưu ý trung thực trước. Apidog không phải là mã nguồn mở; nó là một sản phẩm thương mại có phiên bản miễn phí. Điều mà phiên bản miễn phí cùng với CLI mang lại cho bạn là một dự án tích hợp, vì vậy mock, thiết kế và các thử nghiệm chia sẻ một nguồn thông tin duy nhất thay vì ba tệp và ba quy trình riêng biệt. Nếu tất cả những gì bạn cần là một mock dùng một lần từ một tệp, một công cụ nhẹ hơn sẽ phù hợp hơn. Nếu mock của bạn cần theo kịp API thực của bạn khi nó thay đổi, hãy đọc tiếp.
Cài đặt và xác thực trước (hướng dẫn cài đặt Apidog CLI bao gồm thiết lập token):
npm install -g apidog-cli
apidog login --with-token <YOUR_ACCESS_TOKEN>
Nhập một spec để có các mock thông minh được lưu trữ
Bước đầu tiên là đưa API của bạn vào một dự án. Nhập một tệp OpenAPI, và Apidog sẽ tự động tạo một URL mock cho mỗi endpoint.
apidog import --project <PROJECT_ID> --format openapi --file ./openapi.json
Đây là điểm khác biệt của Apidog so với Prism và json-server. Bạn không chạy máy chủ; việc nhập cung cấp cho bạn một mock thông minh được lưu trữ cho mỗi hoạt động. Mock thông minh đọc các kiểu và tên trường của schema của bạn, vì vậy một trường email trả về một email hợp lý và một createdAt trả về một timestamp trông giống thật, chứ không phải một chuỗi ngẫu nhiên. apidog import cũng chấp nhận các định dạng Swagger 2.0, Postman và Apidog, vì vậy một định nghĩa hiện có sẽ trở thành các mock trực tiếp chỉ bằng một lệnh.
Script các phản hồi tùy chỉnh với apidog mock
Các mock được tạo tự động bao gồm trường hợp phổ biến. Khi bạn cần một phản hồi cụ thể cho một yêu cầu cụ thể, ví dụ một mã 200 cho một ID người dùng và mã 404 cho một ID khác, bạn thêm một kỳ vọng mock. Đây là những gì nhóm lệnh apidog mock quản lý, và đó là các thao tác CRUD (Tạo, Đọc, Cập nhật, Xóa) trên các kỳ vọng đó, chứ không phải một máy chủ mà bạn khởi động.
apidog mock --help
apidog mock list --project <PROJECT_ID>
apidog mock list --project <PROJECT_ID> --http-api-id <ENDPOINT_ID>
Việc liệt kê trả về JSON có cấu trúc, vì vậy bạn có thể chuyển nó qua jq để tìm ID của một kỳ vọng và cấp cho lệnh tiếp theo. Để đọc, thay đổi hoặc xóa một kỳ vọng:
apidog mock get --project <PROJECT_ID>
apidog mock update --project <PROJECT_ID> --file ./mock.json
apidog mock delete --project <PROJECT_ID>
Các lệnh con create và update nhận một --file mô tả kỳ vọng. Nắm vững cấu trúc trước khi bạn viết nó, sẽ được trình bày tiếp theo.
Xác thực tệp kỳ vọng trước khi bạn ghi nó
Đừng tự đoán JSON. CLI đi kèm với một schema cho mỗi thao tác ghi, vì vậy bạn lấy cấu trúc, điền vào và xác thực trước khi ghi thực sự. Một kỳ vọng bị sai cấu trúc sẽ thất bại ngay lập tức thay vì được ghi một cách âm thầm.
apidog cli-schema get mock-create
apidog cli-schema validate mock-create --file ./mock.json
apidog mock create --project <PROJECT_ID> --file ./mock.json
Lấy schema, viết mock.json của bạn cho phù hợp, xác thực nó, sau đó tạo. Nếu xác thực trả về một mã thoát khác không, pipeline sẽ dừng trước khi một tệp lỗi đến dự án của bạn. Chạy ba bước tương tự cho các bản cập nhật với khóa schema mock-update. Mọi lệnh đều trả về JSON với một khối agentHints.nextSteps cho bạn, hoặc một tác nhân, biết phải chạy gì tiếp theo, điều này làm cho quy trình này có thể sử dụng được bởi các công cụ mã hóa AI chứ không chỉ con người. Hướng dẫn hoàn chỉnh về Apidog CLI mô tả phần còn lại của các nhóm lệnh.
Tích hợp vào CI
Cả hai cách đều phù hợp với một pipeline vì mỗi lệnh đều có mã thoát và đầu ra văn bản. Một mock dựa trên máy chủ và một thử nghiệm tích hợp trong cùng một công việc có thể trông như thế này:
# start Prism in the background, then run tests against it
npx @stoplight/prism-cli mock ./openapi.yaml &
PRISM_PID=$!
npm test
kill $PRISM_PID
Quy trình của Apidog có hình dạng khác: không có quy trình cục bộ nào để khởi động và dừng, vì mock được lưu trữ. Bạn xác thực và áp dụng các kỳ vọng như một bước thiết lập, và các thử nghiệm của bạn truy cập trực tiếp URL mock được lưu trữ.
# ensure the expectation is well-formed, then apply it
apidog cli-schema validate mock-create --file ./mock.json
apidog mock create --project <PROJECT_ID> --file ./mock.json
Dù bằng cách nào, không ai phải nhấp chuột. Đó là toàn bộ lý do để tạo mock từ CLI: một nhóm làm việc theo spec, một công việc CI và một tác nhân AI đều có thể thiết lập cùng một API giả từ cùng các lệnh.
Các lỗi thường gặp
Mong đợi apidog mock khởi động một máy chủ. Nó sẽ không. Không có lệnh apidog mock start, apidog mock serve, hoặc apidog mock ./file.yaml. Bạn apidog import một spec để có các mock được lưu trữ, và apidog mock quản lý các kỳ vọng tùy chỉnh trên đó. Nếu bạn muốn một quy trình cục bộ mà bạn khởi chạy từ một tệp, đó là Prism, Mockoon CLI, hoặc json-server.
Bỏ qua bước schema khi ghi. apidog mock create và update nhận một --file, và một cấu trúc sai sẽ thất bại hoặc ghi ra thứ bạn không muốn. Luôn chạy cli-schema get và cli-schema validate trước. Đó là hai lệnh bổ sung và nó giúp bạn tiết kiệm một buổi gỡ lỗi.
Prism trông trống rỗng vì spec của bạn quá mỏng. Mock của Prism chỉ tốt bằng các ví dụ của bạn. Nếu một phản hồi không có example và một schema mơ hồ, bạn sẽ nhận được dữ liệu mơ hồ. Thêm ví dụ vào spec và mock sẽ trở nên sắc nét hơn.
Các kỳ vọng có trạng thái từ một công cụ không trạng thái. Các mock hợp đồng của Prism và Apidog không duy trì các thao tác ghi. Nếu bạn cần một POST sau đó GET để trả về bản ghi mới, hãy dùng json-server hoặc một kỳ vọng Apidog trả về cấu trúc bạn muốn.
Tóm lại
Tạo mock từ CLI biến một công việc nặng nề với chuột thành các lệnh mà bạn có thể script, xem xét và chuyển cho CI hoặc một tác nhân. Cách mở cung cấp cho bạn các máy chủ nhị phân đơn lẻ mà bạn chạy từ một tệp: Prism cho một spec OpenAPI, Mockoon CLI cho một tệp dữ liệu không giao diện, json-server cho một API REST tức thì từ JSON. Cách của Apidog hoạt động theo cách khác; bạn nhập một spec một lần để có các mock thông minh được lưu trữ, sau đó script các phản hồi tùy chỉnh với apidog mock và kiểm tra bảo vệ cli-schema.
Hãy chọn dựa trên những gì bạn đã có và nơi mock cần tồn tại. Nếu bạn muốn một máy chủ dùng một lần từ một tệp, các công cụ mở là hoàn hảo. Nếu bạn muốn mock luôn đồng bộ với thiết kế và các thử nghiệm của mình trong một dự án, Tải xuống Apidog, cài đặt CLI và thiết lập các mock của bạn mà không cần chạm vào chuột.