fieldpolicy —— 字段级可见性(列级权限):三态模式 → 逐字段叠加 → 响应出口
RBAC 回答"这个角色能不能调这个接口"。 scope 回答"放行之后能看哪些行"。 fieldpolicy 回答第三个问题:看到的那一行里,哪些字段给他看。
三根轴互相独立,谁也替代不了谁:
| 轴 | 问的问题 | 实现 |
|---|---|---|
| ① 功能权限 | 能不能调这个接口 / 点这个按钮 | Casbin + RBAC 资源码 |
| ② 行级数据范围 | 能看哪些行 | internal/pkg/scope |
| ③ 字段级可见性 | 能看一行里的哪些字段 | internal/pkg/fieldpolicy(本篇) |
⚠️ "能看这一行" ≠ "能看这一行里的每个字段" —— "客服部能看这个客户"同时意味着"客服部能看到客户的手机号", 而后者要不要给,是另一条规则说了算。
功能
fieldpolicy 做四件事:
- 定义字段的可见性模式 —— 三态(明文 / 打码 / 隐藏)
- 定义打码方式 —— 七种,外加"按字段名自动推断"
- 把默认规则组与业务域规则组叠加 —— 逐字段叠加
- 把策略作用到 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