API http

http

可选的原生 HTTP 客户端模块，提供同步与回调 API。

脚本 API 参考 · 宿主 BuiltInModules

启用与导入

该模块默认禁用。宿主必须在构造引擎前添加 BuiltInModules.HttpClient：

using AuroraScript.Runtime.Package;

var options = EngineOptions.Default.WithBuiltIns(builtIns =>
    builtIns.Add(BuiltInModules.HttpClient));

import http from "http";

仅接受绝对的 http:// 与 https:// URL。http 是导入别名，不是全局对象。

快速参考

同步方法会阻塞当前脚本调用，直到响应体完全读取完毕。

Member	Returns
request(method, url, options?)	HttpResponse
get(url, options?)	HttpResponse
post(url, body?, options?)	HttpResponse
put(url, body?, options?)	HttpResponse
patch(url, body?, options?)	HttpResponse
delete(url, options?)	HttpResponse
head(url, options?)	HttpResponse

每个方法也有异步回调形式。调度完成后返回 true，且 callback 必须为最后一个参数。

Member	回调调用
requestAsync(method, url, options?, callback)	callback(error, response)
getAsync(url, options?, callback)	callback(error, response)
postAsync(url, body?, options?, callback)	callback(error, response)
putAsync(url, body?, options?, callback)	callback(error, response)
patchAsync(url, body?, options?, callback)	callback(error, response)
deleteAsync(url, options?, callback)	callback(error, response)
headAsync(url, options?, callback)	callback(error, response)

通用请求

http.request(method, url, options?)

http.request(
    method: string,
    url: string,
    options?: HttpRequestOptions
): HttpResponse

method 会被修剪并规范化为大写。方法文本必须被 .NET 的 HTTP 方法解析器接受。

http.requestAsync(method, url, options?, callback)

http.requestAsync(
    method: string,
    url: string,
    options?: HttpRequestOptions,
    callback: function
): boolean

调度请求并返回 true。

动词辅助方法

无位置 body 参数的辅助方法（高级调用方仍可通过 options.body 设置 body）：

http.get(url: string, options?: HttpRequestOptions): HttpResponse
http.delete(url: string, options?: HttpRequestOptions): HttpResponse
http.head(url: string, options?: HttpRequestOptions): HttpResponse

http.getAsync(url: string, options?: HttpRequestOptions, callback: function): boolean
http.deleteAsync(url: string, options?: HttpRequestOptions, callback: function): boolean
http.headAsync(url: string, options?: HttpRequestOptions, callback: function): boolean

支持 body 的动词辅助方法：

http.post(url: string, options?: HttpRequestOptions): HttpResponse
http.post(url: string, body?: string|UInt8Array, options?: HttpRequestOptions): HttpResponse

http.put(url: string, options?: HttpRequestOptions): HttpResponse
http.put(url: string, body?: string|UInt8Array, options?: HttpRequestOptions): HttpResponse

http.patch(url: string, options?: HttpRequestOptions): HttpResponse
http.patch(url: string, body?: string|UInt8Array, options?: HttpRequestOptions): HttpResponse

其回调形式接受以下调用形状：

http.postAsync(url, callback)
http.postAsync(url, options, callback)
http.postAsync(url, body, callback)
http.postAsync(url, body, options, callback)

putAsync 与 patchAsync 遵循相同形状。对于两参数同步调用或三参数回调调用，body 位置的普通对象会被视为 options。位置 body 优先于 options.body。

HttpRequestOptions

可选请求对象支持：

Property	Type	说明
headers	object	将标头名映射到 string 或非空 string[]。
body	string|UInt8Array	请求体，主要用于 request；会被位置动词 body 覆盖。
contentType	string	非空 Content-Type 值。
timeout	number	正整数毫秒，不超过 CLR Int32 上限。

不能手动提供 Content-Length；由客户端计算。字符串 body 默认为 text/plain; charset=utf-8；字节 body 默认为 application/octet-stream。显式 contentType 或 Content-Type 标头会覆盖该默认值。

var options = {
    headers: {
        "accept": "application/json",
        "x-tag": ["one", "two"]
    },
    contentType: "application/json; charset=utf-8",
    timeout: 5000
};

var response = http.post(
    "https://example.test/items",
    JSON.stringify({ name: "Aurora" }),
    options);

异步发送前会复制请求选项、标头与字节 body，因此后续脚本变更不会影响已调度的请求。

HttpResponse

响应为冻结对象：

Property	Type	说明
status	number	数值 HTTP 状态码。
statusText	string	HTTP 原因短语，或空字符串。
ok	boolean	2xx 状态时为 true。
url	string	重定向后的最终 URL。
headers	object	冻结的响应标头，键为小写，值为合并后的字符串。
body	string	解码后的响应文本。
text	string	与 body 相同解码文本的别名。
bytes	UInt8Array	完整原始响应体。

客户端在支持时使用声明的响应字符集，检测字节序标记，否则按 UTF-8 解码。在返回或调用回调前会缓冲完整响应。

import http from "http";

export func load(url) {
    var response = http.get(url, { timeout: 5000 });
    if (!response.ok) {
        return { status: response.status, text: response.text };
    }
    return JSON.parse(response.text);
}

回调约定

回调方法采用 error-first 两参数约定：

• 完成的 HTTP 交换：callback(null, response)；
• 传输、超时、请求构造或响应读取失败：callback(error, null)。

404 或 500 等 HTTP 状态码属于完成的交换，不是回调错误。请检查 response.ok 或 response.status。

参数与选项验证在调度前进行。无效 URL、选项类型、超时值或缺失的最终回调会立即抛出 AuroraRuntimeException，而非调用回调。

import http from "http";

export func loadLater(url) {
    return http.getAsync(url, { timeout: 5000 }, (error, response) => {
        if (error != null) {
            console.error(error.message);
            return;
        }

        console.log(response.status, response.text);
    });
}

回调通过独立的脚本上下文运行，可能在原始导出函数返回后执行。不会复用已释放的调用上下文。回调异常会写入宿主配置的错误流，而不会转换为第二次回调。

连接与安全行为

• 共享的 .NET HttpClient 复用连接。
• 重定向与支持的内容解压自动进行。
• Cookie 已禁用，请求、引擎或域之间不会保留。
• 所有响应内容均在内存中缓冲；宿主应考虑响应大小与延迟限制。
• http 在宿主进程身份下具有网络权限。当脚本并非完全可信时，应强制执行 URL 允许列表、出口控制与进程级隔离。