RushWind Admin --- update_mask 写面:字段级白名单、显式清除与点路径合并
本文回答一个问题:前端只改了一个昵称,后端凭什么保证其余几十个字段一个都不会被碰坏?「把某字段清空」和「没传这个字段」又怎么在同一个接口里区分?------拆解 update_mask 从契约字段到 SeaORM 赋值行的整条写面链路。
RushWind Admin 的更新接口是同一个形状:请求体带一个 id 和一个大对象 data。麻烦全在细节里------管理后台的字段动辄几十个,一个"只改昵称"的表单提交,其余字段是原样回传的旧值;只要服务端照单全收,任何一个并发窗口里的旧快照都能把别人刚写进去的值覆盖回去。所以这条写面链路要回答的不是"怎么更新",而是三个更细的动词:写(这个字段变了)、清(这个字段要置空)、不动(请求里根本没有它) 。整提交语义只有前两个的混合体,区分不了"清空"和"没传"------这就是 update_mask 存在的理由。这批更新接口的集合,仓库文档称作写面(write face):face 是契约驱动架构的既有词汇------同一份 proto 契约朝不同协议投影出 REST 面、gRPC 面、服务面,写面就是其中承载全部更新写路径的那一张,与查询侧相对。
一、契约面:掩码是请求消息的第 3 号字段
掩码不是文档约定,是契约字段。每个 Update 请求消息按 AIP-134 的形状声明它:
protobuf
// backend/apps/admin/api/protos/bi/service/v1/bi_dashboard.proto
message UpdateBiDashboardRequest {
uint64 id = 1;
BiDashboard data = 2;
google.protobuf.FieldMask update_mask = 3 [
json_name = "updateMask"
// ......openapi 属性注解略
]; // 要更新的字段列表
}
客户端两种送法都被绑定层吃下:JSON body 里的 "updateMask": ["name","path"],或表单 query 里的 updateMask=name,path。后者要在绑定层做一次归一化------逗号切分、camelCase 转 snake_case。这不是可做可不做的礼貌,是线上契约的一部分,有测试钉着:
rust
// backend/apps/admin/tests/binder.rs
#[test]
fn field_mask_json_name_snake_normalization() {
let mut m = fresh("dict.service.v1.UpdateLanguageRequest");
bind_form(&mut m, &[("updateMask".into(), vec!["aB,cD_e".into()])]).unwrap();
let out: admin::proto::dict::service::v1::UpdateLanguageRequest = m.transcode_to().unwrap();
let mask = out.update_mask.expect("mask set").paths;
assert_eq!(mask, &["a_b".to_string(), "c_d_e".to_string()]);
}
"aB,cD_e" 进来,["a_b", "c_d_e"] 出去。归一化规则只有一条:去掉下划线、转小写后比较 ------homePath、home_path、HomePath 是同一个字段。
二、掩码的三原语
掩码的运行时形态是一个 85 行的小类型。核心不是结构,是三个判断函数------门的所有行为都由它们组合出来:
rust
// backend/apps/admin/src/admin/fieldmask.rs
/// 字段是否被掩码选中。无掩码恒真;点路径按顶层段算选中
/// (`meta.title` 选中 `meta` 域)。收 snake 或 camel 列名。
pub(crate) fn touches(&self, field: &str) -> bool {
match &self.paths {
None => true,
Some(set) => {
let want = normalize(field);
set.iter().any(|p| p.split('.').next().unwrap_or(p) == want)
}
}
}
/// 字段的"整个域"是否被字面选中(无掩码真;`meta.title` 只选子段,
/// 不算选中整个 `meta`)。载荷 None 时只有 selected-whole 才显式清列
/// ------仅点路径选中 + 载荷缺 = "未携带",列原样留给合并域。
pub(crate) fn selects_whole(&self, field: &str) -> bool {
match &self.paths {
None => true,
Some(set) => set.contains(&normalize(field)),
}
}
fn normalize(field: &str) -> String {
field.trim().replace('_', "").to_ascii_lowercase()
}
三个原语各自的职责:
touches:进门判断。掩码选中才允许碰这一列,白名单的本体;selects_whole:整域判断。meta.title算"选中 meta 域"(能进门),但不算"字面写了 meta"(不能整列清空)------这个区分是 jsonb 域特殊形式的全部依据;unrestricted:无掩码判断。paths为None即全量提交语义。
最容易被忽略的是第四种输入:掩码在场但为空集。AIP-134 的严格读法是"什么都不许动"------前端表单零键时送出的空串掩码,不该被当成"全放行":
rust
// backend/apps/admin/src/admin/fieldmask.rs
/// present-but-empty = 什么都不许动(AIP-134 严格读法):前端表单
/// 零键时送出的空串掩码不该被当成"全放行"。
#[test]
fn present_empty_mask_admits_nothing() {
let m = mask(&[]);
assert!(!m.unrestricted());
assert!(!m.touches("name"));
assert!(!m.selects_whole("name"));
}
四种输入、三种语义,一张表摆平:
| 掩码形态 | 语义 |
|---|---|
缺席(None) |
全量提交:与历史无掩码行为逐字节等价 |
| 空集 | 什么都不许动(present-but-empty 严格读法) |
| 顶层字段名 | 该字段可写(含显式清除) |
点路径(meta.title) |
子段可写,整列不可清,合并域接管 |
三、set_masked!:把三通道写进每一行赋值
门判断有了,落点在哪?答案是一个宏。全仓 update 写面的每一行字段赋值都经它发出,三种通道在宏里定型:
rust
// backend/apps/admin/src/admin/macros.rs
(opt_named $mask:expr, $model:expr, $field:ident, $name:expr, $value:expr, $map:expr) => {
if $mask.touches($name) {
match &$value {
Some(v) => $model.$field = sea_orm::Set($map(v)),
None => {
if !$mask.unrestricted() {
$model.$field = sea_orm::Set(None);
}
}
}
}
};
(req_named $mask:expr, $model:expr, $field:ident, $name:expr, $value:expr, $map:expr) => {
if $mask.touches($name) {
if let Some(v) = &$value {
$model.$field = sea_orm::Set($map(v));
}
}
};
opt 形态给可空列,三条通道:
- 掩码选中 + 载荷
Some→ 写值; - 掩码选中 + 载荷
None→ 显式Set(None)清列------这就是"清空"动词的落点,整提交语义永远表达不了的那个; - 无掩码 + 载荷
None→ 什么都不做。存量全量提交语义原封不动:老客户端不带掩码提交,行为与从前逐字节一致。
req 形态给 NOT NULL 列:没有"清成 NULL"的语义可表达,所以只有写值通道,None 永不落笔。
create / sync 这类非 PATCH 入口复用同一条 apply 链,传的是显式无掩码:
rust
// backend/apps/admin/src/admin/fieldmask.rs
/// 显式无掩码------create/sync 等非 PATCH 入口复用 apply 链时用。
pub(crate) fn unmasked() -> Self {
Self { paths: None }
}
rust
// backend/apps/admin/src/admin/services/menu.rs
Self::apply_fields(&mut a, &data, &crate::fieldmask::FieldMask::unmasked());
无掩码时 touches 恒真、unrestricted 为真 → opt 形态的 None 分支被短路------create 的行为与旧 if-let-Some 逐字节一致。同一套赋值代码服务两种语义,切换点收敛在一个参数上,这是全仓 12 处 create/sync 入口敢复用 apply 链的底气。
四、jsonb 域的特殊形式:点路径合并
标量列的门到宏为止。jsonb 列多出一层问题:meta 是一个 JSON 域(图标、标题、keepAlive......),客户端只想改图标时,送 updateMask=meta.icon 加一个只带 icon 的载荷------整列替换会把其余键全部抹掉。
menu 的 apply_fields 先在门内给 meta 一个特判:点路径选中不算整域选中,载荷缺 meta 不是"清列"信号,而是"交给合并域":
rust
// backend/apps/admin/src/admin/services/menu.rs
// meta 不走 opt 清列形态:掩码只选中点路径子段(meta.title)时
// touches("meta") 为真但 selects_whole 为假------载荷缺 meta 是
// "未携带"(列原样,合并域接管),只有整域选中/无掩码的 None
// 才显式清列。
if mask.touches("meta") {
match &data.meta {
Some(m) => a.meta = Set(Some(menu_meta_to_json(m))),
None => {
if mask.selects_whole("meta") {
a.meta = Set(None);
}
}
}
}
update 侧抽取 meta. 前缀的叶子,交给合并函数:
rust
// backend/apps/admin/src/admin/services/menu.rs
/// update_mask 点路径选中的 meta 子字段合并进存量 jsonb:
/// 选中且有值 → 写值;选中但为空 → 显式写 json null(清空
/// 图标/标题不留残值);未选中的键 → 存量原样保留。base 为 NULL 列时从
/// `{}` 起步------应用层合并天然免疫 SQL `NULL || x` 静默丢失。
fn merge_meta_fields(
base: serde_json::Value,
meta: &crate::proto::permission::service::v1::MenuMeta,
leaves: &[&str],
) -> serde_json::Value {
let mut obj = match base {
serde_json::Value::Object(map) => map,
_ => serde_json::Map::new(),
};
let converted = menu_meta_to_json(meta);
for leaf in leaves {
let Some(key) = meta_field_json_key(leaf) else { continue };
let value = converted.get(key).cloned().unwrap_or(serde_json::Value::Null);
obj.insert(key.to_string(), value);
}
serde_json::Value::Object(obj)
}
三条合并规则,每条都有数据库级 round-trip 测试压着:
未选中的键存活 ------掩码只有 meta.icon,title 原样不动:
rust
// backend/apps/admin/src/admin/services/menu.rs(测试截取)
svc.update(me, update_req(row.id as u64,
Menu { meta: Some(MenuMeta { icon: Some("lucide:layout-dashboard".into()), ..Default::default() }), ..Default::default() },
&["meta.icon"])).await.unwrap();
assert_eq!(meta.get("icon").and_then(|v| v.as_str()),
Some("lucide:layout-dashboard"), "masked leaf updated");
assert_eq!(meta.get("title").and_then(|v| v.as_str()),
Some("仪表盘"), "unmasked title survives the merge");
选中但为空 → 显式 null ------清空图标不留残值,读回 proto 时收敛为 None;门本身------载荷夹带了掩码外的字段,落不了地:
rust
// backend/apps/admin/src/admin/services/menu.rs(测试截取)
async fn mask_gates_unlisted_scalar_fields() {
// 载荷带 path: Some("/evil"),掩码只有 ["name"]
assert_eq!(fresh.name, "工作台", "masked field lands");
assert_eq!(fresh.path.as_deref(), Some("/dashboard"),
"unmasked path is not writable through the gate");
}
五、门不管的:特殊逻辑的归属
字段门只管"载荷字段 → 列"的写面,不接管一切。哪些特殊逻辑留在门外、哪些跟着掩码走,docs/binding-spec.md §2.5 有一句成文的原则:
特殊逻辑门控原则:校验类逻辑原位保留(门只管"载荷字段 → 列"的写面);与"字段是否被写"耦合的副作用按掩码门控。
两类各看一例。校验原位保留 :AI Agent 的图结构校验仍在写前执行------但只在掩码选中 graph 时才触发;不更新图就不做图校验,校验拒绝时旧列原样:
rust
// backend/apps/admin/src/admin/services/ai_agent.rs
if mask.touches("graph") {
if let Some(v) = &data.graph {
// 图非空时必须能解析且过静态校验(写前拒绝,不清残列)。
if !v.trim().is_empty() {
let g = agent_graph::parse_agent_graph(v)
.map_err(|e| status_error("BAD_REQUEST", e))?;
agent_graph::validate_agent_graph(&g)
.map_err(|e| status_error("BAD_REQUEST", e))?;
}
}
}
crate::set_masked!(opt mask, a, graph, data.graph, |v: &String| Some(v.clone()));
门外恒执行 :BI 仪表盘的乐观锁 CAS 与版本自增是 handler 自己的职责,与掩码无关------哪怕掩码只选了 name,版本冲突照样拒绝、版本号照样 +1:
rust
// backend/apps/admin/src/admin/services/bi_dashboard.rs
// 乐观锁:data.version 回传读到的版本时按 CAS 校验,冲突 BadRequest;
// 版本号无论走哪条路都 +1。
if let Some(want) = data.version {
if row.version.unwrap_or(0) != want {
return Err(status_error("BAD_REQUEST",
format!("dashboard version conflict: expected {}, got {}", ...)));
}
}
let mask = crate::fieldmask::FieldMask::from(req.update_mask.as_ref());
apply_fields(&mut a, &data, &mask);
crate::stamp_update!(a, payload.user_id);
a.version = Set(Some(a.version.clone().unwrap().unwrap_or(0) + 1));
还有一类是晚落的列的补位 :角色的 home_path(按角色设定默认首页)落在掩码机制之后,用映射函数把 Some(空串) 翻译成 None,走清列通道------空串清除、缺省不动,与旧 if-let-Some 语义对齐:
rust
// backend/apps/admin/src/admin/services/role.rs
crate::set_masked!(opt mask, a, home_path, data.home_path, |v: &String| {
if v.is_empty() { None } else { Some(v.clone()) }
});
门控调用点全仓 32 处、分布在 30 个服务文件,set_masked! 调用行 214 行------一个中型系统的整个写面,就是这一张白名单表的展开。
六、失败模式:当门没落地
这套语义交过一次真金白银的学费。曾经有一段时期,契约在说 update_mask,前端在发 update_mask,OpenAPI 在写 update_mask,发版说明在吹 update_mask------而服务端把每一次掩码都忽略成整提交。起因不是设计缺陷,是一次大规模合并的解决方式:旧布局路径被新布局的删除回答了,整个写面被静默回退,而契约、绑定层、规格、五套前端全都还在广告这个语义。
这类事故的可怕之处在于完全静默 :接口不报错、测试大多还绿(它们提交的是全量数据)、用户得到的是"偶发的字段互相覆盖"。它暴露的不是某个 bug,而是一条工程铁律------广告了的语义必须有独立于实现的守卫 。现在的防线有三层:FieldMask 与归一化规则有纯逻辑测试(present-but-empty、camel 转 snake 各自钉死);menu meta 有数据库级 round-trip 测试(合并、显式 null、门拦截各一);binding-spec 把"无掩码 = 与历史行为逐字节等价"写成差分回归基准。门的可靠性不取决于实现它的那一天,取决于钉住它的那些测试。
七、机制 × 关键决策 × 失败模式
| 机制 | 关键决策 | 失败模式(若无此决策) |
|---|---|---|
touches 白名单门 |
点路径按顶层段进门,掩码外字段不可写 | 并发旧快照覆盖他人写入,静默发生 |
| 显式清列通道 | 掩码选中 + None → Set(None);无掩码 None 不动 |
"清空"不可表达,或无掩码行为被误改 |
| present-but-empty 严格读法 | 空集掩码什么都不许动 | 空表单提交被当全放行,整行被零值洗掉 |
| snake/camel 归一 | 去下划线小写比较,绑定层有归一化测试 | homePath 与 home_path 被当两个字段,门漏放 |
unmasked() 复用 apply 链 |
create/sync 与 PATCH 共用赋值代码 | 两套赋值逻辑漂移,写面行为不一致 |
| jsonb 点路径合并 | 整域选中才可清列;合并以存量 jsonb 为基线、{} 兜底 |
整列替换抹掉未选中键;SQL `NULL |
| 特殊逻辑门控原则 | 校验原位保留;CAS 等副作用门外恒执行 | 不更新图也触发图校验;掩码绕过版本冲突检查 |
| 守卫测试三层 | 纯逻辑 / 数据库 round-trip / 差分基准 | 门被合并静默回退,全量提交回归无人发现 |
写面的一切复杂度,本质上是 PATCH 语义比 PUT 多出来的那一个动词。"清空"与"没传"的区分不可能靠约定俗成,只能靠一个显式的契约字段和一条从绑定层到赋值行的白名单链路。字段级更新做对了是隐形的------用户永远看不到它发力;做错了也是隐形的------直到某天两个管理员互相覆盖了对方的修改。
系列文章: