app.http - HTTP 请求 API

发送 HTTP/HTTPS 请求。

注意: 在 app.thread.create 创建的协程内调用时，会自动异步执行，对调用者透明。

方法

app.http.get(url, headers?)

发送 GET 请求。

参数:

• url (string) - 请求 URL
• headers (table, 可选) - 请求头键值对

返回值: table, error

• status (number) - HTTP 状态码
• body (string) - 响应体
• headers (table) - 响应头键值对

local response = app.http.get("https://api.example.com/data")
if response and response.status == 200 then
    local data = app.json.parse(response.body)
end

-- 带请求头
local response = app.http.get("https://api.example.com/data", {
    ["Authorization"] = "Bearer token123",
    ["Accept"] = "application/json"
})

app.http.post(url, data, headers?)

发送 POST 请求。

参数:

• url (string) - 请求 URL
• data (string|table) - 请求体（字符串或表）
  • 字符串：直接作为请求体
  • 表：自动序列化为 JSON，并设置 Content-Type
• headers (table, 可选) - 请求头键值对

返回值: table, error - 同 GET

-- 发送 JSON
local response = app.http.post("https://api.example.com/users", {
    name = "张三",
    email = "zhangsan@example.com"
})

-- 发送原始字符串
local response = app.http.post("https://example.com/data", "raw body content", {
    ["Content-Type"] = "text/plain"
})

app.http.request(opts)

通用 HTTP 请求方法，支持自定义方法、超时、重定向控制等。

参数:

• opts (table):
  • url (string, 必需) - 请求 URL
  • method (string, 可选) - HTTP 方法（默认 "GET"）
  • headers (table, 可选) - 请求头键值对
  • body (string|table, 可选) - 请求体（表自动序列化为 JSON）
  • timeout (number, 可选) - 超时秒数
  • followRedirects (boolean, 可选) - 是否跟随重定向（默认 true）

返回值: table, error - 同 GET

-- PUT 请求
local resp, err = app.http.request({
    url = "https://api.example.com/users/1",
    method = "PUT",
    headers = {["Authorization"] = "Bearer token123"},
    body = {name = "新名称"},
    timeout = 30
})

-- DELETE 请求
local resp, err = app.http.request({
    url = "https://api.example.com/users/1",
    method = "DELETE"
})

-- 不跟随重定向
local resp, err = app.http.request({
    url = "https://example.com/redirect",
    followRedirects = false
})
if resp then
    app.log.info("Status: " .. resp.status)  -- 可能是 301/302
end

app.http.download(url, savePath, headers?)

下载文件到指定路径。

参数:

• url (string) - 下载 URL
• savePath (string) - 保存路径
• headers (table, 可选) - 请求头键值对

返回值: boolean, error

local ok, err = app.http.download(
    "https://example.com/file.zip",
    "/path/to/save/file.zip"
)

if ok then
    app.notification.show("下载完成", "文件已保存")
else
    app.log.error("下载失败: " .. (err or ""))
end

-- 带自定义请求头
local ok, err = app.http.download(
    "https://example.com/file.zip",
    "/path/to/save/file.zip",
    {["Authorization"] = "Bearer token123"}
)

app.http.upload(url, opts)

上传文件（multipart/form-data）。

注意: 在 app.thread.create 创建的协程内调用时，会自动异步执行。

参数:

• url (string) - 上传 URL
• opts (table):
  • file (string) - 文件路径（必填）
  • fieldName (string, 可选) - 表单字段名，默认 "file"
  • fileName (string, 可选) - 文件名，默认从路径提取
  • mimeType (string, 可选) - MIME 类型，默认自动检测
  • fields (table, 可选) - 附加表单字段
  • headers (table, 可选) - 请求头
  • method (string, 可选) - HTTP 方法，默认 "POST"
  • timeout (number, 可选) - 超时秒数，默认 60

返回值: table, error

• status (number) - HTTP 状态码
• body (string) - 响应体
• headers (table) - 响应头

-- 简单上传
local resp, err = app.http.upload("https://api.example.com/upload", {
    file = "/path/to/photo.jpg"
})

-- 带附加字段
local resp, err = app.http.upload("https://api.example.com/upload", {
    file = "/path/to/document.pdf",
    fieldName = "attachment",
    fields = {
        title = "我的文档",
        category = "report"
    },
    headers = {
        ["Authorization"] = "Bearer token123"
    }
})

if resp and resp.status == 200 then
    app.notification.show("上传成功", "文件已上传")
end

示例

调用 REST API

function MyPlugin:fetchGitHubRepo(owner, repo)
    local url = string.format("https://api.github.com/repos/%s/%s", owner, repo)

    local response = app.http.get(url, {
        ["Accept"] = "application/vnd.github.v3+json",
        ["User-Agent"] = "iRightMenu-Plugin"
    })

    if not response or response.status ~= 200 then
        app.log.error("请求失败: " .. (response and response.status or "network error"))
        return nil
    end

    return app.json.parse(response.body)
end

下载文件

function MyPlugin:handleDownload(context)
    local url = "https://example.com/file.zip"
    local filename = app.path.basename(url)
    local savePath = app.path.join(context.currentDirectory, filename)

    if app.http.download(url, savePath) then
        app.notification.show("下载完成", filename)
        app.finder.reveal(savePath)
    else
        app.notification.show("下载失败", "无法下载文件")
    end
end

在协程中使用（异步）

function MyPlugin:handleFetchData(context)
    app.thread.create(function()
        -- 在协程中，HTTP 请求自动异步执行
        local response = app.http.get("https://api.example.com/data")

        if response and response.status == 200 then
            local data = app.json.parse(response.body)
            app.notification.show("成功", "获取了 " .. #data .. " 条数据")
        end
    end)
end