upfetch

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Translation

Chinese

upfetch

Use

up-fetch

when you need a reusable fetch client with request-scoped defaults, automatic request/response shaping, runtime validation, retries, and lifecycle hooks.

当你需要一款支持请求作用域默认值、自动请求/响应构造、运行时校验、重试以及生命周期钩子的可复用fetch客户端时，即可使用

up-fetch

。

Mental model

核心思路

```
up(fetchFn, getDefaultOptions?)
```
creates the reusable client.
```
getDefaultOptions(input, options, ctx)
```
runs on every request.
```
upfetch(input, options?, ctx?)
```
performs one request.
Keep
```
SKILL.md
```
high-level; load the relevant file under
```
references/
```
for details.

```
up(fetchFn, getDefaultOptions?)
```
用于创建可复用客户端。
每次发起请求时都会执行
```
getDefaultOptions(input, options, ctx)
```
。
```
upfetch(input, options?, ctx?)
```
用于发起单次请求。
请查看
```
SKILL.md
```
了解概览；如需详情请加载
```
references/
```
目录下的对应文件。

Minimum pattern

最简使用示例

import { up } from 'up-fetch'
import { z } from 'zod'

export const upfetch = up(fetch, () => ({
   baseUrl: 'https://api.example.com',
   headers: {
      Authorization: readToken() ? `Bearer ${readToken()}` : undefined,
   },
   timeout: 5000,
}))

const user = await upfetch('/users/1', {
   schema: z.object({
      id: z.number(),
      name: z.string(),
   }),
})

import { up } from 'up-fetch'
import { z } from 'zod'

export const upfetch = up(fetch, () => ({
   baseUrl: 'https://api.example.com',
   headers: {
      Authorization: readToken() ? `Bearer ${readToken()}` : undefined,
   },
   timeout: 5000,
}))

const user = await upfetch('/users/1', {
   schema: z.object({
      id: z.number(),
      name: z.string(),
   }),
})

Workflow

使用流程

Start with client setup and dynamic defaults.
If the request needs auth, params, body shaping, or merge semantics, read auth and request shaping.
If the response contract matters, read validation, parsing, and errors.
If retries, timeouts, or hook timing matter, read retries, timeouts, and lifecycle.
If streaming or runtime quirks matter, read streaming and runtime caveats.

首先参考客户端配置与动态默认值。
如果请求需要身份验证、参数、请求体构造或合并规则，请阅读身份验证与请求构造。
如果需要遵循响应契约，请阅读校验、解析与错误处理。
如果需要配置重试、超时或钩子触发时机，请阅读重试、超时与生命周期。
如果涉及流式处理或运行时特殊问题，请阅读流式处理与运行时注意事项。

High-value rules

最佳实践规则

Pass a function as the second argument to
```
up()
```
, not a plain object.
Read auth and other mutable defaults inside that function so values stay fresh.
Use
```
params
```
and
```
body
```
instead of hand-serializing query strings or JSON.
Use
```
schema
```
when you need runtime trust; TypeScript generics alone do not validate payloads.
If you want error-as-value behavior, set
```
reject: () => false
```
before relying on
```
parseResponse
```
.
Prefer
```
globalThis.fetch
```
over imported
```
undici.fetch
```
.

给
```
up()
```
的第二个参数传递函数，而不是普通对象。
在该函数内部读取身份验证信息以及其他可变默认值，保证取值是最新的。
请使用
```
params
```
和
```
body
```
，不要手动序列化查询字符串或JSON。
需要运行时数据可靠性时请使用
```
schema
```
；仅靠TypeScript泛型无法校验载荷。
如果你需要“错误作为值”的行为，请在使用
```
parseResponse
```
前设置
```
reject: () => false
```
。
优先使用
```
globalThis.fetch
```
，而非导入的
```
undici.fetch
```
。

References

参考文档

Client setup and dynamic defaults
Auth and request shaping
Validation, parsing, and errors
Retries, timeouts, and lifecycle
Streaming and runtime caveats

客户端配置与动态默认值
身份验证与请求构造
校验、解析与错误处理
重试、超时与生命周期
流式处理与运行时注意事项