Zum Hauptinhalt springen

Adapters

In Casbin wird der Richtlinienspeicher als Adapter implementiert (auch bekannt als Middleware für Casbin). Ein Casbin-Benutzer kann einen Adapter verwenden, um Richtlinienregeln von einem Speicher zu laden (auch bekannt als LoadPolicy()), oder um Richtlinienregeln darin zu speichern (auch bekannt als SavePolicy()). Um leichtgewichtig zu bleiben, setzen wir den Adaptercode nicht in die Hauptbibliothek.

Unterstützte Adapter​

Eine vollständige Liste der Casbin-Adapter finden Sie unten. Jeder Beitrag von Dritten zu einem neuen Adapter ist willkommen, bitte informieren Sie uns und wir werden ihn in diese Liste aufnehmen:

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
notiz
  1. Wenn casbin.NewEnforcer() mit einem expliziten oder impliziten Adapter aufgerufen wird, wird die Richtlinie automatisch geladen.
  2. Sie können e.LoadPolicy() aufrufen, um die Richtlinienregeln aus dem Speicher neu zu laden.
  3. Wenn der Adapter die Funktion Auto-Save nicht unterstützt, können die Richtlinienregeln nicht automatisch zurück in den Speicher gespeichert werden, wenn Sie Richtlinien hinzufügen oder entfernen. Sie müssen SavePolicy() manuell aufrufen, um alle Richtlinienregeln zu speichern.

Beispiele​

Hier stellen wir einige Beispiele vor:

Dateiadapter (eingebaut)​

Unten wird gezeigt, wie ein Durchsetzer vom eingebauten Dateiadapter initialisiert wird:

import "github.com/casbin/casbin"

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

Das ist das Gleiche wie:

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-Adapter​

Unten wird gezeigt, wie ein Durchsetzer von einer MySQL-Datenbank initialisiert wird. Es stellt eine Verbindung zu einer MySQL-DB auf 127.0.0.1:3306 mit root und leerem Passwort her.

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)

Verwenden Sie Ihren eigenen Speicheradapter​

Sie können Ihren eigenen Adapter wie folgt verwenden:

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

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

Migration/Konvertierung zwischen verschiedenen Adaptern​

Wenn Sie den Adapter von A zu B konvertieren möchten, können Sie dies wie folgt tun:

  1. Laden Sie die Richtlinie von A in den Speicher
e, _ := NewEnforcer(m, A)

oder

e.SetAdapter(A)
e.LoadPolicy()
  1. Konvertieren Sie Ihren Adapter von A zu B
e.SetAdapter(B)
  1. Speichern Sie die Richtlinie vom Speicher zu B
e.SavePolicy()

Laden/Speichern zur Laufzeit​

Sie möchten vielleicht auch das Modell neu laden, die Richtlinie neu laden oder die Richtlinie nach der Initialisierung speichern:

// 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​

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).

notiz
  1. The Auto-Save feature is optional. An adapter can choose to implement it or not.
  2. Auto-Save only works for a Casbin enforcer when the adapter the enforcer uses supports it.
  3. 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

How to write an 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.

MethodTypeDescription
LoadPolicy()mandatoryLoad all policy rules from the storage
SavePolicy()mandatorySave all policy rules to the storage
AddPolicy()optionalAdd a policy rule to the storage
RemovePolicy()optionalEntfernen Sie eine Richtlinienregel aus dem Speicher
RemoveFilteredPolicy()optionalEntfernen Sie Richtlinienregeln, die dem Filter entsprechen, aus dem Speicher
notiz

Wenn ein Adapter "Auto-Save" nicht unterstützt, sollte er eine leere Implementierung für die drei optionalen Funktionen bereitstellen. Hier ist ein Beispiel für 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 wird den Fehler "nicht implementiert" ignorieren, wenn diese drei optionalen Funktionen aufgerufen werden.

Es gibt Details darüber, wie man einen Adapter schreibt.

  • Datenstruktur. Adapter sollte das Lesen von mindestens sechs Spalten unterstützen.
  • Datenbankname. Der Standarddatenbankname sollte casbin sein.
  • Tabellenname. Der Standardtabellenname sollte casbin_rule sein.
  • Ptype-Spalte. Der Name dieser Spalte sollte ptype statt p_type oder Ptype sein.
  • Die Tabellendefinition sollte (id int primary key, ptype varchar, v0 varchar, v1 varchar, v2 varchar, v3 varchar, v4 varchar, v5 varchar) sein.
  • Der eindeutige Schlüsselindex sollte auf den Spalten ptype,v0,v1,v2,v3,v4,v5 erstellt werden.
  • LoadFilteredPolicy erfordert einen filter als Parameter. Der Filter sollte so etwas sein.
{
    "p":[ [ "alice" ], [ "bob" ] ],
    "g":[ [ "", "book_group" ], [ "", "pen_group" ] ],
    "g2":[ [ "alice" ] ]
}

Wer ist verantwortlich für die Erstellung der DB?​

Nach Konvention sollte der Adapter in der Lage sein, automatisch eine Datenbank namens casbin zu erstellen, wenn sie nicht existiert, und sie zur Richtlinienspeicherung zu verwenden. Bitte verwenden Sie den Xorm-Adapter als Referenzimplementierung: https://github.com/casbin/xorm-adapter

Context Adapter​

ContextAdapter bietet eine kontextbewusste Schnittstelle für Casbin-Adapter.

Durch den Kontext können Sie Funktionen wie die Timeout-Steuerung für die Adapter-API implementieren

Beispiel​

gormadapter unterstützt Adapter mit Kontext, das Folgende ist eine Timeout-Steuerung, die mit Kontext implementiert wird

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

Wie man einen Kontextadapter schreibt​

ContextAdapter API hat nur eine zusätzliche Schicht der Kontextverarbeitung als gewöhnliche Adapter API, und auf der Grundlage der Implementierung gewöhnlicher Adapter API können Sie Ihre eigene Verarbeitungslogik für Kontext kapseln

A simple reference to the gormadapter: context_adapter.go