Перейти к основному контенту

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. он подключается к MySQL DB на 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)

Используйте свой собственный адаптер хранения​

Вы можете использовать свой собственный адаптер, как показано ниже:

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 enforcer в хранилище. Таким образом, могут возникнуть проблемы с производительностью, когда количество правил политики велико.

Когда адаптер поддерживает Auto-Save, вы можете переключить эту опцию с помощью функции Enforcer.EnableAutoSave(). Опция включена по умолчанию (если адаптер ее поддерживает).

заметка
  1. Функция Auto-Save является необязательной. Адаптер может выбрать, реализовать ее или нет.
  2. Auto-Save работает только для Casbin enforcer, когда адаптер, который использует enforcer, поддерживает его.
  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 enforcer проигнорирует ошибку 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, вы можете инкапсулировать свою собственную логику обработки для контекста

A simple reference to the gormadapter: adapter.go