跳转至主要内容

Adapters

在Casbin中，策略存储是作为一个适配器（也称为Casbin的中间件）来实现的。 Casbin用户可以使用适配器从存储中加载策略规则（也称为LoadPolicy()），或者将策略规则保存到存储中（也称为SavePolicy()）。 为了保持轻量级，我们没有将适配器代码放在主库中。

支持的适配器​

下面提供了Casbin适配器的完整列表。 欢迎任何第三方对新适配器的贡献，请通知我们，我们会将其放入此列表：

AdapterTypeAuthorAutoSaveDescription
File Adapter (built-in)FileCasbin❌For .CSV (Comma-Separated Values) files
Filtered File Adapter (built-in)File@faceless-saint❌For .CSV (Comma-Separated Values) files with policy subset loading support
SQL AdapterSQL@Blank-Xu✅MySQL, PostgreSQL, SQL Server, SQLite3 are supported in master branch and Oracle is supported in oracle branch by database/sql
Xorm AdapterORMCasbin✅MySQL, PostgreSQL, TiDB, SQLite, SQL Server, Oracle are supported by Xorm
GORM AdapterORMCasbin✅MySQL, PostgreSQL, Sqlite3, SQL Server are supported by GORM
GORM Adapter ExORMCasbin✅MySQL, PostgreSQL, Sqlite3, SQL Server are supported by GORM
Ent AdapterORMCasbin✅MySQL, MariaDB, PostgreSQL, SQLite, Gremlin-based graph databases are supported by ent ORM
Beego ORM AdapterORMCasbin✅MySQL, PostgreSQL, Sqlite3 are supported by Beego ORM
SQLX AdapterORM@memwey✅MySQL, PostgreSQL, SQLite, Oracle are supported by SQLX
Sqlx AdapterORM@Blank-Xu✅MySQL, PostgreSQL, SQL Server, SQLite3 are supported in master branch and Oracle is supported in oracle branch by sqlx
GF ORM AdapterORM@vance-liu✅MySQL, SQLite, PostgreSQL, Oracle, SQL Server are supported by GoFrame ORM
GoFrame ORM AdapterORM@kotlin2018✅MySQL, SQLite, PostgreSQL, Oracle, SQL Server are supported by GoFrame ORM
gf-adapterORM@zcyc✅MySQL, SQLite, PostgreSQL, Oracle, SQL Server are supported by GoFrame ORM
Gdb AdapterORM@jxo-me✅MySQL, SQLite, PostgreSQL, Oracle, SQL Server are supported by GoFrame ORM
GoFrame V2 AdapterORM@hailaz✅MySQL, SQLite, PostgreSQL, Oracle, SQL Server are supported by GoFrame ORM
Bun AdapterORM@JunNishimura✅MySQL, SQLite, PostgreSQL, SQL Server are supported by Bun ORM
Filtered PostgreSQL AdapterSQLCasbin✅For PostgreSQL
Filtered pgx AdapterSQL@pckhoi✅PostgreSQL is supported by pgx
PostgreSQL AdapterSQL@cychiuae✅For PostgreSQL
RQLite AdapterSQLEDOMO Systems✅For RQLite
MongoDB AdapterNoSQLCasbin✅For MongoDB based on MongoDB Go Driver
RethinkDB AdapterNoSQL@adityapandey9✅For RethinkDB
Cassandra AdapterNoSQLCasbin❌For Apache Cassandra DB
DynamoDB AdapterNoSQLHOOQ❌For Amazon DynamoDB
DynacasbinNoSQLNewbMiao✅For Amazon DynamoDB
ArangoDB AdapterNoSQL@adamwasila✅For ArangoDB
Amazon S3 AdapterCloudSoluto❌For Minio and Amazon S3
Go CDK AdapterCloud@bartventer✅Adapter based on Go Cloud Dev Kit that supports: Amazon DynamoDB, Azure CosmosDB, GCP Firestore, MongoDB, In-Memory
Azure Cosmos DB AdapterCloud@spacycoder✅For Microsoft Azure Cosmos DB
GCP Firestore AdapterCloud@reedom❌For Google Cloud Platform Firestore
GCP Cloud Storage AdapterCloudqurami❌For Google Cloud Platform Cloud Storage
GCP Cloud Spanner AdapterCloud@flowerinthenight✅For Google Cloud Platform Cloud Spanner
Consul AdapterKV store@ankitm123❌For HashiCorp Consul
Redis Adapter (Redigo)KV storeCasbin✅For Redis
Redis Adapter (go-redis)KV store@mlsen✅For Redis
Etcd AdapterKV store@sebastianliu❌For etcd
BoltDB AdapterKV store@speza✅For Bolt
Bolt AdapterKV store@wirepair❌For Bolt
BadgerDB AdapterKV store@inits✅For BadgerDB
Protobuf AdapterStreamCasbin❌For Google Protocol Buffers
JSON AdapterStringCasbin❌For JSON
String AdapterString@qiangmzsx❌For String
HTTP File AdapterHTTP@h4ckedneko❌For http.FileSystem
FileSystem AdapterFile@naucon❌For fs.FS and embed.FS
备注
  1. 如果使用显式或隐式适配器调用casbin.NewEnforcer()，策略将自动加载。
  2. 您可以调用e.LoadPolicy()从存储中重新加载策略规则。
  3. 如果适配器不支持Auto-Save功能，当您添加或删除策略时，策略规则不能自动保存回存储。 您必须手动调用SavePolicy()来保存所有策略规则。

示例​

这里我们提供了几个示例：

文件适配器（内置）​

下面展示了如何从内置文件适配器初始化一个执行器：

import "github.com/casbin/casbin"

e := casbin.NewEnforcer("examples/basic_model.conf", "examples/basic_policy.csv")

这与下面的内容相同：

import (
    "github.com/casbin/casbin"
    "github.com/casbin/casbin/file-adapter"
)

a := fileadapter.NewAdapter("examples/basic_policy.csv")
e := casbin.NewEnforcer("examples/basic_model.conf", a)

MySQL适配器​

下面展示了如何从MySQL数据库初始化一个执行器。 它连接到127.0.0.1:3306上的MySQL DB，使用root和空密码。

import (
    "github.com/casbin/casbin"
    "github.com/casbin/mysql-adapter"
)

a := mysqladapter.NewAdapter("mysql", "root:@tcp(127.0.0.1:3306)/")
e := casbin.NewEnforcer("examples/basic_model.conf", a)

使用您自己的存储适配器​

您可以像下面这样使用您自己的适配器：

import (
    "github.com/casbin/casbin"
    "github.com/your-username/your-repo"
)

a := yourpackage.NewAdapter(params)
e := casbin.NewEnforcer("examples/basic_model.conf", a)

在不同适配器之间迁移/转换​

如果你想从A转换适配器到B，你可以这样做：

1.从A加载策略到内存

e, _ := NewEnforcer(m, A)

或者

e.SetAdapter(A)
e.LoadPolicy()

2.将你的适配器从A转换到B

e.SetAdapter(B)

3.将策略从内存保存到B

e.SavePolicy()

运行时加载/保存​

您可能还希望在初始化后重新加载模型，重新加载策略或保存策略：

// Reload the model from the model CONF file.
e.LoadModel()

// Reload the policy from file/database.
e.LoadPolicy()

// Save the current policy (usually after changed with Casbin API) back to file/database.
e.SavePolicy()

AutoSave​

适配器有一个叫做Auto-Save的功能。 当一个适配器支持Auto-Save时，意味着它可以支持将单个策略规则添加到存储中，或者从存储中删除单个策略规则。 这与SavePolicy()不同，因为后者会删除存储中的所有策略规则，并将所有Casbin执行器的策略规则保存到存储中。 因此，当策略规则的数量较大时，可能会遇到性能问题。

当适配器支持Auto-Save时，您可以通过Enforcer.EnableAutoSave()函数切换此选项。 该选项默认启用（如果适配器支持）。

备注
  1. Auto-Save功能是可选的。 适配器可以选择实现它或者不实现。
  2. Auto-Save只在Casbin执行器使用的适配器支持它时才起作用。
  3. 查看上面的适配器列表中的AutoSave列，以查看适配器是否支持Auto-Save。

这是一个如何使用Auto-Save的示例：

import (
    "github.com/casbin/casbin"
    "github.com/casbin/xorm-adapter"
    _ "github.com/go-sql-driver/mysql"
)

// By default, the AutoSave option is enabled for an enforcer.
a := xormadapter.NewAdapter("mysql", "mysql_username:mysql_password@tcp(127.0.0.1:3306)/")
e := casbin.NewEnforcer("examples/basic_model.conf", a)

// Disable the AutoSave option.
e.EnableAutoSave(false)

// Because AutoSave is disabled, the policy change only affects the policy in Casbin enforcer,
// it doesn't affect the policy in the storage.
e.AddPolicy(...)
e.RemovePolicy(...)

// Enable the AutoSave option.
e.EnableAutoSave(true)

// Because AutoSave is enabled, the policy change not only affects the policy in Casbin enforcer,
// but also affects the policy in the storage.
e.AddPolicy(...)
e.RemovePolicy(...)

更多示例，请参见：https://github.com/casbin/xorm-adapter/blob/master/adapter_test.go

如何编写适配器​

所有适配器都应实现Adapter接口，至少提供两个必需的方法：LoadPolicy(model model.Model) error 和 SavePolicy(model model.Model) error。

其他三个函数是可选的。 如果适配器支持Auto-Save功能，它们应该被实现。

方法类型描述
LoadPolicy()必需从存储中加载所有策略规则
SavePolicy()必需将所有策略规则保存到存储中
AddPolicy()可选将策略规则添加到存储中
RemovePolicy()可选从存储中删除策略规则
RemoveFilteredPolicy()可选从存储中删除与过滤器匹配的策略规则
备注

如果适配器不支持Auto-Save，它应该为这三个可选函数提供一个空的实现。 这是一个Golang的示例：

// AddPolicy adds a policy rule to the storage.
func (a *Adapter) AddPolicy(sec string, ptype string, rule []string) error {
    return errors.New("not implemented")
}

// RemovePolicy removes a policy rule from the storage.
func (a *Adapter) RemovePolicy(sec string, ptype string, rule []string) error {
    return errors.New("not implemented")
}

// RemoveFilteredPolicy removes policy rules that match the filter from the storage.
func (a *Adapter) RemoveFilteredPolicy(sec string, ptype string, fieldIndex int, fieldValues ...string) error {
    return errors.New("not implemented")
}

Casbin执行器在调用这三个可选函数时会忽略not implemented错误。

关于如何编写适配器的详细信息。

  • 数据结构。 适配器应支持至少读取六列。
  • 数据库名称。 默认的数据库名称应该是casbin。
  • 表名。 默认的表名应该是casbin_rule。
  • Ptype列。 此列的名称应为ptype，而不是p_type或Ptype。
  • 表定义应为(id int primary key, ptype varchar, v0 varchar, v1 varchar, v2 varchar, v3 varchar, v4 varchar, v5 varchar)。
  • 唯一键索引应在ptype,v0,v1,v2,v3,v4,v5列上建立。
  • LoadFilteredPolicy需要一个filter作为参数。 过滤器应该像这样。
{
    "p":[ [ "alice" ], [ "bob" ] ],
    "g":[ [ "", "book_group" ], [ "", "pen_group" ] ],
    "g2":[ [ "alice" ] ]
}

谁负责创建数据库？​

按照惯例，如果数据库不存在，适配器应能够自动创建名为casbin的数据库，并用它来存储策略。 请参考Xorm适配器作为参考实现：https://github.com/casbin/xorm-adapter

上下文适配器​

ContextAdapter为Casbin适配器提供了一个上下文感知的接口。

通过上下文，您可以为适配器API实现诸如超时控制等功能

示例​

gormadapter支持带有上下文的适配器，以下是使用上下文实现的超时控制

ca, _ := NewContextAdapter("mysql", "root:@tcp(127.0.0.1:3306)/", "casbin")
// Limited time 300s
ctx, cancel := context.WithTimeout(context.Background(), 300*time.Microsecond)
defer cancel()

err := ca.AddPolicyCtx(ctx, "p", "p", []string{"alice", "data1", "read"})
if err != nil {
    panic(err)
}

如何编写一个上下文适配器​

ContextAdapter API只比普通的Adapter API多了一层上下文处理，在实现普通Adapter API的基础上，你可以为上下文封装你自己的处理逻辑

简单引用 gormadapter： adapter.go