scope —— 数据范围(行级权限):规则 → 作用域 → WHERE
RBAC 回答"这个角色能不能调这个接口"。 放行之后返回多少数据,是每个业务 service 自己写 filter 决定的。 scope 补的就是这一层:这个角色能看哪些行。
功能
scope 做三件事,不多不少:
- 定义数据范围的类型 —— 全部 / 本项目 / 本部门 / 本部门及下级 / 仅本人 / 自定义
- 把「角色上的规则 + 当前调用者」解析成一个具体的
Scope - 把
Scope翻译成一段 WHERE 条件(Apply走 GORM 链式,ApplySQL走裸 SQL)
五样东西:
| 类型 | 是什么 |
|---|---|
Type |
范围类型,六种,见下表 |
Rule |
某个角色在某个业务域上启用的一种范围 |
Actor |
当前调用者(有哪些项目、属于哪些部门) |
Scope |
规则 + 调用者解析出来的具体作用域 |
Columns |
目标表上的作用域列(SQL 模板) |
不解决什么:规则存在哪、谁去解析、怎么落到查询上,都不在本包 ——
本包不碰 DB、不 import model、不 import service。
落库与接线在 internal/service/scope.go。
六种范围类型
| 类型 | 含义 |
|---|---|
all |
全部数据(不施加任何行级限制) |
project |
本项目 —— 调用方身份所属的项目 |
dept |
本部门 —— 调用方身份所属的部门 |
dept_and_child |
本部门及下级部门 |
self |
仅本人 —— 只有归属人是调用方自己的行 |
custom |
自定义 —— 指定列的值落在给定集合里 |
四条语义约定(改之前先读这一段)
- 多条规则之间是「或」 —— 角色同时勾了"本部门"和"仅本人", 那它能看本部门的行 + 自己建的行。
- 「全部数据」一票放行 —— 规则里有
all时,其余规则无意义(不被解析)。 - 有限制但一条都表达不出来 ⇒ 匹配不到任何行,绝不能退化成"不过滤"。 (例:"本项目"规则 + 调用方一个项目都没有 ⇒ 他一条都看不到, 而不是"他能看到全部"。后者是安全事故。)
- 规则里点名的列在目标表上不存在 ⇒ 报错,不静默丢弃那条子句。 丢一条子句在"或"组里会让可见集变窄(不是变宽), 但那同样是错的 —— 用户会莫名看不到自己该看的数据。
配置
没有 yaml 配置项
本包是纯原语,不读配置、不连外部依赖。
需要配置的是业务侧的两处:
// 1. 目标表上的作用域列 —— 三个都是 SQL 模板,各带恰好一个 `?` 占位符
scope.Columns{
Project: "project_id IN ?",
Dept: "dept_id IN ?",
Self: "owner_id = ?",
}
// 2. 部门子树解析器 —— 「本部门及下级」要用,由上层注入(本包不碰 DB)
scope.Actor{
UserID: 1001,
ProjectIDs: []uint64{7, 9},
DeptIDs: []uint64{3},
DeptSubtree: func(ids []uint64) ([]uint64, error) { ... },
}
⚠️ 为什么给模板而不是裸列名 —— 用户与部门的归属关系不一定是表上的一个列。
用户表 sys_user 的部门是多对多(sys_user_department),没有 dept_id 列
⇒ 只能写成子查询:
Dept: "id IN (SELECT user_id FROM sys_user_department WHERE dept_id IN ?)"
⚠️ 模板由框架代码提供,不是管理员填的 —— 管理员能填的只有"自定义范围"的列名
(走 ValidateCustomColumn 校验)。自定义范围不走 Columns。
使用方法
纯原语用法(不碰 DB)
rules := []scope.Rule{
{Type: scope.TypeDept},
{Type: scope.TypeSelf},
}
actor := scope.Actor{
UserID: 1001,
DeptIDs: []uint64{3},
}
// 多条规则之间是「或」⇒ 本部门的行 + 自己建的行
sc, err := scope.Resolve(rules, actor)
if err != nil {
return err
}
fmt.Println(sc.Describe()) // "本部门(1 个) 或 仅本人"
接到 GORM 查询上
tx := db.Model(&Order{}).Where("status = ?", 1)
tx, err = scope.Apply(tx, &sc, scope.Columns{
Project: "project_id IN ?",
Dept: "dept_id IN ?",
Self: "owner_id = ?",
})
if err != nil {
// ⚠️ 规则要求的列在这张表上不存在 —— 必须响亮失败
return nil, err
}
Apply 的三条语义:
| 情况 | 结果 |
|---|---|
没有任何限制性规则(Restrictive=false) |
原样返回 tx,不过滤 |
| 有限制性规则但一条子句都表达不出来 | 匹配不到任何行(1 = 0) |
| 规则要求的列在目标表上不存在 | 报错 |
⚠️ 第二条是安全方向上的关键区别 —— 退化成"不过滤"就是安全事故。
接到裸 SQL 查询上(自己拼 WHERE 的场合)
Apply 只吐 GORM 链式。动态业务集合(dyn)的数据面是裸 SQL ——
自己拼 WHERE a = ? AND b = ? 再 db.Raw(sql, args...)。
两套写法接不上 ⇒ 数据范围这层对它是完全不生效的。
⇒ ApplySQL 给一段 SQL 片段 + 一组参数,调用方自己拼:
frag, args, err := scope.ApplySQL(&sc, scope.Columns{
Project: "project_id IN ?",
Dept: "dept_id IN ?",
Self: "owner_id = ?",
})
if err != nil {
return err
}
if frag != "" {
sql := "SELECT * FROM demo_row WHERE " + frag + " ORDER BY id"
rows, err := db.Raw(sql, args...).Rows()
}
⚠️ 返回空串 = "不过滤";"1 = 0" = "看不到任何行" —— 两者都可能出现,
调用方必须分得清。把 1 = 0 当成空串 ⇒ 数据越权(而且没有任何报错)。
⚠️ 参数与占位符一一对应,顺序不能错 —— 拼进一条更长的 SQL 时, 参数必须放在对应的位置(前面已经有别的参数时,不能直接 append 到末尾)。
⚠️ 别用"两个平行切片"装条件和参数 ——
// ⚠️ 这种写法要求"两边的 append 顺序必须一直对齐",
// 而加一条带自己参数的条件(比如上面那个片段)时,顺序极容易错。
// 而参数错位**不报错**,只是查出错的数据 —— 甚至查到别人的行。
where := []string{"deleted_at IS NULL"}
args := []any{...}
⇒ 一条条件带一组参数,最后再摊平(dyn 侧的做法,见 internal/service/dyn_records.go):
type cond struct {
sql string
args []any
}
⚠️ 数据范围片段要 AND 在最后,参数跟着它自己走 —— 别把片段的参数
直接 append 到整条 SQL 的参数末尾(那要自己数前面占了多少个 ?)。
⚠️ 两个出口由同一个函数编译 —— Apply 与 ApplySQL 不会漂移。
这不是"实现细节",是安全要求:漂移的后果是"GORM 那条路过滤了、
裸 SQL 那条路没过滤",而两条路都跑得好好的,没有任何报错。
等发现的时候,已经有一批数据被越权看过了。
业务域(module)从 ctx 里读
业务域不在参数里传 —— 它由"判定权限的那一层"写进 ctx:
// 路由层:rbac("user", "list") 放行时写入
ctx = scope.WithModule(ctx, "user")
// service 层:只管读
module, _ := scope.ModuleFromContext(ctx)
两处拼同一个字符串必然漂移(一处改了另一处没改), 所以业务域由知道它的人提供:路由层写,service 层读。
规则存哪、怎么配
规则落在 sys_data_scope,唯一键 (role_id, module, scope_type) ——
同一角色同一业务域上"本部门"只能有一条。
// 列出某角色配的全部规则(所有业务域)
rules, err := scopeSvc.ListRoleScopes(ctx, roleID)
// 全量替换某角色在某业务域上的规则
err = scopeSvc.ReplaceRoleScopes(ctx, roleID, "user", []service.ScopeRuleInput{
{ScopeType: "dept"},
})
// 可配置的业务域候选(后台下拉框用)
mods, err := scopeSvc.ListModules(ctx)
⚠️ 写接口是"全量替换",不是"增量" —— 发过来的那组就是该业务域上的全部规则, 发空数组 = 清空该域的规则。
⚠️ module 为空串 = 默认规则组 —— 某业务域没单独配规则时回落到它; 某业务域单独配了规则,就完全用这一组,默认组不参与(两组不是叠加,是"就近覆盖")。
业务域候选为什么不能前端手打
sys_resource.code 是 module + ":" + action 拼出来的,
而 module 本身可以含冒号,action 也可以含冒号:
rbac("audit:operation", "list") → code "audit:operation:list"
rbac("job", "run:read") → code "job:run:read"
rbac("dyn", "design:collection:create") → code "dyn:design:collection:create"
⇒ 从资源码反推 module 是不确定的 —— "audit:operation:list" 的 module 是 "audit:operation" 还是 "audit"?两种切法都能自圆其说,而切错的代价是静默的:
规则配在 "audit" 上,运行时注入的是 "audit:operation"
⇒ 规则不命中 ⇒ 回落默认组 ⇒ 不过滤
⇒ 该角色看到了本该看不到的行,日志里一条痕迹都没有。
⇒ module 只能由知道它的人提供。本包用一张登记表(module.go)把它记下来:
// 路由注册期
scope.RegisterModule("audit:operation")
// 运行期读
mods := scope.RegisteredModules()
登记在启动期(路由注册),读取在运行期(后台页面开下拉框),两者会重叠 ⇒ 登记表是并发安全的,且返拷贝不返内部 map。
⚠️ 空串不登记 —— 空串是"默认规则组",它不是一个业务域,由 service 层单独处理。
动态业务集合的数据面不在登记表里
dyn 的数据面模块是 dyn:<集合编码> —— 那个字符串由请求路径参数决定,
注册期拼不出来(设计面 rbac("dyn", ...) 的 module 是 "dyn",两者是不同的数据域)。
⇒ 数据面那一族由 dyn handler 在请求期写进 ctx,
候选列表由 service 从 sys_dyn_collection 现算。
业务查询接上数据范围(M161)
M155-M160 把"规则层"做出来了(配得到、算得出、落得下), 但没有一个业务查询真的调用它 ⇒ 规则配了也不生效。 这一节讲的就是"真的调用它"的那一层。
三张账本 —— 哪些业务域有行级范围
internal/service/biz_scope.go 是唯一真相源,三张账本:
| 账本 | 是什么 | 谁在用 |
|---|---|---|
bizScopeSpecs |
业务表(受某张表管) | applyBizScope(ctx, scopeSvc, tx, module) |
bizScopeCtxWired |
走 ctx 业务域那条路 | scopeService.Apply(ctx, tx, cols);连列模板变量的名字一起登记(守门网要核对它还在、且真被 applyScope 用上) |
bizScopeUnwired |
明确没有行级范围 + 原因 | 只是账(启动期核对用) |
⚠️ bizScopeUnwired 是账本,不是逃逸名单 ——
每一项都必须写清"为什么它没有行级范围"。
"忘了"不是理由,那是缺口。
⚠️ 路由层新增一个业务域却没在三张账本里登记 ⇒ 启动失败 ——
service.CheckScopeWiring() 在 cmd/server/main.go 里调,
不过就 log.Fatal。
漏登记的后果是静默不过滤:管理员在后台给那个业务域配的规则 永远不生效,而且没有任何报错、没有日志。
接线是声明式的,不是"顺手加一行"
每张业务表都要在 bizScopeSpecs 里登记三件事:
{
module: "activity", table: "activity",
project: "project_id IN ?",
dept: "created_by IN (SELECT user_id FROM sys_user_department WHERE dept_id IN ?)",
self: "created_by IN ?",
},
为什么必须登记,而不是在每个 service 的 List 里随手写一行 scope.Apply:
- "忘了接"是这种机制最常见的失败模式 —— 新加一个业务列表忘了接, 它看起来正常(不过滤),而管理员配的规则对它不生效,一行报错都没有。
- 业务域字符串会漂移 —— 路由层写
rbac("order", "list"), service 层写applyBizScope(..., "order"),两处各写一个字面量。 改一处忘另一处 ⇒ 规则静默失配 ⇒ 回落默认组。 - 维度能力因表而异 —— 有的表有
project_id,有的没有; 有的表有"谁建的",有的只有"谁处理的"。 不登记就没法告诉管理员"这一维在这张表上落不下去"。
⚠️ 业务域现算,不从 ctx 读 —— ctx 里那个是 RBAC 的业务域(判定"能不能调这个接口"用的), 而数据范围配的是这张业务表。两者多数时候同名,但不是同一件事。
各表能表达哪几维
开源版实际登记了哪些业务域,以
internal/service/biz_scope.go的三张账本为准 (guide是随仓库的示例业务表)。下表是示例账本,演示不同形态的表 在三个维度上的典型表达(有独占列的 / 靠反查的 / 什么维度都表达不出来的):
| 业务域 | 表 | 本项目 | 本部门 | 仅本人 |
|---|---|---|---|---|
order |
biz_order |
✅ | ✅ created_by |
✅ created_by |
invoice |
biz_invoice |
— | ✅ handler_id |
✅ handler_id |
order_item |
biz_order_item |
✅ 主单反查 | — | — |
guide |
guide |
✅ | ✅ created_by |
✅ created_by |
⚠️ 业务表通常没有 dept_id 列 —— 部门的归属关系在 sys_user_department 里
⇒ 本部门 = "行归属人在本部门" ⇒ 落成子查询。
⚠️ 归属人列不一定是"创建人" —— 有的表根本没有创建人列,只能落在"当前归属人"上(处理人 / 派单对象 / 提交人 / 发布人)。
⚠️ 「本项目」在有的表上是反查出来的 ——
明细/子表按主单反查(order_id IN (SELECT id FROM biz_order WHERE …)),
成员按"用户-组绑定"反查。
落不下去 ⇒ 响亮报错,不静默跳过
checkDims 在值解析出来之后检查:
这一维有值、而这张表没有对应的列 ⇒ 报错,消息里点名业务域 + 表 + 维度。
业务域 invoice(表 biz_invoice)不支持「self」数据范围
⚠️ 判据是"解析出来的取值",不是"规则里写了什么" ——
「本部门」规则 + 调用方没有部门 ⇒ 解析出来的 DeptIDs 是空的
⇒ 这一维不产生任何子句 ⇒ 匹配不到任何行(安全方向);
而调用方有部门 ⇒ 表达不出来 ⇒ 报错。
同一条规则,不同的人看到的结果不同(一个报错、一个空列表),这是刻意的: 报错的那些人是"配置真的坏了",空列表的那些人是"他本来就没有可见数据"。
配置期就拒(ReplaceRoleScopes)
模块级的规则在保存时就校验"这一维在这个业务域上落不落得下去", 配不出来当场报错,而不是等到用这条规则的人查询时才炸。
⚠️ 默认规则组(module="")不校验 —— 它同时管着所有"没单独配规则"的业务域,而各张表能表达的维度不一样 ⇒ 在这里按"所有表的交集"校验会把默认规则组几乎废掉 (能剩下的只有「全部数据」和「自定义」)。
⇒ 默认组里配了某个业务域表达不出来的维度时, 那个业务域的查询会响亮报错(消息里点名是哪个业务域、哪张表、哪一维)。
列表与单条都要接
⚠️ 只过滤列表的话,用户可以按 id 打开一条他看不见的记录 —— 那等于行级权限只挡了"翻页",没挡"直取"。
⇒ 每个业务查询的 Get 方法也调 applyBizScope(列表 + 单条成对接线,一处都不能少)。
有个容易踩的坑:有的查询有两条链(主查询 + 兜底查询),
兜底那条必须重新起一条链 —— 复用同一条 tx 会把上面那条
status = 1 也带过来(GORM 的链式条件是累加的)。
⚠️ "子查询"也受管 —— 组-成员关联表(biz_group_member)自己没有任何维度
(只有 group_id)⇒ 它的可见性挂在它所属的组上。
不查这一层 ⇒ 知道 groupId 就能列出看不见的组的成员
(成员里有姓名、关系、权限位 —— 比组本身更敏感)。
⚠️ 两条守门网:"登记了"不等于"接上了"
数据范围最贵的失败模式是静默失效 —— 规则配得出、后台看得到、 运行时却根本不查。这类洞光靠人记得接是守不住的,所以有两条网:
| 网 | 在哪 | 抓什么 |
|---|---|---|
CheckScopeWiring() |
启动期(cmd/server/main.go) |
路由层新加的业务域没在三张账本里登记 |
biz_scope_wiring_test.go |
测试期(扫源码) | 账本里登记的业务域在业务查询里根本没被调用 |
⚠️ 第二条网是被一个真 bug 逼出来的 ——
第一版把一个业务域登记进了 bizScopeSpecs,
而它对应的 service 文件里一行 applyBizScope 都没有:
后台候选列表里出现了这个域,管理员配得出规则,
运行时永远不查 ⇒ 配了也不生效,一行报错都没有。
⚠️ 启动期那条网抓不到它 —— 启动期只比"路由登记的业务域"与"三张账本",
而那个业务域两边都在(路由有 rbac(..., ...),账本也登记了)
⇒ 账本自洽,接线却不存在。
⇒ "接上了"这件事只能扫源码验:账本里的每个业务域,
都必须真的有一处 applyBizScope(ctx, s.scope, tx, "<模块>") 调用。
扫源码用
go/parser+go/ast,不用正则 —— 正则会撞上注释里的假调用点、字符串里的//、跨行调用这三种情况。
⇒ 现在这条网是红的才算有问题(它当场抓住了那一处)。
后端候选列表只列"接了"的
GET /system/scope-modules 以前把路由层登记的全部业务域都列出来,
大部分是平台域(角色 / 字典 / 配置 / 短信模板……)——
它们没有业务行,配数据范围永远不生效。
⇒ 现在只列真接了的(bizScopeSpecs / bizScopeCtxWired / dyn:<编码>)。
没接的那些在 bizScopeUnwired 里有账,启动期 CheckScopeWiring 会核对。
⚠️ 每个候选还报得出"自己支持哪些维度"(supported_types)——
前端按它过滤维度下拉框。
不按它过滤,就是让管理员配一个注定被拒的组合
(用户看到的是"我明明能选",点保存却报错)。
⚠️ 默认规则组给的是"所有已知业务域的交集" —— 默认组的规则会在每个业务域上各自求值, 取并集就会出现"某些表表达不出来"的维度 ⇒ 那些业务域的查询直接报错。
注意事项
⚠️ 规则层上线不改变任何现有查询的结果
没配任何规则 ⇒ EffectiveScope 返回零值 Scope(不限行,等于"全部数据")。
这是有意为之:规则层是一个收窄层,铺在 RBAC 之上。
⚠️ 如果改成"默认拒绝"(像 PocketBase 那样),上线当天每个列表都会是空的 —— 因为一张规则表都还没配。这是"收窄层"与"默认拒绝"两种模型的本质区别, 本仓选前者。
⚠️ All 与 Restrictive 是两件事,别混
All—— 规则里明确写了"全部数据"Restrictive—— 存在至少一条限制性规则(非 all)
二者都不会同时为真(有 all 就直接短路了)。
Restrictive=true 而所有子句都为空 ⇒ 匹配不到任何行。
⚠️ 自定义列名要在保存时也校验
ValidateCustomColumn 是防 SQL 注入的一道闸(必须是裸标识符,不许是表达式)。
解析时校验不够 —— 解析发生在"用这条规则的人"身上,保存发生在"配这条规则的人"身上。
前者校验 ⇒ 配错的人当场看不到报错,只有受害者(用规则的人)查询时才炸,
而且错误信息离现场十万八千里。
⇒ 保存时也要调它。
⚠️ 空列表 ≠ 全部
type Actor struct {
ProjectIDs []uint64 // 空列表 = 一个项目都没有(不是"全部")
DeptIDs []uint64 // 空列表 = 一个部门都没有(不是"全部部门")
}
框架里"空 = 全平台"是 identity.project_id = 0 的语义,
而 collectProjectIDs 把 0 过滤掉了
⇒ 调用方拿到的 ProjectIDs 为空,只可能是"没有项目身份"。
⇒ 这里不能沿用"空 = 全平台",否则"本项目"会退化成"看全部"。
⚠️ DeptSubtree 的入参是列表不是单个 id
用户可能同时属于多个部门,"本部门及下级"要把这些部门各自的子树并起来, 传单个 id 会漏掉其余部门的下级。
⚠️ 规则唯一键是 (role_id, module, scope_type)
同一角色同一业务域上"本部门"只能有一条。 所以写接口是全量替换 —— 增量加进来会撞唯一索引。
⚠️ Scope 按指针传
Scope 有四个切片,按值传就是 104 字节的拷贝(gocritic hugeParam 会报)。
Apply / Empty / Describe 都用指针接收者。
⚠️ 动态集合的数据面:只有「归属人」一维
dyn 的数据面已经接上这层了(M160)—— 走的就是上面那个 ApplySQL 出口。
但它只有一维:
| 维度 | dyn 上能不能用 | 为什么 |
|---|---|---|
| 仅本人 | ✅ | 物理表有 owner_id 列 |
| 自定义 | ✅ | 列名填物理列名(如 f_project) |
| 本项目 | ❌ | 物理表没有 project_id 列 |
| 本部门 | ❌ | 物理表没有 dept_id 列 |
⚠️ 表达不出来的那两维会报错,不是静默跳过 ——
丢掉"或"组里的一个分支,可见集是变窄的(方向上安全,但仍然是错的: 管理员配的"本项目 或 仅本人"被悄悄改成"仅本人",他看不到任何报错)。 真正危险的是丢掉最后一个分支 —— 那时整段过滤变成"不过滤" ⇒ 可见集 = 全部行 ⇒ 数据越权。 而"角色只配了一条规则"恰恰是最常见的配置 ⇒ 最容易踩中的正是最危险的那一种。
所以 dyn 侧提前拦下来,给出能指到问题的话:
集合 inspection 配了「本项目」数据范围,但动态集合的物理表没有项目/部门维度的列(只有归属人 owner_id 一维)
⚠️ 判据是"解析出来的取值",不是"规则里写了什么" —— 「本部门」规则 + 调用方没有部门 ⇒ 这一维不产生任何子句 ⇒ 匹配不到任何行(安全方向);而调用方有部门 ⇒ 表达不出来 ⇒ 报错。 同一个错误配置,不同的人看到的结果不同,这是刻意的。
⚠️ 「仅本人」与 owner_scoped 是两回事,别混 ——
| 来源 | 对超管 | |
|---|---|---|
owner_scoped |
集合设计里的一个开关 | 放行(写死的特例) |
| 数据范围「仅本人」 | 角色上的规则 | 不豁免(超管这个角色没配规则就不过滤) |
两者是且的关系:两条都成立才看得见。
⚠️ 数据范围也必须落在单条上,不能只落在列表上 ——
只过滤列表的话,用户仍然可以按 id 打开一条他看不见的记录。
GetRecord / UpdateRecord / DeleteRecord 走的是同一个 recordScope,那里也接了。
⚠️ 业务域用集合编码现算,不从 ctx 读 ——
dyn 的 service 方法自己就知道集合编码(code 参数),
而 ctx 里有没有业务域取决于调用方走没走 handler。
直接调 service 的场景 ctx 里没有 ⇒ 读到空串 = 回落"默认规则组"
⇒ dyn:<编码> 上配的规则整组不生效,而且没有任何报错。
⚠️ 设计面(集合/字段管理)不受数据范围管 ——
它管的是框架配置(有哪些集合、哪些字段),不是业务行。
它的闸门是功能权限(dyn:design:* 那套资源码),
与行级权限是两回事。
⚠️ 默认规则组(module="")对 dyn 一样生效 ——
dyn:<编码> 没单独配 ⇒ 回落默认组 ⇒ 默认组里那条规则对 dyn 集合也管用。
配之前想清楚:默认组一动,所有业务域(含用户列表、操作日志)一起动。