scope —— 数据范围(行级权限):规则 → 作用域 → WHERE

RBAC 回答"这个角色能不能调这个接口"。 放行之后返回多少数据,是每个业务 service 自己写 filter 决定的。 scope 补的就是这一层:这个角色能看哪些行。

功能

scope 做三件事,不多不少:

  1. 定义数据范围的类型 —— 全部 / 本项目 / 本部门 / 本部门及下级 / 仅本人 / 自定义
  2. 把「角色上的规则 + 当前调用者」解析成一个具体的 Scope
  3. 把 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 自定义 —— 指定列的值落在给定集合里

四条语义约定(改之前先读这一段)

  1. 多条规则之间是「或」 —— 角色同时勾了"本部门"和"仅本人", 那它能看本部门的行 + 自己建的行。
  2. 「全部数据」一票放行 —— 规则里有 all 时,其余规则无意义(不被解析)。
  3. 有限制但一条都表达不出来 ⇒ 匹配不到任何行,绝不能退化成"不过滤"。 (例:"本项目"规则 + 调用方一个项目都没有 ⇒ 他一条都看不到, 而不是"他能看到全部"。后者是安全事故。)
  4. 规则里点名的列在目标表上不存在 ⇒ 报错,不静默丢弃那条子句。 丢一条子句在"或"组里会让可见集变窄(不是变宽), 但那同样是错的 —— 用户会莫名看不到自己该看的数据。

配置

没有 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:

  1. "忘了接"是这种机制最常见的失败模式 —— 新加一个业务列表忘了接, 它看起来正常(不过滤),而管理员配的规则对它不生效,一行报错都没有。
  2. 业务域字符串会漂移 —— 路由层写 rbac("order", "list"), service 层写 applyBizScope(..., "order"),两处各写一个字面量。 改一处忘另一处 ⇒ 规则静默失配 ⇒ 回落默认组。
  3. 维度能力因表而异 —— 有的表有 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 集合也管用。 配之前想清楚:默认组一动,所有业务域(含用户列表、操作日志)一起动。

相关

  • authz —— 资源级鉴权(接口级 RBAC 之外的第二层)
  • casbinx —— 接口级 RBAC 的实现
  • dynx —— 动态业务集合(数据面已接数据范围)
  • 可运行示例:examples/scope/main.go —— go run ./examples/scope

results matching ""

    No results matching ""