@finesoft/front 0.5.1 → 0.5.3

package/docs/zh/02-routing-and-controllers.md

@@ -1,314 +1,236 @@
-# 2. 路由与 Controller
+# 路由、控制器与类型化页面
 
-框架的路由层把 URL 映射到 **intent**，把 intent 映射到 **Controller**，Controller 产出 **Page**。本章覆盖这三个概念。
+六个模板均使用 `BaseController` 加载页面。它继续作为公开 API 提供；`definePage` 将控制器工厂或函数处理器接入 Web 应用，两种写法共用运行时、执行作用域和策略。
 
-## 心智模型
+## 各层职责
 
-```
-URL  ──Router.resolve()──▶  RouteMatch { intent, renderMode, guards }
-                                │
-                                ▼
-                       IntentDispatcher.dispatch(intent)
-                                │
-                                ▼
-                         Controller.execute()  →  Page
-```
+| API                               | 职责                                                              |
+| --------------------------------- | ----------------------------------------------------------------- |
+| `BaseController<TInput, TResult>` | 实现 `execute`，通过继承的 `perform` 处理参数、取消和 `fallback`  |
+| `definePage({ id, create })`      | 声明页面加载工厂，生成可复用的 `route`、`leaf` 和 `bindView` 引用 |
+| `defineWebApp`                    | 组装页面声明、路由、守卫及可选导航结构                            |
+| 原生页面组件                      | 接收 `page` 数据，渲染 UI 和处理交互                              |
 
-一条路由定义包含：
+控制器、页面、路由与公开数据声明统一从 `@finesoft/front` 导入。
 
-- **路径模式**（`/products/:id`）
-- **intent id**（操作的逻辑名；一个 intent 可以对应多条路由）
-- **Controller 实例**（产出页面数据）
-- 可选的**参数 codec**（`params` / `query`）—— 校验并类型化 URL 参数
-- 可选的**渲染模式**（`ssr` / `csr` / `prerender`）
-- 可选的**守卫**（`beforeLoad` / `afterLoad`）
+## 用 BaseController 加载页面
 
-## 定义路由
+`src/lib/controllers/product.ts`：
 
 ```ts
-// src/bootstrap.ts
-import { type Framework, defineRoutes } from "@finesoft/front";
-import { HomeController } from "./lib/controllers/home";
-import { ProductController } from "./lib/controllers/product";
-import { authGuard } from "./lib/guards/auth";
-
-export function bootstrap(framework: Framework): void {
-    defineRoutes(framework, [
-        // 普通 SSR 路由
-        { path: "/", intentId: "home", controller: new HomeController() },
-
-        // 动态参数段
-        { path: "/products/:id", intentId: "product", controller: new ProductController() },
-
-        // 仅 CSR（服务端只返回空壳）
-        {
-            path: "/dashboard",
-            intentId: "dashboard",
-            controller: new DashboardController(),
-            renderMode: "csr",
-        },
-
-        // 构建期静态化
-        {
-            path: "/about",
-            intentId: "about",
-            controller: new AboutController(),
-            renderMode: "prerender",
-        },
-
-        // 受保护路由 —— 复用 home intent，但加守卫
-        {
-            path: "/admin",
-            intentId: "home",
-            controller: new HomeController(),
-            beforeLoad: [authGuard],
-        },
-    ]);
-}
-```
-
-### 路由选项
-
-| 字段         | 类型                             | 说明                                                           |
-| ------------ | -------------------------------- | -------------------------------------------------------------- |
-| `path`       | `string`                         | 路径模式，含 `:param` 占位。结尾的 `/` 会被归一化。            |
-| `intentId`   | `string`                         | 操作的逻辑名。用于注册 Controller。                            |
-| `controller` | `BaseController<TParams, TPage>` | 若 intent 已注册可省略。                                       |
-| `params`     | codec map                        | 校验/转换 **path** 参数。key 必须出现在 `path` 中。见下文。    |
-| `query`      | codec map                        | 校验/转换 **query** 参数。key 开放。见下文。                   |
-| `renderMode` | `"ssr" \| "csr" \| "prerender"`  | 默认 `"ssr"`。详见[第 4 章](./04-rendering-and-hydration.md)。 |
-| `beforeLoad` | `BeforeLoadGuard[]`              | Controller 之前执行。详见[第 3 章](./03-middleware.md)。       |
-| `afterLoad`  | `AfterLoadGuard[]`               | Page 产出之后执行。                                            |
-
-### 路径模式
+import { BaseController, DEP_KEYS } from "@finesoft/front";
+import { markPublic, type BasePage } from "@finesoft/front";
 
-- 静态：`/about`
-- 带参数：`/products/:id`、`/users/:userId/posts/:postId`
-- 可选参数：`/blog/:slug?` 同时匹配 `/blog` 和 `/blog/hello`。
-
-默认情况下，path 和 query 参数以**字符串键对象**的形式进入 `controller.execute(params, container)`。挂上 codec（下一节）即可校验并转换它们。
-
-## 路由参数类型化
+export interface ProductPage extends BasePage {
+    pageType: "product";
+    product: { id: number; name: string };
+}
 
-codec 把原始字符串参数变成经校验、已转换、**编译期类型化**的值。内置原语零依赖覆盖常见场景；任意 [Standard Schema](https://standardschema.dev)（zod、valibot、arktype……）也能用。
+export class ProductController extends BaseController {
+    async execute({ params, context }): Promise<ProductPage> {
+        const logger = await context.get(DEP_KEYS.LOGGER_FACTORY);
+        logger.loggerFor("ProductController").info(`Loading product ${params.id}`);
+        context.record("product.load", { productId: params.id });
+
+        return markPublic(
+            {
+                id: String(params.id),
+                pageType: "product",
+                title: `Product ${params.id}`,
+                product: { id: params.id, name: `Product ${params.id}` },
+            },
+            { product: { id: true, name: true } },
+        );
+    }
 
-```ts
-import { defineRoutes, int, list, oneOf, optional, str, withDefault } from "@finesoft/front";
-
-defineRoutes(framework, [
-    {
-        path: "/products/:id",
-        intentId: "product",
-        controller: new ProductController(),
-        params: { id: int({ min: 1 }) }, // :id 校验为正整数，转换为 number
-        query: {
-            page: withDefault(int({ min: 1 }), 1), // ?page= → number，缺失时默认 1
-            sort: optional(oneOf(["asc", "desc"] as const)), // 可选的 "asc" | "desc"
-            tags: list(str()), // ?tags=a&tags=b → string[]
-        },
-    },
-]);
+    override fallback({ params }): ProductPage {
+        return markPublic(
+            {
+                id: String(params.id),
+                pageType: "product",
+                title: "Product unavailable",
+                product: { id: params.id, name: "Unavailable" },
+            },
+            { product: { id: true, name: true } },
+        );
+    }
+}
 ```
 
-### 内置 codec
-
-| codec                   | 输出       | 校验                                              |
-| ----------------------- | ---------- | ------------------------------------------------- |
-| `str(opts?)`            | `string`   | `minLength` / `maxLength` / `pattern`（`RegExp`） |
-| `int(opts?)`            | `number`   | 整数 + `min` / `max`                              |
-| `num(opts?)`            | `number`   | 有限数 + `min` / `max`                            |
-| `bool()`                | `boolean`  | `"true" \| "1" \| "false" \| "0"`                 |
-| `oneOf([...] as const)` | 字面量联合 | 成员检查                                          |
-| `uuid()`                | `string`   | UUID v1–v5                                        |
-| `list(item, opts?)`     | `T[]`      | 多值 query；每项过 `item` + `min`/`max` 个数      |
-
-修饰器包裹 codec（codec 保持可序列化纯数据，不用链式 `.optional()`）：
+框架根据下方路由声明维护类型导入、方法注解和基类泛型；这里展示首次编写时的源码，省略自动生成的引用。运行 `vp dev`、`vp check` 或构建即可生成。类型集中在 `.finesoft/controller-types.d.ts`，Controller 文件末尾不再追加声明区块。配置方式见[控制器类型自动关联](./11-navigation.md)。
 
-- `optional(codec)` —— 输入缺失 → `undefined`；把该 key 渲染为**可选属性**（`page?: T`）。
-- `withDefault(codec, fallback)` —— 输入缺失 → `fallback`；key 保持必选。
+两个方法统一接收一个对象：`execute({ params, query, context })` 和 `fallback({ params, query, context, error })`，只解构需要的字段即可。Query 与路径参数分开，根据路由中的 `query` 声明推断类型。
 
-### 校验失败 = fall-through 到 404
+这个示例使用本地数据；实际业务可以在 `execute` 中调用服务。`context` 提供当前执行的 `signal`、`fetch`、`get(token)` 和 `execute(operation, input)`。执行异步请求时，将 `context.signal` 传给请求 API，取消才能传递到实际工作。
 
-codec 校验失败意味着该路由**不匹配** —— 路由器继续尝试下一条，全不中时落到既有 404。**没有**单独的 `400` 通道。这让重叠路由可以按类型消歧：
-
-```ts
-defineRoutes(framework, [
-    { path: "/item/:id", intentId: "item-by-id", controller, params: { id: int() } },
-    { path: "/item/:slug", intentId: "item-by-slug", controller, params: { slug: str() } },
-]);
-// /item/42    → item-by-id   （int 匹配）
-// /item/hello → item-by-slug （int 拒绝 → fall-through 到 str）
-```
+`fallback` 仅在 `execute` 发生普通异常时调用，返回类型仍是 `ProductPage`；示例选择展示不可用状态。未覆写时默认重新抛出错误，交给页面加载流程的错误处理。取消、`AbortError` 和 `ExecutionError("cancelled")` 会继续抛出，不进入 `fallback`。运行时策略在控制器外执行，策略拒绝也不会由控制器回退处理。
 
-### 编译期参数类型
+## 注册工厂、路由与导航目标
 
-`InferParams` / `InferQuery` 直接从 codec 对象推导 Controller 的参数类型 —— 无需手写、也不必和路由保持同步：
+`src/app-definition.ts`：
 
 ```ts
-import {
-    BaseController,
-    type InferParams,
-    type InferQuery,
-    int,
-    oneOf,
-    optional,
-} from "@finesoft/front";
+import { int } from "@finesoft/front";
+import { definePage, defineWebApp } from "@finesoft/front";
+import { ProductController } from "./lib/controllers/product";
 
-const params = { id: int() };
-const query = { sort: optional(oneOf(["asc", "desc"] as const)) };
+export const product = definePage({
+    id: "load-product",
+    create: () => new ProductController(),
+    routes: [{ path: "/products/:id", params: { id: int() } }],
+});
+export const target = product.leaf({ id: 42 });
 
-class ProductController extends BaseController<
-    InferParams<typeof params> & InferQuery<typeof query>, // { id: number; sort?: "asc" | "desc" }
-    ProductPage
-> {
-    readonly intentId = "product";
-    execute(params) {
-        // params.id: number, params.sort: "asc" | "desc" | undefined
-    }
-}
+export const app = defineWebApp({
+    id: "example",
+    pages: [product],
+    getErrorPage: (status, message) => ({ id: String(status), pageType: "error", title: message }),
+});
 ```
 
-### `route()` —— 参数 key 安全
+页面声明拥有唯一操作标识，控制器不再重复声明 intentId。URL `/products/42` 经 `int()` 解码后，`execute` 收到 `params: { id: 42 }`；代码内的 `product.leaf({ id: 42 })` 保留同样的参数类型。
 
-数组对象形态本身已会检查 `params` 的每个 key 都出现在 `path` 中。`route(path, def)` helper 把同样的检查做成独立、可组合的条目：
+`create` 每次实际执行时返回新控制器。声明、路由发现及引用辅助方法只读取定义；命中已预取或保留的页面结果时也无需创建控制器。请求身份放在执行上下文或有作用域的 provider 中；页面草稿放在页面实例中。
 
-```ts
-route("/products/:id", { intentId: "product", params: { id: int() } }); // ✓
-route("/products/:id", { intentId: "product", params: { slug: str() } }); // ✗ 编译报错："slug" 不在 path 中
-```
+`id` 是操作标识，`pageType` 选择视图，每个叶子节点生成独立 EntryId。`product.bindView("product", ProductView)` 检查结果中的字面量页面类型，不从操作 id 推断类型。显式保留 `ProductPage.pageType: "product"` 才能获得该检查；宽泛的 `BasePage.pageType: string` 无法约束视图名称。
+
+类型化叶子参数保留控制器类型；外部 URL 仍需显式 codec 解码。泛型提供编译期类型约束，不替代运行期输入校验，也不会自动证明任意 codec 与业务校验规则等价。
 
-### `defineRoute()` —— 自动类型化的 handler
+## 简单页面的函数写法
 
-`defineRoute(path, def)` 接受一个 **handler** 函数而非 Controller 类，并从 codec 自动推导其入参类型 —— 无需 `InferParams`。它复刻 `BaseController` 的 `try/catch → fallback`：
+只需直接返回页面数据时，可以使用 `handler`。它也能通过执行上下文使用依赖、取消和嵌套操作；需要回退逻辑时，在函数内自行处理。`create` 和 `handler` 二选一。
 
 ```ts
-defineRoute("/products/:id", {
-    intentId: "product",
-    params: { id: int() },
-    query: { page: withDefault(int(), 1) },
-    handler: (params, container) => {
-        // params: { id: number; page: number } —— 从 codec 推导
-        return loadProduct(params.id, params.page);
-    },
-    fallback: (params, error) => errorPage(error), // 可选
+import { definePage, markPublic } from "@finesoft/front";
+
+export const home = definePage({
+    id: "load-home",
+    handler: () => markPublic({ id: "home", pageType: "home" as const, title: "Home" }, []),
 });
 ```
 
-没有 `params` / `query` 的路由行为完全不变 —— 参数保持字符串，运行时无变化。
-
-## 写一个 Controller
+模板采用控制器类来保持组织方式一致；函数形式适用于简短加载逻辑。既有函数处理器接收 `(params, context, query)`。继承基类是可选的，实现 `perform(params, context, query)` 契约也能由 `create` 工厂接入。
 
-```ts
-// src/lib/controllers/product.ts
-import { BaseController, type Container, type HttpClient } from "@finesoft/front";
-
-interface ProductPage {
-    kind: "product";
-    id: string;
-    name: string;
-    price: number;
-}
+## 服务端 Controller 与两种上下文
 
-export class ProductController extends BaseController<{ id: string }, ProductPage> {
-    readonly intentId = "product";
+需要机密、HttpOnly Cookie 或响应设置的页面使用 `@finesoft/front` 的 `BaseServerController`。方法仍然是 `execute({ params, query, context })` / `fallback({ params, query, context, error })`，路由仍通过 `definePage({ create, routes })` 注册。类型生成器识别基类并维护同样简短的 `Input` / `Failure` 引用，不需要第二套路由声明。
 
-    async execute(params: { id: string }, container: Container): Promise<ProductPage> {
-        const http = container.resolve<HttpClient>("http");
-        const product = await http.get<{ name: string; price: number }>(
-            `/api/products/${params.id}`,
+```ts
+import { BaseServerController } from "@finesoft/front";
+import { markPublic } from "@finesoft/front";
+import { loadAccount } from "./account-service";
+
+export class AccountController extends BaseServerController {
+    async execute({ params, context }) {
+        const account = await loadAccount(params.id, context.getCookie("session"));
+        context.responseHeaders.set("Cache-Control", "private, no-store");
+        return markPublic(
+            { id: String(params.id), pageType: "account", title: account.name, account },
+            { account: { id: true, name: true } },
         );
-        return {
-            kind: "product",
-            id: params.id,
-            name: product.name,
-            price: product.price,
-        };
-    }
-
-    fallback(params: { id: string }, _error: unknown): ProductPage {
-        return { kind: "product", id: params.id, name: "Not available", price: 0 };
     }
 }
 ```
 
-### Controller 契约
+示例省略框架自动维护的类型注解。`account-service` 是业务实现；Controller 可以放在任意业务目录。Vite 根据继承关系替换整个服务端 Controller 模块，浏览器获得调用代理；SSR 保留原实现并直接执行。客户端导航通过同站 `POST /__finesoft/controller` 加载公开页面数据，服务端重新解析路由、执行策略和守卫。首次水合使用已有 SSR 数据，不重复请求。
+
+| 能力                                                   | 共享 `BaseController` 的页面上下文     | `BaseServerController`              |
+| ------------------------------------------------------ | -------------------------------------- | ----------------------------------- |
+| `params`、`query`                                      | 独立输入，按路由推断                   | 相同                                |
+| `context.url`、`path`、`intent`、`isServer`            | 当前页面与执行位置                     | 相同，`isServer` 为 `true`          |
+| `getCookie(name)`                                      | 浏览器可读 Cookie；SSR 当前请求 Cookie | 读取原始请求 Cookie，包含 HttpOnly  |
+| `getHeader(name)`                                      | SSR 请求头；浏览器无服务端请求头       | 当前服务端请求头                    |
+| `get(token)`、`fetch`、`signal`、`execute`、日志和追踪 | 现有执行上下文                         | 相同                                |
+| `request`、`responseHeaders`                           | 无专用接口                             | 原始 `Request` 与最终响应头         |
+| `setCookie`、`deleteCookie`                            | 无专用接口                             | 写入最终响应，不改变原始请求 Cookie |
 
-| 成员       | 必需 | 用途                                                                        |
-| ---------- | ---- | --------------------------------------------------------------------------- |
-| `intentId` | 是   | 必须与路由的 `intentId` 一致（或与 `IntentDispatcher.register` 调用一致）。 |
-| `execute`  | 是   | 产出页面。接受解析后的路径参数和请求级 DI 容器。                            |
-| `fallback` | 是   | `execute()` 抛错时返回降级页面。必须同步且总能返回。                        |
+自动生成的页面 `Input` 使用 `ControllerContext` 或 `ServerControllerContext`。独立数据操作仍使用可移植的 `ExecutionContext`；直接执行 Page operation、没有导航时，`url` / `path` 为空。远程调用的 `request.url` 是传输端点地址，页面地址请使用 `context.url`。
 
-`BaseController` 把 `execute()` 包在 `try/catch` 里，错误都走 `fallback()`。框架从不让 `dispatch()` 抛错 —— 你的 `fallback()` 是最后一道防线。
+### 构建边界
 
-### 为什么 `fallback` 是必需的
+服务端 Controller 模块只导出 Controller 类和类型。该模块的本地运行时依赖也属于服务端边界；客户端直接导入这些依赖会报错。共享类型请使用 `import type`，共享的客户端实现放在独立模块。构造函数内的依赖创建属于受保护模块；不要在共享的 `create` 工厂参数、共享配置或页面组件中写入机密。
 
-SSR 期间 `execute()` 抛错本来会让整个请求崩 —— 要么 500，要么渲出空白文档。`fallback()` 让你返回一个结构化的「错误」`Page`，让视图层渲成优雅失败（banner、重试按钮等）。完整模式见 [可观测性 · 错误处理](./08-observability.md#通过-fallback-处理错误)。
+生产客户端 JS / source map 不包含被替换的实现。开发服务拒绝 Controller 的原始资源导入和受保护依赖的源码请求。模块与依赖索引在启动时建立，后续缓存 AST，只重新分析变更文件；开发期间已识别的私有依赖保持保护，若要将它迁回共享模块，应重启开发服务。动态计算的文件路径、`public/` 资源和另行复制的源码不属于静态导入边界。开发服务器仍只用于受信任的开发环境。
 
-## 渲染模式
+使用框架 Vite 插件及具有 SSR 请求处理能力的 Node / Worker 等宿主。纯静态托管没有远程执行端点。此入口用于注册的服务端页面 Controller，不会自动发布任意方法或代替登录、注册等命令端点。
 
-| 模式          | 服务端返回的内容                 | 适用场景                                    |
-| ------------- | -------------------------------- | ------------------------------------------- |
-| `"ssr"`       | 完整渲染的 HTML + 序列化数据     | 默认。SEO 和 TTFB 敏感的页面。              |
-| `"csr"`       | 空壳 HTML；Controller 在浏览器跑 | 鉴权后的 dashboard、高度个性化的页面。      |
-| `"prerender"` | 部署期生成的静态 HTML            | 营销页、文档、博客。结合 ISR（见第 4 章）。 |
+### 显式传递请求与响应信息
 
-模式是**按路由**配置，可以自由混合。框架在构建期重生成 prerendered 路由；SSR 路由每次请求都执行。
+框架提供 `request`、`getHeader`、`getCookie`、`fetch`、`responseHeaders`、`setCookie` 和 `deleteCookie` 等通用工具。登录状态、鉴权、令牌存储与刷新，以及凭据是否传递，均由业务代码决定。
 
-## 不绑路由也能注册 Controller
+服务端 `context.fetch` 只使用调用者提供的请求头，不会从外层请求自动继承 Cookie / Authorization，也不会把内部响应的 `Set-Cookie` 自动复制到页面响应。`credentials` 选项不会在服务端创建或启用 Cookie 存储。浏览器发起请求时，Cookie 仍遵循浏览器原生的同站请求规则。
 
-可以为 intent 注册 Controller 但不暴露成路由。这对只通过 `dispatchAction` 触发的 intent 有用：
+例如，业务选择给一个内部接口传递 Authorization，并将该接口返回的 Cookie 写入最终响应：
 
 ```ts
-framework.intentDispatcher.register("checkout", new CheckoutController());
+const headers = new Headers();
+const authorization = context.getHeader("authorization");
+if (authorization) headers.set("authorization", authorization);
 
-// 别处：
-const page = await framework.intentDispatcher.dispatch({
-    intentId: "checkout",
-    params: { cartId },
-});
+const response = await context.fetch("/api/account", { headers });
+for (const cookie of response.headers.getSetCookie()) {
+    context.responseHeaders.append("set-cookie", cookie);
+}
 ```
 
-路由本质上就是按 URL 索引的 intent dispatch。
-
-## 一个 intent 多个路由
+选择哪些请求头、哪些响应 Cookie、发给哪个接口，都是上面业务代码的决定。需要多处复用时，可放进业务 `HttpClient` 拦截器或请求作用域服务，通过 `context.get` 使用。
 
-同一个 intent 可以服务不同 URL：
+业务也可以直接构造响应 Cookie：
 
 ```ts
-defineRoutes(framework, [
-    { path: "/", intentId: "home", controller: new HomeController() },
-    { path: "/welcome", intentId: "home" }, // 复用已注册的 HomeController
-    { path: "/landing/:slug", intentId: "home" }, // 同 intent，参数不同
-]);
+context.setCookie("theme", "dark", { path: "/", sameSite: "Lax" });
+context.deleteCookie("theme", { path: "/" });
 ```
 
-避免只是 URL 表面不同就复制 Controller 实例。前面例子里 `/admin` 复用 `home` intent 也是同一个套路。
+`getCookie` 始终读取本次收到的请求；写响应 Cookie 不会修改它，也不会自动更新任何用户身份。后续业务逻辑需要新值时，使用业务自身保存的结果。`responseHeaders` 是显式响应写入工具；框架负责组装最终响应，包括错误响应中的业务响应头，同时保留框架错误正文类型及禁用缓存的约束。
 
-## 检查解析后的 match
+远程请求提供的 `context` / `bindings` 不会成为可信身份。`markPublic` 继续控制发给浏览器的数据字段，机密也不能直接渲染进 HTML。
 
-诊断或自定义路由时，可以直接调 `Router.resolve()`。它是**异步**的（codec 可能异步校验），需 `await`：
+## 独立业务操作也可以用控制器
+
+`BaseController` 的结果泛型不要求是页面。通过 `implementController` 将类绑定到操作后，可以在独立数据运行时执行；HTTP / Worker 入口也可以调用该操作。
 
 ```ts
-const match = await framework.router.resolve("/products/42");
-// {
-//   intent: { id: "product", params: { id: "42" } },
-//   action: { kind: "flow", url: "/products/42" },
-//   renderMode: "ssr",
-//   beforeGuards: [...],
-//   afterGuards: [...],
-// }
-```
+import {
+    BaseController,
+    createRuntime,
+    defineApp,
+    defineOperation,
+    implementController,
+    type ControllerInput,
+} from "@finesoft/front";
 
-未命中时 resolve 出 `null` —— 在服务端 404 逻辑里处理它。
+type TotalInput = { unitPrice: number; quantity: number };
+interface TotalResult {
+    total: number;
+}
 
-## 实时演示
+class TotalController extends BaseController<ControllerInput<TotalInput>, TotalResult> {
+    execute({ params }: ControllerInput<TotalInput>): TotalResult {
+        return { total: params.unitPrice * params.quantity };
+    }
+}
 
-下方注册了一个真实的 `Router` 实例（包含示例路由）。在左侧输入 URL，右侧实时显示 `Router.resolve()` 的 `RouteMatch` —— 与框架运行时走的是同一段代码。
+const calculateTotal = defineOperation<TotalInput, TotalResult>({
+    id: "calculate-total",
+    kind: "query",
+});
+const runtime = createRuntime({
+    app: defineApp({
+        id: "data-example",
+        operations: [calculateTotal],
+        implementations: [implementController(calculateTotal, () => new TotalController())],
+    }),
+});
 
-<Ch02RouteResolver />
+try {
+    const result = await runtime.execute(calculateTotal, { unitPrice: 29, quantity: 2 });
+    console.log(result); // { total: 58 }
+} finally {
+    await runtime.dispose();
+}
+```
 
-## 下一步
+操作声明定义输入输出契约，控制器负责实现。将操作暴露为 HTTP 接口仍需显式配置端点，注册控制器本身不会公开接口。
 
-- [中间件](./03-middleware.md) —— 守卫导航、重定向、拒绝
-- [渲染与 Hydration](./04-rendering-and-hydration.md) —— Controller 产出 Page 之后发生什么
+<Ch02RouteResolver />