同一段请求代码,在 Node 测试里能跑,放进浏览器就报 CORS,塞进 Tauri 的 WebView 又连不上本地服务。你开始写环境判断:测试用 fetch,浏览器用 fetch 加代理,桌面壳里换成 invoke。三套代码,三套错误处理,超时和重试各写一遍,最后没人说得清线上到底走的是哪条路。
unireq 想解决的就是这件事:请求的写法、响应结构、错误分类、超时、重试、拦截器保持一套,底下接 HTTP 还是 Tauri IPC 由传输层决定。它不是浏览器 fetch 的替代品,也不是 axios 的平替;它更像一个「请求协议适配层」。这一篇按源码讲清楚它能做什么、装不上的时候怎么办、在 Node 和 Tauri 里的真实边界。
它解决什么,不解决什么
先看它提供的抽象。一个请求从输入到响应分为五步,核心层只认识 Transport 接口和 RawResponse,不关心底下是 node:http 还是 Tauri 的 IPC。
它解决的是「请求怎么写、错误怎么分类、重试和超时放在哪一层」。它不解决代理、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 |
method | GET | 原样传给传输层,不自动改大小写 |
headers | {} | 与 client 默认头合并,同名时请求级覆盖客户端级;键统一转小写 |
query | 无 | 对象或 URLSearchParams;数组展开成重复键,null/undefined 跳过,Date 转 ISO |
body | 无 | 对象自动 JSON 序列化并补 content-type;字符串和 Uint8Array 原样发送;null/undefined 不发 body |
timeout | 无 | 毫秒,按每次尝试计时,不是整个重试过程的总时限;0 或负数表示不超时 |
signal | 无 | AbortSignal,取消后抛 CancelError,code 为 ECANCEL |
responseType | auto | auto / 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,这条规则不会生效。
传输层:自定义协议和「后注册覆盖」
核心层不认识 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 key | unireq 在首次 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 或各平台的官方客户端。
自己验证:五个练习
- 按本文流程 clone、build、pack、安装,确认
import("unireq")能拿到request;再试一次 GitHub 直装,记录dist/index.js找不到的报错。 - 起一个本地服务,分别请求 200、404、302、空 JSON、坏 JSON,记录每种情况抛出的错误类、
code和status。 - 给同一个 500 接口写 POST 请求,先用
retry: 2,再用retry: { methods: ["POST"] },在服务端打日志对比收到的次数。 - 注册两个中间件,打印进入和离开的顺序,确认是
a:before、b:before、b:after、a:after。 - 写一个
my:自定义传输层,用builtins: false注册,确认请求不经过网络也能返回 201;再观察打包时node:http仍然被引用。 - 用
createClient({ policy: { mode: "deny", allow: [...] } })请求一个不在白名单的地址,确认PolicyError的reason、origin和context都被保留。
小结
三篇的顺序到这里闭环:CompactProfile 把一段文本解析成对象,VarJson 把多个文件和多个作用域组装成对象,unireq 负责在需要的时候把远程数据取回来。三者没有强绑定关系,其中 VarJson 和 unireq 的组合需要你自己写「取回文本、落临时文件、再解析」的桥接代码,这一点在前一篇已经跑过。选型时先问清楚要解决的是解析、组装还是传输,不要把三个库当成一个框架。