Documentation
¶
Overview ¶
Package scoper 提供行级数据可见性规则的单源插件(#102):同一份规则定义 同时驱动 SQL WHERE 面(GORM scope)与内存判定面(CheckScope 形态), 消除「SQL 侧手搓 WHERE 变体 + 服务层 if 同规则两处维护」的双轨漂移面 ——规则改动要两处同步、SQL 侧列名字符串拼接无类型保护、拼错编译期不可发现。
规则形态覆盖消费方实证的「admin 全量 / 其余仅本人 + 内置行可见」矩阵:
rule := scoper.NewRule[Task]("uid", func(t Task) int64 { return t.UID },
scoper.WithBuiltinRows("is_builtin", true, func(t Task) bool { return t.Builtin }))
// SQL 面:与既有仓储形态共存(Scopes 非侵入)
db.Scopes(rule.Scope(scoper.Subject{UID: uid, Admin: isAdmin})).Find(&items)
// 内存面:同一份规则求值(服务层 CheckScope 的单源替身)
if !rule.Allows(item, scoper.Subject{UID: uid, Admin: isAdmin}) { ... }
与两轨现状的关系 ¶
消费方此前的三变体(ApplyScope / ApplyScopeOrBuiltin / ApplyScopeWithSystem) 在这里是同一 Rule 的两种配置:不配 WithBuiltinRows = 仅本人;配上 = 本人 OR 内置行。admin 旁路在 Subject 上显式声明(role→admin 的解释属调用方)。
fail-closed 契约 ¶
规则未配置完整(ownerColumn 空 / ownerOf nil;配置了 WithBuiltinRows 时 column 空 / match nil,#195)时:SQL 面注入恒假 1=0、内存面恒 false—— 可见性规则缺失时宁可全不可见,绝不无过滤放行(与 crud 包 Query 的 fail-closed 同一纪律)。
Index ¶
Constants ¶
This section is empty.
Variables ¶
This section is empty.
Functions ¶
This section is empty.
Types ¶
type Rule ¶
type Rule[T any] struct { // contains filtered or unexported fields }
Rule[T] 是行级可见性规则的单源定义:admin 全量 / 其余仅本人, 可选内置行(如系统预置数据)对所有人可见。不可变,构造后可并发共享。
func NewRule ¶
func NewRule[T any](ownerColumn string, ownerOf func(T) int64, opts ...RuleOption[T]) *Rule[T]
NewRule 创建行级可见性规则。ownerColumn 是行所有者的**数据库列名** (SQL WHERE 侧直接使用,禁止拼入用户输入);ownerOf 从实体取所有者标识 (内存面),两者必须指向同一语义列。
type RuleOption ¶
RuleOption 配置 Rule 的行为(函数选项模式;不裸用 Option 之名, 避免多包 co-import 冲突)。
func WithBuiltinRows ¶
func WithBuiltinRows[T any](column string, value any, match func(T) bool) RuleOption[T]
WithBuiltinRows 声明内置行可见:非 admin 主体除本人行外还可见 `<column> = <value>` 的行(SQL 面 owner = ? OR column = value; 内存面 ownerOf(row) == uid 或 match(row))。column 禁止拼入用户输入。
column 为空或 match 为 nil 属非法配置:规则**整体**走 fail-closed (SQL 面恒假 1=0、内存面恒 false,#195)——此前不在完整性判定里, match nil 在 Allows 内存面 nil func call 直接 panic、column 空在 Scope SQL 面拼出非法 SQL(500),都不是声明的 fail-closed 形态。