同一段请求代码,在 Node 测试里能跑,放进浏览器就报 CORS,塞进 Tauri 的 WebView 又连不上本地服务。你开始写环境判断:测试用 fetch,浏览器用 fetch 加代理,桌面壳里换成 invoke。三套代码,三套错误处理,超时和重试各写一遍,最后没人说得清线上到底走的是哪条路。

unireq 想解决的就是这件事:请求的写法、响应结构、错误分类、超时、重试、拦截器保持一套,底下接 HTTP 还是 Tauri IPC 由传输层决定。它不是浏览器 fetch 的替代品,也不是 axios 的平替;它更像一个「请求协议适配层」。这一篇按源码讲清楚它能做什么、装不上的时候怎么办、在 Node 和 Tauri 里的真实边界。

它解决什么,不解决什么

先看它提供的抽象。一个请求从输入到响应分为五步,核心层只认识 Transport 接口和 RawResponse,不关心底下是 node:http 还是 Tauri 的 IPC。

一次请求在库内部的路径
合并默认值与 query
policy 先判定
用户中间件洋葱链
传输层发送
按 responseType 解码
失败则退避重试

它解决的是「请求怎么写、错误怎么分类、重试和超时放在哪一层」。它不解决代理、Cookie 罐、HTTP/2、服务端渲染缓存、CORS 本身,也不替你在浏览器里绕过跨域。它的 policy 是客户端自己给自己立的规矩,不是服务端的安全边界。

从源码看版本与依赖:package.json 是 0.1.0,声明 Node 18 及以上,运行时零依赖,只用到 node:http、node:https 和 Web 标准的 fetch、Headers、AbortSignal。它没有发布到 npm;仓库自带 39 个测试,全部通过。本文实测环境是 Node 24.21.0。

安装:npm 上没有,GitHub 直装也缺文件

先复现两个真实的失败现场,免得你以为是网络问题。执行 npm install unireq:

npm error code E404
npm error 404 Not Found - GET https://registry.npmjs.org/unireq - Not found

那就从 GitHub 装:

npm install github:Deepl-ysp/unireq

安装本身能完成,但一 import 就失败:

ERR_MODULE_NOT_FOUND: Cannot find module '.../node_modules/unireq/dist/index.js'

原因是仓库没有把 dist 提交进去,package.json 的 files 只允许发布 dist 和 README,而安装 GitHub 仓库时不会自动跑构建。打开安装目录,里面只有:

package.json
README.md

正确做法是 clone 后本地构建,再打包安装。这套流程在本机验证过:

git clone https://github.com/Deepl-ysp/unireq.git
cd unireq
npm install
npm run build
npm pack

会得到 unireq-0.1.0.tgz,然后在你的项目里安装这个 tarball:

npm install ../unireq/unireq-0.1.0.tgz

安装后导入成功,能拿到的导出包括 request、createClient、createTauriClient、HttpError、TimeoutError、PolicyError 等。这个「先 build 再 pack」的步骤不是可选项,是当前仓库形态决定的必选项。

最小请求:从本地服务到对象

起一个只返回 JSON 的本地服务,把库的基本行为跑一遍。下面这段可以完整运行:

import http from "node:http";
import {
  request,
  createClient,
  HttpError,
  TimeoutError,
  PolicyError,
} from "unireq";

let hits = 0;
const server = http.createServer((req, res) => {
  const url = new URL(req.url, "http://127.0.0.1");
  if (url.pathname === "/users") {
    res.writeHead(200, { "Content-Type": "application/json" });
    res.end(JSON.stringify({ ok: true, tag: url.searchParams.getAll("tag") }));
    return;
  }
  if (url.pathname === "/missing") {
    res.writeHead(404, { "Content-Type": "application/json" });
    res.end(JSON.stringify({ error: "not found" }));
    return;
  }
  if (url.pathname === "/slow") {
    setTimeout(() => {
      res.writeHead(200, { "Content-Type": "application/json" });
      res.end(JSON.stringify({ slow: true }));
    }, 300);
    return;
  }
  if (url.pathname === "/flaky") {
    hits += 1;
    res.writeHead(hits < 3 ? 500 : 200, { "Content-Type": "application/json" });
    res.end(JSON.stringify({ attempt: hits }));
    return;
  }
});

await new Promise((resolve) => server.listen(3000, "127.0.0.1", resolve));
const base = "http://127.0.0.1:3000";

const res = await request({
  url: `${base}/users`,
  query: { tag: ["a", "b"], page: 1, skip: undefined },
  headers: { "X-Demo": "hi" },
});
console.log("status:", res.status);
console.log("data:", JSON.stringify(res.data));
console.log("headers lowercase:", res.headers["content-type"]);
console.log("raw bytes:", res.raw.body.length);

实际输出:

status: 200
data: {"ok":true,"tag":["a","b"]}
headers lowercase: application/json
raw bytes: 27

这段没有关闭 server,实际跑完要自己调用 server.close(),否则进程不会退出;下面的重试示例继续复用这个服务,所以先别关。

这里有三个行为值得记住。第一,query 里的数组会展开成重复的 tag=a&tag=b,undefined 和 null 会被跳过,Date 会转成 ISO 字符串。第二,响应头全部归一化成小写,Content-Type 要按 content-type 取。第三,res.raw.body 是未解码的 Uint8Array,即使 data 已经解码成对象也还在,排查编码问题时能直接用。

默认的 responseType 是 auto:看响应头决定按 JSON、文本还是二进制解码。也可以显式写 json、text、buffer、arraybuffer。显式 json 但响应不是合法 JSON 时抛 ParseError,不是静默返回字符串;空 body 会得到 null。

API 全覆盖:导出清单、选项和返回结构

README 只演示了 request 和 createClient,实际入口比这多。按用途可以分成四组,先看全景:

分组成员用途
请求入口request、createClient前者是共享默认客户端,后者创建带 baseUrl、默认头、默认超时和策略的实例
错误族RequestError 基类,以及 HttpError、TimeoutError、PolicyError、CancelError、NetworkError、ParseError、InvalidRequestError、TauriError、IpcError所有失败都可按类型或 code 分支,不用猜错误消息
策略createPolicyMiddleware、evaluatePolicy、originOf把 allow/deny 规则做成中间件;后两个是拆开使用的底层函数
Tauri 适配createTauriClient、DEFAULT_TAURI_TIMEOUT_MS、TauriTransport、buildTauriInvokeUrl、BrowserTauriBridge、NodeTauriBridge、installTauriKeyInterceptor在 Tauri 应用里走 IPC,或自己接管桥接层

request(input) 的 input 是字符串或对象;字符串就是 URL,对象里的每个字段都有默认值和明确行为:

选项默认行为
url必填相对路径会与 client 的 baseUrl 拼接,绝对 URL 直接覆盖 baseUrl
methodGET原样传给传输层,不自动改大小写
headers{}与 client 默认头合并,同名时请求级覆盖客户端级;键统一转小写
query无对象或 URLSearchParams;数组展开成重复键,null/undefined 跳过,Date 转 ISO
body无对象自动 JSON 序列化并补 content-type;字符串和 Uint8Array 原样发送;null/undefined 不发 body
timeout无毫秒,按每次尝试计时,不是整个重试过程的总时限;0 或负数表示不超时
signal无AbortSignal,取消后抛 CancelError,code 为 ECANCEL
responseTypeautoauto / json / text / buffer / arraybuffer
retry不重试数字是 { count } 的简写;对象支持 count、delayMs、methods、retryOn
fetchOptions无透传给底层 fetch 传输层,Node 的 http 传输层不读它
context无原样带到响应链路和 PolicyError 上,用来放调用方自己的信息

响应固定是四个字段:status 数字、headers 小写 Headers、data 已按 responseType 解码、raw 是未解码的 { status, headers, body }。空响应体在 auto 和 json 下得到 null,不是空字符串。

createClient(options) 的选项同样是逐个有含义的:baseUrl 只影响相对 URL;headers 作为默认头;timeout 和 responseType 作为默认值;retry 作为所有请求的默认重试;fetchOptions 透传;policy 会注册成第一个中间件;transports 追加自定义传输层;builtins: false 跳过内置的 HTTP 和 Tauri 传输层。返回的 Client 有四个方法:request、use(追加中间件并返回自身)、registerTransport(后注册的优先)、close(调用各传输层的清理钩子)。

策略部分的完整形状是 PolicyOptions:mode 取 "allow" 或 "deny",allow 和 deny 是规则数组,denySchemes 按协议名拦截,allowSameOrigin 放行与当前页面同源的请求。规则可以是字符串或正则;字符串支持 METHOD origin/path 前缀,例如 "POST https://api.example.com/v1"。默认模式是 allow,也就是没写规则时全部放行;只有 deny 模式才会把「不在 allow 列表里」的请求拦下。

Tauri 客户端返回的 TauriClient 提供这些方法:invoke(命令名进、JSON 出)、invokeRaw(保留完整响应,默认按字节返回)、ipcRequest(低层请求,Tauri-Response 对调用方可见)、listen(订阅事件,返回取消订阅函数)、request(逃生口,可发 ipc:// URL)、use 和 close。默认超时是 DEFAULT_TAURI_TIMEOUT_MS,即 15 秒,比 HTTP 默认更短。错误族的公共字段包括 code、method、url、response、cause;HttpError 多一个 status,TimeoutError 多 timeoutMs,PolicyError 多 reason、origin、context,TauriError 多 command 和 payload。

底层导出各自负责一小块:TauriTransport 是把 ipc:// 映射到 invoke 的传输层实现,适合自己组装 client;buildTauriInvokeUrl 把 ipc:// 地址转成真实调用地址,Windows 下会落到 ipc.localhost;BrowserTauriBridge 从 window.__TAURI_INTERNALS__ 捕获 invoke key,NodeTauriBridge 接受一个 keyProvider 回调;installTauriKeyInterceptor 用于你无法控制初始化顺序、需要在第一次 invoke 之前就把 key 截下来的场景。普通应用直接用 createTauriClient 就够,不需要碰这些底层件。

静默行为:输入、实际结果、为什么

这个库的大部分边界会抛错,但有几处是「接受但不按你想的方式工作」。下面这些都在本机跑过,或者直接对应源码里的默认分支。

输入实际结果为什么
client.request("/echo", { method: "POST" })第二个参数被忽略,实际发的是 GET,body 为空request 只接收一个 RequestInput;要带选项必须写成对象 { url, method }
retry: 2 配 method: "POST"服务端只收到 1 次请求,500 直接抛出默认只重试幂等方法;POST 不在列表里,需要显式写 methods: ["POST"]
服务端返回 429不重试,直接抛 HttpError默认重试范围是 5xx、超时和网络错误;429 属于 4xx,需要自己加 retryOn
服务端返回 302抛 HttpError,status 是 302,不自动跟随传输层不实现重定向,且非 2xx 一律按错误处理
中间件里数重试次数一次 before、一次 after,即使底层试了 3 次中间件包在整个重试循环外面,不是每次尝试都进出
timeout: 1000 配 3 次重试总耗时可能远超 1 秒超时按单次尝试计算,重试会重新计时
用字符串 body 发 JSON不会自动补 content-type只有对象 body 才自动序列化并设置 JSON 头
请求头写 Content-Type能生效,但读响应头时必须用小写请求头合并时归一化;响应头也统一转小写
builtins: false 后打包到浏览器仍可能因静态引入 node:http 报错关闭注册不等于移除静态 import,打包器仍会解析 Node 内置模块

第一行是最容易犯的:TypeScript 会拦住第二个参数,纯 JS 不会,结果就是「我明明写了 POST,服务端却收到 GET」。第二、三行则说明「开了重试」不等于「所有失败都会重试」,方法、状态码、错误类型三道筛子都在。

错误、超时和取消

非 2xx 不会返回给你自己判断,而是直接抛 HttpError。它带 status 和 response,响应体在 response.body 里还是原始字节。

try {
  await request(`${base}/missing`);
} catch (e) {
  if (e instanceof HttpError) {
    console.log("404:", e.code, e.status, e.response.body.toString());
  }
}
// 404: EHTTP 404 {"error":"not found"}

超时按「每次尝试」计时,不是整个重试过程的总时长。默认不设超时,要显式传 timeout。超时抛 TimeoutError,带 timeoutMs:

try {
  await request({ url: `${base}/slow`, timeout: 30 });
} catch (e) {
  if (e instanceof TimeoutError) console.log("timeout:", e.code, e.timeoutMs);
}
// timeout: ETIMEOUT 30

取消用标准的 AbortSignal:传 signal,调用 controller.abort(),得到 CancelError,code 是 ECANCEL。如果在重试的等待期取消,也会抛这个错误,不会继续发下一次。

错误体系是一组类而不是一堆字符串:InvalidRequestError(EINVALID)、CancelError(ECANCEL)、TimeoutError(ETIMEOUT)、NetworkError(ENETWORK)、HttpError(EHTTP)、IpcError(EIPC)、TauriError(ETAURI)、PolicyError(EPOLICY)、ParseError(EPARSE)。它们都带 code、url、method,部分带 response。你可以只判断 code,不依赖具体类。

还有一个容易误判的地方:它不跟随重定向。遇到 302 会直接抛 HttpError,status 是 302。这是源码里明写的设计,不是 bug。需要跟随就自己处理 Location,或者换传输层。

重试:默认只碰幂等方法

重试的 count 是「首次失败之后」的次数,不是总次数。默认只重试 GET、HEAD、OPTIONS、PUT、DELETE,默认只重试超时、网络错误和 HTTP 5xx;退避是 delayMs * factor^attempt,默认 100ms 起步、因子 2。

最容易踩的坑是:给 POST 写 retry: 2 以为会重试,实际一次就结束。实测服务端只收到一次请求,然后抛 500:

hits = 0;
await request({
  url: `${base}/flaky`,
  method: "POST",
  body: { a: 1 },
  retry: 2,
});
// HttpError 500, server hits: 1

要重试 POST,必须显式把方法加进去,并且想清楚接口是否幂等:

hits = 0;
const res = await request({
  url: `${base}/flaky`,
  method: "POST",
  body: { a: 1 },
  retry: { count: 2, delayMs: 50, methods: ["POST"] },
});
// {"attempt":3}, server hits: 3

429 默认不重试,因为它不在「5xx」这个条件里。要做限流退避,得用 retryOn 自己判断状态码或错误码,并且自己读 Retry-After。库给了钩子,但没有替你实现完整的限流策略。

createClient、中间件和 policy

单次 request 适合脚本;应用里用 createClient,把 baseUrl、公共头、超时、重试收在一起。中间件是洋葱模型,注册顺序从外到内,响应按相反顺序回来。

const client = createClient({ baseUrl: base, headers: { "x-app": "demo" } });
client.use(async (req, next) => {
  console.log("before:", req.url);
  const response = await next();
  console.log("after:", response.status);
  return response;
});
const viaClient = await client.request("/users");
await client.close();

实际顺序输出是:

before: http://127.0.0.1:3000/users
after: 200

两个中间件时顺序是 a:before、b:before、b:after、a:after,和 README 写的一致。中间件能改请求头、改响应头、短路请求,也能捕获下游异常再决定是否继续抛。它是这套库最像「框架」的部分。

policy 是内置的第一个中间件,跑在所有用户中间件之前,所以后面的中间件绕不过它。默认 mode: "allow",也就是不设规则时全部放行;设成 "deny" 后,只有命中 allow、同源或没有命中 deny 的请求才放行。规则支持 *、完整 origin、host 或 host:port、路径前缀和正则。

const denied = createClient({
  policy: { mode: "deny", allow: ["127.0.0.1:3000"] },
});

try {
  await denied.request({
    url: "http://evil.example/x",
    context: { chain: ["root.vjson"] },
  });
} catch (e) {
  if (e instanceof PolicyError) {
    console.log(e.code, e.reason, e.origin, e.context);
  }
}
// EPOLICY not-allowlisted http://evil.example {"chain":["root.vjson"]}

context 会原样挂在错误上,适合把「这条请求是从哪个配置文件来的」一路带上去。allowSameOrigin 依赖浏览器的 location.origin,在 Node 里没有 location,这条规则不会生效。

policy 是客户端自律,不是安全边界。恶意代码可以直接不用这个 client,或者改掉规则。它的价值是防止业务代码误请求内网地址、把允许的目标收敛到一处,不是防止攻击者发起请求。

传输层:自定义协议和「后注册覆盖」

核心层不认识 HTTP,所以扩展传输层不需要改库。实现一个带 name、supports、send 的对象,注册进去就能接管某个协议。下面这个自定义 my: 传输层在本机跑过,返回 201 和 JSON:

const custom = {
  name: "my",
  supports: (url) => url.protocol === "my:",
  async send() {
    return {
      status: 201,
      headers: { "content-type": "application/json" },
      body: Buffer.from(JSON.stringify({ from: "custom" })),
    };
  },
};

const customClient = createClient({ builtins: false, transports: [custom] });
const response = await customClient.request("my://local/resource");
console.log(response.status, JSON.stringify(response.data));
// 201 {"from":"custom"}

supports 决定谁能接这个 URL,注册表按后注册优先匹配,所以你可以用自定义传输层覆盖内置的 http:。这在测试里很有用:把网络请求换成一个假传输层,不启动服务也能验证中间件、重试和错误映射。

但 builtins: false 只关掉运行时的默认注册,不关掉模块依赖。库入口静态导入了 HttpTransport,而它又静态导入 node:http 和 node:https。也就是说,即使你只用自定义传输层,打包到浏览器或 WebView 时仍然要给这两个 Node 内置模块提供 stub,否则构建阶段就会报模块找不到。README 也提到浏览器打包需要 stub,这一点绕不过去。

Tauri 里的真实形态

createTauriClient 是给 Tauri 2.x 用的高层封装。它返回的 client 不止 request,还有 invoke、invokeRaw、ipcRequest、listen。默认超时 15 秒,因为 invoke key 拿不到时不能让页面一直挂着。

import { createTauriClient } from "unireq";

const tauri = createTauriClient();
const result = await tauri.invoke<number>("add", { a: 1, b: 2 });
const unlisten = await tauri.listen("download-progress", (payload) => {
  console.log(payload);
});

它内部把命令名转成 ipc://命令名;Windows 默认用 ipc.localhost,可以开 useHttpsScheme 改用 https。Tauri 的 Tauri-Response: error 会映射成 TauriError,带 command 和原始 payload。IPC 层自己的错误,比如信封不对、连接失败,映射成 IpcError。

有一个导入顺序的坑:库需要在首次 invoke 之前劫持 Headers.prototype.set 和 window.fetch,从 Tauri 自己的请求里抓 Tauri-Invoke-Key。如果你先导入了 @tauri-apps/api/core 并已经发过 invoke,再导入 unireq,就会拿不到 key,Tauri 侧报「缺少 invoke key」。所以要在应用入口尽早导入 unireq,并确认没有被别的包提前触发 invoke。

这里必须说明一个边界:createTauriClient 只注册了 IPC 传输层,request 里写普通 http:// URL 没有传输层能接,会抛 InvalidRequestError。它不是为了在 WebView 里发 HTTP 而设计的;要在 Tauri 前端同时发 HTTP 和 IPC,需要自己用 fetch 写一个传输层注册进去。README 标题里的「统一 HTTP 与 IPC」指的是接口统一,不是同一个 client 在 WebView 里两种协议都自带。这个标题容易让人以为一个 client 同时支持两种协议,当前代码是分开的,后续是否会在 WebView 里补一个基于 fetch 的默认传输层,标为待确认。本文没有在真实 Tauri 应用里实测 IPC,只跑了仓库的 Node 假桥接测试和 Node 下的 HTTP 示例,Tauri 部分标为未在本机实测。

完整小项目:从空目录到带策略的请求层

这个项目把前面的零件装起来:一个本地服务、一个带 baseUrl 和默认头的 client、一个日志中间件、一个 deny 策略、一次重试和一次 POST。目录只有两个文件:

req-demo/
├── server.mjs
└── client.mjs

因为 unireq 没有发布到 npm,先按前面的流程构建出 tgz,再在空目录里安装:

git clone https://github.com/Deepl-ysp/unireq.git
cd unireq
npm install
npm run build
npm pack
mkdir ../req-demo
cd ../req-demo
npm init -y
npm install ../unireq/unireq-0.1.0.tgz

server.mjs 提供三个端点:/health 返回 JSON,/flaky 前两次返回 500、第三次返回 200,/echo 回显方法和 body。

import http from "node:http";

let hits = 0;
const server = http.createServer((req, res) => {
  const url = new URL(req.url, "http://127.0.0.1");
  if (url.pathname === "/health") {
    res.writeHead(200, { "content-type": "application/json" });
    res.end(JSON.stringify({ ok: true, service: "demo" }));
    return;
  }
  if (url.pathname === "/flaky") {
    hits += 1;
    res.writeHead(hits < 3 ? 500 : 200, { "content-type": "application/json" });
    res.end(JSON.stringify({ attempt: hits }));
    return;
  }
  if (url.pathname === "/echo") {
    let body = "";
    req.on("data", (chunk) => (body += chunk));
    req.on("end", () => {
      res.writeHead(201, { "content-type": "application/json" });
      res.end(JSON.stringify({ method: req.method, body }));
    });
    return;
  }
  res.writeHead(404, { "content-type": "application/json" });
  res.end(JSON.stringify({ error: "not found" }));
});

server.listen(3100, "127.0.0.1", () => console.log("ready"));

client.mjs 的完整代码。注意 POST 必须写成对象形式,不能给 request 传第二个参数:

import { createClient, PolicyError } from "unireq";

const client = createClient({
  baseUrl: "http://127.0.0.1:3100",
  headers: { "x-app": "demo" },
  timeout: 1000,
  retry: { count: 2, delayMs: 50 },
  policy: { mode: "deny", allow: ["127.0.0.1:3100"] },
});

client.use(async (req, next) => {
  console.log("[mw] before", req.method, req.url);
  const res = await next();
  console.log("[mw] after", res.status);
  return res;
});

const health = await client.request("/health");
console.log("health:", JSON.stringify(health.data));

const flaky = await client.request("/flaky");
console.log("flaky:", JSON.stringify(flaky.data));

const echo = await client.request({
  url: "/echo",
  method: "POST",
  body: { a: 1 },
});
console.log("echo:", echo.status, String(echo.data.body));

try {
  await client.request("http://evil.example/x");
} catch (e) {
  if (e instanceof PolicyError) {
    console.log("policy:", e.code, e.reason, e.origin);
  }
}

await client.close();

先跑 node server.mjs,再开另一个终端跑 node client.mjs。实际输出:

[mw] before GET http://127.0.0.1:3100/health
[mw] after 200
health: {"ok":true,"service":"demo"}
[mw] before GET http://127.0.0.1:3100/flaky
[mw] after 200
flaky: {"attempt":3}
[mw] before POST http://127.0.0.1:3100/echo
[mw] after 201
echo: 201 {"a":1}
policy: EPOLICY not-allowlisted http://evil.example

输出里有三件事值得对照。第一,/flaky 底层实际发了 3 次,但中间件只出现一次 before 和一次 after,因为中间件包在重试循环外面。第二,/echo 的 body 是字符串 {"a":1},说明对象 body 被自动 JSON 序列化了;如果写成字符串,就要自己设 content-type。第三,恶意地址没有发出去,抛出的 PolicyError 带了 EPOLICY、not-allowlisted 和 origin,排查时不用翻日志猜是哪条规则拦的。

这个项目的策略是 deny 模式,只允许 127.0.0.1:3100。把 allow 数组改错、或者把模式改成 allow,恶意地址就会被放行——策略是配置出来的,不是自动推断的。生产里通常按「允许哪些 origin」写白名单,而不是先全放行再逐条 deny。

排查表:现象、原因和第一步

现象真实原因第一步查什么
npm install unireq 报 404包没有发布到 npm改用 clone 后 npm run build 加 npm pack,安装生成的 tgz
GitHub 安装后 import 报找不到 dist/index.js仓库没提交 dist,安装时也不跑构建看安装目录里是不是只有 package.json 和 README;回到源码目录构建后再打包
POST 写了 retry 但只发了一次默认只重试幂等方法,POST 不在列表里用 retry: { methods: ["POST"] },同时确认接口是否幂等
响应头取 Content-Type 得到 undefined响应头被统一成小写用 res.headers["content-type"],不要用原始大小写
请求 302 地址直接抛错库故意不跟随重定向读 Location 自己再发一次,或换传输层
浏览器打包报找不到 node:http入口静态依赖 HttpTransport,即使 builtins 设为 false 也在模块图里给 Node 内置模块配空 stub,或只在 Node/桌面端使用
Tauri invoke 报缺少 invoke keyunireq 在首次 invoke 之后才导入,错过了抓取时机把 unireq 的导入提到应用入口最前面,避免提前触发 Tauri 的 invoke
Tauri client 请求 http URL 抛 EINVALID它只注册 IPC 传输层用 createClient 加自定义 fetch 传输层,或改用别的 HTTP 客户端

边界与代价:它不解决什么

第一,不跟随重定向。第二,不做 Cookie 罐、代理、HTTP/2、连接池调优,这些都交给底层或外部工具。第三,响应体是全量缓冲的:HttpTransport 把所有 chunk 收进数组,结束后一次性返回,不能做流式下载或上传进度。第四,不支持 multipart/form-data 自动组装,body 只接受字符串、Uint8Array 和可 JSON 序列化的对象;文件上传要自己拼字节或换传输层。

第五,浏览器不是一等公民。默认 HTTP 传输依赖 Node 内置模块,WebView 里要么 stub,要么自己写基于 fetch 的传输层;库自带的 Tauri client 只做 IPC。第六,policy 是客户端自律,不防攻击者。第七,重试只覆盖它认识的错误,业务语义上的「结果不对但状态码 200」它不知道,也不会重试。

第八,错误分类清楚但不会替你做用户提示。HttpError 里有响应体,NetworkError 里有 cause,PolicyError 里有 context,怎么拼成一句人话仍然是调用方的事。第九,0.1.0 版本意味着 API 还可能变;仓库没有发布 npm,也没有版本迁移说明,升级前要自己读 diff。

适合用

Node 服务、构建脚本、桌面应用的命令通道、需要统一错误和重试策略的多协议场景、想用假传输层做确定性测试的项目。请求数量不大、但错误处理和策略要求清楚。

不适合用

纯浏览器前端、需要流式上传下载、需要 Cookie 和代理管理、需要自动重定向、需要完整 multipart 表单、需要成熟生态和长期版本承诺。这些需求应该直接用 fetch、axios 或各平台的官方客户端。

自己验证:五个练习

  1. 按本文流程 clone、build、pack、安装,确认 import("unireq") 能拿到 request;再试一次 GitHub 直装,记录 dist/index.js 找不到的报错。
  2. 起一个本地服务,分别请求 200、404、302、空 JSON、坏 JSON,记录每种情况抛出的错误类、code 和 status。
  3. 给同一个 500 接口写 POST 请求,先用 retry: 2,再用 retry: { methods: ["POST"] },在服务端打日志对比收到的次数。
  4. 注册两个中间件,打印进入和离开的顺序,确认是 a:before、b:before、b:after、a:after。
  5. 写一个 my: 自定义传输层,用 builtins: false 注册,确认请求不经过网络也能返回 201;再观察打包时 node:http 仍然被引用。
  6. 用 createClient({ policy: { mode: "deny", allow: [...] } }) 请求一个不在白名单的地址,确认 PolicyError 的 reason、origin 和 context 都被保留。

小结

核心是一套请求语义,不是某个协议HTTP 和 IPC 都是传输层;核心只管合并、策略、中间件、重试和解码。
它不是浏览器 fetchNode 内置模块是静态依赖;WebView 要 stub 或自定义传输层,Tauri client 只做 IPC。
重试和超时有明确默认值默认只重试幂等方法、超时和 5xx;POST 和 429 要自己显式配置。
先 build 再 pack 是必经步骤包没有发布到 npm,GitHub 直装缺 dist;按源码构建后才能用。

三篇的顺序到这里闭环:CompactProfile 把一段文本解析成对象,VarJson 把多个文件和多个作用域组装成对象,unireq 负责在需要的时候把远程数据取回来。三者没有强绑定关系,其中 VarJson 和 unireq 的组合需要你自己写「取回文本、落临时文件、再解析」的桥接代码,这一点在前一篇已经跑过。选型时先问清楚要解决的是解析、组装还是传输,不要把三个库当成一个框架。