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

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

Коли адаптер підтримує 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