API 概述

本页面概述 Casbin 的主要 API。有关安装配置和基本概念，请参阅快速开始和工作原理。

Enforce API

下面的示例使用 model.conf 中的 RBAC model 和 policy.csv 中的 policy。model 语法见 Model 语法。示例文件如下：

model.conf

[request_definition]
r = sub, obj, act

[policy_definition]
p = sub, obj, act

[role_definition]
g = _, _

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

[matchers]
m = g(r.sub, p.sub) && r.obj == p.obj && r.act == p.act

policy.csv

p, admin, data1, read
p, admin, data1, write
p, admin, data2, read
p, admin, data2, write
p, alice, data1, read
p, bob, data2, write
g, amber, admin
g, abc, admin

用法示例：

// Load information from files.
enforcer, err := casbin.NewEnforcer("./example/model.conf", "./example/policy.csv")
if err != nil {
    log.Fatalf("Error, detail: %s", err)
}
ok, err := enforcer.Enforce("alice", "data1", "read")

NewEnforcer() 从给定路径（或从一个 model 和一个 adapter）加载 model 和 policy。它返回一个 enforcer 和一个 error。传入两个文件路径时使用默认的文件 adapter；你可以替换为任意 adapter。

enforcer.Enforce("alice", "data1", "read") 检查 Alice 是否可以读取 data1。允许时返回 (true, nil)，拒绝时返回 (false, nil)。根据上面的 policy，该调用返回 true。

EnforceEx API

如果想查看是哪条 policy 允许了请求，可以使用 EnforceEx()：

ok, reason, err := enforcer.EnforceEx("amber", "data1", "read")
fmt.Println(ok, reason) // true [admin data1 read]

reason 是匹配的 policy（例如 [admin data1 read]）。Amber 拥有 admin 角色，因此 policy p, admin, data1, read 允许该请求。

Management API

Get API

这些方法返回 policy 数据。示例：

enforcer, err := casbin.NewEnforcer("./example/model.conf", "./example/policy.csv")
if err != nil {
    fmt.Printf("Error, details: %s\n", err)
}
allSubjects := enforcer.GetAllSubjects()
fmt.Println(allSubjects)

GetAllSubjects() 返回 policy 中出现的所有 subject（此处为 admin、alice、bob）。输出：

[admin alice bob]

使用 GetAllNamedSubjects("p") 可以针对特定 policy 类型获取。Objects、Actions 和 Roles 遵循同样的模式。

其他 getter：

GetPolicy() / GetFilteredPolicy(0, "alice") —— 所有规则，或按字段过滤。
GetNamedPolicy("p") / GetFilteredNamedPolicy("p", 0, "bob") —— 命名 policy 同理。
GetGroupingPolicy() / GetFilteredGroupingPolicy(0, "alice") —— 角色分配规则。
GetNamedGroupingPolicy("g") / GetFilteredNamedGroupingPolicy("g", 0, "alice") —— 命名 grouping 同理。

Add、Delete、Update API

你可以在运行时修改 policy。示例：添加、删除、更新和检查：

// load information from files
enforcer, err := casbin.NewEnforcer("./example/model.conf", "./example/policy.csv")
if err != nil {
    fmt.Printf("Error, details: %s\n", err)
}

// add a policy and use HasPolicy() to confirm
enforcer.AddPolicy("added_user", "data1", "read")
hasPolicy := enforcer.HasPolicy("added_user", "data1", "read")
fmt.Println(hasPolicy) // true, the policy was added successfully

// remove a policy and use HasPolicy() to confirm
enforcer.RemovePolicy("alice", "data1", "read")
hasPolicy = enforcer.HasPolicy("alice", "data1", "read")
fmt.Println(hasPolicy) // false, the policy was removed successfully

// update a policy and use HasPolicy() to confirm
enforcer.UpdatePolicy([]string{"added_user", "data1", "read"}, []string{"added_user", "data1", "write"})
hasPolicy = enforcer.HasPolicy("added_user", "data1", "read")
fmt.Println(hasPolicy) // false, the original policy has expired
hasPolicy = enforcer.HasPolicy("added_user", "data1", "write")
fmt.Println(hasPolicy) // true, the new policy is in effect

过滤 policy、命名 policy 以及 grouping policy 同样支持 add/remove/update/has 这一模式。对于批量更新，请使用复数形式（例如 AddPolicies、UpdatePolicies）并以切片作为参数。

示例：

enforcer.UpdatePolicy([]string{"eve", "data3", "read"}, []string{"eve", "data3", "write"})

将 Policy 改为 Policies 并相应调整参数，即可进行批量操作：

enforcer.UpdatePolicies([][]string{{"eve", "data3", "read"}, {"jack", "data3", "read"}}, [][]string{{"eve", "data3", "write"}, {"jack", "data3", "write"}})

批量操作同样适用于 GroupingPolicy 和 NamedGroupingPolicy。

AddEx API

AddEx 方法批量添加规则，但会跳过已存在的规则，而不是直接失败：

AddPoliciesEx(rules [][]string) (bool, error)
AddNamedPoliciesEx(ptype string, rules [][]string) (bool, error)
AddGroupingPoliciesEx(rules [][]string) (bool, error)
AddNamedGroupingPoliciesEx(ptype string, rules [][]string) (bool, error)
SelfAddPoliciesEx(sec string, ptype string, rules [][]string) (bool, error) 

使用 AddPolicies 时，只要有一条规则已存在，整个调用就会失败，不会添加任何规则。使用 AddPoliciesEx 时，已存在的规则会被跳过，其余规则会被添加。示例：

func TestDemo(t *testing.T) {
    e, err := NewEnforcer("examples/basic_model.conf", "examples/basic_policy.csv")
    if err != nil {
        fmt.Printf("Error, details: %s\n", err)
    }
    e.ClearPolicy()
    e.AddPolicy("user1", "data1", "read")
    fmt.Println(e.GetPolicy())
    testGetPolicy(t, e, [][]string{{"user1", "data1", "read"}})

    // policy {"user1", "data1", "read"} now exists

    // Use AddPolicies to add rules in batches
    ok, _ := e.AddPolicies([][]string{{"user1", "data1", "read"}, {"user2", "data2", "read"}})
    fmt.Println(e.GetPolicy())
    // {"user2", "data2", "read"} failed to add because {"user1", "data1", "read"} already exists
    // AddPolicies returns false and no other policies are checked, even though they may not exist in the existing ruleset
    // ok == false
    fmt.Println(ok)
    testGetPolicy(t, e, [][]string{{"user1", "data1", "read"}})

    // Use AddPoliciesEx to add rules in batches
    ok, _ = e.AddPoliciesEx([][]string{{"user1", "data1", "read"}, {"user2", "data2", "read"}})
    fmt.Println(e.GetPolicy())
    // {"user2", "data2", "read"} is added successfully
    // because AddPoliciesEx automatically filters the existing {"user1", "data1", "read"}
    // ok == true
    fmt.Println(ok)
    testGetPolicy(t, e, [][]string{{"user1", "data1", "read"}, {"user2", "data2", "read"}})
}

RBAC API

enforcer 还提供了 RBAC 相关的辅助方法（角色、用户、权限）。有关 model 配置，请参阅 RBAC。

像之前一样加载 model 和 policy：

enforcer, err := casbin.NewEnforcer("./example/model.conf", "./example/policy.csv")
if err != nil {
    fmt.Printf("Error, details: %s\n", err)
}

RBAC 调用示例：

roles, err := enforcer.GetRolesForUser("amber")
fmt.Println(roles) // [admin]
users, err := enforcer.GetUsersForRole("admin")
fmt.Println(users) // [amber abc]

GetRolesForUser("amber") 返回 [admin]。GetUsersForRole("admin") 返回拥有该角色的所有用户。HasRoleForUser("amber", "admin") 为 true。

fmt.Println(enforcer.Enforce("bob", "data2", "write")) // true
enforcer.DeletePermission("data2", "write")
fmt.Println(enforcer.Enforce("bob", "data2", "write")) // false

DeletePermission("data2", "write") 会为所有人移除该权限。DeletePermissionForUser("alice", "data1", "read") 则只为 Alice 移除该权限。

完整的 RBAC API 列表见 RBAC API。

Enforce API​

EnforceEx API​

Management API​

Get API​

Add、Delete、Update API​

AddEx API​

RBAC API​