npm - @finesoft/front - Versions diffs - 0.1.76 → 0.1.78 - Mend

@finesoft/front 0.1.76 → 0.1.78

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 (51) hide show

package/docs/01-getting-started.md +230 -0
package/docs/02-routing-and-controllers.md +203 -0
package/docs/03-middleware.md +220 -0
package/docs/04-rendering-and-hydration.md +271 -0
package/docs/05-i18n.md +243 -0
package/docs/06-http-client.md +286 -0
package/docs/07-di-container.md +264 -0
package/docs/08-observability.md +290 -0
package/docs/09-server-and-deployment.md +242 -0
package/docs/10-features-platform-pwa.md +238 -0
package/docs/README.md +72 -0
package/docs/advanced/custom-action-handler.md +248 -0
package/docs/advanced/custom-adapter.md +264 -0
package/docs/advanced/custom-event-recorder.md +318 -0
package/docs/advanced/inline-proxy-codegen.md +200 -0
package/docs/advanced/multi-tenant-scopes.md +330 -0
package/docs/engineering/ci-release-flow.md +244 -0
package/docs/engineering/project-structure.md +296 -0
package/docs/engineering/testing.md +317 -0
package/docs/pitfalls/container-scope-leak.md +215 -0
package/docs/pitfalls/i18n-bundle-size.md +182 -0
package/docs/pitfalls/proxy-binary-payloads.md +133 -0
package/docs/pitfalls/redirect-vs-rewrite.md +147 -0
package/docs/pitfalls/ssr-hydration-mismatch.md +163 -0
package/docs/pitfalls/ssr-vs-csr-globals.md +176 -0
package/docs/zh/01-getting-started.md +230 -0
package/docs/zh/02-routing-and-controllers.md +203 -0
package/docs/zh/03-middleware.md +220 -0
package/docs/zh/04-rendering-and-hydration.md +271 -0
package/docs/zh/05-i18n.md +243 -0
package/docs/zh/06-http-client.md +286 -0
package/docs/zh/07-di-container.md +264 -0
package/docs/zh/08-observability.md +287 -0
package/docs/zh/09-server-and-deployment.md +242 -0
package/docs/zh/10-features-platform-pwa.md +238 -0
package/docs/zh/README.md +72 -0
package/docs/zh/advanced/custom-action-handler.md +248 -0
package/docs/zh/advanced/custom-adapter.md +264 -0
package/docs/zh/advanced/custom-event-recorder.md +318 -0
package/docs/zh/advanced/inline-proxy-codegen.md +200 -0
package/docs/zh/advanced/multi-tenant-scopes.md +330 -0
package/docs/zh/engineering/ci-release-flow.md +244 -0
package/docs/zh/engineering/project-structure.md +296 -0
package/docs/zh/engineering/testing.md +317 -0
package/docs/zh/pitfalls/container-scope-leak.md +215 -0
package/docs/zh/pitfalls/i18n-bundle-size.md +182 -0
package/docs/zh/pitfalls/proxy-binary-payloads.md +133 -0
package/docs/zh/pitfalls/redirect-vs-rewrite.md +147 -0
package/docs/zh/pitfalls/ssr-hydration-mismatch.md +163 -0
package/docs/zh/pitfalls/ssr-vs-csr-globals.md +176 -0
package/package.json +2 -1

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

@@ -0,0 +1,243 @@
+# 5. 国际化
+框架处理四个 i18n 关注点：
+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`：
+```ts
+createSSRRender({
+    bootstrap,
+    async loadMessages(locale) {
+        const resp = await fetch(`https://cdn.example.com/i18n/${locale}.json`);
+        return resp.json();
+    },
+    async renderApp(page) {
+        /* ... */
+    },
+});
+```
+这**覆盖** 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) —— 把翻译留在关键路径之外

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

@@ -0,0 +1,286 @@
+# 6. HTTP 客户端
+`HttpClient` 是 `fetch` 之上的薄层、强类型包装，给你：
+- 面向类的子类化，便于组织 API 表面
+- 请求/响应拦截器：鉴权、日志、重试
+- 结构化的 `HttpError` 替代不透明的 reject
+- 大小写不敏感的头处理，与 `Response.headers.get()` 语义一致
+它**不是** axios 的替代。它是为框架需求设计的小而锋利的工具。
+## 子类化
+预期用法是按每个逻辑 API 表面子类化：
+```ts
+import { HttpClient } 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");
+    }
+    async getById(id: string): Promise<User> {
+        return this.get<User>(`/users/${id}`);
+    }
+    async create(data: NewUser): Promise<User> {
+        return this.post<User>("/users", data);
+    }
+    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}`);
+    }
+}
+```
+每个子类实例绑定一个 `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 };
+}
+```
+## 方法
+| 方法                              | 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.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" } });
+```
+客户端对对象自动设 `Content-Type: application/json`，`FormData` 不动头（让浏览器自己设 multipart 边界）。
+## 下一步
+- [DI 容器](./07-di-container.md) —— 注册 API 客户端，按请求 scope 化实例
+- [可观测性](./08-observability.md) —— 记录请求失败，监控里捕获