适配器 · Casbin

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

目前支持的adapter列表

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

Java

Node.js

PHP

Python

.NET

Rust

适配器	类型	作者	自动保存	描述
File Adapter (built-in)	File	Casbin	❌	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
Xorm Adapter	ORM	Casbin	✅	MySQL, PostgreSQL, TiDB, SQLite, SQL Server, Oracle are supported by Xorm
Gorm Adapter	ORM	Casbin	✅	MySQL, PostgreSQL, Sqlite3, SQL Server are supported by Gorm
Beego ORM Adapter	ORM	Casbin	✅	MySQL, PostgreSQL, Sqlite3 are supported by Beego ORM
SQLX Adapter	ORM	@memwey	✅	MySQL, PostgreSQL, SQLite, Oracle are supported by SQLX
Sqlx Adapter	SQL	@Blank-Xu	✅	MySQL, PostgreSQL, MsSql, SQLite3 are supported in `master` branch and Oracle is supported in `oracle` branch by sqlx
GF ORM Adapter	ORM	@vance-liu	✅	MySQL, SQLite, PostgreSQL, Oracle, SQL Server are supported by GF ORM
Filtered PostgreSQL Adapter	SQL	Casbin	✅	For PostgreSQL
PostgreSQL Adapter	SQL	@cychiuae	✅	For PostgreSQL
PostgreSQL Adapter (Archived)	SQL	Going	❌	For PostgreSQL
RQLite Adapter	SQL	EDOMO Systems	✅	For RQLite
MongoDB Adapter	NoSQL	Casbin	✅	For MongoDB based on MongoDB driver for Go
MongoDB Adapter	NoSQL	Titan DC	✅	For MongoDB based on MongoDB Go driver
RethinkDB Adapter	NoSQL	@adityapandey9	✅	For RethinkDB
Cassandra Adapter	NoSQL	Casbin	❌	For Apache Cassandra DB
DynamoDB Adapter	NoSQL	HOOQ	❌	For Amazon DynamoDB
Dynacasbin	NoSQL	NewbMiao	✅	For Amazon DynamoDB
ArangoDB Adapter	NoSQL	@adamwasila	✅	For ArangoDB
Amazon S3 Adapter	Cloud	Soluto	❌	For Minio and Amazon S3
Azure Cosmos DB Adapter	Cloud	@spacycoder	✅	For Microsoft Azure Cosmos DB
GCP Datastore Adapter	Cloud	LivingPackets	❌	For Google Cloud Platform Datastore
GCP Firestore Adapter	Cloud	@reedom	❌	For Google Cloud Platform Firestore
Consul Adapter	KV store	@ankitm123	❌	For HashiCorp Consul
Redis Adapter	KV store	Casbin	❌	For Redis
Etcd Adapter	KV store	@sebastianliu	❌	For etcd
BoltDB Adapter	KV store	@speza	✅	For Bolt
Bolt Adapter	KV store	@wirepair	❌	For Bolt
BadgerDB Adapter	KV store	@inits	✅	For BadgerDB
Protobuf Adapter	Stream	Casbin	❌	For Google Protocol Buffers
JSON Adapter	String	Casbin	❌	For JSON
String Adapter	String	@qiangmzsx	❌	For String

适配器	类型	作者	自动保存	描述
File Adapter (built-in)	File	Casbin	❌	For .CSV (Comma-Separated Values) files
JDBC Adapter	JDBC	Casbin	✅	MySQL, Oracle, PostgreSQL, DB2, Sybase, SQL Server are supported by JDBC
Hibernate Adapter	ORM	Casbin	✅	Oracle, DB2, SQL Server, Sybase, MySQL, PostgreSQL are supported by Hibernate
MyBatis Adapter	ORM	Casbin	✅	MySQL, Oracle, PostgreSQL, DB2, Sybase, SQL Server (the same as JDBC) are supported by MyBatis 3
Hutool Adapter	ORM	@fanlide	✅	MySQL, Oracle, PostgreSQL, SQLite are supported by Hutool
DynamoDB Adapter	NoSQL	Casbin	❌	For Amazon DynamoDB

适配器	类型	作者	自动保存	描述
File Adapter (built-in)	File	Casbin	❌	For .CSV (Comma-Separated Values) files
Filtered File Adapter (built-in)	File	Casbin	❌	For .CSV (Comma-Separated Values) files with policy subset loading support
String Adapter (built-in)	String	@calebfaruki	❌	For String
Sequelize Adapter	ORM	Casbin	✅	MySQL, PostgreSQL, SQLite, Microsoft SQL Server are supported by Sequelize
TypeORM Adapter	ORM	Casbin	✅	MySQL, PostgreSQL, MariaDB, SQLite, MS SQL Server, Oracle, WebSQL, MongoDB are supported by TypeORM
Mongoose Adapter	ORM	elastic.io and Casbin	✅	MongoDB is supported by Mongoose
Knex Adapter	ORM	@sarneeh	✅	MSSQL, MySQL, PostgreSQL, SQLite3, Oracle are supported by Knex.js
Objection.js Adapter	ORM	@willsoto	✅	MSSQL, MySQL, PostgreSQL, SQLite3, Oracle are supported by Objection.js
Node MongoDB Native Adapter	NoSQL	@juicycleff	✅	For Node MongoDB Native
Node PostgreSQL Native Adapter	SQL	@touchifyapp	✅	PostgreSQL adapter with advanced policy subset loading support and improved performances built with node-postgres.
Couchbase Adapter	NoSQL	@MarkMYoung	✅	For Couchbase
Redis Adapter	KV store	@NandaKishorJeripothula	❌	For Redis

适配器	类型	作者	自动保存	描述
File Adapter (built-in)	File	Casbin	❌	For .CSV (Comma-Separated Values) files
Database Adapter	ORM	Casbin	✅	MySQL, PostgreSQL, SQLite, Microsoft SQL Server are supported by techone/database
Zend Db Adapter	ORM	Casbin	✅	MySQL, PostgreSQL, SQLite, Oracle, IBM DB2, Microsoft SQL Server, Other PDO Driver are supported by zend-db
Doctrine DBAL Adapter(Recommend)	ORM	Casbin	✅	Powerful PHP database abstraction layer (DBAL) with many features for database schema introspection and management.
Medoo Adapter	ORM	Casbin	✅	Medoo is a lightweight PHP Database Framework to Accelerate Development, supports all SQL databases, including `MySQL`, `MSSQL`, `SQLite`, `MariaDB`, `PostgreSQL`, `Sybase`, `Oracle` and more.
Redis Adapter	KV store	@nsnake	❌	For Redis

适配器	类型	作者	自动保存	描述
File Adapter (built-in)	File	Casbin	❌	For .CSV (Comma-Separated Values) files
SQLAlchemy Adapter	ORM	Casbin	✅	PostgreSQL, MySQL, SQLite, Oracle, Microsoft SQL Server, Firebird, Sybase are supported by SQLAlchemy
Peewee Adapter	ORM	@shblhy	✅	PostgreSQL, MySQL, SQLite are supported by Peewee
MongoEngine Adapter	ORM	@zhangbailong945	❌	MongoDB is supported by MongoEngine
Couchbase Adapter	NoSQL	ScienceLogic	✅ (without `remove_filtered_policy()`)	For Couchbase
DynamoDB Adapter	NoSQL	@abqadeer	✅	For DynamoDB

Adapter	Type	Author	AutoSave	Description
File Adapter (built-in)	File	Casbin	❌	For .CSV (Comma-Separated Values) files
EF Adapter	ORM	Casbin	❌	MySQL, PostgreSQL, SQLite, Microsoft SQL Server, Oracle, DB2, etc. are supported by Entity Framework 6
EFCore Adapter	ORM	Casbin	✅	MySQL, PostgreSQL, SQLite, Microsoft SQL Server, Oracle, DB2, etc. are supported by Entity Framework Core

Adapter	Type	Author	AutoSave	Description
File Adapter (built-in)	File	Casbin	❌	For .CSV (Comma-Separated Values) files
Diesel Adapter	ORM	Casbin	✅	SQLite, PostgreSQL, MySQL are supported by Diesel
Sqlx Adapter	ORM	Casbin	✅	PostgreSQL, MySQL are supported by Sqlx with fully asynchronous operation

note

如果使用显式或隐式adapter调用casbin.NewEnforcer()，策略将自动加载。
可以调用e.LoadPolicy() 来从存储中重新加载策略规则。
如果adapter不支持Auto-Save特性，则在添加或删除策略时不能将策略规则自动保存回存储器。 You have to call SavePolicy() manually to save all policy rules.

例子

这里我们提供几个例子:

文件适配器 (内置)

以下代码展示了如何通过内置文件适配器初始化一个enforcer：

PHP

rust

import "github.com/casbin/casbin"

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

use Casbin\Enforcer;

$e = new Enforcer('examples/basic_model.conf', 'examples/basic_policy.csv');

use casbin::prelude::*;

let mut e = Enforcer::new("examples/basic_model.conf", "examples/basic_policy.csv").await?;

它等同于如下代码：

PHP

rust

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)

use Casbin\Enforcer;
use Casbin\Persist\Adapters\FileAdapter;

$a = new FileAdapter('examples/basic_policy.csv');
$e = new Enforcer('examples/basic_model.conf', $a);

use casbin::prelude::*;

let a = FileAdapter::new("examples/basic_policy.csv");
let e = Enforcer::new("examples/basic_model.conf", a).await?;

MySQL 适配器

下面展示了如何从MySQL数据库初始化一个enforcer。此处样例中的MySQL数据库运行在127.0.0.1:3306上，用户为root，密码为空。

rust

PHP

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)

// https://github.com/casbin-rs/diesel-adapter
// make sure you activate feature `mysql`

use casbin::prelude::*;
use diesel_adapter::{ConnOptions, DieselAdapter};

let mut conn_opts = ConnOptions::default();
conn_opts
    .set_hostname("127.0.0.1")
    .set_port(3306)
    .set_host("127.0.0.1:3306") // overwrite hostname, port config
    .set_database("casbin")
    .set_auth("casbin_rs", "casbin_rs");

let a = DieselAdapter::new(conn_opts)?;
let mut e = Enforcer::new("examples/basic_model.conf", a).await?;

// https://github.com/php-casbin/dbal-adapter

use Casbin\Enforcer;
use CasbinAdapter\DBAL\Adapter as DatabaseAdapter;

$config = [
    // Either 'driver' with one of the following values:
    // pdo_mysql,pdo_sqlite,pdo_pgsql,pdo_oci (unstable),pdo_sqlsrv,pdo_sqlsrv,
    // mysqli,sqlanywhere,sqlsrv,ibm_db2 (unstable),drizzle_pdo_mysql
    'driver'     => 'pdo_mysql', 
    'host' => '127.0.0.1',
    'dbname' => 'test',
    'user' => 'root',
    'password' => '',
    'port' => '3306',
];

$a = DatabaseAdapter::newAdapter($config);
$e = new Enforcer('examples/basic_model.conf', $a);

使用自建的adapter

您可以按照如下所示的方式使用您自定义的适配器：

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

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

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

您可以在初始化后重新加载模型与策略，或保存新的策略：

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

自动保存

自动保存机制 (Auto-Save) 是适配器的特性之一。如果当前适配器支持自动保存特性，该适配器可以向存储中添加一个策略规则，或者从存储中移除一个策略规则。这与SavePolicy()不同，因为后者将删除存储中的所有策略规则，并将所有策略规则从Casbin enforcer保存到存储中。因此，当策略规则的数量较多时，使用SavePolicy()可能会出现性能问题。

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

note

Auto-Save 特性是可选的。 Adapter可以选择是否实现它。
Auto-Save 只在Casbin enforcer使用的adapter支持它时才有效。
See the AutoSave column in the above adapter list to see if Auto-Save is supported by an adapter.

Here's an example about how to use 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(...)

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

如何编写 Adapter

All adapters should implement the Adapter interface by providing at least two mandatory methods:LoadPolicy(model model.Model) error and SavePolicy(model model.Model) error.

The other three functions are optional. They should be implemented if the adapter supports the Auto-Save feature.

方法	类型	描述
LoadPolicy()	强制的	从存储中加载所有策略规则
SavePolicy()	强制的	将所有策略规则保存到存储中
AddPolicy()	可选择的	向存储中添加策略规则
RemovePolicy()	可选择的	从存储中删除策略规则
RemoveFilteredPolicy()	可选择的	从存储中删除匹配筛选器的策略规则

note

如果一个适配器不支持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 enforcer will ignore the not implemented error when calling these three optional functions.

关于数据库表结构的创建

As a convention, the adapter should be able to automatically create a database named casbin if it doesn't exist and use it for policy storage. Please use the Xorm adapter as a reference implementation: https://github.com/casbin/xorm-adapter