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

Adapters

У Casbin зберігання політики реалізовано як адаптер (також відомий як проміжне ПЗ для Casbin). Користувач Casbin може використовувати адаптер для завантаження правил політики зі сховища (також відомо як LoadPolicy()), або зберігати правила політики в ньому (також відомо як SavePolicy()). Щоб залишатися легковаговими, ми не включаємо код адаптера в основну бібліотеку.

Підтримувані адаптери

Повний список адаптерів Casbin наведено нижче. Будь-який внесок сторонніх розробників щодо нового адаптера вітається, будь ласка, повідомте нас, і ми додамо його до цього списку:

AdapterTypeAuthorAutoSaveDescription
File Adapter (built-in)FileCasbinFor .CSV (Comma-Separated Values) files
Filtered File Adapter (built-in)File@faceless-saintFor .CSV (Comma-Separated Values) files with policy subset loading support
SQL AdapterSQL@Blank-XuMySQL, PostgreSQL, SQL Server, SQLite3 are supported in master branch and Oracle is supported in oracle branch by database/sql
Xorm AdapterORMCasbinMySQL, PostgreSQL, TiDB, SQLite, SQL Server, Oracle are supported by Xorm
GORM AdapterORMCasbinMySQL, PostgreSQL, Sqlite3, SQL Server are supported by GORM
GORM Adapter ExORMCasbinMySQL, PostgreSQL, Sqlite3, SQL Server are supported by GORM
Ent AdapterORMCasbinMySQL, MariaDB, PostgreSQL, SQLite, Gremlin-based graph databases are supported by ent ORM
Beego ORM AdapterORMCasbinMySQL, PostgreSQL, Sqlite3 are supported by Beego ORM
SQLX AdapterORM@memweyMySQL, PostgreSQL, SQLite, Oracle are supported by SQLX
Sqlx AdapterORM@Blank-XuMySQL, PostgreSQL, SQL Server, SQLite3 are supported in master branch and Oracle is supported in oracle branch by sqlx
GF ORM AdapterORM@vance-liuMySQL, SQLite, PostgreSQL, Oracle, SQL Server are supported by GoFrame ORM
GoFrame ORM AdapterORM@kotlin2018MySQL, SQLite, PostgreSQL, Oracle, SQL Server are supported by GoFrame ORM
gf-adapterORM@zcycMySQL, SQLite, PostgreSQL, Oracle, SQL Server are supported by GoFrame ORM
Gdb AdapterORM@jxo-meMySQL, SQLite, PostgreSQL, Oracle, SQL Server are supported by GoFrame ORM
GoFrame V2 AdapterORM@hailazMySQL, SQLite, PostgreSQL, Oracle, SQL Server are supported by GoFrame ORM
Bun AdapterORM@JunNishimuraMySQL, SQLite, PostgreSQL, SQL Server are supported by Bun ORM
Filtered PostgreSQL AdapterSQLCasbinFor PostgreSQL
Filtered pgx AdapterSQL@pckhoiPostgreSQL is supported by pgx
PostgreSQL AdapterSQL@cychiuaeFor PostgreSQL
RQLite AdapterSQLEDOMO SystemsFor RQLite
MongoDB AdapterNoSQLCasbinFor MongoDB based on MongoDB Go Driver
RethinkDB AdapterNoSQL@adityapandey9For RethinkDB
Cassandra AdapterNoSQLCasbinFor Apache Cassandra DB
DynamoDB AdapterNoSQLHOOQFor Amazon DynamoDB
DynacasbinNoSQLNewbMiaoFor Amazon DynamoDB
ArangoDB AdapterNoSQL@adamwasilaFor ArangoDB
Amazon S3 AdapterCloudSolutoFor Minio and Amazon S3
Go CDK AdapterCloud@bartventerAdapter based on Go Cloud Dev Kit that supports: Amazon DynamoDB, Azure CosmosDB, GCP Firestore, MongoDB, In-Memory
Azure Cosmos DB AdapterCloud@spacycoderFor Microsoft Azure Cosmos DB
GCP Firestore AdapterCloud@reedomFor Google Cloud Platform Firestore
GCP Cloud Storage AdapterCloudquramiFor Google Cloud Platform Cloud Storage
GCP Cloud Spanner AdapterCloud@flowerinthenightFor Google Cloud Platform Cloud Spanner
Consul AdapterKV store@ankitm123For HashiCorp Consul
Redis Adapter (Redigo)KV storeCasbinFor Redis
Redis Adapter (go-redis)KV store@mlsenFor Redis
Etcd AdapterKV store@sebastianliuFor etcd
BoltDB AdapterKV store@spezaFor Bolt
Bolt AdapterKV store@wirepairFor Bolt
BadgerDB AdapterKV store@initsFor BadgerDB
Protobuf AdapterStreamCasbinFor Google Protocol Buffers
JSON AdapterStringCasbinFor JSON
String AdapterString@qiangmzsxFor String
HTTP File AdapterHTTP@h4ckednekoFor http.FileSystem
FileSystem AdapterFile@nauconFor 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 в сховище. Таким чином, це може створити проблеми з продуктивністю, коли кількість правил політики велика.

Коли адаптер підтримує 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()необов'язковийВидалити правила політики, які відповідають фільтру, зі сховища
примітка

Якщо адаптер не підтримує 'Авто-Збереження', він повинен надати порожню реалізацію для трьох необов'язкових функцій. Ось приклад для 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 ігноруватиме помилку 'не реалізовано' при виклику цих трьох необов'язкових функцій.

Тут є деталі про те, як написати адаптер.

  • Структура даних. Адаптер повинен підтримувати читання принаймні шести колонок.
  • Назва бази даних. Назва бази даних за замовчуванням повинна бути '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

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

Як написати адаптер з контекстом

API 'ContextAdapter' має лише додатковий шар обробки контексту порівняно зі звичайним API 'Adapter', і на основі реалізації звичайного API адаптера, ви можете інкапсулювати власну логіку обробки для контексту

A simple reference to the gormadapter: adapter.go