API Overview

本页概述 Casbin 的主要 API。安装和概念见快速开始和工作原理。

Enforce API

下面的示例使用 model.conf 中的 RBAC 模型和 policy.csv 中的策略。模型语法见模型语法。示例文件：

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() 从给定路径（或从模型和适配器）加载模型和策略。它返回一个 enforcer 和一个 error。传入两个文件路径时使用默认的文件适配器；你可以换成任何适配器。

enforcer.Enforce("alice", "data1", "read") 检查 Alice 能否读取 data1。允许时返回 (true, nil)，拒绝时返回 (false, nil)。按上面的策略，这次调用返回 true。

EnforceEx API

要查看是哪条策略允许了请求，使用 EnforceEx()：

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

reason 是匹配的策略（例如 [admin data1 read]）。 Amber 拥有 admin 角色，所以策略 p, admin, data1, read 允许了这个请求。

管理API

获取API

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

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() 返回策略中出现的所有主体（这里是 admin、alice、bob）。输出：

[admin alice bob]

针对特定的策略类型，使用 GetAllNamedSubjects("p")。 Objects、Actions 和 Roles 也遵循同样的模式。

其他查询方法：

GetPolicy() / GetFilteredPolicy(0, "alice")：所有规则，或按字段过滤。
GetNamedPolicy("p") / GetFilteredNamedPolicy("p", 0, "bob")：针对命名策略的同类方法。
GetGroupingPolicy() / GetFilteredGroupingPolicy(0, "alice")：角色分配规则。
GetNamedGroupingPolicy("g") / GetFilteredNamedGroupingPolicy("g", 0, "alice")：针对命名分组策略的同类方法。

添加、删除、更新 API

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

// 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

过滤策略、命名策略和分组策略也都有同样的 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 辅助方法（角色、用户、权限）。模型配置见 RBAC。

和前面一样加载模型和策略：

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​

管理API​

获取API​

添加、删除、更新 API​

AddEx API​

RBAC API​