跳到主要内容
版本：当前开发版

HTTP API

HTTP 客户端辅助能力位于 ptool.http 和 p.http 下。

ptool.http.request​

v0.1.0 - 引入。

ptool.http.request(options) 发送一个 HTTP 请求，并返回 Response 对象。

options 字段：

  • url（string，必填）：请求 URL。
  • method（string，可选）：HTTP 方法。默认值为 "GET"。
  • headers（table，可选）：请求头，键和值都必须是字符串。
  • query（table，可选）：追加到请求 URL 的查询参数。键必须是字符串，值可以 是字符串、数字或布尔值。
  • body（string，可选）：请求体。
  • json（Lua 值，可选）：会被编码为 JSON 并作为请求体发送。当未显式设置 content-type 时，默认使用 application/json。
  • form（table，可选）：会被编码为 application/x-www-form-urlencoded 并作为请求体发送。键必须是字符串，值 可以是字符串、数字或布尔值。
  • timeout_ms（integer，可选）：超时时间，单位毫秒。默认值为 30000。
  • connect_timeout_ms（integer，可选）：连接超时时间，单位毫秒。
  • follow_redirects（boolean，可选）：是否跟随重定向。
  • max_redirects（integer，可选）：允许跟随的最大重定向次数。
  • user_agent（string，可选）：设置 user-agent 请求头。
  • basic_auth（table，可选）：HTTP Basic 认证信息，包含字符串字段 username 和 password。
  • bearer_token（string，可选）：用于 authorization 请求头的 Bearer Token。
  • fail_on_http_error（boolean，可选）：为 true 时，4xx 和 5xx HTTP 响应会直接抛错。默认值为 false。

说明：

  • body、json 和 form 互斥。
  • basic_auth 和 bearer_token 互斥。

示例：

local resp = ptool.http.request({
  url = "https://httpbin.org/post",
  method = "POST",
  query = {
    page = 1,
    draft = false,
  },
  json = {
    name = "alice",
    tags = {"admin", "beta"},
  },
  user_agent = "ptool-script/1.0",
  fail_on_http_error = true,
})

print(resp.status, resp.ok)
print(resp:header("content-type"))
local data = resp:json()
print(data.json.name)

Response​

v0.1.0 - 引入。

Response 表示 ptool.http.request(...) 返回的 HTTP 响应。

字段：

  • status（integer）：HTTP 状态码。
  • ok（boolean）：状态码是否位于 2xx 范围内。
  • url（string）：重定向后的最终 URL。
  • headers（table）：响应头的扁平化便捷视图（table<string, string>）。 重复响应头会使用 , 合并。

方法：

  • resp:text()：读取并以文本形式返回响应体。
  • resp:json()：读取响应体，按 JSON 解析后返回 Lua 值。
  • resp:bytes()：读取并返回原始字节（作为 Lua 字符串）。
  • resp:header(name)：返回第一个匹配的响应头值，若不存在则返回 nil。
  • resp:header_values(name)：返回所有匹配的响应头值数组。
  • resp:raise_for_status()：对 4xx 和 5xx HTTP 响应抛出错误。

text​

规范 API 名称：ptool.http.Response:text。

resp:text() 读取并以文本形式返回响应体。

  • 返回：string。

json​

规范 API 名称：ptool.http.Response:json。

resp:json() 读取响应体，按 JSON 解析后返回 Lua 值。

bytes​

规范 API 名称：ptool.http.Response:bytes。

resp:bytes() 读取并以原始字节形式返回响应体。

  • 返回：string。

规范 API 名称：ptool.http.Response:header。

resp:header(name) 返回第一个匹配 name 的响应头值。

  • name（string，必填）：要查找的响应头名称。
  • 返回：string | nil。

header_values​

规范 API 名称：ptool.http.Response:header_values。

resp:header_values(name) 返回所有匹配 name 的响应头值。

  • name（string，必填）：要查找的响应头名称。
  • 返回：string[]。

raise_for_status​

规范 API 名称：ptool.http.Response:raise_for_status。

resp:raise_for_status() 会在响应状态码处于 4xx 或 5xx 范围时抛出错误。

说明：

  • 默认情况下，非 2xx HTTP 状态不会抛错。调用方可以检查 resp.ok、设置 fail_on_http_error = true，或调用 resp:raise_for_status()。
  • 响应体会在首次读取后缓存，因此 text、json 和 bytes 可以重复调用。