API 概览

本页提供了 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。当你传入两个文件路径时，会使用默认的文件适配器；你可以替换为任何 adapter。

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 允许该请求。

Management API

Get 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。

其他 getter 方法：

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

Add, delete, update 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

执行器还暴露了 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​

Management API​

Get API​

Add, delete, update API​

AddEx API​

RBAC API​