http HTTP 客户端

http 是 JSXHook 脚本里的 HTTP 客户端对象。
这页只讲一件事：你怎么主动去请求别人。

如果你想在脚本里启动本地服务、注册路由、处理 req.query / req.body / req.params，请去看 httpServer HTTP 服务。
如果你想把能力包装成 MCP 的 Tool / Resource / Prompt，请去看 mcpServer MCP 服务。

这一页重点解决这几个最容易混的点：

1. http.post() 和 http.postJson() 不是一回事。
2. params 只负责拼 URL，不会自动变成 JSON body。
3. http.setTimeout() 支持数字、对象、null 三种写法。
4. response 顶层字段叫 statusCode / statusMessage，不是 code / message。

先记住这 6 条

1. http.get("example.com") 这种没写协议的地址，会自动补成 http://example.com。
2. http.post() 默认按表单发，http.postJson() 默认按 JSON 发。
3. params 只会拼到 URL 上，值最终都会被转成字符串。
4. http.setTimeout() 支持传数字、对象、null 三种写法。
5. response.header(name) 大小写不敏感。
6. response.body.json() 遇到非法 JSON 会直接抛错，不会默默返回空对象。

先分清 http / httpServer / mcpServer

• http：我主动去请求别人
• httpServer：我开普通 HTTP 接口给别人请求
• mcpServer：我把能力注册成 MCP 客户端能识别的能力给别人请求

如果你已经明确是在写客户端请求，就留在这页继续看。
如果你下一步要开本地服务，请直接跳去 httpServer HTTP 服务。

http

http 里有哪些方法

• http.get(url, options?)
• http.post(url, data, options?)
• http.postJson(url, data, options?)
• http.setTimeout(config)
• http.config()

所有请求共用的 options 字段

字段	类型	可填值	默认值	说明
headers	object	普通对象 / map	空对象	header 名和值最终都会转成字符串
params	object	普通对象 / map	空对象	只对 GET 真正有意义，会拼进 URL
timeout	number	>= 0	当前全局值	connectTimeout + readTimeout 的快捷写法
connectTimeout	number	>= 0	当前全局值	连接超时
readTimeout	number	>= 0	当前全局值	读取超时
followRedirects	boolean	true / false	当前全局值	是否自动跟随重定向

说明：

• 负数会被修正成 0。
• headers / params 如果不是对象，会被当成空对象。
• params 的 value 最终都会 .toString() 后再 URL 编码。

http.get(url, options?)

参数

参数	类型	可填值	默认值	说明
url	string	任意 HTTP / HTTPS 地址	必填	为空会直接抛错
options	object	见上表	空对象	可选

URL 规则

你传的值	实际效果
"https://httpbin.org/get"	原样使用
"http://example.com"	原样使用
"example.com"	自动补成 http://example.com
""	报错

params 如何拼接

如果你这样写：

http.get("https://httpbin.org/get", {
  params: {
    q: "jsxhook",
    page: 1,
    enabled: true
  }
});

最终会拼成类似：

https://httpbin.org/get?q=jsxhook&page=1&enabled=true

例子

const res = http.get("https://httpbin.org/get", {
  params: {
    q: "jsxhook",
    page: 1
  },
  headers: {
    "User-Agent": "JSXHook"
  },
  timeout: 5000
});

log(res.statusCode);
log(res.body.string());

http.post(url, data, options?)

参数

参数	类型	可填值	默认值	说明
url	string	HTTP / HTTPS 地址	必填	为空会抛错
data	any	通常是对象或字符串	无	会被编码成请求体
options	object	见通用 options	空对象	可选

默认 Content-Type

如果你没有自己传 Content-Type，源码会自动补：

application/x-www-form-urlencoded; charset=UTF-8

data 怎么编码

data 形态	实际发送内容
普通对象 / map	编码成 a=1&b=2 这种表单串
其他值	直接 toString() 后发送
null	空字符串

这意味着：

http.post("https://example.com/api", {
  username: "demo",
  password: "123456"
});

会按表单发；但下面这种：

http.post("https://example.com/api", "raw-body");

不会自动变成 JSON，它就只是原样发 "raw-body"。

例子

const res = http.post("https://httpbin.org/post", {
  username: "demo",
  password: "123456"
}, {
  headers: {
    "X-Trace-Id": "abc-001"
  }
});

log(res.statusCode);
log(res.body.string());

http.postJson(url, data, options?)

参数

参数	类型	可填值	默认值	说明
url	string	HTTP / HTTPS 地址	必填	为空会抛错
data	any	对象、数组、字符串、数字、布尔值等	无	会先做 JSON 序列化
options	object	见通用 options	空对象	可选

默认 Content-Type

如果你没有自己传 Content-Type，源码会自动补：

application/json; charset=UTF-8

data 怎么编码

• 会先把 JS 值归一化成普通 Kotlin / JSON 兼容值。
• 然后统一做 JSON.stringify 风格序列化。

例子

const res = http.postJson("https://httpbin.org/post", {
  module: "jsxhook",
  feature: "http",
  enabled: true
});

log(res.statusCode);
log(JSON.stringify(res.body.json(), null, 2));

http.setTimeout(config)

这个接口专门改 http 客户端的全局默认超时配置。

支持 3 种写法

1. 传单个数字

http.setTimeout(5000);

含义：

• connectTimeout = 5000
• readTimeout = 5000

2. 传对象

http.setTimeout({
  timeout: 5000,
  followRedirects: false
});

或者更细分：

http.setTimeout({
  connectTimeout: 3000,
  readTimeout: 10000,
  followRedirects: true
});

3. 传 null

http.setTimeout(null);

会恢复默认值：

字段	默认值
connectTimeout	10000
readTimeout	10000
followRedirects	true

对象模式支持字段

字段	类型	可填值	默认值	说明
timeout	number	>= 0	不改	一次性改连通和读取超时
connectTimeout	number	>= 0	不改	单独改连接超时
readTimeout	number	>= 0	不改	单独改读取超时
followRedirects	boolean	true / false	不改	是否自动跟随跳转

http.config()

这个接口只读当前全局配置，不接收参数。

返回格式

{
  connectTimeout: 10000,
  readTimeout: 10000,
  followRedirects: true
}

例子

http.setTimeout({
  connectTimeout: 3000,
  readTimeout: 8000,
  followRedirects: false
});

log(JSON.stringify(http.config(), null, 2));

response 响应对象

顶层字段

字段	类型	说明
url	string	实际请求 URL
statusCode	number	HTTP 状态码
statusMessage	string	HTTP 状态文本
headers	object	响应头对象
contentType	string	响应 Content-Type
charset	string	从 Content-Type 里解析出的字符集，取不到时是 UTF-8
body	object	响应体包装对象
header(name)	function	按名字取响应头，大小写不敏感

response.header(name)

大小写不敏感：

log(res.header("Content-Type"));
log(res.header("content-type"));

response.body 字段和方法

字段 / 方法	类型	说明
body.contentType	string	响应内容类型
body.charset	string	当前用来解码文本的字符集
body.length	number	原始字节长度
body.string()	function	按 charset 转成字符串
body.json()	function	按 JSON 解析
body.bytes()	function	返回原始字节数组

response.body.json() 的规则

响应内容	结果
空字符串	null
合法 JSON 对象	JS 对象
合法 JSON 数组	JS 数组
合法 JSON 基本类型	对应基本类型
非法 JSON	直接抛错

例子

const res = http.get("https://httpbin.org/json");

log(res.statusCode);
log(res.contentType);
log(res.body.length);
log(JSON.stringify(res.body.json(), null, 2));

实战例子

1. GET 请求拿 JSON

const res = http.get("https://httpbin.org/get", {
  params: { q: "jsxhook" }
});

if (res.statusCode === 200) {
  const data = res.body.json();
  log(JSON.stringify(data, null, 2));
}

2. POST 表单

const res = http.post("https://httpbin.org/post", {
  username: "demo",
  password: "123456"
});

log(res.body.string());

3. POST JSON

const res = http.postJson("https://httpbin.org/post", {
  action: "ping",
  packageName: lpparam.packageName
});

log(res.statusCode);
log(JSON.stringify(res.body.json(), null, 2));

常见错误与排查

1. http.get(url, options) requires a url

原因：

• url 是空字符串。

2. http.post(url, data, options) requires a url

原因：

• url 是空字符串。

3. http.postJson(url, data, options) requires a url

原因：

• url 是空字符串。

4. http.setTimeout(...) expects a number or config object

原因：

• 你传了字符串、数组之类的不支持类型。

实战建议

1. 发 JSON 用 postJson()，发表单用 post()，不要混着猜。
2. 看响应先看 statusCode，再看 body。
3. 只要要取某个响应头，就优先用 response.header(name)。
4. 不确定接口是不是 JSON 时，先 body.string() 再决定要不要 body.json()。
5. 如果你下一步要开本地 HTTP 服务，继续看 httpServer HTTP 服务。