jcasbin 1.99.0 配置参数详解

目标：把 jcasbin 1.99.0 的"配置面"一次讲透——model.conf 五个 section 的每一项参数、policy.csv 的列规则、三种策略效果表达式的实测行为、内置匹配函数清单、Enforcer 构造器与运行期开关。所有结论均在 Ubuntu 22.04（OpenJDK 11 + Maven 3.6.3，jcasbin 1.99.0）实测验证，回显可复现。

一、jcasbin 的"配置"由三部分构成

与常规软件的配置文件不同，jcasbin 的行为配置分三层：

层	载体	决定什么
模型	`model.conf`	请求/策略/角色/效果/匹配器五段定义，即"授权怎么算"
策略	`policy.csv`（FileAdapter 加载）	具体的授权规则数据
开关	Enforcer 运行期 API	enableEnforce、enableAutoSave 等行为开关

模型是"逻辑"、策略是"数据"，二者解耦后换策略无需改代码，换模型无需改数据结构。

二、model.conf 五段参数详解

2.1 request_definition / policy_definition（请求与策略的列定义）

[request_definition]
r = sub, obj, act

[policy_definition]
p = sub, obj, act

r 定义 enforce 请求的参数列，p 定义策略规则的列，列名完全自由（sub/obj/act 只是惯例）。
列数即校验规则：FileAdapter 加载的每行策略必须与 p 列数一致，多一列直接报错（实测）：

invalid policy size: expected 3, got 4, pvals: [alice, data2, write, deny]

jcasbin 与 Go casbin 的关键差异：Go 支持策略行比定义多一列时把多余列隐式当作 p.eft；jcasbin 1.99.0 不支持隐式 eft，要用 deny 语义必须显式写第 4 列：p = sub, obj, act, eft（实测修正后通过）。

2.2 role_definition（角色/分组定义）

[role_definition]
g = _, _            # 用户-角色两元组
g = _, _, _         # 带 domain 的三元组（多租户），如 g, alice, admin, domain1

g 是内置的分组关系表，策略文件里对应 g, alice, data2_admin 这样的行。
匹配器中用 g(r.sub, p.sub) 引用；只要匹配器里用了 g(...)，模型就必须有 role_definition 段，否则运行时报错（实测）：

Function not found: g

支持自定义命名分组（如 g2 = _, _ 用于资源分组），匹配器以 g2(r.obj, p.obj) 引用。

2.3 policy_effect（策略效果，三种实测形态）

# 1) 默认 allow-override：任一 allow 即放行
e = some(where (p.eft == allow))

# 2) deny-override：有 allow 且无 deny 才放行（显式拒绝优先）
e = some(where (p.eft == allow)) && !some(where (p.eft == deny))

# 3) 显式优先级（需配合 [priority_definition]）：数值小的规则优先
[policy_definition]
p = priority, sub, obj, act, eft
[priority_definition]
p = p
e = priority(p.eft) || deny

deny-override 实测（角色 allow + 用户 deny 共存）：

alice, data2, write (role allow + user deny) => false    # deny 覆盖角色 allow
alice, data1, read => true

显式优先级实测（priority 列 10 < 20，数值小者优先）：

alice, data1, read (deny@10 vs allow@20) => false        # 组 deny@10 压过用户 allow@20
bob,   data2, read (allow@10 via group)  => true

三种形态覆盖绝大多数授权场景；jcasbin 亦支持自定义 Effector 扩展更多效果语义（见官方文档）。

2.4 matchers（匹配器表达式）

匹配器是对每个 (请求, 策略) 组合求值的布尔表达式，可用元素：

元素	示例	说明
相等比较	`r.sub == p.sub`	字符串精确匹配
逻辑运算	`&&`、`
分组函数	`g(r.sub, p.sub)`	角色继承判定（RBAC 必备）
keyMatch	`keyMatch(r.obj, p.obj)`	前缀通配：`/foo/*` 匹配 `/foo/bar`，不匹配 `/foo` 本身或 `/foobar`
keyMatch2	`keyMatch2(r.obj, p.obj)`	RESTful 风格：`/api/*` 通配多段，`:id` 只匹配单段
keyMatch3/4/5	`keyMatch3(...)`	更多路径参数风格（`/api/{id}` 等）
regexMatch	`regexMatch(r.act, p.act)`	正则匹配，如 `GET\|POST`
globMatch	`globMatch(r.obj, p.obj)`	标准 glob 语义
ipMatch	`ipMatch(r.sub, p.sub)`	IP/CIDR 匹配（依赖 ipaddress 库）
eval	`eval(p.sub_rule)`	运行期把策略列当表达式求值（ABAC 规则式）

内置函数语义实测（org.casbin.jcasbin.util.BuiltInFunctions）：

keyMatch("/foo/bar", "/foo/*") = true
keyMatch("/foobar", "/foo/*") = false
keyMatch2("/api/2021/01", "/api/*") = true
keyMatch2("/api/2021/01", "/api/:id") = false     # :id 只吃一段
keyMatch2("/api/2021", "/api/:id") = true
globMatch("/foo/bar", "/foo/*") = true
regexMatch("foo123", "^foo") = true
ipMatch("192.168.1.1", "192.168.0.0/16") = true
ipMatch("192.168.1.1", "10.0.0.0/8") = false

matcher 里写 keyMatch(...) 即可，函数由 jcasbin 自动注册（源自 org.casbin.jcasbin.util.function.*Func 封装类）；Java 代码里直接调用静态版本时注意——1.99.0 的 Util 类没有 keyMatch 系列，须用 BuiltInFunctions。

三、policy.csv 规则文件

p, alice, data1, read            # p 行：按 [policy_definition] 列序
p, alice, data2, write, deny     # eft 列显式给出时：allow/deny
g, alice, data2_admin            # g 行：用户→角色
g, alice, admin, domain1         # 三元组 g 行：用户→角色→域

列数严格对齐定义（见 2.1 实测报错）；逗号后空格可容忍，解析时自动 trim。
行顺序即文件顺序；对显式优先级模型，priority 列数值小者优先。
策略文件由 Adapter 管理：FileAdapter（本地文件）、FilteredAdapter（条件过滤加载，isFiltered() 实测返回 true）、以及各类 DB 适配器。

四、模型的加载方式与 Enforcer 构造器

模型三种加载方式（org.casbin.jcasbin.model.Model，javap 实测）：

Model.newModel();                       // 空模型
Model.newModelFromFile(String path);    // 从文件
Model.newModelFromString(String text);  // 从字符串（实测 enforce 行为与文件一致）

Enforcer 构造器（javap 实测，9 个重载）：

Enforcer();                                             // 手动 setModel/setAdapter
Enforcer(String modelPath, String policyPath);          // 最常用
Enforcer(String modelPath, Adapter adapter);
Enforcer(String modelPath, Adapter adapter, boolean log)
Enforcer(Model model, Adapter adapter);
Enforcer(Model model, Adapter adapter, boolean log);
Enforcer(Model model);
Enforcer(String modelPath);
Enforcer(String modelPath, String policyPath, boolean log);

五、运行期开关

CoreEnforcer 提供的核心开关（javap 实测 + 行为实测）：

开关	默认	实测行为
`enableEnforce(boolean)`	true	关闭后 enforce 直接返回 false，用于灰度/只读模式
`enableAutoSave(boolean)`	true	关闭后 addPolicy/removePolicy 只改内存，需手动 `savePolicy()` 才落盘

autoSave 关闭实测（jshell）：

addPolicy(dave,data3,read) with autoSave off => true
enforce(dave,data3,read) => true
policy_auto.csv before savePolicy => []
policy_auto.csv after savePolicy => [p, dave, data3, read]

即关闭期间文件始终为空，显式 savePolicy 后一次性写入。

六、日志配置

jcasbin 通过 slf4j 输出决策日志（Model/Policy/Request/Hit Policy），运行期首屏实测：

[main] INFO org.casbin.jcasbin - Model:
[main] INFO org.casbin.jcasbin - p.p: sub, obj, act
[main] INFO org.casbin.jcasbin - m.m: g(r_sub, p_sub) && r_obj == p_obj && r_act == p_act
[main] INFO org.casbin.jcasbin - Policy:
[main] INFO org.casbin.jcasbin - Request: [alice, data2, read] ---> true
[main] INFO org.casbin.jcasbin - Hit Policy: [data2_admin, data2, read]

选绑定即控日志：slf4j-simple 输出控制台日志，slf4j-nop 静默；注意用 2.x 绑定（与内置 slf4j-api 2.0.16 配套）。日志中 r_sub 等下划线写法是内部对 r.sub 的改写（escapeAssertion），不是配置写法。

七、常见配置错误速查

报错（实测原文）	根因	修正
`invalid policy size: expected 3, got 4`	策略行列数与定义不符（jcasbin 无隐式 eft）	定义显式加 eft 列：`p = sub, obj, act, eft`
`Function not found: g`	匹配器用了 `g()` 但模型无 `[role_definition]`	补 `g = _, _`（或三元组 `_, _, _`）
编译错误 `cannot find symbol: method keyMatch(...)` location: Util	1.99.0 内置函数不在 Util 类	改用 `org.casbin.jcasbin.util.BuiltInFunctions`
SLF4J 绑定告警	slf4j-simple 1.7.x 与 api 2.x 不匹配	换 slf4j-simple 2.0.16+

八、参考链接

Casbin 官方文档（模型语法）：https://casbin.org/zh/docs/syntax-for-models
内置函数一览：https://casbin.org/zh/docs/builtin-functions
策略效果（effector）文档：https://casbin.org/zh/docs/policy-effect
jcasbin 源码（model/Model.java）：https://github.com/casbin/jcasbin
在线模型编辑器：https://editor.casbin.org/