Casbin 快速开始：用最小示例看懂 Model、Policy 和 Enforcer

沈知远

发布时间：2026-08-25 | 96人浏览过

原创

前言

刚接触 Casbin 时，很多人会先被几个名词绕住：Model、Policy、Enforcer 到底各管什么，最小示例又该怎么跑起来。下面就按“概念拆解 + 安装 + 实战验证”的顺序展开，用一组最基础的 PHP 示例把 Casbin 的工作方式说明白，读完你可以判断自己现在需要改的是模型、策略，还是调用校验的代码。

Casbin 三个核心概念关系示意图 — **Casbin 核心角色怎么分工**用专栏卡片形式拆开 Model、Policy、Enforcer 的职责。

Casbin 的三个核心概念

Casbin 中最核心的三个概念是 Model、Policy 和 Enforcer。理解这三者的分工，后面的使用方式就会清晰很多。

Model：定义权限判断规则

Model 本质上是一个 CONF 文件，用来描述权限系统按什么规则判断请求。它基于 PERM metamodel，也就是 Policy、Effect、Request、Matchers 这几个部分来组织。

可以把它理解为“权限判断模板”：系统收到一个访问请求后，要比较哪些字段、采用什么匹配逻辑，都是由 Model 决定的。

Policy：存放具体授权数据

Policy 用来动态存储 policy rules，也就是具体的授权规则。它可以保存在 .csv 文件里，也可以放到数据库中。

如果说 Model 决定“怎么判断”，那么 Policy 决定“谁对什么资源拥有什么操作权限”。实际项目里，策略通常是变化最频繁的一层。

Enforcer：执行最终权限判定

Enforcer 是 Casbin 的执行入口。它负责判断某个 subject 对某个 object 是否拥有指定 action 的权限。

通常在业务代码里，你只需要把用户、资源和操作传给它，它就会结合前面的模型和策略返回允许或拒绝的结果。

安装 Casbin

在 PHP 项目中，可以直接通过 Composer 安装：

composer require casbin/casbin

安装完成后，就可以开始准备模型文件和策略文件，构造一个最小可运行的权限校验示例。

最小示例：从模型到策略文件

先创建 model.conf 和 policy.csv 两个文件。前者定义权限判断结构，后者写入具体授权规则。

model.conf：

[request_definition]
r = sub, obj, act

[policy_definition]
p = sub, obj, act

[policy_effect]
e = some(where (p.eft == allow))

[matchers]
m = r.sub == p.sub && r.obj == p.obj && r.act == p.act

这份模型的意思比较直接：

请求里包含 sub、obj、act 三个字段；
策略里也按这三个字段存储；
只要存在一条允许规则匹配成功，就通过；
匹配条件是请求和策略的三项内容完全相等。

policy.csv：

p, alice, data1, read
p, bob, data2, write

这里定义了两条最基础的授权关系：alice 可以读取 data1，bob 可以写入 data2。

在 PHP 中创建 Enforcer 并校验权限

准备好模型文件和策略文件后，就可以创建 Casbin 决策器。创建 Enforcer 时，需要把模型文件和策略文件路径传进去：

Casbin 最小示例的请求匹配流程图 — **一次权限校验是怎么完成的**把一次权限请求拆成请求字段、匹配条件和结果返回，便于理解 enforce 的实际判断过程。

require_once './vendor/autoload.php';

use CasbinEnforcer;

$e = new Enforcer("path/to/model.conf", "path/to/policy.csv");

接下来，在需要访问控制的位置调用 enforce 方法进行权限验证：

$sub = "alice"; // the user that wants to access a resource.
$obj = "data1"; // the resource that is going to be accessed.
$act = "read"; // the operation that the user performs on the resource.

if ($e->enforce($sub, $obj, $act) === true) {
    // 允许 alice 读取 data1
} else {
    // 拒绝请求, 显示错误
}

这段代码的判断逻辑就是：把当前用户、目标资源和操作类型交给 Enforcer，再由它根据 model.conf 的匹配规则去查 policy.csv 中是否存在对应授权。

以这个示例来说，alice 访问 data1 并执行 read 时会返回 true；如果请求内容和策略不匹配，就会返回拒绝结果。