@finesoft/front 0.5.1 → 0.5.3

package/docs/zh/07-di-container.md

@@ -1,264 +1,30 @@
-# 7. DI 容器
+# 依赖与资源归属
 
-框架用一个小型的依赖注入容器，支持父子 scope。它存在的两个理由：
-
-1. **服务端请求隔离** —— 每个 SSR 请求拿到自己的 scope，请求级状态（鉴权、request id）不跨请求泄漏。
-2. **解耦测试** —— Controller 从容器里 resolve 依赖，测试时可以任意 swap。
-
-容器有意保持很小。没有装饰器、没有注解、没有自动装配。注册工厂，按 key resolve。
-
-## 注册
-
-```ts
-import { Container } from "@finesoft/front";
-
-const container = new Container();
-
-container.register("userApi", () => new UserApi({ baseUrl: "/api" }));
-container.register("logger", () => new ConsoleLogger());
-```
-
-工厂默认**每个容器调用一次**。结果被缓存。
-
-要每次 resolve 都重新构造（非单例）：
-
-```ts
-container.register("requestId", () => crypto.randomUUID(), false);
-container.resolve("requestId"); // 每次都是新 id
-```
-
-## Resolve
-
-```ts
-const api = container.resolve<UserApi>("userApi");
-const logger = container.resolve<Logger>("logger");
-```
-
-泛型参数只对 TypeScript 生效 —— 运行时无类型检查。
-
-Resolve 未注册的 key 会抛错：
-
-```ts
-container.resolve("missing"); // Error: Dependency "missing" not registered
-```
-
-## Scope —— 核心特性
-
-```ts
-const requestScope = framework.container.createScope();
-requestScope.register("currentUser", () => loadUserFromSession(request));
-
-// scope 里没有的 key 回退到父容器：
-requestScope.resolve("userApi"); // 父
-requestScope.resolve("currentUser"); // scope
-
-requestScope.dispose();
-```
-
-子 scope：
-
-- **继承**所有父 key（resolve 时回退）
-- **覆盖**任意 key（注册自己的工厂）
-- `dispose()` 时**清理** —— 子 scope 递归 dispose；自己从父的 children 集合移除
-
-框架自动按 SSR 请求创建请求级容器，传给守卫和 Controller（作为 `ctx.container` / `execute()` 的第二个参数）。普通请求处理不需要你手动创建 scope。
-
-## 什么时候自己开 scope
-
-- 多租户应用，每个租户有自己的配置 / API 客户端（详见 [advanced/multi-tenant-scopes](./advanced/multi-tenant-scopes.md)）
-- 长跑操作需要自己的短期依赖
-- 测试时想在基础容器上叠加 override
-
-## Dispose 和泄漏
+在 app/runtime 声明类型化 provider。普通调用使用 runtime.execute，由它管理调用 scope。同调用中的 scope provider 共享初始化；runtime provider 生存至 runtime.dispose。transient 每次获取创建并登记清理。默认拥有创建值，传入值默认外部管理，除非 owned=true。异步初始化和释放按依赖顺序等待。runtime provider 不可捕获请求绑定。命名 Container 仍支持控制器依赖，新的异步服务使用 context.get(token)。
 
 ```ts
-const scope = container.createScope();
-// ... 使用 scope ...
-scope.dispose();
-```
-
-`dispose()`：
-
-1. 递归 dispose 任何未完成的子 scope
-2. 对工厂结果实现了 `destroy()` 的对象调用（logger、recorder）
-3. 自己从父的 children 集合移除
-4. 幂等 —— 调用两次安全
-
-**不 dispose 一个 scope 会泄漏里面每一个缓存值。** 请求 scope 活过响应就会持有：
-
-- HTTP 客户端（以及它们待发的请求状态）
-- Logger / recorder
-- Controller 在里面 resolve 过的任何东西
-
-框架处理它创建的请求 scope 的 dispose。**你**自己创建的 scope 你自己 dispose。
-
-忘记 dispose 的症状，见 [陷阱：container scope 泄漏](./pitfalls/container-scope-leak.md)。
-
-## 标准 DI key
-
-用 `DEP_KEYS` 常量而不是字符串字面量，能在类型检查时抓到拼写错误：
-
-```ts
-import { DEP_KEYS } from "@finesoft/front";
-
-container.register(DEP_KEYS.LOGGER, () => new ConsoleLogger());
-container.register(DEP_KEYS.EVENT_RECORDER, () => myRecorder);
-
-const logger = container.resolve(DEP_KEYS.LOGGER);
-```
-
-常量列表：
-
-| Key                       | 标准类型           | 用于                                  |
-| ------------------------- | ------------------ | ------------------------------------- |
-| `DEP_KEYS.LOGGER`         | `Logger`           | 框架日志                              |
-| `DEP_KEYS.LOGGER_FACTORY` | `LoggerFactory`    | 分类 logger（`logger.scope("auth")`） |
-| `DEP_KEYS.NET`            | `Net`              | 网络状态检查（离线 / 计费网络）       |
-| `DEP_KEYS.STORAGE`        | `Storage`          | KV 持久化（localStorage / 内存）      |
-| `DEP_KEYS.FEATURE_FLAGS`  | `FeatureFlags`     | Feature flag 读取                     |
-| `DEP_KEYS.METRICS`        | `MetricsClient`    | 计数器 / gauge / 计时                 |
-| `DEP_KEYS.FETCH`          | `typeof fetch`     | `HttpClient` 底层 fetch（可 mock）    |
-| `DEP_KEYS.EVENT_RECORDER` | `EventRecorder`    | 结构化事件记录                        |
-| `DEP_KEYS.LOCALE`         | `LocaleAttributes` | 解析出的 locale（lang + dir）         |
-| `DEP_KEYS.PLATFORM`       | `PlatformInfo`     | 检测到的 user-agent 平台信息          |
-| `DEP_KEYS.TRANSLATOR`     | `Translator`       | 翻译函数                              |
-
-框架在 `Framework.create()` 期间为这些 key 注册默认实现。要覆盖就在 framework 创建后再注册：
-
-```ts
-const framework = Framework.create({
-    /* ... */
+import { createToken, provide, defineApp, defineOperation, createRuntime } from "@finesoft/front";
+const tenant = createToken<string>("tenant");
+const who = defineOperation({
+    id: "who",
+    kind: "query",
+    handler: async (_: undefined, context) => context.get(tenant),
 });
-framework.container.register(DEP_KEYS.LOGGER, () => myCustomLogger);
-```
-
-## 自定义 key
-
-你自己的服务直接用字符串 key：
-
-```ts
-container.register("userApi", () => new UserApi({ baseUrl: "/api" }));
-container.register("session", () => new SessionService());
-container.register("featureBucketing", () => new BucketingService());
-```
-
-想让自己的 key 有类型安全，定义自己的常量 map：
-
-```ts
-// src/lib/di-keys.ts
-export const APP_KEYS = {
-    USER_API: "userApi",
-    SESSION: "session",
-    FEATURE_BUCKETING: "featureBucketing",
-} as const;
-
-// 使用
-container.register(APP_KEYS.USER_API, () => new UserApi({ baseUrl: "/api" }));
-const api = container.resolve<UserApi>(APP_KEYS.USER_API);
-```
-
-## 生命周期顺序
-
-```
-Framework.create({ ... })
-    │
-    ▼
-默认 DEP_KEYS 注册（logger、locale、platform、...）
-    │
-    ▼
-你的自定义注册（在 onBeforeStart 或 bootstrap 里）
-    │
-    ▼
-─── 每个请求 ──────────────────────────────────
-framework.container.createScope()      ← 请求 scope
-    │
-    ▼
-beforeLoad 守卫（ctx.container = scope）
-    │
-    ▼
-controller.execute(params, scope)
-    │
-    ▼
-afterLoad 守卫（ctx.container = scope）
-    │
-    ▼
-renderApp() / response
-    │
-    ▼
-scope.dispose()                        ← 框架清理
-```
-
-## 在测试中使用容器
-
-按 scope 层注入 mock：
-
-```ts
-import { Framework } from "@finesoft/front";
-
-const framework = Framework.create({
-    /* ... */
+const app = defineApp({
+    id: "example",
+    operations: [who],
+    providers: [
+        provide({
+            token: tenant,
+            lifetime: "scope",
+            create: ({ bindings }) => String(bindings.tenant),
+        }),
+    ],
 });
-const testScope = framework.container.createScope();
-testScope.register("userApi", () => mockUserApi);
-
-const controller = new UserListController();
-const page = await controller.execute({}, testScope);
-
-testScope.dispose();
-```
-
-完整模式见 [工程实践 · 测试](./engineering/testing.md)。
-
-## 反模式
-
-### 别在模块顶层 resolve
-
-```ts
-// 不好 —— import 时跑，在 framework.create() 之前
-const logger = container.resolve(DEP_KEYS.LOGGER);
-export function log(msg: string) {
-    logger.info(msg);
-}
-```
-
-这里能拿到的 `container` 不是请求 scope；你拿到的是父容器，丢失请求隔离。
-
-正确做法是在能访问 scope 的函数里 resolve：
-
-```ts
-export function logFromController(container: Container, msg: string) {
-    container.resolve<Logger>(DEP_KEYS.LOGGER).info(msg);
+const runtime = createRuntime({ app });
+try {
+    await runtime.execute(who, undefined, { bindings: { tenant: "one" } });
+} finally {
+    await runtime.dispose();
 }
 ```
-
-### dispose 后别留 scoped 实例的引用
-
-```ts
-// 不好
-let api: UserApi;
-beforeLoad: (ctx) => {
-    api = ctx.container.resolve("userApi");
-    return next();
-};
-// `api` 现在指向一个 scope 已 dispose 的实例
-```
-
-如果你需要跨请求共享状态，注册到父容器，不是请求 scope。
-
-### 别在守卫里注册
-
-```ts
-// 不好 —— 每个请求都跑
-beforeLoad: (ctx) => {
-    ctx.container.register("userApi", () => new UserApi(/*...*/));
-    return next();
-};
-```
-
-每次请求都新建一个工厂闭包。在 framework 启动时注册一次；scope 会继承。
-
-## 下一步
-
-- [可观测性](./08-observability.md) —— 通过 DI 接 Logger / EventRecorder / ReportCallback
-- [工程实践：测试](./engineering/testing.md) —— 用 scope 隔离测试
-- [陷阱：container scope 泄漏](./pitfalls/container-scope-leak.md) —— 忘记 dispose 时会发生什么

package/docs/zh/08-observability.md

@@ -1,287 +1,10 @@
-# 8. 可观测性
+# 可观测性
 
-三个原语，各自可组合、可替换：
-
-- **`Logger`** —— 行式（debug/info/warn/error）
-- **`EventRecorder`** —— 结构化事件记录（`{ name, fields }`）
-- **`ReportCallback`** —— 把 `warn`/`error` 日志 fan-out 到外部监控
-
-外加通过 `IntersectionImpressionObserver` 做 impression 追踪。
-
-## Logger
-
-基础的 `ConsoleLogger` 把日志写到 `console.{debug,info,warn,error}`，带分类前缀。Scope 化 logger 加嵌套前缀。
-
-```ts
-import { ConsoleLogger } from "@finesoft/front";
-
-const logger = new ConsoleLogger("app");
-logger.info("hello"); // [app] hello
-
-const auth = logger.scope("auth");
-auth.warn("token expired"); // [app:auth] token expired
-```
-
-级别：`debug`、`info`、`warn`、`error`。框架对内部失败（守卫失败、dispatch 错误）会在自己的 logger 上调 `warn`/`error`。
-
-### 替换框架 logger
+可移植结构化事件使用 runtime recorder。Web 日志配置放在 app.configuration，不为注册诊断再创建框架实例。ReportingLoggerFactory 可通过业务回调转发警告/错误。公开诊断不能带私有输入、凭据或任意上游错误。浏览器曝光观察使用浏览器入口。
 
 ```ts
-import { DEP_KEYS } from "@finesoft/front";
-
-framework.container.register(DEP_KEYS.LOGGER, () => myLogger);
-framework.container.register(DEP_KEYS.LOGGER_FACTORY, () => ({
-    create(category) {
-        return myLoggerImpl.scope(category);
-    },
-}));
+import { ConsoleEventRecorder, createRuntime } from "@finesoft/front";
+const runtime = createRuntime({ app, recorder: new ConsoleEventRecorder() });
+// In an operation: context.record("checkout.completed", { itemCount: 2 });
+// In defineWebApp: configuration: { eventRecorder: recorder, reportCallback }
 ```
-
-## `ReportCallback` —— 把日志转发到监控
-
-把 `warn`/`error` 日志送到 Sentry / Datadog / 自家收集器最干净的方式：
-
-```ts
-import { Framework, type ReportCallback } from "@finesoft/front";
-
-const reportCallback: ReportCallback = (level, category, args) => {
-    Sentry.captureMessage(`[${category}] ${args.join(" ")}`, level);
-};
-
-const framework = Framework.create({
-    reportCallback,
-    // ...
-});
-```
-
-工作原理：
-
-- `Framework.create({ reportCallback })` 在 `ConsoleLogger` 上装 `ReportingLoggerFactory`
-- 所有 `logger.warn(...)` 和 `logger.error(...)` 调用都触发回调**并且**继续走 console
-- `debug` 和 `info` 不转发（避免在量里淹没信号）
-- 回调在 `try/catch` 里跑 —— reporter 失败不会让框架崩
-
-### 分类
-
-每个 `logger.scope("auth")` 变成传给回调的 category。用它们在监控系统里做路由：
-
-```ts
-reportCallback(level, category, args) {
-    if (category.startsWith("auth")) {
-        sentry.captureMessage(/* 送到 auth 项目 */);
-    } else {
-        sentry.captureMessage(/* 默认项目 */);
-    }
-}
-```
-
-### 反爆量
-
-`ReportCallback` 每次都跑。如果你有热循环重复打同一条告警一千次，你会发出一千个 event。在回调里加去重：
-
-```ts
-const seen = new Map<string, number>();
-const reportCallback: ReportCallback = (level, category, args) => {
-    const key = `${category}:${args[0]}`;
-    const now = Date.now();
-    const last = seen.get(key) ?? 0;
-    if (now - last < 60_000) return; // 每个 (category, message) 每分钟最多 1 次
-    seen.set(key, now);
-    Sentry.captureMessage(/* ... */);
-};
-```
-
-## `EventRecorder` —— 结构化事件
-
-要带字段的事件而不是自由文本日志时用 `EventRecorder`。
-
-```ts
-import { Framework, ConsoleEventRecorder, type EventRecorder } from "@finesoft/front";
-
-const recorder: EventRecorder = new ConsoleEventRecorder();
-const framework = Framework.create({ eventRecorder: recorder });
-
-// 任意位置：
-recorder.record({
-    name: "PageView",
-    fields: { url: "/products/42", referrer: "/search?q=widget" },
-});
-```
-
-### 内置事件
-
-框架通过 `framework.didEnterPage(page)` 自动记录 `PageView`。每次导航成功（SSR + CSR）都触发，字段：`{ intentId, url, renderMode }`。
-
-### 组合 recorder
-
-`CompositeEventRecorder` 把事件分发给多个 sink：
-
-```ts
-import { ConsoleEventRecorder, CompositeEventRecorder } from "@finesoft/front";
-
-const recorder = new CompositeEventRecorder([
-    new ConsoleEventRecorder(), // dev 可见性
-    productionAnalyticsRecorder, // 上送后端
-]);
-```
-
-一个 recorder 抛错时其他仍然收到事件。
-
-### 添加公共字段
-
-`WithFieldsRecorder` 装饰另一个 recorder，给每个事件前置字段：
-
-```ts
-import { WithFieldsRecorder, ConsoleEventRecorder } from "@finesoft/front";
-
-const recorder = new WithFieldsRecorder(new ConsoleEventRecorder(), [
-    { getFields: () => ({ app: "myApp", version: "1.0.0" }) },
-    { getFields: () => ({ userId: getCurrentUserId() }) },
-]);
-
-recorder.record({ name: "Click", fields: { id: "buy" } });
-// → { app, version, userId, id }
-```
-
-适用于不想在每次 `record()` 调用里重复的 session 级字段。
-
-### 写自己的 recorder
-
-实现 `EventRecorder` 接口：
-
-```ts
-import type { EventRecorder, EventRecord } from "@finesoft/front";
-
-class HttpEventRecorder implements EventRecorder {
-    constructor(private endpoint: string) {}
-    record(event: EventRecord): void {
-        // fire-and-forget；不要 await —— record() 不该阻塞 UI
-        navigator.sendBeacon(this.endpoint, JSON.stringify(event));
-    }
-    destroy(): void {
-        // flush、关闭连接等
-    }
-}
-```
-
-批处理、重试、生命周期处理见 [高阶 · 自定义 event recorder](./advanced/custom-event-recorder.md)。
-
-## Impression 追踪
-
-通过 `IntersectionObserver` 跟踪元素进入视口：
-
-```ts
-import { IntersectionImpressionObserver, type EventRecorder } from "@finesoft/front";
-
-const observer = new IntersectionImpressionObserver((entries) => {
-    for (const entry of entries) {
-        recorder.record({
-            name: "Impression",
-            fields: { id: entry.id, ...entry.metadata },
-        });
-    }
-});
-
-// 元素挂载时绑定
-observer.observe(productCardElement, "product-card-123", {
-    category: "featured",
-    position: 3,
-});
-
-// 元素卸载时解绑
-observer.unobserve(productCardElement);
-
-// 应用 teardown 时
-observer.destroy();
-```
-
-observer 对每个元素每次可见性变化触发一次回调。它不会跨 observe/unobserve 循环去重 —— 你的回调决定是否再次记录。
-
-## 通过 `fallback` 处理错误
-
-Controller 错误会自动变成记录的事件：
-
-```ts
-class HomeController extends BaseController<{}, HomePage> {
-    readonly intentId = "home";
-
-    async execute(_params, container) {
-        const api = container.resolve<UserApi>("userApi");
-        return { kind: "home", users: await api.list() };
-    }
-
-    fallback(_params, error) {
-        // 1. 框架通过自己的 logger 记录错误（→ reportCallback）
-        // 2. 你返回降级页面
-        return { kind: "home", users: [], degraded: true };
-    }
-}
-```
-
-错误时的操作顺序：
-
-1. `execute()` 抛错。
-2. `BaseController` catch 之后调 `framework.logger.error("[controller:home]", error)`。
-3. Logger 触发 `reportCallback("error", "controller:home", [error])` → Sentry。
-4. `fallback()` 返回你设计的 `Page`。
-5. 渲染继续，用 fallback 页面（默认 HTTP 200）。
-
-要返回非 200 状态码，让 page 带「错误」标记，在 `afterLoad` 守卫里检查：
-
-```ts
-afterLoad: [
-    (ctx) => {
-        if ("degraded" in ctx.page && ctx.page.degraded) {
-            return deny(503, "Service degraded");
-        }
-        return next();
-    },
-],
-```
-
-## 指标（计数器 / gauge / 计时）
-
-框架的 `MetricsClient` 是最小的：
-
-```ts
-import { DEP_KEYS } from "@finesoft/front";
-
-const metrics = framework.container.resolve(DEP_KEYS.METRICS);
-
-metrics.increment("requests.total");
-metrics.increment("login.failed", { reason: "wrong_password" });
-metrics.gauge("queue.depth", 17);
-metrics.timing("render.duration", 142);
-```
-
-默认实现是 no-op。注册自己的：
-
-```ts
-framework.container.register(DEP_KEYS.METRICS, () => new StatsdMetrics(/* ... */));
-```
-
-大多数应用 `EventRecorder` 就够 —— 你的分析后端已经把事件聚合成指标了。
-
-## Trace ID 和请求关联
-
-常见模式：给每个日志和事件打上请求级 trace id。
-
-```ts
-// beforeLoad 守卫
-function traceIdGuard(ctx) {
-    const traceId = ctx.getHeader("x-request-id") ?? crypto.randomUUID();
-    ctx.container.register("traceId", () => traceId);
-    ctx.container.register(
-        DEP_KEYS.EVENT_RECORDER,
-        () => new WithFieldsRecorder(baseRecorder, [{ getFields: () => ({ traceId }) }]),
-    );
-    return next();
-}
-```
-
-通过 `WithFieldsRecorder` 注册 scope 化的 recorder，让本请求里每个事件自动带 trace id。
-
-## 下一步
-
-- [服务器与部署](./09-server-and-deployment.md) —— 这些原语在 HTTP 层是怎么用的
-- [高阶 · 自定义 event recorder](./advanced/custom-event-recorder.md) —— 生产级实现