Adapters
在Casbin中，策略存储作为adapter(Casbin的中间件) 实现。 Casbin用户可以使用adapte从存储中加载策略规则 (aka LoadPolicy()) 或者将策略规则保存到其中 (aka SavePolicy())。 为了保持代码轻量级，我们没有把adapte代码放在主库中。
目前支持的adapter列表
Casbin角色管理器的完整列表如下所示。 欢迎任何第三方对adapter进行新的贡献，如果有请通知我们，我们将把它放在这个列表中:)
| 适配器 | 类型 | 作者 | 自动保存 | 描述 |
|---|---|---|---|---|
| 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 |
| 适配器 | 类型 | 作者 | 自动保存 | 描述 |
|---|---|---|---|---|
| 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 | ✅ | MongoDB is supported by Mongoose |
| Knex Adapter | ORM | @sarneeh | ✅ | MSSQL, MySQL, PostgreSQL, SQLite3, Oracle are supported by Knex.js |
| 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 Database Adapter |
| 适配器 | 类型 | 作者 | 自动保存 | 描述 |
|---|---|---|---|---|
| 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 |
| Adapter | Type | Author | AutoSave | Description |
|---|---|---|---|---|
| File Adapter (built-in) | File | Casbin | ❌ | For .CSV (Comma-Separated Values) files |
| EFCore Adapter | ORM | Casbin | ❌ | MySQL, PostgreSQL, SQLite, Microsoft SQL Server, Oracle, DB2, etc. are supported by Entity Framework Core |
Here are some things you need to know:
- 如果使用显式或隐式adapter调用
casbin.NewEnforcer()，策略将自动加载。 - 可以调用
e.LoadPolicy()来从存储中重新加载策略规则。 - 如果adapter不支持
Auto-Save特性，则在添加或删除策略时不能将策略规则自动保存回存储器。 您可以手动调用SavePolicy()来保存所有策略规则。
例子
Here we provide several examples:
文件适配器 (内置)
Below shows how to initialize an enforcer from the built-in file adapter:
import "github.com/casbin/casbin"
e := casbin.NewEnforcer("examples/basic_model.conf", "examples/basic_policy.csv")
This is the same with:
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 适配器
Below shows how to initialize an enforcer from MySQL database. it connects to a MySQL DB on 127.0.0.1:3306 with root and blank password.
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
You can use your own adapter like below:
import (
"github.com/casbin/casbin"
"github.com/your-username/your-repo"
)
a := yourpackage.NewAdapter(params)
e := casbin.NewEnforcer("examples/basic_model.conf", a)
在运行时进行加载或保存配置信息
You may also want to reload the model, reload the policy or save the policy after initialization:
// 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()
自动保存
There is a feature called Auto-Save for adapters. When an adapter supports Auto-Save, it means it can support adding a single policy rule to the storage, or removing a single policy rule from the storage. This is unlike SavePolicy(), because the latter will delete all policy rules in the storage and save all policy rules from Casbin enforcer to the storage. So it may suffer performance issue when the number of policy rules is large.
When the adapter supports Auto-Save, you can switch this option via Enforcer.EnableAutoSave() function. The option is enabled by default (if the adapter supports it).
Note:
Auto-Save特性是可选的。 Adapter可以选择是否实现它。Auto-Save只在Casbin enforcer使用的adapter支持它时才有效。- 查看上述adapter列表中的
AutoSave列，查看adapter是否支持Auto-Save。
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: if an adapter doesn't support the Auto-Save feature, it should provide an empty implementation for the three optional functions. If you don't provide it, Golang compiler will complain errors. Here's an example:
// 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