物件HttpClient

HttpClient 是針對HTTP 用戶端功能設計的類別庫，提供了基本的HTTP/HTTPS 請求、代理存取、cookie 管理等功能

使用HttpClient 可以輕鬆地存取和操作web 頁面，這裡舉一個簡單的例子——在一個web 頁面上列印其原始程式碼：

1
2
3
4
5
const http = require('http');

const res = http.get('http://www.example.com/');

console.log(res.body.readAll().toString());

在該例子中，透過require 引入http模組，然後使用http.get發起一個get 請求，其中url參數指定了請求的網址。因為http.get方法回傳的是一個HttpResponse對象，所以可以透過其body 屬性來存取請求返回的主體內容並透過toString 方法將其轉換為字串。

當請求的url是https 類型而不是http類型時，程式碼只需要將http改為https 即可：

1
2
3
4
5
const http = require('http');

const res = http.get('https://www.example.com/');

console.log(res.body.readAll().toString());

除此之外，還有透過HttpClient 直接發起POST 請求、設定User-Agent 的範例：

1
2
3
4
5
6
7
8
9
10
11
const http = require('http');

const httpClient = new http.Client();
httpClient.userAgent = 'Mozilla/5.0 (Windows NT 10.0; Win64; x64) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/58.0.3029.110 Safari/537.36';
const res = httpClient.post('http://www.example.com/post', {
    json: {
        name: 'fibjs',
        version: '0.31.0'
    }
});
console.log(res.body.readAll().toString());

在該範例中，首先建立了一個HttpClient 物件httpClient，並設定其userAgent 為瀏覽器的User-Agent。然後透過它的post 方法來發起一個post 請求，其中參數name 和version 來指定請求的主體內容。最後將傳回值的主體內容輸出。

繼承關係

建構函數

HttpClient

HttpClient 建構函數，建立一個新的HttpClient物件

1
new HttpClient();

成員屬性

cookies

NArray, 返回http客戶端的HttpCookie物件列表

1readonly NArray HttpClient.cookies;

timeout

Integer, 查詢和設定超時時間單位毫秒

1Integer HttpClient.timeout;

enableCookie

Boolean, cookie 功能開關，預設開啟

1
Boolean HttpClient.enableCookie;

autoRedirect

Boolean, 自動redirect 功能開關，預設開啟

1
Boolean HttpClient.autoRedirect;

enableEncoding

Boolean, 自動解壓縮功能開關，預設開啟

1
Boolean HttpClient.enableEncoding;

maxHeadersCount

Integer, 查詢並設定最大請求頭個數，缺省為128

1Integer HttpClient.maxHeadersCount;

maxHeaderSize

Integer, 查詢並設定最大請求頭長度，預設為8192

1Integer HttpClient.maxHeaderSize;

maxBodySize

Integer, 查詢並設定body 最大尺寸，以MB 為單位，預設為-1，不限制尺寸

1Integer HttpClient.maxBodySize;

userAgent

String, 查詢與設定http請求中的瀏覽器標識

1
String HttpClient.userAgent;

poolSize

Integer, 查詢與設定keep-alive 最大快取連線數，預設值128

1Integer HttpClient.poolSize;

poolTimeout

Integer, 查詢與設定keep-alive 快取連線逾時時間，預設值10000 ms

1Integer HttpClient.poolTimeout;

http_proxy

String, 查詢與設定http請求代理，支持http/https/socks5 代理

1
String HttpClient.http_proxy;

https_proxy

String, 查詢與設定https 請求代理，支持http/https/socks5 代理，不設置，或設定為空，則重複使用http_proxy

1
String HttpClient.https_proxy;

sslVerification

Integer, 查詢與設定連接https 時的憑證驗證模式, 參考ssl模組的VERIFY_* 常數, 預設值為ssl.verification

1Integer HttpClient.sslVerification;

成員函數

setClientCert

設定缺省客戶端證書

1
2
HttpClient.setClientCert(X509Cert crt,
    PKey key);

呼叫參數:

crt:X509Cert, 證書，用於發送給伺服器驗證客戶端
key:PKey, 私鑰，用於與客戶端會話

request

傳送http請求到指定的流對象，並返回結果

1
2
HttpResponse HttpClient.request(Stream conn,
    HttpRequest req) async;

呼叫參數:

conn:Stream, 指定處理請求的流對象
req:HttpRequest, 要發送的HttpRequest物件

回傳結果:

HttpResponse, 回傳伺服器回應

傳送http請求到指定的流對象，並返回結果

1
2
3
HttpResponse HttpClient.request(Stream conn,
    HttpRequest req,
    SeekableStream response_body) async;

呼叫參數:

conn:Stream, 指定處理請求的流對象
req:HttpRequest, 要發送的HttpRequest物件
response_body:SeekableStream, 指定response.body 的流

回傳結果:

HttpResponse, 回傳伺服器回應

請求指定的url，並回傳結果

1
2
3
HttpResponse HttpClient.request(String method,
    String url,
    Object opts = {}) async;

呼叫參數:

method: String, 指定http請求方法：GET, POST 等
url: String, 指定url，必須是包含主機的完整url
opts: Object, 指定附加訊息

回傳結果:

HttpResponse, 回傳伺服器回應

opts 包含請求的附加選項，支援的內容如下：

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16{
    "method": "GET", // specify the http request method: GET, POST, etc, default: GET.
    "protocol": "http",
    "slashes": true,
    "username": "",
    "password": "",
    "hostname": "",
    "port": "",
    "pathname": "",
    "query": {},
    "body": SeekableStream | Buffer | String | {},
    "json": {},
    "pack": {},
    "headers": {},
    "response_body": SeekableStream // specify the response.body stream
}

其中body，json，pack 不得同時出現。缺省為{}，不包含任何附加資訊

用GET 方法請求指定的url，並回傳結果，等同於request("GET", ...)

1
2
HttpResponse HttpClient.request(String url,
    Object opts = {}) async;

呼叫參數:

url: String, 指定url，必須是包含主機的完整url
opts: Object, 指定附加訊息

回傳結果:

HttpResponse, 回傳伺服器回應

opts 包含請求的附加選項，支援的內容如下：

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15{
    "method": "GET", // specify the http request method: GET, POST, etc, default: GET.
    "protocol": "http",
    "slashes": true,
    "username": "",
    "password": "",
    "hostname": "",
    "port": "",
    "pathname": "",
    "query": {},
    "body": SeekableStream | Buffer | String | {},
    "json": {},
    "pack": {},
    "headers": {}
}

其中body，json，pack 不得同時出現。缺省為{}，不包含任何附加資訊

請求opts 指定的url，並回傳結果

1
HttpResponse HttpClient.request(Object opts) async;

呼叫參數:

opts: Object, 指定附加訊息

回傳結果:

HttpResponse, 回傳伺服器回應

opts 包含請求的附加選項，支援的內容如下：

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15{
    "method": "GET", // specify the http request method: GET, POST, etc, default: GET.
    "protocol": "http",
    "slashes": true,
    "username": "",
    "password": "",
    "hostname": "",
    "port": "",
    "pathname": "",
    "query": {},
    "body": SeekableStream | Buffer | String | {},
    "json": {},
    "pack": {},
    "headers": {}
}

其中body，json，pack 不得同時出現。缺省為{}，不包含任何附加資訊

get

用GET 方法請求指定的url，並回傳結果，等同於request("GET", ...)

1
2
HttpResponse HttpClient.get(String url,
    Object opts = {}) async;

呼叫參數:

url: String, 指定url，必須是包含主機的完整url
opts: Object, 指定附加訊息

回傳結果:

HttpResponse, 回傳伺服器回應

opts 包含請求的附加選項，支援的內容如下：

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15{
    "method": "GET", // specify the http request method: GET, POST, etc, default: GET.
    "protocol": "http",
    "slashes": true,
    "username": "",
    "password": "",
    "hostname": "",
    "port": "",
    "pathname": "",
    "query": {},
    "body": SeekableStream | Buffer | String | {},
    "json": {},
    "pack": {},
    "headers": {}
}

其中body，json，pack 不得同時出現。缺省為{}，不包含任何附加資訊

post

用POST 方法請求指定的url，並回傳結果，等同於request("POST", ...)

1
2
HttpResponse HttpClient.post(String url,
    Object opts = {}) async;

呼叫參數:

url: String, 指定url，必須是包含主機的完整url
opts: Object, 指定附加訊息

回傳結果:

HttpResponse, 回傳伺服器回應

opts 包含請求的附加選項，支援的內容如下：

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15{
    "method": "GET", // specify the http request method: GET, POST, etc, default: GET.
    "protocol": "http",
    "slashes": true,
    "username": "",
    "password": "",
    "hostname": "",
    "port": "",
    "pathname": "",
    "query": {},
    "body": SeekableStream | Buffer | String | {},
    "json": {},
    "pack": {},
    "headers": {}
}

其中body，json，pack 不得同時出現。缺省為{}，不包含任何附加資訊

del

用DELETE 方法請求指定的url，並回傳結果，等同於request("DELETE", ...)

1
2
HttpResponse HttpClient.del(String url,
    Object opts = {}) async;

呼叫參數:

url: String, 指定url，必須是包含主機的完整url
opts: Object, 指定附加訊息

回傳結果:

HttpResponse, 回傳伺服器回應

opts 包含請求的附加選項，支援的內容如下：

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15{
    "method": "GET", // specify the http request method: GET, POST, etc, default: GET.
    "protocol": "http",
    "slashes": true,
    "username": "",
    "password": "",
    "hostname": "",
    "port": "",
    "pathname": "",
    "query": {},
    "body": SeekableStream | Buffer | String | {},
    "json": {},
    "pack": {},
    "headers": {}
}

其中body，json，pack 不得同時出現。缺省為{}，不包含任何附加資訊

put

用PUT 方法請求指定的url，並回傳結果，等同於request("PUT", ...)

1
2
HttpResponse HttpClient.put(String url,
    Object opts = {}) async;

呼叫參數:

url: String, 指定url，必須是包含主機的完整url
opts: Object, 指定附加訊息

回傳結果:

HttpResponse, 回傳伺服器回應

opts 包含請求的附加選項，支援的內容如下：

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15{
    "method": "GET", // specify the http request method: GET, POST, etc, default: GET.
    "protocol": "http",
    "slashes": true,
    "username": "",
    "password": "",
    "hostname": "",
    "port": "",
    "pathname": "",
    "query": {},
    "body": SeekableStream | Buffer | String | {},
    "json": {},
    "pack": {},
    "headers": {}
}

其中body，json，pack 不得同時出現。缺省為{}，不包含任何附加資訊

patch

用PATCH 方法請求指定的url，並回傳結果，等同於request("PATCH", ...)

1
2
HttpResponse HttpClient.patch(String url,
    Object opts = {}) async;

呼叫參數:

url: String, 指定url，必須是包含主機的完整url
opts: Object, 指定附加訊息

回傳結果:

HttpResponse, 回傳伺服器回應

opts 包含請求的附加選項，支援的內容如下：

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15{
    "method": "GET", // specify the http request method: GET, POST, etc, default: GET.
    "protocol": "http",
    "slashes": true,
    "username": "",
    "password": "",
    "hostname": "",
    "port": "",
    "pathname": "",
    "query": {},
    "body": SeekableStream | Buffer | String | {},
    "json": {},
    "pack": {},
    "headers": {}
}

其中body，json，pack 不得同時出現。缺省為{}，不包含任何附加資訊

head

用HEAD 方法請求指定的url，並回傳結果，等同於request("PATCH", ...)

1
2
HttpResponse HttpClient.head(String url,
    Object opts = {}) async;

呼叫參數:

url: String, 指定url，必須是包含主機的完整url
opts: Object, 指定附加訊息

回傳結果:

HttpResponse, 回傳伺服器回應

opts 包含請求的附加選項，支援的內容如下：

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15{
    "method": "GET", // specify the http request method: GET, POST, etc, default: GET.
    "protocol": "http",
    "slashes": true,
    "username": "",
    "password": "",
    "hostname": "",
    "port": "",
    "pathname": "",
    "query": {},
    "body": SeekableStream | Buffer | String | {},
    "json": {},
    "pack": {},
    "headers": {}
}

其中body，json，pack 不得同時出現。缺省為{}，不包含任何附加資訊

toString

傳回物件的字串表示，一般回傳"[Native Object]"，物件可以根據自己的特性重新實現

1
String HttpClient.toString();

回傳結果:

String, 傳回物件的字串表示

toJSON

傳回物件的JSON 格式表示，一般傳回物件定義的可讀屬性集合

1
Value HttpClient.toJSON(String key = "");

呼叫參數:

key: String, 未使用

回傳結果:

Value, 傳回包含可JSON 序列化的值

開發指南

基礎模組

內建對象

社群模組

物件HttpClient

繼承關係

建構函數

HttpClient

成員屬性

cookies

timeout

enableCookie

autoRedirect

enableEncoding

maxHeadersCount

maxHeaderSize

maxBodySize

userAgent

poolSize

poolTimeout

http_proxy

https_proxy

sslVerification

成員函數

setClientCert

request

get

post

del

put

patch

head

toString

toJSON