npm - @finesoft/front - Versions diffs - 0.5.1 → 0.5.3 - Mend

@finesoft/front 0.5.1 → 0.5.3

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.

Files changed (128) hide show

package/README.md +4 -4
package/dist/Outlet.svelte +39 -0
package/dist/Outlet.svelte.d.ts +7 -0
package/dist/browser-CR5vhgXg.mjs +1317 -0
package/dist/browser-kFMjlLGT.d.mts +262 -0
package/dist/browser.d.mts +7 -2
package/dist/browser.mjs +9 -1
package/dist/controller-types-CgmJ6-le.d.mts +16 -0
package/dist/cookies-BiRlUanX.d.mts +786 -0
package/dist/fetch-policy-BHT8RtrL.mjs +82 -0
package/dist/host-guard-DDWxLpFL.mjs +222 -0
package/dist/http-B6CJqDyf.d.mts +46 -0
package/dist/http-CaxrMD1A.d.mts +1 -0
package/dist/http-D70PL72H.mjs +257 -0
package/dist/http.d.mts +3 -0
package/dist/http.mjs +2 -0
package/dist/index-node.d.mts +15 -0
package/dist/index-node.mjs +15 -0
package/dist/index.d.mts +48 -697
package/dist/index.mjs +44 -261
package/dist/load-node.d.mts +5 -0
package/dist/load-node.mjs +10 -0
package/dist/load-portable.d.mts +5 -0
package/dist/load-portable.mjs +8 -0
package/dist/lru-map-BKoUAySU.mjs +50 -0
package/dist/messages-CAt2QdGr.mjs +140 -0
package/dist/native-contract-DuR25hYB.d.mts +14 -0
package/dist/native-contract.d.mts +2 -0
package/dist/native-contract.mjs +1 -0
package/dist/node-D9hB4dsz.d.mts +35 -0
package/dist/node.d.mts +2 -0
package/dist/node.mjs +59 -0
package/dist/path-CGFl2w7D.mjs +113 -0
package/dist/path-CXT6xGPO.d.mts +261 -0
package/dist/portable-CaxrMD1A.d.mts +1 -0
package/dist/portable.d.mts +11 -0
package/dist/portable.mjs +12 -0
package/dist/proxy-2dSWO-Xw.d.mts +53 -0
package/dist/proxy-z02VvGIj.mjs +7520 -0
package/dist/public-types-BcJM-AYc.mjs +835 -0
package/dist/react-DhwBRw01.d.mts +16 -0
package/dist/react.d.mts +3 -0
package/dist/react.mjs +29 -0
package/dist/rolldown-runtime-B4iAMlE-.mjs +35 -0
package/dist/secure-fetch-Xlht2jd7.d.mts +30 -0
package/dist/server-controller-proxy-BkVuVWVD.d.mts +38 -0
package/dist/session-DnB4ZC3x.d.mts +1279 -0
package/dist/src-BQBfaaPO.mjs +3825 -0
package/dist/src-Ftl_0rhu.mjs +28 -0
package/dist/ssr-BLzYP4wU.d.mts +207 -0
package/dist/ssr-Tn4YkuxM.mjs +357 -0
package/dist/ssr.d.mts +3 -0
package/dist/ssr.mjs +3 -0
package/dist/svelte-Dr5to3SE.d.mts +16 -0
package/dist/svelte.d.mts +3 -0
package/dist/svelte.mjs +13 -0
package/dist/typegen-C-WeJCtf.d.mts +12 -0
package/dist/typegen-cli.d.mts +1 -0
package/dist/typegen-cli.mjs +11 -0
package/dist/typegen.d.mts +3 -0
package/dist/typegen.mjs +2 -0
package/dist/types-B1BT0N3t.mjs +402 -0
package/dist/undici-CPfL25Hr.mjs +22262 -0
package/dist/vite-Cj4SPA8D.d.mts +277 -0
package/dist/vite.d.mts +4 -0
package/dist/vite.mjs +2354 -0
package/dist/vue-DGmzuKho.d.mts +32 -0
package/dist/vue.d.mts +3 -0
package/dist/vue.mjs +56 -0
package/dist/web.d.mts +6 -0
package/dist/web.mjs +8 -0
package/dist/worker.d.mts +2 -0
package/dist/worker.mjs +2 -0
package/docs/01-getting-started.md +67 -199
package/docs/02-routing-and-controllers.md +163 -241
package/docs/03-middleware.md +10 -212
package/docs/04-rendering-and-hydration.md +7 -332
package/docs/05-i18n.md +7 -237
package/docs/06-http-client.md +20 -263
package/docs/07-di-container.md +23 -257
package/docs/08-observability.md +6 -286
package/docs/09-server-and-deployment.md +59 -219
package/docs/10-features-platform-pwa.md +7 -231
package/docs/11-navigation.md +143 -288
package/docs/12-session-restoration.md +6 -214
package/docs/README.md +7 -7
package/docs/advanced/custom-action-handler.md +29 -229
package/docs/advanced/custom-adapter.md +7 -259
package/docs/advanced/custom-event-recorder.md +7 -312
package/docs/advanced/inline-proxy-codegen.md +6 -185
package/docs/advanced/multi-tenant-scopes.md +10 -323
package/docs/engineering/ci-release-flow.md +35 -222
package/docs/engineering/project-structure.md +34 -277
package/docs/engineering/testing.md +8 -310
package/docs/pitfalls/container-scope-leak.md +2 -214
package/docs/pitfalls/i18n-bundle-size.md +6 -176
package/docs/pitfalls/proxy-binary-payloads.md +8 -12
package/docs/pitfalls/ssr-hydration-mismatch.md +9 -155
package/docs/pitfalls/ssr-vs-csr-globals.md +9 -170
package/docs/zh/01-getting-started.md +67 -199
package/docs/zh/02-routing-and-controllers.md +166 -244
package/docs/zh/03-middleware.md +10 -212
package/docs/zh/04-rendering-and-hydration.md +7 -332
package/docs/zh/05-i18n.md +7 -237
package/docs/zh/06-http-client.md +20 -263
package/docs/zh/07-di-container.md +23 -257
package/docs/zh/08-observability.md +6 -283
package/docs/zh/09-server-and-deployment.md +59 -219
package/docs/zh/10-features-platform-pwa.md +7 -231
package/docs/zh/11-navigation.md +130 -290
package/docs/zh/12-session-restoration.md +6 -214
package/docs/zh/README.md +4 -4
package/docs/zh/advanced/custom-action-handler.md +29 -229
package/docs/zh/advanced/custom-adapter.md +7 -259
package/docs/zh/advanced/custom-event-recorder.md +7 -312
package/docs/zh/advanced/inline-proxy-codegen.md +6 -185
package/docs/zh/advanced/multi-tenant-scopes.md +10 -323
package/docs/zh/engineering/ci-release-flow.md +35 -222
package/docs/zh/engineering/project-structure.md +34 -277
package/docs/zh/engineering/testing.md +8 -310
package/docs/zh/pitfalls/container-scope-leak.md +2 -214
package/docs/zh/pitfalls/i18n-bundle-size.md +6 -176
package/docs/zh/pitfalls/proxy-binary-payloads.md +8 -12
package/docs/zh/pitfalls/ssr-hydration-mismatch.md +9 -155
package/docs/zh/pitfalls/ssr-vs-csr-globals.md +9 -170
package/package.json +118 -20
package/dist/browser-BHhVWXik.mjs +0 -2
package/dist/browser-BV2BBXm7.d.mts +0 -2811

package/docs/zh/05-i18n.md CHANGED Viewed

@@ -1,243 +1,13 @@
-# 5. 国际化
+# 语言与文案
-框架处理四个 i18n 关注点：
+文案加载放在应用声明，请求语言放在 invocation。浏览器语言属性属于各自的挂载目标。
-1. **解析用户的 locale**（cookie、accept-language、手动覆盖）
-2. **加载正确的字典**而不让 bundle 膨胀
-3. **翻译字符串**（带插值和复数）
-4. **渲染正确的文本方向**（LTR / RTL）
-## Locale 解析
-给 `Framework.create()` 传默认 `locale`：
-```ts
-const framework = Framework.create({ locale: "zh-Hans" });
-```
-SSR 的 locale 优先级（最高优先）：
-1. `createSSRRender({ resolveLocale })` 里的 `resolveLocale` 回调 —— 能访问请求头 / cookie
-2. `frameworkConfig` 里的 `locale`（通过 DI 容器）
-浏览器的 locale 是服务端解析出的结果（通过 `<html lang>` 属性传过来）。`startBrowserApp` hydration 时读取并写回 `documentElement.lang`/`dir`。
-### 运行时读取
-```ts
-const { lang, dir } = framework.getLocale();
-// { lang: "zh-Hans", dir: "ltr" }
-```
-## 自定义 resolver
-```ts
-import { parseAcceptLanguage } from "@finesoft/front";
-createSSRRender({
-    bootstrap,
-    resolveLocale(ctx) {
-        // 1. cookie
-        const fromCookie = ctx.getCookie("locale");
-        if (fromCookie && isSupported(fromCookie)) return fromCookie;
-        // 2. accept-language
-        const accept = ctx.getHeader("accept-language");
-        const best = parseAcceptLanguage(accept ?? "").find((l) => isSupported(l.tag));
-        if (best) return best.tag;
-        // 3. fallback
-        return "en-US";
-    },
-    async renderApp(page) {
-        /* ... */
-    },
-});
-```
-`parseAcceptLanguage` 解析 `Accept-Language: en;q=0.9,fr;q=0.8` 为排序后的标签数组。`q=0` 的标签被过滤掉。
-## 通过 `messagesDir` 加载字典
-推荐方式是 JSON 文件 + Vite 插件：
-```ts
-// vite.config.ts
-finesoftFrontViteConfig({
-    ssr: { entry: "src/ssr.ts" },
-    i18n: { messagesDir: "src/locales" },
-});
-```
-```
-src/locales/
-├── en-US.json
-├── zh-Hans.json
-└── ja-JP.json
-```
-```json
-// src/locales/zh-Hans.json
-{
-    "hello": "你好",
-    "welcome": "欢迎，{name}",
-    "items.one": "{count} 个项目",
-    "items.other": "{count} 个项目"
-}
-```
-插件生成的代码会：
-- 只加载解析后的 locale 对应的 JSON（服务端：从磁盘读；浏览器端：动态 import chunk）
-- 服务端跨请求缓存
-- 按解析后的 locale 加 key，切换 locale 时重新拉取
-你**不**用把字典序列化进 HTML 载荷。浏览器和初始渲染并行拉自己的 locale chunk。
-## `SimpleTranslator`
-用于内存字典（小型应用、测试、或手动加载的数据）：
-```ts
-import { SimpleTranslator } from "@finesoft/front";
-const t = new SimpleTranslator({
-    locale: "zh-Hans",
-    messages: {
-        hello: "你好",
-        welcome: "欢迎，{name}",
-        "items.one": "{count} 个项目",
-        "items.other": "{count} 个项目",
-    },
-});
-t.t("hello"); // "你好"
-t.t("welcome", { name: "World" }); // "欢迎，World"
-t.plural("items", 5); // "5 个项目"
-t.plural("items", 1); // "1 个项目"
-```
-### 插值
-花括号占位：`{name}`、`{count}`、`{0}`。值是否 HTML 转义取决于你视图层的 escape —— `SimpleTranslator` 返回原始字符串。
-### 复数
-基于 `Intl.PluralRules`。key 用 CLDR 复数类别：`zero`、`one`、`two`、`few`、`many`、`other`。总要提供 `other` 作为兜底。
-```json
-{
-    "messages.zero": "No messages",
-    "messages.one": "1 message",
-    "messages.other": "{count} messages"
-}
-```
-```ts
-t.plural("messages", 0); // "No messages"
-t.plural("messages", 1); // "1 message"
-t.plural("messages", 5); // "5 messages"
-```
-复数系统更复杂的语言（俄语、阿拉伯语）自动选 `few`/`many`（如有）。
-## 与 DI 集成
-在容器里注册 translator：
-```ts
-container.register(
-    "translator",
-    () =>
-        new SimpleTranslator({
-            locale: framework.getLocale().lang,
-            messages: loadedMessages,
-        }),
-);
-```
-或用框架内置的 DI key：
-```ts
-import { DEP_KEYS } from "@finesoft/front";
-container.register(DEP_KEYS.TRANSLATOR, () => translator);
-// 之后在任何组件或 Controller 里：
-const t = framework.container.resolve(DEP_KEYS.TRANSLATOR);
-t.t("hello");
-```
-## 自定义消息源
-如果消息要从 API 或 CDN 加载，在 `createSSRRender` / `startBrowserApp` 上覆盖 `loadMessages`：
+## Configuration / 配置
 ```ts
-createSSRRender({
-    bootstrap,
-    async loadMessages(locale) {
-        const resp = await fetch(`https://cdn.example.com/i18n/${locale}.json`);
-        return resp.json();
-    },
-    async renderApp(page) {
-        /* ... */
-    },
-});
+import { loadMessages } from "virtual:finesoft-front/i18n-loader";
+// defineWebApp({ ..., loadMessages, configuration: { locale: "zh-Hans" } })
+// finesoftFrontViteConfig({ ..., i18n: { messagesDir: "src/locales" } })
 ```
-这**覆盖** Vite 生成的 loader。适用于：
-- 翻译由服务管理（Lokalise、Phrase）并在运行时拉取
-- 需要 stale-while-revalidate 缓存
-- 需要合并来自不同源的多个命名空间
-大多数应用文件 loader 就够 —— 只发当前 locale 一份字节，运行时不拉取。
-## RTL 支持
-```ts
-import { isRtl, getTextDirection, getLocaleAttributes } from "@finesoft/front";
-isRtl("ar"); // true
-isRtl("he"); // true
-isRtl("zh-Hans"); // false
-getTextDirection("ar"); // "rtl"
-getTextDirection("en"); // "ltr"
-getLocaleAttributes("ar-SA"); // { lang: "ar-SA", dir: "rtl" }
-```
-框架对 RTL locale 自动设 `<html dir="rtl">`。CSS 用逻辑属性（`margin-inline-start` 替代 `margin-left`）保证布局能镜像。
-```css
-/* 推荐 */
-.card {
-    padding-inline-start: 16px;
-}
-/* 避免 —— RTL 下不会镜像 */
-.card {
-    padding-left: 16px;
-}
-```
-## Locale 切换
-用户触发的 locale 切换：
-1. 在服务端更新 cookie / 用户偏好：`Set-Cookie: locale=ja-JP`。
-2. 触发整页刷新（`window.location.reload()`），让服务端解析新 locale、加载新字典、重新渲染。
-纯客户端切换技术上可行，但跳过 SSR 重渲染 —— 首屏会显示旧 locale 直到新字典加载。大多数应用整页刷新更简单也更正确。
-## 注意事项
-- **不要把整个字典序列化进 HTML。** 拖慢首屏。文件 loader 只发当前 locale，只发当前的 chunk。详见 [陷阱：i18n 包体积](./pitfalls/i18n-bundle-size.md)。
-- **运行时别改字典。** 缓存假设不可变。需要动态字符串（用户生成内容）就和翻译分开存。
-- **`SimpleTranslator` 是同步的。** 如果你的翻译源是异步的，在 Controller 跑之前加载（如 `beforeLoad` 或 `onBeforeStart`）。
-## 下一步
-- [HTTP 客户端](./06-http-client.md) —— 发请求，必要时带 locale 头
-- [陷阱：i18n 包体积](./pitfalls/i18n-bundle-size.md) —— 把翻译留在关键路径之外
+使用语言文件时启用 Vite loader，避免浏览器提前导入所有语言。通过框架依赖读取配置，勿在并发请求中修改进程级语言。可移植调用可向 `runtime.execute` 传入 `{ locale }`。

package/docs/zh/06-http-client.md CHANGED Viewed

@@ -1,286 +1,43 @@
-# 6. HTTP 客户端
+# HTTP 客户端
-`HttpClient` 是 `fetch` 之上的薄层、强类型包装，给你：
-- 面向类的子类化，便于组织 API 表面
-- 请求/响应拦截器：鉴权、日志、重试
-- 结构化的 `HttpError` 替代不透明的 reject
-- 大小写不敏感的头处理，与 `Response.headers.get()` 语义一致
-它**不是** axios 的替代。它是为框架需求设计的小而锋利的工具。
-## 子类化
-预期用法是按每个逻辑 API 表面子类化：
+`HttpClient` 是可选的类型化 fetch 封装，需要显式传入 `fetch`。服务端的连接地址校验由主机提供；浏览器应用也必须显式选择 DNS 策略。
 ```ts
-import { HttpClient } from "@finesoft/front";
+import { HttpClient, type HttpClientConfig } from "@finesoft/front";
 interface User {
     id: string;
     name: string;
 }
-interface NewUser {
-    name: string;
-    email: string;
-}
 export class UserApi extends HttpClient {
-    async list(): Promise<User[]> {
-        return this.get<User[]>("/users");
+    constructor(config: HttpClientConfig) {
+        super(config);
     }
-    async getById(id: string): Promise<User> {
-        return this.get<User>(`/users/${id}`);
+    getById(id: string, signal?: AbortSignal) {
+        return this.get<User>(`/users/${encodeURIComponent(id)}`, undefined, { signal });
     }
-    async create(data: NewUser): Promise<User> {
-        return this.post<User>("/users", data);
+    create(user: Omit<User, "id">) {
+        return this.post<User>("/users", user);
     }
-    async update(id: string, data: Partial<NewUser>): Promise<User> {
-        return this.patch<User>(`/users/${id}`, data);
-    }
-    async delete(id: string): Promise<void> {
-        await this.delete(`/users/${id}`);
+    remove(id: string) {
+        return this.del<void>(`/users/${encodeURIComponent(id)}`);
     }
 }
 ```
-每个子类实例绑定一个 `baseUrl` 和共享 options。
-## 实例化
-```ts
-const api = new UserApi({
-    baseUrl: "/api",
-    defaultHeaders: {
-        "X-App-Version": "1.0.0",
-    },
-});
-```
-注册到 DI 里让 Controller 能 resolve：
+## 主机绑定
 ```ts
-import { DEP_KEYS } from "@finesoft/front";
-container.register("userApi", () => new UserApi({ baseUrl: "/api" }));
-```
-然后在 Controller 里：
-```ts
-async execute(params, container) {
-    const api = container.resolve<UserApi>("userApi");
-    const users = await api.list();
-    return { kind: "users", items: users };
-}
+// Node 主机代码；浏览器和 Worker 模块不要引入此入口。
+import { nodeSafeFetchOptions } from "@finesoft/front";
+const api = new UserApi({ baseUrl: "https://api.example.com", fetch, ...nodeSafeFetchOptions });
 ```
-## 方法
-| 方法                              | HTTP 动词 | 带 body？ |
-| --------------------------------- | --------- | --------- |
-| `get<T>(path, options?)`          | GET       | 否        |
-| `post<T>(path, body?, options?)`  | POST      | 是        |
-| `put<T>(path, body?, options?)`   | PUT       | 是        |
-| `patch<T>(path, body?, options?)` | PATCH     | 是        |
-| `delete<T>(path, options?)`       | DELETE    | 否        |
-所有方法返回 `Promise<T>`。响应 body 按 `Content-Type` 解析：
-- `application/json` → `JSON.parse`
-- `text/*` → `string`
-- 其他 → `Response`（你自己处理解析）
-## 单次请求 options
-```ts
-await api.get<User>("/users/42", {
-    headers: { "X-Request-Id": requestId },
-    signal: abortController.signal,
-    credentials: "include",
-});
-```
-所有标准 `RequestInit` 字段直通。单次请求头与 `defaultHeaders` 合并（key 冲突时单次请求胜）。
-## 拦截器
-### 请求拦截器
-请求发出前改 URL 和 `RequestInit`。
-```ts
-const api = new UserApi({
-    baseUrl: "/api",
-    requestInterceptors: [
-        (url, init) => {
-            init.headers = {
-                ...init.headers,
-                Authorization: `Bearer ${getToken()}`,
-            };
-            return init;
-        },
-    ],
-});
-```
-多个拦截器按数组顺序跑。每个接收上一个返回的 `init`。
-### 响应拦截器
-`fetch` resolve 之后、body 解析之前检查 `Response`。
-```ts
-new UserApi({
-    baseUrl: "/api",
-    responseInterceptors: [
-        async (response, url) => {
-            if (response.status === 401) {
-                await refreshToken();
-                // 可选：throw 让你自己的代码触发重试
-            }
-            return response;
-        },
-    ],
-});
-```
-返回不同的 `Response` 可以替换响应（如 5xx 时走缓存）。
-### 动态添加拦截器
-```ts
-api.useRequestInterceptor((url, init) => {
-    init.headers = { ...init.headers, "X-Trace-Id": traceId };
-    return init;
-});
+浏览器可用绝对 API URL、所选 fetch 实现和 `validateDns: false` 构造同一个类，这表示明确交由浏览器解析 DNS。服务端缺少必需能力时，不应静默关闭校验。默认禁止内部或回环地址；确有需要时，由主机配置显式允许。
-api.useResponseInterceptor((resp) => {
-    metrics.recordLatency(resp.url, performance.now() - start);
-    return resp;
-});
-```
-用于构造时不知道的横切关注点。
-## 错误处理
-`HttpClient` 对非 2xx 响应抛 `HttpError`：
-```ts
-import { HttpError } from "@finesoft/front";
-try {
-    const user = await api.getById("missing");
-} catch (e) {
-    if (e instanceof HttpError) {
-        e.status; // 404
-        e.statusText; // "Not Found"
-        e.url; // "/api/users/missing"
-        e.body; // unknown —— 已解析的响应 body（如可解析）
-    }
-}
-```
-网络错误（DNS、连接被拒、abort）会以标准 `TypeError` / `DOMException` 形式抛出，不是 `HttpError`。需要都关心的话两个都 catch：
-```ts
-try {
-    await api.list();
-} catch (e) {
-    if (e instanceof HttpError) {
-        if (e.status >= 500) showRetryBanner();
-        else showInputError(e.body);
-    } else {
-        showOfflineBanner();
-    }
-}
-```
-## 服务端 vs 浏览器
-`HttpClient` 直接用 `fetch`，Node 22+ 原生支持。无需平台特定代码。
-浏览器端请求可以打：
-- 你的框架自己的 proxy 路由（`/api/*` → 通过 `proxies` 配置去上游）
-- 公网源直接（上游配好 CORS）
-服务端请求通常打：
-- 内网的内部服务
-- 直接打 proxy 上游（SSR 时跳过 proxy hop）
-如果你把 `/api` proxy 到 `https://upstream.example`，Controller 在 SSR 期间调 `api.get("/api/users")` 会走 proxy 再出网 —— 浪费。在服务端用 `baseUrl: process.env.UPSTREAM_URL`，在浏览器端用 `baseUrl: "/api"`，按 `framework.platform.isServer` 决定。
-## 重试
-框架不内置重试拦截器。自己包：
-```ts
-async function withRetry<T>(fn: () => Promise<T>, attempts = 3): Promise<T> {
-    for (let i = 0; i < attempts; i++) {
-        try {
-            return await fn();
-        } catch (e) {
-            if (i === attempts - 1) throw e;
-            if (e instanceof HttpError && e.status < 500) throw e; // 4xx 不重试
-            await new Promise((r) => setTimeout(r, 2 ** i * 200));
-        }
-    }
-    throw new Error("unreachable");
-}
-const user = await withRetry(() => api.getById(id));
-```
-作为外层包装而不是拦截器 —— 拦截器每次请求跑一次，重试逻辑需要重跑包括所有早期拦截器在内的整次请求。
-## Abort 和超时
-用 `AbortController`：
-```ts
-const controller = new AbortController();
-const timeout = setTimeout(() => controller.abort(), 5000);
-try {
-    const user = await api.getById(id, { signal: controller.signal });
-} finally {
-    clearTimeout(timeout);
-}
-```
-中途导航走的 Controller，把 controller 存起来并在 `fallback()` 清理或下次 dispatch 时 abort。
-## 发非 JSON body
-`post`/`put`/`patch` 默认 JSON 序列化 body，除非已经是 string、`FormData`、`URLSearchParams` 或 `Blob`：
-```ts
-// JSON（默认）
-api.post("/users", { name: "Alice" });
-// 表单
-const form = new FormData();
-form.append("file", file);
-api.post("/upload", form);
-// URL 编码
-api.post("/login", new URLSearchParams({ user: "alice", pass: "secret" }));
-// 原始文本
-api.post("/webhook", "raw payload", { headers: { "Content-Type": "text/plain" } });
-```
+Node 入口随包提供按需加载的连接传输实现，无需额外安装传输依赖。标准 Node/Vercel/Netlify 主机、开发和预览主机使用 `nodeSafeFetchOptions`：实际创建连接时查询并校验全部 DNS 地址，将同一结果交给 socket，保留主机名、TLS SNI、请求取消及连接复用。连接池按需加载，不进入浏览器或 Worker 模块。自定义 Node fetch 必须支持 Undici `dispatcher` 选项。单独使用 `nodeDnsLookup` 只做预检，不能防止查询与连接之间的 DNS 重绑定。
-客户端对对象自动设 `Content-Type: application/json`，`FormData` 不动头（让浏览器自己设 multipart 边界）。
+受保护的 fetch 逐跳校验重定向，最多跟随 20 次，跨源时移除认证和 Cookie 请求头。显式 `manual` / `error` 模式保持原意。浏览器不可读取的 opaque redirect 会拒绝；需要重发 body 的重定向不缓冲或重放 `Request.body` / 流式 body，请使用可重放的 `RequestInit.body`（如字符串）或最终 URL。`allowInternalHosts: true` 是完全退出这些保护的显式配置。
-## 下一步
+需要作用域业务服务时，声明类型化 provider，并通过 `context.get(token)` 获取，见[依赖注入](./07-di-container.md)。绑定本次调用的 fetch 和 signal，让请求能够接收取消信号。命令取消前可能已完成写入，取消不会回滚；操作运行时不会自动重试或缓存命令。
-- [DI 容器](./07-di-container.md) —— 注册 API 客户端，按请求 scope 化实例
-- [可观测性](./08-observability.md) —— 记录请求失败，监控里捕获
+请求和响应拦截器按注册顺序执行。`HttpError` 表示非成功 HTTP 结果。泛型返回类型描述预期数据；必要时应在业务边界校验不可信的响应内容。底层受保护方法为 `get`、`post`、`put`、`del` 和 `request`；`get` / `del` 的查询参数位于请求选项之前。