Topcoat Runtime 实战指南:用 Rust 编写信号、事件与分片式交互
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>
})
}
这带来两个实用结论:
- 忘记挂载
RuntimeLayer时,页面会在渲染阶段直接 panic,并给出明确提示,而不是在浏览器里悄无声息地失效。 - 脚本标签上的
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 源码中的双引号会渲染成 ",不会破坏注释边界。
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 会自动提供服务端请求上下文。有两条容易踩的坑:
- 必须在异步上下文中 await,例如事件处理器的
async闭包。 - 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 在多次渲染间稳定,因此重渲染外层内容会产出相同标记,浏览器可以保留它们;参数源码被包在引号字符串中,并用注释上下文密封,源码里的 " 会渲染成 ",引号边界保持无歧义。
请求体结构则由 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 内部对数量与地址做了服务端校验,正是文档强调的"在服务端校验客户端输入"的落地写法。
十二、注意事项与选型建议
根据文档与源码,落地时建议按下列顺序做决策:
- 是否需要服务端参与? 只改 DOM 就够的,用
$()+ signal + 事件处理器;需要服务端数据的,进入下一步。 - 重渲染范围多大? 只有一块内容依赖服务端数据,用 shard;整页语义都依赖它(如排序、筛选影响布局与标题),用追踪读取触发 page rerun。
- 是否需要写操作? 写操作走 procedure,并注意错误无法被表达式检查,必要时用嵌套
Result把失败作为数据返回。 - 端点是否稳定? 默认路径随名字与源码位置变化,跨版本部署或对外暴露时显式指定绝对路径。
- 层顺序是否正确? 应用层必须注册在
RuntimeLayer之前,才能以GET身份处理重跑;需要限制并发渲染时调整max_runs_per_connection。 - 是否只面向浏览器? WASM 部署下 WebSocket 连接不可用,但 HTTP 页面重跑仍可用。
最后重申文档开头的提醒:runtime 仍处于实验阶段,表达式仅支持 Rust 的子集,API 可能变化。读者可以从 crates/topcoat/docs/runtime.md 了解主线,再分别深入 expr、shard、procedure、record、link 与 coherence,配合 crates/topcoat-runtime 的源码与测试,构成完整的学习闭环。