التخطي إلى المحتوى الرئيسي

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 على 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()

الحفظ التلقائي​

هناك ميزة تسمى 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 الخطأ 'غير مُنفذ' عند استدعاء هذه الوظائف الثلاث الاختيارية.

هناك تفاصيل حول كيفية كتابة محول.

  • هيكل البيانات. يجب أن يدعم المحول قراءة ستة أعمدة على الأقل.
  • اسم قاعدة البيانات. يجب أن يكون اسم قاعدة البيانات الافتراضي '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.

من خلال السياق، يمكنك تنفيذ ميزات مثل التحكم في وقت الانتظار لواجهة برمجة تطبيقات المحول

مثال​

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' لديها فقط طبقة إضافية من معالجة السياق أكثر من واجهة برمجة تطبيقات 'Adapter' العادية، وعلى أساس تنفيذ واجهة برمجة تطبيقات المحول العادية، يمكنك تغليف منطق معالجتك الخاص للسياق

إشارة بسيطة إلى gormadapter: adapter.go