ข้ามไปยังเนื้อหาหลัก

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() ด้วยตัวเองเพื่อบันทึกกฎนโยบายทั้งหมด

ตัวอย่าง​

ที่นี่เรามีตัวอย่างหลายอย่าง:

อะแดปเตอร์ไฟล์ (ในตัว)​

ด้านล่างนี้แสดงวิธีการเริ่มต้นใช้งาน enforcer จากอะแดปเตอร์ไฟล์ในตัว:

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​

ด้านล่างนี้แสดงวิธีการเริ่มต้นใช้งาน enforcer จากฐานข้อมูล 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()

AutoSave​

มีคุณสมบัติที่เรียกว่า Auto-Save สำหรับอะแดปเตอร์ เมื่ออะแดปเตอร์รองรับ Auto-Save, หมายความว่ามันสามารถรองรับการเพิ่มกฎนโยบายเดี่ยวไปยังที่เก็บข้อมูล, หรือการลบกฎนโยบายเดี่ยวออกจากที่เก็บข้อมูล นี่ไม่เหมือนกับ SavePolicy(), เพราะว่าคำสั่งหลังจะลบกฎนโยบายทั้งหมดในที่เก็บข้อมูลและบันทึกกฎนโยบายทั้งหมดจาก Casbin enforcer ไปยังที่เก็บข้อมูล ดังนั้นอาจเกิดปัญหาด้านประสิทธิภาพเมื่อจำนวนกฎนโยบายมีมาก

เมื่ออะแดปเตอร์รองรับ Auto-Save, คุณสามารถเปลี่ยนตัวเลือกนี้ผ่านฟังก์ชัน Enforcer.EnableAutoSave() ตัวเลือกนี้ถูกเปิดใช้งานโดยค่าเริ่มต้น (หากอะแดปเตอร์รองรับ)

หมายเหตุ
  1. คุณสมบัติ Auto-Save เป็นตัวเลือก อะแดปเตอร์สามารถเลือกที่จะดำเนินการหรือไม่
  2. Auto-Save จะทำงานได้เฉพาะเมื่อ Casbin enforcer ใช้อะแดปเตอร์ที่รองรับมัน
  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()ไม่บังคับลบกฎนโยบายที่ตรงกับตัวกรองออกจากที่เก็บข้อมูล
หมายเหตุ

หากอะแดปเตอร์ไม่รองรับ 'Auto-Save' ควรจะให้การดำเนินการที่ว่างเปล่าสำหรับฟังก์ชันที่ไม่บังคับทั้งสาม นี่คือตัวอย่างสำหรับ 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 จะไม่สนใจข้อผิดพลาด 'not implemented' เมื่อเรียกใช้ฟังก์ชันที่ไม่บังคับทั้งสาม

มีรายละเอียดเกี่ยวกับวิธีการเขียนอะแดปเตอร์

  • โครงสร้างข้อมูล อะแดปเตอร์ควรรองรับการอ่านอย่างน้อยหกคอลัมน์
  • ชื่อฐานข้อมูล ชื่อฐานข้อมูลเริ่มต้นควรเป็น '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 Adapter ปกติ, คุณสามารถห่อหุ้มตรรกะการประมวลผลของคุณเองสำหรับบริบท

A simple reference to the gormadapter: adapter.go