Nguon: Microsoft Learn · .NET 8.0

Kiểm thử Web API với HttpRepl

Nguồn: Test web APIs with the HttpRepl

HTTP Read-Eval-Print Loop (REPL) là:

Các HTTP verb (phương thức HTTP) sau được hỗ trợ:

Điều kiện tiên quyết (Prerequisites)

Cài đặt (Installation)

Để cài đặt HttpRepl, hãy chạy lệnh sau:

dotnetcli
dotnet tool install -g Microsoft.dotnet-httprepl

Một .NET Global Tool được cài đặt từ gói NuGet Microsoft.dotnet-httprepl.

Trên macOS, cập nhật path (đường dẫn):

bash
export PATH="$HOME/.dotnet/tools:$PATH"

Sử dụng (Usage)

Sau khi cài đặt thành công công cụ, chạy lệnh sau để khởi động HttpRepl:

console
httprepl

Để xem các lệnh HttpRepl có sẵn, hãy chạy một trong các lệnh sau:

console
httprepl -h
console
httprepl --help

Kết quả sau được hiển thị:

console
Usage:
  httprepl [<BASE_ADDRESS>] [options]

Arguments:
  <BASE_ADDRESS> - The initial base address for the REPL.

Options:
  -h|--help - Show help information.

Once the REPL starts, these commands are valid:

Setup Commands:
Use these commands to configure the tool for your API server

connect        Configures the directory structure and base address of the api server
set header     Sets or clears a header for all requests. e.g. `set header content-type application/json`

HTTP Commands:
Use these commands to execute requests against your application.

GET            get - Issues a GET request
POST           post - Issues a POST request
PUT            put - Issues a PUT request
DELETE         delete - Issues a DELETE request
PATCH          patch - Issues a PATCH request
HEAD           head - Issues a HEAD request
OPTIONS        options - Issues a OPTIONS request

Navigation Commands:
The REPL allows you to navigate your URL space and focus on specific APIs that you are working on.

ls             Show all endpoints for the current path
cd             Append the given directory to the currently selected path, or move up a path when using `cd ..`

Shell Commands:
Use these commands to interact with the REPL shell.

clear          Removes all text from the shell
echo [on/off]  Turns request echoing on or off, show the request that was made when using request commands
exit           Exit the shell

REPL Customization Commands:
Use these commands to customize the REPL behavior.

pref [get/set] Allows viewing or changing preferences, e.g. 'pref set editor.command.default 'C:\\Program Files\\Microsoft VS Code\\Code.exe'`
run            Runs the script at the given path. A script is a set of commands that can be typed with one command per line
ui             Displays the Swagger UI page, if available, in the default browser

Use `help <COMMAND>` for more detail on an individual command. e.g. `help get`.
For detailed tool info, see https://aka.ms/http-repl-doc.

HttpRepl cung cấp tính năng hoàn thành lệnh (command completion). Nhấn phím Tab để duyệt qua danh sách các lệnh hoàn thành các ký tự hoặc API endpoint mà bạn đã gõ.

Kết nối đến Web API

Kết nối đến Web API bằng cách chạy lệnh sau:

console
httprepl <ROOT URI>

<ROOT URI> là URI cơ sở cho Web API. Ví dụ:

console
httprepl https://localhost:5001

Ngoài ra, hãy chạy lệnh sau bất kỳ lúc nào trong khi HttpRepl đang chạy:

console
connect <ROOT URI>

Ví dụ:

console
(Disconnected)> connect https://localhost:5001

Chỉ định thủ công mô tả OpenAPI cho Web API

Lệnh connect ở trên sẽ cố gắng tìm mô tả OpenAPI tự động. Nếu vì lý do nào đó không thể làm vậy, bạn có thể chỉ định URI của mô tả OpenAPI cho Web API bằng tùy chọn --openapi:

console
connect <ROOT URI> --openapi <OPENAPI DESCRIPTION ADDRESS>

Ví dụ:

console
(Disconnected)> connect https://localhost:5001 --openapi /swagger/v1/swagger.json

Bật đầu ra chi tiết để xem thông tin tìm kiếm mô tả OpenAPI

Chỉ định tùy chọn --verbose với lệnh connect sẽ cho ra thêm chi tiết khi công cụ tìm kiếm mô tả OpenAPI, phân tích cú pháp và xác thực nó.

console
connect <ROOT URI> --verbose

Ví dụ:

console
(Disconnected)> connect https://localhost:5001 --verbose
Checking https://localhost:5001/swagger.json... 404 NotFound
Checking https://localhost:5001/swagger/v1/swagger.json... 404 NotFound
Checking https://localhost:5001/openapi.json... Found
Parsing... Successful (with warnings)
The field 'info' in 'document' object is REQUIRED [#/info]
The field 'paths' in 'document' object is REQUIRED [#/paths]

Điều hướng Web API

Xem các endpoint có sẵn

Để liệt kê các endpoint (controller) khác nhau tại đường dẫn hiện tại của địa chỉ Web API, hãy chạy lệnh ls hoặc dir:

console
https://localhost:5001/> ls

Định dạng đầu ra sau được hiển thị:

console
.        []
Fruits   [get|post]
People   [get|post]

https://localhost:5001/>

Đầu ra trên cho thấy có hai controller: Fruits và People. Cả hai controller đều hỗ trợ các thao tác HTTP GET và POST không có tham số.

Điều hướng vào một controller cụ thể sẽ cho thấy thêm chi tiết. Ví dụ, đầu ra của lệnh sau cho thấy controller Fruits cũng hỗ trợ các thao tác HTTP GET, PUT và DELETE. Mỗi thao tác này yêu cầu tham số id trong route:

console
https://localhost:5001/fruits> ls
.      [get|post]
..     []
{id}   [get|put|delete]

https://localhost:5001/fruits>

Điều hướng đến một endpoint

Để điều hướng đến một endpoint khác trên Web API, hãy chạy lệnh cd:

console
https://localhost:5001/> cd people

Đường dẫn sau lệnh cd không phân biệt chữ hoa/thường. Định dạng đầu ra sau được hiển thị:

console
/people    [get|post]

https://localhost:5001/people>

Tùy chỉnh HttpRepl

Màu sắc mặc định của HttpRepl có thể được tùy chỉnh. Ngoài ra, một trình soạn thảo văn bản mặc định có thể được định nghĩa. Các tùy chọn của HttpRepl được lưu giữ trong phiên hiện tại và được tôn trọng trong các phiên tương lai. Sau khi được sửa đổi, các tùy chọn được lưu trong file sau:

File .httpreplprefs được tải khi khởi động và không được theo dõi để thay đổi tại runtime. Các thay đổi thủ công đối với file chỉ có hiệu lực sau khi khởi động lại công cụ.

Xem cài đặt

Để xem các cài đặt có sẵn, hãy chạy lệnh pref get. Ví dụ:

console
https://localhost:5001/> pref get

Lệnh trên hiển thị các cặp key-value có sẵn:

console
colors.json=Green
colors.json.arrayBrace=BoldCyan
colors.json.comma=BoldYellow
colors.json.name=BoldMagenta
colors.json.nameSeparator=BoldWhite
colors.json.objectBrace=Cyan
colors.protocol=BoldGreen
colors.status=BoldYellow

Đặt tùy chọn màu sắc

Tô màu phản hồi hiện chỉ được hỗ trợ cho JSON. Để tùy chỉnh màu sắc mặc định của công cụ HttpRepl, hãy tìm key tương ứng với màu cần thay đổi. Ví dụ, thay đổi giá trị key colors.json từ Green thành White như sau:

console
https://localhost:5001/people> pref set colors.json White

Chỉ các màu được phép mới có thể được sử dụng. Các yêu cầu HTTP tiếp theo hiển thị đầu ra với màu sắc mới.

Đặt kích thước thụt lề (indentation)

Tùy chỉnh kích thước thụt lề phản hồi hiện chỉ được hỗ trợ cho JSON. Kích thước mặc định là hai khoảng trắng. Để thay đổi kích thước mặc định, hãy đặt key formatting.json.indentSize. Ví dụ, để luôn sử dụng bốn khoảng trắng:

console
pref set formatting.json.indentSize 4

Đặt trình soạn thảo văn bản mặc định

Theo mặc định, HttpRepl không có trình soạn thảo văn bản nào được cấu hình để sử dụng. Để kiểm thử các phương thức Web API yêu cầu body của yêu cầu HTTP, cần đặt trình soạn thảo văn bản mặc định. Chạy lệnh sau để đặt trình soạn thảo văn bản ưa thích làm mặc định:

console
pref set editor.command.default "<EXECUTABLE>"

Trong lệnh trên, <EXECUTABLE> là đường dẫn đầy đủ đến file thực thi của trình soạn thảo văn bản. Ví dụ, chạy lệnh sau để đặt Visual Studio Code làm trình soạn thảo văn bản mặc định:

Để khởi chạy trình soạn thảo văn bản mặc định với các đối số CLI cụ thể, hãy đặt key editor.command.default.arguments. Ví dụ, giả sử Visual Studio Code là trình soạn thảo văn bản mặc định và bạn muốn HttpRepl luôn mở Visual Studio Code trong một phiên mới với các extension bị vô hiệu hóa:

console
pref set editor.command.default.arguments "--disable-extensions --new-window"

Đặt đường dẫn tìm kiếm mô tả OpenAPI

Theo mặc định, HttpRepl có một tập hợp các đường dẫn tương đối mà nó sử dụng để tìm mô tả OpenAPI khi thực thi lệnh connect mà không có tùy chọn --openapi. Các đường dẫn tương đối này được kết hợp với các đường dẫn root và base được chỉ định trong lệnh connect. Các đường dẫn tương đối mặc định là:

Để sử dụng một tập hợp đường dẫn tìm kiếm khác trong môi trường của bạn, hãy đặt tùy chọn swagger.searchPaths. Giá trị phải là danh sách các đường dẫn tương đối được phân tách bằng dấu pipe. Ví dụ:

console
pref set swagger.searchPaths "swagger/v2/swagger.json|swagger/v3/swagger.json"

Kiểm thử yêu cầu HTTP GET

Cú pháp (Synopsis)

console
get <PARAMETER> [-F|--no-formatting] [-h|--header] [--response:body] [--response:headers] [-s|--streaming]

Ví dụ (Example)

Để thực hiện yêu cầu HTTP GET:

  1. Chạy lệnh get trên endpoint hỗ trợ nó:

``console https://localhost:5001/people> get ``

Lệnh trên hiển thị định dạng đầu ra sau:

```console HTTP/1.1 200 OK Content-Type: application/json; charset=utf-8 Date: Fri, 21 Jun 2019 03:38:45 GMT Server: Kestrel Transfer-Encoding: chunked

[ { "id": 1, "name": "Scott Hunter" }, { "id": 2, "name": "Scott Hanselman" }, { "id": 3, "name": "Scott Guthrie" } ]

https://localhost:5001/people> ```

  1. Lấy một bản ghi cụ thể bằng cách truyền tham số vào lệnh get:

``console https://localhost:5001/people> get 2 ``

Kiểm thử yêu cầu HTTP POST

Cú pháp (Synopsis)

console
post <PARAMETER> [-c|--content] [-f|--file] [-h|--header] [--no-body] [-F|--no-formatting] [--response] [--response:body] [--response:headers] [-s|--streaming]

Ví dụ (Example)

Để thực hiện yêu cầu HTTP POST:

  1. Chạy lệnh post trên endpoint hỗ trợ nó:

``console https://localhost:5001/people> post -h Content-Type=application/json ``

Trong lệnh trên, header yêu cầu HTTP Content-Type được đặt để chỉ ra kiểu phương tiện body yêu cầu là JSON. Trình soạn thảo văn bản mặc định mở một file .tmp với template JSON đại diện cho body yêu cầu HTTP.

  1. Sửa đổi template JSON để đáp ứng yêu cầu xác thực model.
  2. Lưu file .tmp và đóng trình soạn thảo văn bản. Kết quả sau xuất hiện trong command shell:

```console HTTP/1.1 201 Created Content-Type: application/json; charset=utf-8 Date: Thu, 27 Jun 2019 21:24:18 GMT Location: https://localhost:5001/people/4 Server: Kestrel Transfer-Encoding: chunked

{ "id": 4, "name": "Scott Addie" }

https://localhost:5001/people> ```

Kiểm thử yêu cầu HTTP PUT

Cú pháp (Synopsis)

console
put <PARAMETER> [-c|--content] [-f|--file] [-h|--header] [--no-body] [-F|--no-formatting] [--response] [--response:body] [--response:headers] [-s|--streaming]

Kiểm thử yêu cầu HTTP DELETE

Cú pháp (Synopsis)

console
delete <PARAMETER> [-F|--no-formatting] [-h|--header] [--response] [--response:body] [--response:headers] [-s|--streaming]

Kiểm thử yêu cầu HTTP PATCH

Cú pháp (Synopsis)

console
patch <PARAMETER> [-c|--content] [-f|--file] [-h|--header] [--no-body] [-F|--no-formatting] [--response] [--response:body] [--response:headers] [-s|--streaming]

Kiểm thử yêu cầu HTTP HEAD

Cú pháp (Synopsis)

console
head <PARAMETER> [-F|--no-formatting] [-h|--header] [--response] [--response:body] [--response:headers] [-s|--streaming]

Kiểm thử yêu cầu HTTP OPTIONS

Cú pháp (Synopsis)

console
options <PARAMETER> [-F|--no-formatting] [-h|--header] [--response] [--response:body] [--response:headers] [-s|--streaming]

Đặt header yêu cầu HTTP

Để đặt header yêu cầu HTTP, hãy sử dụng một trong các phương pháp sau:

``console https://localhost:5001/people> post -h Content-Type=application/json ``

``console https://localhost:5001/people> set header Content-Type application/json ``

Khi đặt header trước khi gửi yêu cầu, header vẫn được đặt trong suốt phiên command shell. Để xóa header, hãy cung cấp giá trị rỗng:

``console https://localhost:5001/people> set header Content-Type ``

Kiểm thử các endpoint bảo mật

HttpRepl hỗ trợ kiểm thử các endpoint bảo mật theo các cách sau:

Thông tin đăng nhập mặc định (Default credentials)

Để truyền thông tin đăng nhập mặc định của người dùng đang đăng nhập:

  1. Đặt tùy chọn httpClient.useDefaultCredentials thành true:

``console pref set httpClient.useDefaultCredentials true ``

  1. Thoát và khởi động lại công cụ trước khi gửi yêu cầu khác đến Web API.

Header yêu cầu HTTP

Ví dụ về các sơ đồ xác thực và ủy quyền được hỗ trợ bao gồm:

Ví dụ, bạn có thể gửi bearer token đến một endpoint bằng lệnh sau:

console
set header Authorization "bearer <TOKEN VALUE>"

Bật/tắt hiển thị yêu cầu HTTP

Theo mặc định, việc hiển thị yêu cầu HTTP đang được gửi bị ẩn. Có thể thay đổi cài đặt tương ứng trong phiên command shell hiện tại.

Bật hiển thị yêu cầu

Xem yêu cầu HTTP đang được gửi bằng cách chạy lệnh echo on. Ví dụ:

console
https://localhost:5001/people> echo on
Request echoing is on

Tắt hiển thị yêu cầu

Ẩn việc hiển thị yêu cầu HTTP đang được gửi bằng cách chạy lệnh echo off. Ví dụ:

console
https://localhost:5001/people> echo off
Request echoing is off

Chạy script

Nếu bạn thường xuyên thực thi cùng một tập hợp các lệnh HttpRepl, hãy cân nhắc lưu trữ chúng trong một file văn bản. Các lệnh trong file có cùng dạng với các lệnh được thực thi thủ công trên dòng lệnh. Các lệnh có thể được thực thi theo dạng hàng loạt bằng lệnh run. Ví dụ:

  1. Tạo một file văn bản chứa một tập hợp các lệnh được phân tách bằng dòng mới. Ví dụ, file people-script.txt chứa các lệnh sau:

``text set base https://localhost:5001 ls cd People ls get 1 ``

  1. Thực thi lệnh run, truyền vào đường dẫn của file văn bản. Ví dụ:

``console https://localhost:5001/> run C:\http-repl-scripts\people-script.txt ``

Xóa đầu ra

Để xóa tất cả đầu ra được ghi vào command shell bởi công cụ HttpRepl, hãy chạy lệnh clear hoặc cls.