fieldpolicy —— 字段级可见性(列级权限):三态模式 → 逐字段叠加 → 响应出口

RBAC 回答"这个角色能不能调这个接口"。 scope 回答"放行之后能看哪些行"。 fieldpolicy 回答第三个问题:看到的那一行里,哪些字段给他看。

三根轴互相独立,谁也替代不了谁:

轴 问的问题 实现
① 功能权限 能不能调这个接口 / 点这个按钮 Casbin + RBAC 资源码
② 行级数据范围 能看哪些行 internal/pkg/scope
③ 字段级可见性 能看一行里的哪些字段 internal/pkg/fieldpolicy(本篇)

⚠️ "能看这一行" ≠ "能看这一行里的每个字段" —— "客服部能看这个客户"同时意味着"客服部能看到客户的手机号", 而后者要不要给,是另一条规则说了算。

功能

fieldpolicy 做四件事:

  1. 定义字段的可见性模式 —— 三态(明文 / 打码 / 隐藏)
  2. 定义打码方式 —— 七种,外加"按字段名自动推断"
  3. 把默认规则组与业务域规则组叠加 —— 逐字段叠加
  4. 把策略作用到 JSON 上 —— ApplyJSON(字节)/ ApplyTree(树)

五样东西:

类型 是什么
Mode 可见性模式,三态
MaskType 打码方式,七种 + MaskAuto(空串)
Rule 某个角色在某个业务域上对一个字段的一条规则
Policy 一组已解析的规则(不可变,解析一次到处用)
Policy.Overlay 默认组与业务域组的逐字段叠加

不解决什么:规则存在哪、谁去解析、候选字段有哪些、怎么落到响应上, 都不在本包 —— 本包是纯函数,不碰 DB。 落库在 internal/service/field_policy.go,接线在 internal/api/handler/field_policy.go。

三种模式

模式 效果
visible 原样返回(不配规则时也是这个效果)
masked 值被打码(138****1234)
hidden 从响应里删掉这个键

⚠️ hidden 是删键,不是置空 —— 置空的话前端看到的是 {"phone": null} —— 它知道"这里有个手机号字段", 而这个字段名本身可能就是信息(emergency_contact_phone 说明这个人有紧急联系人)。 删键则连字段名都不出现。

⚠️ 空串模式按 visible 处理 —— 与行级数据范围同一条约定: "没配" 与 "配成明文" 效果一样(都不处理)。

⚠️ 不认识的模式一律报错,不静默当成 visible —— 静默当成 visible = 规则失效 = 该打码的字段原样吐出去。

七种打码方式

方式 例子
phone 138****1234
id_card 1101**********1234
name 张*
email z******@qq.com
bank_card ****1234
contract_no ABC****0234
full 等长星号(猜不出类型时的兜底)

⚠️ 空串不是一种打码方式,是"按字段名猜"(MaskAuto)—— AutoMaskType("real_name") ⇒ name;猜不出来返回空串。 ⇒ 猜不出来时必须在配置期就拒,运行期兜底是 full(整串打码,安全方向)。

⚠️ 推断表是精确匹配,不做前缀/后缀匹配 —— 后缀匹配会把 project_name / dept_name / group_name 全打成 张*, 而那些是机构名不是人名 —— 打完之后整个列表没法看了。

逐字段叠加(与行级的"整组就近覆盖"故意不同)

默认规则组(module="")管所有业务域;业务域专属规则只覆盖它自己写了的那些字段。

默认组:phone → hidden
user 域:real_name → masked

⇒ user 域上:phone 仍然隐藏,real_name 打码

⚠️ 与行级数据范围故意不一样 —— 行级(scope)是"某业务域配了规则 ⇒ 整组就近覆盖,默认组不参与"; 字段级是"业务域只覆盖它自己写了规则的那些字段"。

⇒ 安全方向:多藏一点没关系,少藏一点是泄露。 若按行级那套"整组覆盖"来实现,user 域上 phone 会因为一条无关的 real_name 规则而重新露出来。

配置

没有 yaml 配置项

本包是纯原语,不读配置、不连外部依赖。

规则存哪

落在 sys_field_policy,唯一键 (role_id, module, field) —— 同一角色同一业务域上,一个字段只能有一条规则。

// 列出某角色配的全部规则(所有业务域)
rules, err := fieldPolicySvc.ListRoleFieldPolicies(ctx, roleID)

// 全量替换某角色在某业务域上的规则
err = fieldPolicySvc.ReplaceRoleFieldPolicies(ctx, roleID, "user", []service.FieldPolicyInput{
    {Field: "real_name", Mode: "masked", MaskType: "name"},
})

// 可配置的业务域候选(后台下拉框用)
mods, err := fieldPolicySvc.ListFieldPolicyModules(ctx)

⚠️ 写接口是"全量替换",不是"增量" —— body 里给的那组就是该业务域上的全部规则, 发空数组 = 清空该域的规则。

⚠️ module 为空串 = 默认规则组 —— 某业务域没单独配规则时回落到它。 它只作用于业务域,不撒到 auth / config / dict / role 上 (那些域的响应不是"业务行的一个投影",一条"隐藏 name"的默认规则 会把配置项的名字也一起藏掉)。

⚠️ 业务域必须存在,否则配置期就拒 —— 错误消息里带上可配的业务域清单:

业务域 userx 不存在或不支持字段级可见性(规则配了也不会生效)

候选字段从响应模型反射出来

⚠️ 候选 = 模型的 json tag 名(排除 -),不是数据库列名 —— 字段级可见性配的是响应 JSON 里的键名,不是列名。

model.Owner.Phone  gorm:"size:512" json:"-"   ← 列存在,但**永远不在响应里**

按列名列候选 ⇒ 管理员会看到"手机号"这个候选,勾上"隐藏" ⇒ 什么都不会发生(那个键压根不在响应里),而他以为自己已经防住了。

⇒ 候选必须从真实的响应模型上反射(internal/service/biz_field_domain.go)。 手写一份清单 ⇒ 模型改字段名而清单没改 ⇒ 管理员配了一个不存在的字段 ⇒ 规则静默不生效,而且页面看起来一切正常。

⚠️ 动态集合(dyn:<集合编码>)不在静态登记表里 —— 它的字段是运行期建的,候选从 sys_dyn_field 现算。

⚠️ 登记的是"响应模型",不是"表" —— 一个业务域可能返回不止一种结构(列表项 / 详情 / 子表), 候选取那些模型字段的并集。例:family 域登记了组与成员两个模型, 因为成员表上的 real_name / phone 才是要管的那个。

配置期就拒三件事

ReplaceRoleFieldPolicies 在保存时就拒:

拒什么 为什么
业务域不存在 配了也不会生效(域压根不受这层管)
字段不在该域的候选里 规则作用在一个不存在的键上 ⇒ 静默不生效
masked 但猜不出打码方式 运行期兜底是整串打码,管理员会看到一堆意料之外的星号

⚠️ 后端拒的是整组(一个字段不合法 ⇒ 这个域的这次 PUT 全废), 所以前端也先拒一遍,好让错误精确落在那一行上 (web/src/pages/system/role/fieldPolicyRules.ts 的 findPolicyIssues)。

使用方法

纯原语用法(不碰 DB)

rules := []fieldpolicy.Rule{
    {Field: "phone", Mode: fieldpolicy.ModeHidden},
    {Field: "real_name", Mode: fieldpolicy.ModeMasked, MaskType: fieldpolicy.MaskName},
}
p := fieldpolicy.NewPolicy(rules)

out, changed, err := p.ApplyJSON(raw)
if err != nil {
    return nil, err
}
if !changed {
    return raw, nil   // ⚠️ 没改过 ⇒ 原样返回,响应逐字节不变
}

叠加:默认组 + 业务域组

def := fieldpolicy.NewPolicy(defaultRules)
mod := fieldpolicy.NewPolicy(moduleRules)
effective := def.Overlay(mod)

⚠️ Overlay 的方向不能反 —— 后者优先(业务域组覆盖默认组), 且只覆盖它自己写了规则的字段。

接到响应上(M163)

⚠️ 为什么落在响应出口,而不是每个业务 service —— 逐个业务 service 加一行 ⇒ ① 漏一个接口 = 那个接口的敏感字段裸奔 (没有任何报错);② 每个 service 都要多一个参数,业务代码被框架污染。

⇒ 收口在 BaseHandler.OK / OKWithMessage / Page / PageWith —— 每个 handler 都经过这几个出口。

// internal/api/handler/field_policy.go
raw, changed, err := h.maskData(c, data)
if err != nil {
    h.Fail(c, err)   // ⚠️ 闭:宁可报错,不许悄悄放行
    return
}
if !changed {
    // 原样渲染
    return
}

⚠️ 失败一律"闭" —— 脱敏失败时原样返回 = 一次数据库抖动就把敏感字段放出去, 而且日志里一条痕迹都没有。⇒ 这一层出错直接 500。

⚠️ "没配规则 ⇒ 响应逐字节不变" —— 没配规则 / 规则没命中 / 这个域不受管 ⇒ 一律走原来的渲染路径, 不重新序列化(重新序列化会打乱键序,让响应"每次都不一样"没法比对)。

⚠️ 业务域从 Hertz 的 KV 取(scope.ModuleKey)—— ctx 里那份是派生 ctx,响应出口读不到。

✅ 出口绕不过去:机械守卫(M167)

⚠️ 上面那句"每个 handler 都经过这几个出口"曾经是一句手工核对过的话 ——

// 某个新 handler
c.JSON(200, rows)     // 写得很自然,编译器不报错,评审也可能一眼滑过去

⇒ 响应照常返回,该脱敏的字段原样上 wire,而且没有任何报错。

⇒ M167 把它变成一条断言:internal/api/handler/outlet_guard_test.go 扫源码(go/ast,不碰注释),把"实际写了响应的地方"和"账本上登记的豁免"对账。

判据 说明
扫哪些 internal/api/ 整棵树(handler / router / middleware)—— 绕过出口不只发生在业务 handler 里
算什么"写了响应" c.JSON / c.String / c.Data / c.Render / c.Redirect / c.Write / c.Response.SetBody* / fmt.Fprintf(c, …) / io.Copy(c, …) / response.OKWithData 一类
怎么认出 c 靠类型(*app.RequestContext),不靠变量名 —— 变量叫 c / ctx / rc 都行
什么算正当 pkg/response 的业务出口调用,只在这五个出口函数体内才算正当(挪出去就红)

⚠️ 豁免是账本,不是逃逸名单 —— 每条都要写清"为什么它可以绕过", 而且条数是精确值(同一个函数里再加一处 ⇒ 红)。

今天账本上有 10 条,三类:

  • 健康检查 / 就绪探针(health.go)—— body 里只有依赖状态,没有业务行
  • 文件字节流(file.go)—— 二进制,不是 JSON 业务行
  • SSE 通道(event.go)—— 载荷只有信号(未读数增量 / 审批动作名 / 字典 group_code); ⚠️ 若将来往 payload 里塞业务行,这一条就失效了,必须改走出口
  • 路由层的 /version(router.go)—— 构建信息快照
  • 中间件的三个写入点 —— 413 错误体 / 幂等 409 与缓存重放 / gzip 把已写好的 body 换成压缩后的字节

⚠️ 两个方向都要查 ——

  • 扫出来的每一处,账本上必须有(否则:新写的 handler 悄悄绕过了出口)
  • 账本上的每一处,必须真的还在、条数对得上(否则:过期条目会让人以为"有人管过")

大整数不丢精度

⚠️ UseNumber 是必须的,不是优化 —— sonyflake 主键是 17 位数(当前 ≈9.7e16),超出 float64 的 2^53 精确整数范围。 走 float64 中转 ⇒ 尾数被静默截断 ⇒ 前端拿到的是另一个 id ⇒ 按那个 id 查详情 404。

⇒ ApplyJSON 用 json.Decoder + UseNumber(),json.Number 保留原始字面量。

配规则的界面(M164)

角色管理页行内动作「字段可见性」⇒ 抽屉:

  • 左侧业务域菜单(默认规则组排第一,带规则条数)
  • 右侧字段表(可见性 / 打码方式 / 备注)
  • 三条语义提示直接写在页面上:逐字段叠加、隐藏 = 删键、打码要选方式

⚠️ 业务域与字段候选一律来自后端,前端不许手打 —— 域配错 ⇒ 规则落到默认组 ⇒ 静默失配; 字段名配错 ⇒ 作用在不存在的键上 ⇒ 静默不生效。

⚠️ 「跟随默认组」与「明文可见」是两件事 —— "没有规则" = 继承默认组的限制;"显式 visible" = 覆盖默认组的限制。 改回「跟随默认组」= 删掉这条规则(发空数组),不是发一条 visible。

⚠️ 表里渲染"候选 ∪ 已配规则的字段" —— 已配但字段已不在候选里的旧规则(比如动态集合删了那个字段)看不见 ⇒ 管理员删不掉它 ⇒ 每次保存都被后端拒。

注意事项

⚠️ 本包只做"收窄",不做"放宽"

能把一个已经在响应里的字段打码或删掉; 不能把一个本来就不在响应里的字段(如 json:"-" 的加密手机号)变出来。

⇒ 要让某个角色看到某个字段,得业务侧先把值放进响应 —— 那是业务决定,不是框架决定。

⚠️ "不配 = 全部可见"是默认语义

与行级数据范围同一条约定:规则层上线不改变任何现有响应。 没配规则 ⇒ 字段原样返回(与框架落地前逐字节相同)。

⚠️ 这不是"默认拒绝" —— 若改成默认拒绝,上线当天每个接口的响应都会变形。

✅ 两个登记表之间的交叉守门网(M166)

登记表 管什么
bizScopeSpecs / bizScopeCtxWired 行级:哪些业务域有行级范围
bizFieldDomains 字段级:哪些业务域的响应受字段规则管

两张表说的是同一组业务域(今天 19 个,逐字相同)⇒ 两个方向都得有网:

方向 守它的网
字段层 ⊆ 行级层 TestBizFieldDomain_每个域都在行级账本里
行级层 ⊆ 字段层 CheckFieldPolicyWiring()(启动期 fail-fast)+ 同名单测

⚠️ 反方向曾经没有网 —— 行级账本里新增一个业务域而没登记进字段层 ⇒

  • 该域不受字段级可见性管(fieldPolicyDomainSupported 早退)⇒ 响应完全不过脱敏
  • 管理员也配不出来(配置期会拒"业务域不存在")
  • ⇒ 配了不生效,没有任何报错,页面看起来一切正常

⇒ M166 补上:CheckFieldPolicyWiring() 在启动期就 fail-fast(cmd/server/main.go), 单测用假账本直接喂"漏登记"的场景 —— 不改包级变量(改了要恢复, 漏一次就把后面的用例带歪)。

⚠️ 网本身有人守还不够,"网还在不在跑"也要有人守 —— cmd/server/main_startup_check_test.go 扫源码:启动检查被删掉、 或 log.Fatal 被换成 log.Warn ⇒ 用例红。

⚠️ 判据是"有没有业务行",不是"有没有敏感字段" —— 一个域今天没有手机号,不等于它永远没有;模型加一个字段,没人会记得回来登记。

✅ 前端消费那一半(M168)

服务端这一半已经完整:规则层(M162)+ 执行层(M163)+ 配置界面(M164)。 这一节是业务页消费这份规则的那一半 —— 它解决的症状:

  • 服务端"隐藏"= 删键 ⇒ 前端拿到的响应里根本没有那个键 ⇒ 表格的列定义还列着它 ⇒ 列还在,格是空的
  • 表单里那个字段也还显示 ⇒ 用户还能把打码后的值原样提交回去 (138****1234 覆盖真实手机号)—— 这是数据损坏,不只是难看

⚠️ 核心纪律:报告由执行层算,前端只读

前端若自己拿"规则表"再算一遍,就多了一份实现 —— 与服务端那份漂移时, 表现是"界面说有这列、后端说没有"或反过来(后者是泄露)。

⇒ 显示层不许自己算,必须读执行层给的权威字段(与 M149 同一条纪律)。

传输方式:响应头 + Symbol 戳

① 响应头 —— 服务端在响应出口算好报告,随响应带回来:

X-Field-Policy: hidden=phone,id_card;masked=real_name
  • 只在配了规则时才有这个头(没配 = 逐字节不变,连头都不多)
  • 规则配了但这次响应里没有那个字段,头照样有 —— 报的是"规则说了什么",不是"这次响应里改了什么"; 前端要的是"这一列该不该存在",不是"这一次有没有动过它"
  • 含分隔符(,;=)的字段名会被丢掉(兜底;字段名来自 json tag / 动态集合的 field_key,本来就校验过不含这些字符)
  • ⚠️ 必须列进 CORS 的 ExposeHeaders —— 跨域时浏览器只把白名单里的 响应头暴露给 JS,不列 ⇒ 前端读出来恒为 undefined,不报任何错。 见 router.go 的 corsConfig(有 cors_config_test.go 守着)。

② Symbol 戳 —— 前端在 axios 拦截器里把报告盖到 resp.data.data 上 (web 的 utils/fieldPolicy.ts):

  • Symbol.for('rapid-admin.fieldPolicy'),enumerable: true —— 对 Object.keys / JSON.stringify / for...in 全部隐身 (报告不会漏进请求体、日志、DOM), 但能被 {...row} 展开复制(页面经常把行对象展开成初始值, 不可枚举的话展开一次报告就丢了)
  • 递归盖章(信封、列表、每一行、嵌套对象),带深度上限 + seen 集合防环
  • 响应头只在这一个地方能拿到(拦截器是唯一看见原始响应的层), 所以业务页面一行都不用改

界面怎么消费(web 的 components/common/fieldPolicy.ts,纯函数)

场景 hidden masked
表格列 整列不渲染(列头都不给) 照常显示(值已是打码后的)
表单项 不渲染 照常显示但变只读
详情项 不渲染 照常显示
提交载荷 剔掉 剔掉

⚠️ 打码字段"变只读"还不够,必须从载荷里剔掉 —— antd 的 validateFields() 照样把禁用字段的值收进来; 原样提交 = 用打码值覆盖数据库里的真实值。这是 M168 修掉的半个数据损坏洞。

⚠️ "打码"在界面上不删字段 —— 用户要能看到"这里有个手机号,只是看不全"; 删掉反而让人以为这个字段不存在。

兜底:页面归档

页面对象经常被重新拼(逐字段手抄 initialValues、重拼分页信封), Symbol 戳会丢。⇒ 拦截器把每份报告按请求发起时的页面路径归档一份, 组件从行对象上读不到戳时读归档。

  • 路径对不上 ⇒ 返回 null —— 宁可没有保护,不拿别的页面的规则禁自己的字段
  • 归档套错的代价是"多限制"(字段被多禁用了),不是泄露
  • 归档只在有报告时才更新 —— 没配规则的响应不产生归档

守卫

  • Go 侧:TestOK_响应带字段可见性头 一族(带头的时机 / 没配规则不带 / 规则没命中照样带 / 分页同路 / 编码格式与分隔符兜底)+ TestCORSConfig_暴露字段可见性响应头(白名单)
  • web 侧:utils/__tests__/fieldPolicy.test.ts(解析 / 戳的三条硬性质: 对 Object.keys 隐身、能被展开复制、防环)+ fieldPolicy.test.ts (三个过滤函数 + 载荷剔除)+ client.fieldPolicy.test.ts(拦截器端到端)+ 组件级用例(列 / 表单 / 详情 / 提交载荷)
  • 可逆探针已跑:拆掉拦截器盖章、拆掉载荷剔除,对应用例变红;复原后全绿

⚠️ 隐藏 ≠ 加密

字段级可见性是出口上的遮蔽,不是存储层的加密。 internal/pkg/crypto 管的是"落库前就加密"。

⇒ 两者互补,不能互相替代:加密管的是库里躺着的那份, 字段级可见性管的是这次响应里露不露。

⚠️ 脱敏是出口上的,不是"每个 service 自己记得遮"

internal/pkg/desensitize 只做日志脱敏(写日志时打码), 不按角色遮字段。前端那个 SensitiveField 组件是"所有人一起打码", 也不是"按角色决定能不能看"。

⇒ 按角色决定可见性的唯一通道是本篇这一层。

⚠️ 规则唯一键是 (role_id, module, field)

同一角色同一业务域上,一个字段只能有一条规则 ⇒ 写接口是全量替换,增量加进来会撞唯一索引。

⇒ 落库时是硬删(软删的墓碑会挡住唯一索引,第二次保存同一个组合就撞 UNIQUE)。

相关

  • scope —— 数据范围(行级权限):同一套"三轴"里的第二根
  • desensitize —— 日志脱敏(与"按角色遮字段"是两件事)
  • crypto —— 字段级加密(存储层,与出口遮蔽互补)
  • casbinx —— 接口级 RBAC 的实现(第一根轴)
  • 可运行示例:examples/fieldpolicy/main.go —— go run ./examples/fieldpolicy

results matching ""

    No results matching ""