Simple HTTP Skill

使用 Node.js 内置模块发起 HTTP 请求。支持所有标准方法、任意请求头、自动重试（指数退避），且从不抛出异常 —— 始终以可检查的响应对象进行解析。

必需输入

• url (string)：要请求的完整 URL。
• method (string，可选)：HTTP 方法。默认为 GET。
• headers (object，可选)：请求头。
• body (string | Buffer | object，可选)：请求体。对象会自动序列化为 JSON。
• maxRetries (number，可选)：临时失败时的重试次数。默认为 3。
• timeout (number，可选)：Socket 超时时间（毫秒）。默认为 30000。

步骤说明

1. 从 src/http-client.js 导入客户端：

const { HttpClient } = require("./src/http-client");

1. 创建客户端实例（可选：设置跨调用共享的默认请求头）：

const client = new HttpClient({
  defaultHeaders: { Authorization: "Bearer <token>" },
  maxRetries: 3,
});

1. 使用便捷方法或通用 request() 发起请求：

// GET
const resp = await client.get("https://api.example.com/items");

// POST 附带 JSON 请求体
const resp = await client.post("https://api.example.com/items", {
  body: { name: "widget" },
});

// PUT 附带自定义请求头
const resp = await client.put("https://api.example.com/items/1", {
  headers: { "X-Request-Id": "abc123" },
  body: { name: "updated" },
});

// DELETE
const resp = await client.delete("https://api.example.com/items/1");

// 通用形式 —— 支持任意方法
const resp = await client.request("PATCH", "https://api.example.com/items/1", {
  body: { qty: 5 },
});

1. 检查响应结果：

if (resp.ok) {
  console.log(resp.body);      // 解析后的 JSON 或原始字符串
  console.log(resp.status);    // 例如 200
  console.log(resp.headers);   // 响应头对象
} else {
  console.log(resp.error);     // 可读的错误信息（若为 HTTP 错误则为 null）
  console.log(resp.status);    // HTTP 状态码；网络错误时为 null
}

输出格式

每次调用都会返回一个包含以下字段的对象：

错误处理与重试行为

• 自动重试：连接错误、超时、HTTP 429 / 5xx 响应。
• 不重试：4xx 错误（除 429 外）—— 立即返回。
• 退避策略：指数退避并加入随机抖动（基础延迟 500ms，最大 30 秒）。
• 优雅失败：客户端从不抛出异常。重试耗尽后，仍以最后一次错误响应进行解析，使调用方始终可以检查 resp.ok 和 resp.error。

配置选项

所有选项可在客户端级别（构造函数中）设置，并在单次请求中覆盖：

依赖项

无外部依赖 —— 仅使用 Node.js 内置模块（http、https、url）。