Topcoat Runtime 实战指南:用 Rust 编写信号、事件与分片式交互

原创2026-11-11 19:28:531,421 阅读
文章标签:后端Web框架前端

Topcoat Runtime 实战指南:用 Rust 编写信号、事件与分片式交互

Topcoat 的 runtime 让服务端渲染的页面具备浏览器端的交互能力:状态、表达式与事件处理都写在 Rust 代码里,运行时会把这些逻辑编译成 JavaScript 一并下发给页面。本文以官方 runtime 文档为骨架,结合 crates/topcoat-runtime 的源码实现与 examples/runtime 示例,逐层拆解 script()、RuntimeLayer、$(...) 表达式、signal、事件处理器、bind 属性、procedure 与 shard 的完整用法与底层机制。

需要注意:该 runtime 目前处于高度实验性阶段(文档原文为 "highly experimental")。表达式只支持 Rust 的一个子集类型与运算,API 可能发生变化。本文涉及的行为均以当前仓库代码为准。

一、整体架构:页面如何在浏览器与服务器之间往返

理解 runtime 之前,先把三条链路分清楚,它们分别对应文档中的不同章节:

链路 触发方式 服务端参与 典型用途
纯浏览器更新 $(...) 读取 signal 变化 否 计数器、折叠面板、输入框联动
页面重渲染(page rerun) RuntimeLayer 把 POST 改写为 GET 是,整页 + 布局重新渲染 需要服务端数据的列表、排序
局部重渲染(shard) 独立 HTTP 端点,POST 参数与信号值 是,仅 shard 自身 搜索建议、分页列表
服务端调用(procedure) 表达式内 .await 一次 HTTP 调用 是,执行单个异步函数 写数据库、提交订单

从 crates/topcoat-runtime/src/lib.rs 可以看到模块划分:signal、expr、bind_attribute、event_handler、js 始终可用;而 layer、procedure、shard、shard_scope 由 router feature 控制。也就是说,只要不引入 topcoat-router,你依然可以使用纯浏览器侧的表达式与信号,但无法使用页面重渲染、procedure 和 shard。

// crates/topcoat-runtime/src/lib.rs(节选)
#[cfg(feature = "router")]
mod layer;
#[cfg(feature = "router")]
mod procedure;
#[cfg(feature = "router")]
mod shard;
#[cfg(feature = "router")]
mod shard_scope;

pub const SCRIPT: Asset = asset!("browser/dist/index.js", rename: "topcoat");

SCRIPT 是浏览器脚本的静态资源常量,由 topcoat-asset-macro 在编译期打包,重命名为 topcoat。script() 组件渲染的 <script> 标签正是引用它。

二、环境搭建:script、asset bundle 与 RuntimeLayer

2.1 在文档 head 中渲染脚本标签

交互页面必须加载 runtime 的浏览器脚本。script() 负责渲染这个 <script>,应放入文档的 <head>:

use topcoat::{Result, context::Cx, view::*};

#[component]
async fn document(cx: &Cx) -> Result<impl View> {
    Ok(view! {
        <html>
            <head>
                topcoat::runtime::script()
            </head>
            <body></body>
        </html>
    })
}

script() 并不是一个静态字符串拼接函数,它内部会检查请求上下文里是否存在 RuntimeSetup 标记:

// crates/topcoat/src/runtime.rs
pub async fn script(cx: &Cx) -> topcoat::Result<impl topcoat::view::View> {
    assert!(
        topcoat::context::try_context::<RuntimeSetup>(cx).is_some(),
        "the browser runtime is not set up on this router; add `.layer(RuntimeLayer::new())` to \
         the router builder",
    );
    Ok(topcoat::view::view! {
        <script
            type="module"
            src=(topcoat::runtime::SCRIPT)
            data-topcoat-usize-bits=(usize::BITS)
        ></script>
    })
}

这带来两个实用结论:

  1. 忘记挂载 RuntimeLayer 时,页面会在渲染阶段直接 panic,并给出明确提示,而不是在浏览器里悄无声息地失效。
  2. 脚本标签上的 data-topcoat-usize-bits 会把服务端 usize::BITS 传给浏览器。浏览器运行时据此对齐指针宽度整数的运算语义——这也是后文“整数在浏览器中保持完整精度”的实现基础。

2.2 挂载 RuntimeLayer 与 asset bundle

要启用页面重渲染,需要添加 RuntimeLayer,并加载 asset bundle 以提供浏览器脚本。应用层的注册顺序必须早于 runtime 层:

use topcoat::{
    asset::{AssetBundle, RouterBuilderAssetExt},
    router::{Router, RouterBuilderDiscoverExt, module_router},
    runtime::RuntimeLayer,
};

pub fn router() -> Router {
    module_router!()
        .discover()
        .assets(AssetBundle::load().unwrap())
        .layer(RuntimeLayer::new())
        .build()
}

文档给出了这条规则的原因:runtime 通过把浏览器上报的当前信号值发往页面 URL 来重跑页面,RuntimeLayer 会把该请求转换为 GET,从而让页面及其布局以这些值重新渲染。先注册你自己的层,它们才能以 GET 的身份处理这次重跑。

RuntimeLayer::path() 返回 None,说明它是一个"无路径层",作用于所有路径上的请求,而不是某个 prefix:

impl Layer for RuntimeLayer {
    fn path(&self) -> Option<&Path> {
        None
    }

    fn handle<'a>(&'a self, cx: &'a Cx, body: Body, next: Next<'a>) -> LayerFuture<'a> {
        #[cfg(not(target_family = "wasm"))]
        if socket::requested(cx) {
            return Box::pin(socket::accept(cx, body, self.max_runs_per_connection));
        }
        if rerun::requested(cx) {
            return Box::pin(rerun::dispatch(cx, body));
        }
        let cx = cx.with(RuntimeSetup);
        Box::pin(async move { next.run(&cx, body).await })
    }
}

处理流程可以概括为三步:命中 WebSocket 协议则进入连接模式;命中了重跑标记则改写请求;其余请求原样放行,只是给上下文加上 RuntimeSetup。

2.3 路由注册:module_router 与 discover

module_router!() 从模块树注册页面。.discover() 会额外注册应用中的 procedure 与 shard。若要显式注册某个 procedure 或 shard,把它的名字传给 .route()。

examples/runtime/src/main.rs 是一个可直接运行的最小完整配置:

#[tokio::main]
async fn main() {
    topcoat::start(
        module_router!()
            .assets(AssetBundle::load().unwrap())
            .discover()
            .layer(RuntimeLayer::new())
            .build(),
    )
    .await
    .unwrap();
}

配套的布局中同时引入开发脚本与 runtime 脚本,并用 link 组件做无整页刷新的导航:

#[layout]
async fn layout(cx: &Cx, slot: Slot<'_>) -> Result<impl View> {
    Ok(view! {
        <!DOCTYPE html>
        <html>
            <head>
                topcoat::dev::script()
                topcoat::runtime::script()
            </head>
            <body>
                <nav>
                    link(href: href!(counter::page), "counter")
                    " | "
                    link(href: href!(shard::page), "shard")
                </nav>
                (slot)
            </body>
        </html>
    })
}

三、RuntimeLayer 的请求协议与并发限额

原始文档只提到"见 RuntimeLayer 了解请求格式与改写行为"。源码把这个协议写得很清楚,值得展开,因为在调试反向代理、CSRF 策略或自定义中间件时这些细节会直接影响行为。

3.1 HTTP 重跑:POST 改写为 GET

浏览器侧发起重跑时发送一个带标记的 POST:

  • 方法:POST
  • 请求头:X-Topcoat-Runtime: true(常量 RUNTIME_HEADER)
  • 请求体:JSON,形如 {"signals": { "<signal-id>": <value> }}

RuntimeLayer 检测条件如下:

// crates/topcoat-runtime/src/layer/rerun.rs
pub(super) fn requested(cx: &Cx) -> bool {
    *method(cx) == Method::POST && headers(cx).get(&RUNTIME_HEADER) == Some(&RERUN)
}

派发时,它去掉描述"信封"本身的头,把请求改写为同路径、同查询串的 GET,并把信号值注入上下文:

pub(super) async fn dispatch(cx: &Cx, body: Body) -> Result<Response> {
    let Json(request) = Json::<PageRerunRequest>::from_request(cx, body).await?;

    let mut headers = headers(cx).clone();
    headers.remove(&RUNTIME_HEADER);
    headers.remove(header::CONTENT_TYPE);
    headers.remove(header::CONTENT_LENGTH);

    let uri = uri(cx);
    let target = uri
        .path_and_query()
        .map_or(uri.path(), |path_and_query| path_and_query.as_str());
    Err(rewrite(target, Body::empty())
        .method(Method::GET)
        .headers(headers)
        .with(request.signals)
        .into())
}

改写后的请求有三个特征:请求体为空、不再携带 X-Topcoat-Runtime / Content-Type / Content-Length。因此页面里如果检查 method(cx),拿到的是 GET;如果还想知道原始方法,用 topcoat_router::request::original_method(original_uri 同理)。

crates/topcoat-runtime/macro/tests/page_rerun.rs 用一系列集成测试把这些约束固化下来,可作为行为参考:

测试 断言的行为
a_rerun_runs_the_page_as_a_get_for_its_own_url method 为 GET,original_method 为 POST
a_rerun_runs_the_page_layouts 布局也会参与重渲染
a_rerun_drops_the_headers_describing_its_envelope content-type 读出来是 none
a_rerun_resumes_the_page_signals_from_the_values_it_carries 信号值被恢复,signal id 保持不变
a_rerun_of_an_unknown_page_is_not_found 未知路径返回 404
a_rerun_needs_a_json_body 缺少 JSON body 返回 400
an_unmarked_post_reaches_the_form_handler 不带标记的 POST 仍走普通表单路由
a_cross_site_rerun_is_forbidden sec-fetch-site: cross-site 返回 403
application_layers_registered_before_the_runtime_see_only_the_rewritten_get 前置层只看到改写后的 GET

最后一条尤其重要:如果你的鉴权层、日志层、限流层依赖请求方法或请求体,注册顺序决定了它们看到的是原始 POST 还是改写后的 GET。

3.2 WebSocket 连接:多路并发渲染

除 HTTP 重跑外,浏览器还可以用子协议 topcoat-runtime(常量 RUNTIME_PROTOCOL)建立 WebSocket 连接。连接上的每条渲染请求描述一次 HTTP 请求:方法、路径、body,以及少量 runtime 头。渲染可以并行进行,返回的每条消息都标注它属于哪个 run。文档同时说明:WebSocket 连接需要原生服务器;HTTP 页面重跑在 WebAssembly 上也可用。

并发上限由 RuntimeLayer 控制,默认为 64:

let router = Router::builder()
    .layer(RuntimeLayer::new().max_runs_per_connection(128))
    .build();

达到上限时,新的渲染请求会收到 429 Too Many Requests,直到某个渲染结束或停止才会重新接纳。源码中的字段与默认值:

pub struct RuntimeLayer {
    #[cfg_attr(target_family = "wasm", allow(dead_code))]
    max_runs_per_connection: usize,
}

impl RuntimeLayer {
    pub const fn new() -> Self {
        Self { max_runs_per_connection: 64 }
    }
}

注意该字段在 wasm 目标下不会被读取(WebSocket 处理只由原生服务端编译),因此 max_runs_per_connection 在 WASM 部署中不产生效果。

四、Runtime 表达式:$(...)

4.1 基本形态

$(...) 块是 runtime 表达式。放在视图中即可渲染它的值:

use topcoat::{Result, context::Cx, view::*};

#[component]
async fn example(cx: &Cx) -> Result<impl View> {
    Ok(view! {
        <p>"The answer: " $(1 + 2)</p>
    })
}

服务端会为初始 HTML 求值该表达式;需要浏览器更新的表达式还会编译成 JavaScript,之后无需再向服务端发请求即可重复执行。上面这个 1 + 2 是静态的——要让它随交互变化,必须让它读取 signal。

从 crates/topcoat-runtime/src/expr.rs 的实现看,一个 Expr<T> 同时持有三部分信息:服务端求值结果 evaluated、浏览器代码 js、以及是否为静态的标记 is_static。

pub struct Expr<T> {
    pub(crate) evaluated: T,
    pub(crate) js: Js,
    pub(crate) is_static: bool,
}

pub fn evaluate(evaluate: impl FnOnce() -> T, js: Js) -> Self {
    let _scope = ReadScope::enter();
    let evaluated = evaluate();
    Self {
        evaluated,
        js,
        is_static: SIGNAL_READ.get() == Some(false),
    }
}

ReadScope 是一个线程局部的读取作用域:求值期间任何 signal 读取都会把 is_static 翻转为 false。因此"是否动态"不是猜的,而是由实际读取行为决定的。测试还覆盖了嵌套求值与 panic 展开时作用域的恢复,保证兄弟表达式不会被污染。

在渲染层面,动态表达式被一段标记注释包裹:

<!--::topcoat::expr::start("<js>")-->  服务端渲染的值  <!--::topcoat::expr::end-->

标记内容经过注释上下文转义,所以 JavaScript 源码中的双引号会渲染成 &quot;,不会破坏注释边界。

4.2 支持的词汇表

runtime 表达式支持 Rust 的一个子集,且在两种语言中行为一致。核心约束如下(完整说明见 expr 文档):

  • f64:+ - * /、比较、取负;浮点字面量即 f64;文本输出遵循 Rust 的 Display,包括 inf、-inf、-0。
  • 整数:+ - * / %、比较,有符号类型支持取负;无后缀整数字面量是 usize,其他类型需写后缀(如 42u64、-1i32);操作数类型必须一致;浏览器中保留完整精度(含 128 位整数),指针宽度取自服务端目标。
  • bool:!、相等比较、then、then_some。
  • String / &str:len、is_empty、trim、trim_start、trim_end、starts_with、ends_with、contains、to_owned 与比较;len 返回 usize。
  • Option<T>:is_some、is_none、unwrap、expect。
  • Result<T, E>:is_ok、is_err、ok、err、unwrap、expect、unwrap_err、expect_err。
  • Vec<T>、[T; N]、切片:len、is_empty、get、index、first、last、to_vec、to_owned;向量与数组还支持 as_slice 与 clone。
  • 元组:字面量、字段访问(pair.0)、clone;支持 () 与 (value,);元组按顺序无分隔地渲染各元素;不支持比较。
  • 带 #[record] 的结构体:结构体字面量构造、按名访问字段、clone;不能比较,也不能直接渲染。
  • Signal:get、set,以及常用写入的简写——bool 信号的 toggle、数值信号的 increment / decrement、字符串信号的 push_str。

语义细节同样与 Rust 对齐:字符串 len 计算 UTF-8 字节数,比较按码点序,trim 使用 Unicode White_Space。这意味着 trim 会保留 U+FEFF,但会去掉 U+0085。

算术在两种语言中都会在溢出、除零、取余零时 panic(debug 与 release 皆然);有符号 MIN / -1、MIN % -1、对 MIN 取负同样 panic。这类"两端一致"的约束由 crates/topcoat-runtime/coherence 测试套件持续校验,运行方式见 coherence 文档:cargo test -p topcoat-runtime-coherence。

4.3 支持的语法与捕获变量

表达式使用 Rust 语法的子集:字面量;一元/二元运算符;方法调用、字段访问、索引;Some/None、Ok/Err、元组字面量、结构体字面量;带 let 绑定与尾表达式的块;if/else 表达式;闭包(可 async)与 .await;loop、while、break、continue、return。不支持的语法会在表达式处产生编译错误。

未在表达式内部定义的标识符将从外围 Rust 作用域捕获:

#[component]
async fn example(cx: &Cx, step: usize) -> Result<impl View> {
    let count = signal(cx, || 0usize);

    Ok(view! {
        $(count.get() + step)
    })
}

捕获是克隆语义,所以外围代码仍可继续使用该值。浏览器拿到的是本次渲染的快照,之后的服务器变更不会更新这个快照。捕获拥有所有权的集合会克隆其元素;捕获切片在服务端借用元素,但仍会向浏览器发送快照。

捕获一个 Expr<T> 时,它在另一个表达式内表现为 T:服务端复用其已求值结果,浏览器在每次使用时重新求值,因此信号读取保持响应式,事件处理器内部亦然。

let selected = signal(cx, || "overview".to_owned());
let active = expr!(selected.get() == "overview");
let label = expr!(if active { "Selected" } else { "Select" });

4.4 用 raw! 嵌入 JavaScript

超出词汇表的操作可以用 raw!。第一个参数是 JavaScript 源码,可选的第二个参数是服务端等价 Rust:

#[component]
async fn example(cx: &Cx) -> Result<impl View> {
    let name = signal(cx, String::new);

    Ok(view! {
        $({
            let n = name.get();
            raw!("${n}.toUpperCase()", n.to_uppercase())
        })
    })
}

${ident} 会把表达式作用域中的绑定插入 JavaScript 字符串。省略 Rust 参数时,该表达式仅能在浏览器执行——此时一致性的责任在你身上。此外,Rust 回退分支中的信号读取决定了该表达式是否需要浏览器绑定,所以回退代码必须读取其 JavaScript 所依赖的信号,哪怕初始值恰好产生常量结果。

五、Signals:浏览器状态的服务端来源

5.1 创建与读写

signal 保存浏览器侧的状态。用 signal 创建,传入请求上下文与初始值闭包;在 runtime 表达式中用 .get() 读取:

let count = signal(cx, || 0usize);

Ok(view! {
    <p>"Count: " $(count.get())</p>
})

服务端计算初始值并发送给浏览器。浏览器回传的值属于用户输入,必须校验。 这一点在后面的安全小节会反复出现。

signal 克隆开销很低。源码中它是 id 加 Arc<T>:

pub struct Signal<T> {
    id: SignalId,
    /// Shared between clones, so capturing a signal never copies its value.
    value: Arc<T>,
}

所以 runtime 表达式可以共享同一个 signal,组件也可以把 &Signal<T> 作为参数接收。

在浏览器中,表达式读取的任意 signal 发生变化,该表达式就会重新执行。.get() 读取当前值,.set(...) 替换它。要响应用户点击来改变 count,就需要事件处理器。

5.2 SignalId 如何生成

signal 的身份由"上下文身份 + 调用点源码位置"共同决定:

impl SignalId {
    pub(crate) fn derive(identity: Identity, location: &Location<'_>) -> Self {
        Self(identity.child(SiteKey::from_location(location)).hash())
    }
}

pub fn signal<T>(cx: &Cx, init: impl FnOnce() -> T) -> Signal<T>
where
    T: SignalValue,
{
    let id = SignalId::derive(identity(cx), Location::caller());
    let value = try_context::<SignalValues>(cx)
        .and_then(|values| values.get(id))
        .and_then(T::from_value)
        .unwrap_or_else(init);
    ...
}

这解释了几个容易被忽视的限制:

  • 同一次调用在多次渲染中保持同一个 id,因此浏览器状态可以被恢复。
  • 循环中的组件需要 #[key(...)],否则多个实例会落在同一调用点、产生同一身份。
  • 普通辅助函数被多次调用时,应传入 cx.keyed(...) 派生的上下文;同一位置的重复调用需要不同的 key。
  • signal 不能在 memoized 调用内创建,也不能在没有任何视图收集渲染产物时创建——后者会 panic:no view is collecting hoisted parts。

examples/runtime/src/shard.rs 里有一个很好的示例:limit 信号声明在 shard 内部,每次重渲染时浏览器都会把它当前的值带上来,因此它不会退回初始值 5。

5.3 状态恢复与类型校验

signal 的恢复逻辑是"匹配则替换,不匹配则用 init":

let value = try_context::<SignalValues>(cx)
    .and_then(|values| values.get(id))
    .and_then(T::from_value)
    .unwrap_or_else(init);

测试 a_value_that_does_not_fit_the_signal_is_ignored 明确验证了这一点:给一个 f64 信号传 "five" 字符串,init 仍会执行,值是 1.0。SignalValues 的类型注释也直接写明 "All restored values are untrusted."。

更关键的是:类型匹配不等于内容合法。客户端可以发送任何符合该类型的值,业务层面的范围、权限、格式必须在服务端校验。示例代码里 limit.get().min(100) 就是在做这种夹取。

5.4 服务端读取的"追踪"语义

在服务端 .get() 是克隆,.read() 是借用,两者都是追踪读取:浏览器中的变更会导致页面(或所属 shard)在服务端重新渲染。不追踪的变体是 .get_untracked() 与 .read_untracked(),用于"用值但不订阅变化"。

追踪的实现是向输出中注入依赖标记注释:

fn track(&self) {
    // Rust fallbacks inside expr! follow the client-reactive path too.
    if crate::expr::mark_signal_read() {
        return;
    }
    let id = self.id;
    hoist_once(
        HoistKey::new((TypeId::of::<SignalId>(), id)),
        move |parts| {
            parts.push_comment(|comment| {
                comment
                    .push_promoted_str_unescaped(&"::topcoat::dep(\"")
                    .push_string_unescaped(id.to_string())
                    .push_promoted_str_unescaped(&"\")");
            });
        },
    );
}

产出的 HTML 形如 <!--::topcoat::dep("<id>")-->。测试保证:重复读取只产生一个标记;get_untracked / read_untracked 不产生标记;在 runtime 表达式内部的读取也不产生标记(那条路径由浏览器负责响应式)。

六、事件处理器:@ 前缀

以 @ 开头的属性会绑定 DOM 事件处理器,例如 @click。它的值是返回闭包的 runtime 表达式;事件触发时浏览器调用该闭包:

let count = signal(cx, || 0usize);

Ok(view! {
    <button @click=$(|_e| count.set(count.get() + 1))>"+1"</button>
    <p>"Count: " $(count.get())</p>
})

点击按钮执行闭包,闭包更新 signal,$(count.get()) 重新渲染——整个闭环都发生在浏览器中。

闭包接收 Event,可访问 DOM 事件的数据与方法。例如把输入框的值写入 signal:

let query = signal(cx, String::new);

Ok(view! {
    <input @input=$(|e: Event| query.set(e.target.value))>
})

Event 的类型定义在 crates/topcoat-runtime/src/surrogate/event.rs,文件头注释说明了它的定位:这些门面类型只是为了让 rustc 能对 expr! 内的处理器做类型检查,服务端永远不会构造它们;浏览器在运行时会针对真实 DOM 的 Event 解析字段访问。字段覆盖了常用项:

  • 修饰键与鼠标:alt_key、ctrl_key、shift_key、meta_key、button、buttons、client_x / client_y、page_x / page_y、offset_x / offset_y、movement_x / movement_y、screen_x / screen_y。
  • 键盘与输入:key、code、repeat、is_composing、input_type、data。
  • 指针与滚轮:pointer_id、pointer_type、delta_x / delta_y / delta_z。
  • 目标与行为:target、current_target(含 value、checked、id、name、text_content)、prevent_default()、stop_propagation()、stop_immediate_propagation()。

超出表达式词汇表的操作,可用 JavaScript 字符串字面量,例如 @click="alert('hi')"。

signal 还提供常见更新的简写,例如 $(|_e| count.increment()) 会给数值 signal 加一。这些方法在服务端调用必定 panic(write_in_browser_only()),因为它们只存在于客户端路径。

事件处理器最终渲染为带前缀的属性。源码中键名被包装成 data-topcoat-on:<event>:

// crates/topcoat-runtime/src/event_handler.rs
Attribute::new(
    (Unescaped::new_unchecked("data-topcoat-on:"), self.key),
    self.value.js,
)

这也是为什么服务端不需要为事件绑定生成内联 onclick,浏览器脚本可以统一接管。

七、Bind 属性:: 前缀

以 : 开头的属性是 bind 属性。服务端渲染表达式初始值;当表达式读取的 signal 变化时,浏览器更新该属性:

let open = signal(cx, || false);

Ok(view! {
    <button @click=$(|_e| open.set(!open.get()))>"What is Topcoat?"</button>
    <p :hidden=$(!open.get())>"A fullstack Rust framework."</p>
})

把 :value 与 @input 组合,就可以让输入框与 signal 双向同步:

let name = signal(cx, String::new);

Ok(view! {
    <input
        :value=$(name.get())
        @input=$(|e: Event| name.set(e.target.value))
    >

    <p>"Hello, " $(name.get()) "!"</p>
})

7.1 静态 bind 与 value 的差别

普通 value 属性设置的是输入框的默认值。如果用户已经在输入框里打字,那么页面或 shard 重新渲染时用户的文本会保留;如果用户没有编辑过,则采用新的默认值。

当 :value 的表达式不读取任何 signal 时,它与普通 value 效果相同。要让每次渲染都写入输入框的当前值(即使没有 signal),对表达式调用 Expr::dynamic():

// Every render clears what the user typed.
let draft = Expr::from(String::new()).dynamic();

Ok(view! {
    <input :value=(draft)>
})

dynamic() 的文档注释把这个区别讲得很直白:

/// A static expression only renders its value. A dynamic one is also
/// evaluated in the browser whenever its content renders. As a bind
/// attribute, this sets the element's live state on every render, such as
/// the value of an input the user has edited, instead of only its default.
pub fn dynamic(mut self) -> Self {
    self.is_static = false;
    self
}

7.2 bind 属性的输出形态

BindAttribute 在静态时只渲染普通属性;动态时同时渲染属性值与一个 data-topcoat-bind:<name> 标记,值是该表达式的 JavaScript:

if is_static {
    Attribute::new(self.key, evaluated).into_view_parts(cx, parts);
    return;
}

Attribute::new(self.key.clone(), evaluated).into_view_parts(cx, parts);
Attribute::new(
    (Unescaped::new_unchecked("data-topcoat-bind:"), self.key),
    js,
)
.into_view_parts(cx, parts);

这种"先渲染服务端值,再附带浏览器表达式"的模式,保证了首屏无需等待脚本即可显示正确内容,同时保留了后续响应式更新的能力。

八、Procedures:从表达式调用服务端函数

procedure 是被 runtime 表达式调用的异步服务端函数。当事件处理器需要访问服务端资源(如数据库)时使用它:

#[procedure]
async fn double(cx: &Cx, value: usize) -> Result<usize> {
    Ok(value * 2)
}

#[component]
async fn example(cx: &Cx) -> Result<impl View> {
    let count = signal(cx, || 1usize);

    Ok(view! {
        <button @click=$(async |_e| {
            let doubled = double(count.get()).await;
            count.set(doubled);
        })>
            "double it"
        </button>
    })
}

浏览器带着参数发送 HTTP 请求并等待结果。必须在 procedure 内部校验参数并做授权,因为调用方可以自行发起请求。

8.1 调用约束

在 runtime 表达式内像普通异步函数一样调用并 .await,调用时省略 cx——Topcoat 会自动提供服务端请求上下文。有两条容易踩的坑:

  1. 必须在异步上下文中 await,例如事件处理器的 async 闭包。
  2. procedure 调用只能发生在浏览器侧。 服务端会做类型检查,但如果在渲染期真的求值该调用会 panic。事件处理器闭包体内的代码只在浏览器触发时才执行,因此天然满足这一约束。

源码中 ProcedureSurrogate::call 直接 panic,注释即为此意:

/// # Panics
///
/// Always panics; procedures can only be invoked from the client runtime.
pub async fn call(&self, _args: ...) -> ... {
    panic!("procedures cannot be executed on the server");
}

而序列化给浏览器的形状是 { "t": "Procedure", "path": "<url>" },浏览器据此知道向哪个端点发请求。

8.2 参数、返回值与错误

函数必须是 async,第一个参数是 cx: &Cx(即使不用也必须写)。其余参数类型须属于 expr! 的共享词汇表,返回 Result,其 Ok 值也必须属于该词汇表——这些值都要在 Rust 与 JavaScript 之间往返。

参数编码为 JSON 数组,最多支持 12 个;空参数列表是 [],单个 unit 参数是 [null],两者编码不同(见 crates/topcoat-runtime/src/arguments.rs)。每个参数保留自己的 surrogate 编码,例如 u128 会带上位数信息。

关于错误:await 得到的是 Ok 值;若 procedure 返回 Err,服务端发出错误响应,浏览器表达式失败,且表达式无法检查该错误。要让客户端能够处理失败,把失败当作数据返回,例如 Ok 类型用 Result<String, String>。examples/runtime/src/record.rs 的 place_order 正是这种模式——外层 Result 表示传输层成败,内层 Result<Receipt, String> 承载校验消息,页面再用 match 渲染。

8.3 注册与路径

procedure 实现 Route,可传给 .route() 注册;启用 discover feature 时,.discover() 会注册所有链接进应用的 procedure。

默认路径由名字与源码位置生成,重命名或移动文件会改变路径。需要稳定端点时显式指定绝对路径:

#[procedure("/api/double")]
async fn double(cx: &Cx, value: usize) -> Result<usize> {
    Ok(value * 2)
}

浏览器将以 POST /api/double 调用。参数在请求体中传输,因此路径不能包含动态参数或 catch-all 参数。路径遵循 router 的路径语法,分组会影响层匹配但不出现在 URL 中:#[procedure("/(api)/double")] 实际服务于 /double。

九、Shards:按需局部重渲染

shard 是一个在其输入变化时于服务端重新渲染的组件。适合用服务端数据更新标记的场景,比如搜索结果。参数接受固定值或 runtime 表达式:

#[shard]
async fn search_results(cx: &Cx, query: String) -> Result<impl View> {
    let products = search_products(cx, &query).await?;
    Ok(view! {
        for product in products {
            <div>(product)</div>
        }
    })
}

#[component]
async fn example(cx: &Cx) -> Result<impl View> {
    let query = signal(cx, String::new);

    Ok(view! {
        <input @input=$(|e: Event| query.set(e.target.value))>

        search_results(query: $(query.get()))
    })
}

shard 拥有独立的 HTTP 端点。必须在 shard 内部校验参数并做授权:它的页面与布局守卫不会为该端点的请求执行。

9.1 调用形式与刷新行为

在 view! 体内像组件一样调用 shard,省略 cx,Topcoat 自动提供服务端请求上下文。其余参数接受声明类型 T 或 Expr<T>,转换自动完成:

search_results(query: $(query.get()))
search_results(query: "shoes".to_owned())

初始页面渲染就包含 shard 的内容,不需要额外请求。shard 内部的实时内容(如 live 区域)会随页面渲染一起流出,重渲染时随 shard 自己的响应流出。query 变化时,浏览器把当前参数发给服务端并用返回的 HTML 更新 shard;其余页面保持不变。

关于元素更新与请求合并,shard 文档补充了三条关键规则:

  • 元素按位置与标签匹配,有 id 时按 id 匹配。可重排列表的条目应给稳定 id,让元素跟随其数据项。
  • 同一 tick 内的多个信号变更合并为一次请求。
  • 新请求会中止仍在等待的旧请求,因此最新参数获胜。

9.2 shard 自身的状态

shard 支持与组件相同的内容。其函数体内创建的 signal 在多次重渲染间保值:浏览器每次请求都带上这些值,signal 负责恢复。恢复值同样视为用户输入。

在服务端用 .get() / .read() 读取这类 signal 会让 shard 依赖它,于是浏览器中的变更只重渲染该 shard,而不是整页:

#[shard]
async fn paginated(cx: &Cx) -> Result<impl View> {
    let page = signal(cx, || 1usize);
    let items = load_page(cx, page.get()).await?;

    Ok(view! {
        for item in items {
            <div>(item)</div>
        }

        <button @click=$(|_e| {
            if page.get() > 1 {
                page.decrement()
            }
        })>"previous"</button>
        <button @click=$(|_e| page.increment())>"next"</button>
    })
}

点击按钮在浏览器中改变 page;因为 shard 在服务端读取过它,shard 会带着新值再次运行并换入下一页条目。

9.3 从调用方接收 Signal<T>

shard 参数类型可以是 Signal<T>,调用时直接把信号句柄传进去:

#[shard]
async fn search_results(cx: &Cx, query: String, limit: Signal<usize>) -> Result<impl View> {
    // A new limit takes effect on the next re-render, but does not cause one.
    let products = search_products(cx, &query, limit.get_untracked()).await?;
    ...
}

调用形如 search_results(query: $(query.get()), limit: limit)。要点是:信号句柄本身不会因其值变化而改变,所以一次变更是否触发 shard 重渲染,取决于 shard 函数体如何读取它。上例用 get_untracked(),新上限在下一次重渲染时生效,但自身不引发重渲染。

9.4 参数与返回类型、注册与路径

函数必须 async,首个参数为 cx: &Cx;其余参数类型须属于 expr! 词汇表(因为值要在 Rust 与 JavaScript 之间穿越);返回 Result<impl View>。

注册方式与 procedure 一致:shard 实现 Route,可传给 .route(),或由 .discover() 批量注册。

路径同样默认由名字与源码位置生成,重命名或移动即变化;需要稳定端点时显式指定:

#[shard("/search/results")]
async fn search_results(cx: &Cx, query: String) -> Result<impl View> {
    Ok(view! { <p>"Results for " (query)</p> })
}

浏览器将以 POST /search/results 请求重渲染,参数与信号值在请求体中,因此路径不能含动态或 catch-all 参数。分组同样只影响层匹配:#[shard("/(api)/search/results")] 实际服务于 /search/results。

9.5 shard 边界的实现形态

shard 内容被一对标记注释包住,浏览器据此定位替换范围。ShardScope 会输出起始标记(带 URL、identity、各参数的 JavaScript 源码)与结束标记:

// crates/topcoat-runtime/src/shard_scope.rs
// <!-- ::topcoat::shard::start("<url>", "<identity>", ["<js>", ...]) -->
// <!-- ::topcoat::shard::end("<identity>") -->

注释说明了两点设计意图:identity 在多次渲染间稳定,因此重渲染外层内容会产出相同标记,浏览器可以保留它们;参数源码被包在引号字符串中,并用注释上下文密封,源码里的 " 会渲染成 &quot;,引号边界保持无歧义。

请求体结构则由 ShardRequest 定义——参数与信号值在 body,invocation 的 identity 走单独的 identity 头:

pub struct ShardRequest<A> {
    args: Arguments<A>,
    #[serde(default)]
    signals: SignalValues,
}

十、在服务端读取 signal:整页重渲染模式

在服务端 Rust 中用 .get() 克隆值、.read() 借用值,这些是追踪读取。浏览器中的变更会导致页面在服务端以新值重新渲染:

// src/app/search.rs
#[page]
async fn search(cx: &Cx) -> Result<impl View> {
    let query = signal(cx, String::new);
    let products = search_products(cx, &query.get()).await?;

    Ok(view! {
        <input :value=$(query.get()) @input=$(|e: Event| query.set(e.target.value))>

        for product in products {
            <div>(product)</div>
        }
    })
}

输入框在浏览器中即时更新,同时服务端刷新产品列表。重渲染时 signal 会恢复浏览器发送的值。注意:$(...) 内的读取只更新浏览器表达式,不触发服务端渲染。

examples/runtime/src/sort.rs 是同一模式的精简版,注释把因果关系写得很清楚:

let descending = signal(cx, || false);

// Reading the signal on the server makes the page depend on it: when the
// button below changes it in the browser, the page runs again on the
// server with the current value and its content is replaced.
let mut fruit = FRUIT;
if descending.get() {
    fruit.reverse();
}

10.1 安全边界

在服务端读到的每个值都是用户输入,不可信。 客户端持有 signal,可以发送任何符合其类型的值,因此使用前必须校验,和对待 shard 参数完全一样。

这不是"防御性编程建议",而是协议层的既成事实:重跑请求的 body 就是一段客户端提交的 JSON,RuntimeLayer 只检查了 X-Topcoat-Runtime 头、Content-Type 和同站来源(sec-fetch-site)。字段内容由客户端决定。

10.2 DOM 保真与列表 key

浏览器原地更新已有元素,以保留焦点、滚动位置与输入状态;signal 保持其值。可重排列表的条目要给稳定 ID,让每个元素跟随其数据项。

10.3 用 shard 缩小重渲染范围

要避免整页重跑,就用 shard:在 shard 内部被追踪的 signal 只重渲染该 shard。shard 创建 signal、读取它,并把修改它的处理器交给浏览器。这就是第 9.2 节示例的完整含义,也是"信号归属决定重渲染粒度"的实践结论。

10.4 不追踪读取

用 .get_untracked() 或 .read_untracked() 在服务端读值,但不让它的变化触发再次渲染。适用场景包括:读取一次快照用于日志、在 shard 参数中消费外部信号而不改变自身依赖关系。

十一、把示例跑起来

examples/runtime 提供了六个递进式示例,每个对应本文一个主题:

示例 文件 对应能力
counter examples/runtime/src/counter.rs 事件处理器写入 signal
show examples/runtime/src/show.rs bind 属性同步 hidden
sort examples/runtime/src/sort.rs 服务端追踪读取触发整页重渲染
procedure examples/runtime/src/procedure.rs 事件处理器 await 服务端函数
shard examples/runtime/src/shard.rs 查询变化驱动 shard 局部刷新
record examples/runtime/src/record.rs #[record] 存储订单并提交 procedure

启动方式(见 examples/runtime/README.md):

cargo topcoat dev -p runtime

其中 record 示例把多个机制串了起来:Order / Address / Receipt 三个 #[record] 类型在一个 signal 中保存,输入框通过 :value 与 @input 逐字段同步,最后用异步事件处理器把完整订单交给 place_order procedure,并用内层 Result 把校验错误渲染回页面。place_order 内部对数量与地址做了服务端校验,正是文档强调的"在服务端校验客户端输入"的落地写法。

十二、注意事项与选型建议

根据文档与源码,落地时建议按下列顺序做决策:

  1. 是否需要服务端参与? 只改 DOM 就够的,用 $() + signal + 事件处理器;需要服务端数据的,进入下一步。
  2. 重渲染范围多大? 只有一块内容依赖服务端数据,用 shard;整页语义都依赖它(如排序、筛选影响布局与标题),用追踪读取触发 page rerun。
  3. 是否需要写操作? 写操作走 procedure,并注意错误无法被表达式检查,必要时用嵌套 Result 把失败作为数据返回。
  4. 端点是否稳定? 默认路径随名字与源码位置变化,跨版本部署或对外暴露时显式指定绝对路径。
  5. 层顺序是否正确? 应用层必须注册在 RuntimeLayer 之前,才能以 GET 身份处理重跑;需要限制并发渲染时调整 max_runs_per_connection。
  6. 是否只面向浏览器? WASM 部署下 WebSocket 连接不可用,但 HTTP 页面重跑仍可用。

最后重申文档开头的提醒:runtime 仍处于实验阶段,表达式仅支持 Rust 的子集,API 可能变化。读者可以从 crates/topcoat/docs/runtime.md 了解主线,再分别深入 expr、shard、procedure、record、link 与 coherence,配合 crates/topcoat-runtime 的源码与测试,构成完整的学习闭环。

登录后查看全文
topcoat