跳转至主要内容

适配器

在Casbin中，策略存储作为adapter(Casbin的中间件) 实现。 Casbin用户可以使用adapter从存储中加载策略规则 (aka LoadPolicy()) 或者将策略规则保存到其中 (aka SavePolicy())。 为了保持代码轻量级，我们没有把adapter代码放在主库中。

目前支持的适配器列表​

Casbin的适配器完整列表如下。 我们欢迎任何第三方对adapter进行新的贡献，如果有请通知我们，我们将把它放在这个列表中:)

适配器类型作者自动保存描述
File Adapter (内置)FileCasbin❌For .CSV (Comma-Separated Values) files
Filtered File Adapter (内置)FileFile❌对于 CSV (逗号分隔的值) 个带策略子集加载支持的文件
SQL AdapterSQL@Blank-Xu✅MySQL，PostgreSQL，SQL Server和SQLite3在 master分支中受到database/sql的支持，Oacle在 oracle分支中也受到database/sql的支持
Xorm AdapterORMCasbin✅通过 Xorm实现，支持MySQL, PostgreSQL, Sqlite3, SQL Server等多种存储引擎的adapter
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的图数据库由 [ent ORM](https://entgo. io/) 支持。
Beego ORM AdapterORMCasbin✅MySQL, PostgreSQL, Sqlite3 are supported by Beego ORM
SQLX AdapterORM@memwey✅MySQL, PostgreSQL, SQLite, Oracle 由 SQLX 支持
Sqlx AdapterORM@Blank-Xu✅MySQL, PostgreSQL, SQL Server, SQLite3 由 master 分支支持，Oracle由oracle 分支受到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
Filtered PostgreSQL AdapterSQLCasbin✅用于PostgreSQL
Filtered pgx AdapterSQL@pckhoi✅使用 pgx 支持PostgreSQL
PostgreSQL AdapterSQL@cychiuae✅用于PostgreSQL
RQLite AdapterSQLEDOMO Systems✅用于 RQLite
MongoDB AdapterNoSQLCasbin✅基于 MongoDB Go Driver 用于 MongoDB
RethinkDB AdapterNoSQL@adityapandey9✅用于RethinkDB
Cassandra AdapterNoSQLCasbin❌用于Apache Cassandra DB
DynamoDB AdapterNoSQLHOOQ❌用于Amazon DynamoDB
DynacasbinNoSQLNewbMiao✅用于Amazon DynamoDB
ArangoDB AdapterNoSQL@adamwasila✅用于ArangoDB
Amazon S3 Adapter云Soluto❌用于Minio和Amazon S3
Azure Cosmos DB Adapter云@spacycoder✅用于 Microsoft Azure Cosmos DB
GCP Firestore Adapter云@reedom❌用于 Google Cloud Platform Firestore
GCP Cloud Storage Adapter云qurami❌用于 Google Cloud Platform Cloud Storage
GCP Cloud Storage Adapter云@flowerinthenight✅用于Google Cloud Platform Cloud Spanner
Consul AdapterKV store@ankitm123❌用于 HashiCorp Consul
Redis 适配器 (Redigo)KV storeCasbin✅用于 Redis
Redis Adapter (go-redis)KV store@mlsen✅用于 Redis
Etcd 适配器KV store@sebastianliu❌用于 etcd
BoltDB AdapterKV store@speza✅用于 Bolt
Bolt AdapterKV store@wirepair❌用于 Bolt
BadgerDB AdapterKV store@inits✅用于 BadgerDB
Protobuf AdapterStreamCasbin❌用于 Google Protocol Buffers
JSON AdapterStringCasbin❌用于 JSON
String AdapterString@qiangmzsx❌用于 String
HTTP File AdapterHTTP@h4ckedneko❌用于 http.FileSystem
FileSystem AdapterFile@naucon❌用于fs.FS 和 embed.FS
备注
  1. 如果使用显式或隐式adapter调用casbin.NewEnforcer()，策略将自动加载。
  2. 可以调用e.LoadPolicy() 来从存储中重新加载策略规则。
  3. 如果adapter不支持Auto-Save特性，则在添加或删除策略时不能将策略规则自动保存回存储器。 你必须手动调用 SavePolicy() 来保存所有的策略规则

例子​

我们为您提供以下示例作为参考：

文件适配器 (内置)​

下面的代码演示了如何从File adapter初始化enforcer：

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数据库初始化一个enforcer。 此处样例中的MySQL数据库运行在127.0.0.1:3306上，用户为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)

使用自建的adapter​

您可以参考如下代码来使用自建的adapter

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()

在运行时进行加载或保存配置信息​

如果您在初始化后仍想重载model和policy的配置（或是保存policy的配置信息），那么可以参照如下方法：

// 从CONF配置文件中加载model
e.LoadModel()
// 从文件或数据库中加载policy
e. LoadPolicy()
// 保存当前的policy（通常在调用Casbin API改变了配置信息后）至文件或数据库
e.SavePolicy()

自动保存​

自动保存机制（Auto-Save）是adapter的特性之一。 支持自动保存机制的adapter可以自动向存储回写内存中单个policy规则的变更（删除/更新）。 与自动回写机制不同，调用SavePolicy()会直接删除所有存储中的policy规则并将当前Casbin enforcer存储在内存中的policy规则悉数持久化到存储中。 因此，当内存中的policy规则过多时，直接调用SavePolicy()会引起一些性能问题。

当适配器支持自动保存机制时，您可以通过Enforcer.EnableAutoSave() 函数来开启或关闭该机制。 默认情况下启用该选项（如果适配器支持自动保存的话）。

备注
  1. Auto-Save 特性是可选的。 Adapter可以选择是否实现它。
  2. Auto-Save 只在Casbin enforcer使用的adapter支持它时才有效。
  3. 查看上述adapter列表中的 AutoSave列，查看adapter是否支持 Auto-Save。

以下示例演示了 Auto-Save的使用方法：

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

// enforcer会默认开启AutoSave机制.
a := xormadapter.NewAdapter("mysql", "mysql_username:mysql_password@tcp(127.0.0.1:3306)/")
e := casbin.NewEnforcer("examples/basic_model.conf", a)

// 禁用AutoSave机制
e.EnableAutoSave(false)

// 因为禁用了AutoSave，当前策略的改变只在内存中生效
// 这些策略在持久层中仍是不变的
e.AddPolicy(...)
e.RemovePolicy(...)

// 启用自动保存选项。
e.EnableAutoSave(true)

// 因为开启了AutoSave机制，现在内存中的改变会同步回写到持久层中
e.AddPolicy(...)
e.RemovePolicy(...)

For more examples, please see: https://github.com/casbin/xorm-adapter/blob/master/adapter_test.go

如何编写 Adapter​

Adapter应实现Adapter 中定义的接口，其中必须实现的为LoadPolicy(model model.Model) error和SavePolicy(model model.Model) error。

其他三个函数是可选的。 如果adapter支持Auto-Save特性，则应该实现它们。

接口名类型描述
LoadPolicy()必须从持久层中加载policy规则
SavePolicy()必须将policy规则保存至持久层
AddPolicy()可选添加单条policy规则至持久层
RemovePolicy()optional从持久层删除单条policy规则
RemoveFilteredPolicy()optional从持久层删除符合筛选条件的policy规则
备注

如果适配器不支持 自动保存, 它应该为以下三个可选函数提供一个空实现。 下面是Golang的一个例子：

// AddPolicy 添加一个policy规则至持久层
func (a *Adapter) AddPolicy(sec string, ptype string, rule []string) error {
    return errors.New("not implemented")
}

// RemovePolicy 从持久层删除单条policy规则
func (a *Adapter) RemovePolicy(sec string, ptype string, rule []string) error {
    return errors.New("not implemented")
}

//  RemoveFilteredPolicy 从持久层删除符合筛选条件的policy规则
func (a *Adapter) RemoveFilteredPolicy(sec string, ptype string, fieldIndex int, fieldValues ...string) error {
    return errors.New("not implemented")
}

Casbin enforcer在调用这三个可选实现的接口时，会忽略返回的not implemented 异常。

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

  • 数据结构 适配器应 最少 支持六列。

  • 数据库名称: 默认数据库名称应该是 casbin。

  • 表格名称 默认表名应该是 casbin_rule。

  • Ptype 栏。 此列的名称应该是 ptype 而不是 p_type 或 Ptype。

  • 表定义应该是 (id int priorkey, ptype varchar, v0 varchar, v1 varchar, v2 varchar, v3 varchar, v4 varchar, v5 varchar)

  • 唯一的密钥索引应该建立在列 ptype, v0, v1, v2, v3, v4, v5 上。

  • LoadFilteredPolicy需要一个 filter 作为参数。 Filter应该像这样。

    {
        "p":[ [ "alice" ], [ "bob" ] ],
        "g":[ [ "", "book_group" ], [ "", "pen_group" ] ],
        "g2":[ [ "alice" ] ]
    }

谁负责创建数据库？​

我们通常约定，如果相应的数据库结构尚未建立，那么使用adapter作为policy的持久化工具时，它应具有自动创建一个名为 casbin 的数据库的能力。 Please use the Xorm adapter as a reference implementation: https://github.com/casbin/xorm-adapter

Context Adapter​

ContextAdapter provides a context-aware interface for Casbin adapters.

Through context, you can implement features such as timeout control for the Adapter API

Example​

gormadapter supports adapter with context, the following is a timeout control implemented using context

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)
}

How to write an context adapter​

ContextAdapter API only has an extra layer of context processing than ordinary Adapter API, and on the basis of implementing ordinary Adapter API, you can encapsulate your own processing logic for context

A simple reference to the gormadapter: context_adapter.go