jokymouse.http API

jokymouse.http 模块通过 require("jokymouse.http") 加载，提供受白名单保护的 HTTP 请求能力。

所有请求目标域名必须由管理员在后台”Lua HTTP 白名单”页面中预先配置，否则请求会被拒绝。

local http = require("jokymouse.http")

可用函数

函数	签名	说明
request	`http.request(url, opts?)`	发起任意 HTTP 请求，返回响应对象
get	`http.get(url, opts?)`	发起 GET 请求，等同于 method=“GET”
post	`http.post(url, opts?)`	发起 POST 请求，等同于 method=“POST”
post_json	`http.post_json(url, body_table, opts?)`	发起 POST 请求，自动编码 JSON body 并解码响应

request

local http = require("jokymouse.http")

local res = http.request("https://api.example.com/data", {
  method = "GET",
  headers = { ["Accept"] = "application/json" },
  timeout_ms = 8000
})

if res.ok then
  print(res.body)
else
  print("请求失败，状态码：" .. res.status)
end

opts

字段	类型	默认值	说明
method	`string`	`"GET"`	HTTP 方法，如 `"GET"` / `"POST"` / `"PUT"`
headers	`table`	`{}`	请求头键值对
body	`string`	`nil`	请求体，适用于 POST / PUT / PATCH
timeout_ms	`number`	`15000`	超时毫秒数，范围 100 – 120000

返回结构

{
  ok      = true,       -- HTTP 状态码 2xx 时为 true
  status  = 200,        -- HTTP 状态码（number）
  url     = "https://api.example.com/data",  -- 实际请求的 URL（含重定向后地址）
  body    = "...",      -- 响应体字符串
  headers = {           -- 响应头键值对（小写 key）
    ["content-type"] = "application/json"
  }
}

get

local http = require("jokymouse.http")

local res = http.get("https://api.example.com/status")
if res.ok then
  print(res.body)
end

http.get(url, opts?) 等价于 http.request(url, { method = "GET", ... })，opts 中无需再指定 method。

post

local http = require("jokymouse.http")

local res = http.post("https://api.example.com/submit", {
  headers = { ["Content-Type"] = "application/json" },
  body    = '{"key":"value"}'
})

if res.ok then
  print("提交成功")
end

http.post(url, opts?) 等价于 http.request(url, { method = "POST", ... })，opts 中无需再指定 method。

post_json

local http = require("jokymouse.http")

local res = http.post_json("https://api.example.com/order", { count = 1, item = "sword" })

if res.ok and res.json then
  print("订单 ID：" .. res.json.order_id)
else
  print("请求失败：" .. res.status)
end

http.post_json(url, body_table, opts?) 将 Lua table 自动序列化为 JSON 字符串作为请求体，并自动添加 Content-Type: application/json 请求头。

与 http.post 不同，响应对象会额外包含 json 字段：

当响应头 content-type 含 application/json 且响应体是合法 JSON 时，json 为已解码的 Lua table；
否则 json 为 nil，body 仍保留原始字符串。

参数

参数	类型	说明
url	`string`	请求目标 URL，需命中白名单
body_table	`table`	请求体数据，自动序列化为 JSON
opts	`table?`	可选配置，支持 `headers`、`timeout_ms`

opts.headers 中可覆盖 content-type，其余与 request 的 opts 一致（method 和 body 字段无效）。

返回结构

{
  ok      = true,
  status  = 200,
  url     = "https://api.example.com/order",
  body    = '{"order_id":42}',  -- 原始响应字符串
  headers = { ["content-type"] = "application/json" },
  json    = { order_id = 42 }   -- 自动解码的响应（非 JSON 响应时为 nil）
}

白名单规则

当前白名单配置

加载中…

只有 https:// 请求被允许；http:// 仅限 localhost、127.0.0.1、::1。
请求目标的主机名必须命中后台配置的白名单规则之一：
- 精确域名：api.example.com 只匹配 api.example.com。
- 通配子域：*.example.com 匹配 api.example.com、cdn.example.com，但不匹配 example.com 本身。
白名单为空时，所有外部请求均被拒绝。
白名单每 30 秒从服务端拉取一次并缓存；首次请求时立即拉取。

错误处理

请求失败时（包含网络错误、白名单拦截、超时）会向 Lua 抛出运行时错误，可用 pcall 捕获：

local http = require("jokymouse.http")

local ok, result = pcall(function()
  return http.get("https://api.example.com/data")
end)

if not ok then
  -- result 是错误信息字符串
  print("请求异常：" .. tostring(result))
elseif result.ok then
  print(result.body)
else
  print("HTTP 错误：" .. result.status)
end