Langkau ke kandungan utama

Adapters

Dalam Casbin, penyimpanan polisi dilaksanakan sebagai pengaya (juga dikenali sebagai perantaraan untuk Casbin). Pengguna Casbin boleh menggunakan pengaya untuk memuatkan peraturan polisi dari penyimpanan (juga dikenali sebagai LoadPolicy()), atau menyimpan peraturan polisi ke dalamnya (juga dikenali sebagai SavePolicy()). Untuk mengekalkan keberatannya, kami tidak meletakkan kod pengaya dalam pustaka utama.

Pengaya yang disokong​

Senarai lengkap pengaya Casbin diberikan seperti di bawah. Sumbangan pihak ketiga ke atas pengaya baru dialu-alukan, sila maklumkan kepada kami dan kami akan meletakkannya dalam senarai ini:

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
nota
  1. Jika casbin.NewEnforcer() dipanggil dengan pengaya yang jelas atau tersirat, dasar akan dimuatkan secara automatik.
  2. Anda boleh memanggil e.LoadPolicy() untuk memuatkan semula peraturan dasar dari storan.
  3. Jika pengaya tidak menyokong ciri Auto-Save, Peraturan dasar tidak boleh disimpan semula ke storan secara automatik apabila anda menambah atau mengalih keluar dasar. Anda perlu memanggil SavePolicy() secara manual untuk menyimpan semua peraturan dasar.

Contoh​

Di sini kami menyediakan beberapa contoh:

Pengaya Fail (terbina dalam)​

Di bawah menunjukkan cara untuk memulakan enforcer dari pengaya fail terbina dalam:

import "github.com/casbin/casbin"

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

Ini adalah sama dengan:

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)

Penyesuai MySQL​

Di bawah menunjukkan cara memulakan enforcer dari pangkalan data MySQL. ia menyambung ke DB MySQL di 127.0.0.1:3306 dengan root dan kata laluan kosong.

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)

Gunakan penyesuai storan anda sendiri​

Anda boleh menggunakan penyesuai anda sendiri seperti di bawah:

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

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

Migrasi/Tukar antara penyesuai yang berbeza​

Jika anda ingin menukar penyesuai dari A ke B, anda boleh lakukan seperti ini:

1.Muatkan polisi dari A ke memori

e, _ := NewEnforcer(m, A)

atau

e.SetAdapter(A)
e.LoadPolicy()

Tukar penyesuai anda dari A ke B

e.SetAdapter(B)

Simpan polisi dari memori ke B

e.SavePolicy()

Muat/Simpan pada masa berjalan​

Anda mungkin juga ingin memuat semula model, memuat semula polisi atau menyimpan polisi selepas inisialisasi:

// 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()

AutoSimpan​

Terdapat satu ciri yang dipanggil "Auto-Save" untuk penyesuai. Apabila penyesuai menyokong "Auto-Save", ini bermakna ia boleh menyokong menambah satu peraturan polisi ke storan, atau mengalih keluar satu peraturan polisi dari storan. Ini berbeza dengan "SavePolicy()", kerana yang terakhir akan memadam semua peraturan polisi dalam storan dan menyimpan semua peraturan polisi dari enforcer Casbin ke storan. Jadi ia mungkin mengalami masalah prestasi apabila bilangan peraturan polisi adalah besar.

Apabila penyesuai menyokong "Auto-Save", anda boleh menukar pilihan ini melalui fungsi Enforcer.EnableAutoSave(). Pilihan ini diaktifkan secara lalai (jika penyambung menyokongnya).

nota
  1. Ciri Auto-Save adalah pilihan. Penyambung boleh memilih untuk melaksanakannya atau tidak.
  2. Auto-Save hanya berfungsi untuk enforcer Casbin apabila penyambung yang digunakan oleh enforcer itu menyokongnya.
  3. Lihat lajur AutoSave dalam senarai penyambung di atas untuk melihat sama ada Auto-Save disokong oleh penyambung.

Berikut adalah contoh tentang cara menggunakan 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(...)

Untuk lebih banyak contoh, sila lihat: https://github.com/casbin/xorm-adapter/blob/master/adapter_test.go

Cara menulis penyambung​

Semua penyambung harus melaksanakan antara muka Adapter dengan menyediakan sekurang-kurangnya dua kaedah wajib: LoadPolicy(model model.Model) error dan SavePolicy(model model.Model) error.

Tiga fungsi lain adalah pilihan. Ia harus dilaksanakan jika pengubah suai menyokong ciri Auto-Save.

KaedahJenisPenerangan
LoadPolicy()wajibMuatkan semua peraturan dasar dari storan
SavePolicy()wajibSimpan semua peraturan dasar ke storan
AddPolicy()pilihanTambahkan peraturan polisi ke dalam penyimpanan
RemovePolicy()pilihanBuang peraturan polisi dari penyimpanan
RemoveFilteredPolicy()pilihanBuang peraturan polisi yang sesuai dengan penapis dari penyimpanan
nota

Jika pengubah tidak menyokong Auto-Save, ia harus memberikan pelaksanaan kosong untuk ketiga-tiga fungsi pilihan tersebut. Berikut adalah contoh untuk 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")
}

Enforcer Casbin akan mengabaikan ralat tidak dilaksanakan apabila memanggil tiga fungsi pilihan ini.

Terdapat butiran mengenai cara menulis penyesuai.

  • Struktur Data. Penyesuai harus menyokong pembacaan sekurang-kurangnya enam lajur.
  • Nama Pangkalan Data. Nama pangkalan data lalai haruslah casbin.
  • Nama Jadual. Nama jadual lalai haruslah casbin_rule.
  • Lajur Ptype. Nama lajur ini harus menjadi ptype bukan p_type atau Ptype.
  • Definisi jadual harus menjadi (id int primary key, ptype varchar, v0 varchar, v1 varchar, v2 varchar, v3 varchar, v4 varchar, v5 varchar).
  • Indeks kunci unik harus dibina pada lajur ptype,v0,v1,v2,v3,v4,v5.
  • LoadFilteredPolicy memerlukan filter sebagai parameter. Penapis harus menjadi seperti ini.
{
    "p":[ [ "alice" ], [ "bob" ] ],
    "g":[ [ "", "book_group" ], [ "", "pen_group" ] ],
    "g2":[ [ "alice" ] ]
}

Siapa yang bertanggungjawab untuk mencipta DB?​

Sebagai konvensyen, pengubahsuai harus dapat mencipta pangkalan data bernama casbin secara automatik jika ia tidak wujud dan menggunakannya untuk penyimpanan dasar. Sila gunakan pengubahsuai Xorm sebagai pelaksanaan rujukan: https://github.com/casbin/xorm-adapter

Pengubahsuai Konteks​

ContextAdapter menyediakan antara muka yang sedar konteks untuk pengubahsuai Casbin.

Melalui konteks, anda boleh melaksanakan ciri-ciri seperti kawalan timeout untuk API Adapter

Contoh​

gormadapter menyokong adapter dengan konteks, berikut adalah kawalan timeout yang dilaksanakan menggunakan konteks

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

Cara menulis adapter konteks​

ContextAdapter API hanya mempunyai lapisan tambahan pemprosesan konteks berbanding API Adapter biasa,

Rujukan mudah kepada gormadapter: adapter.go