Bỏ qua đến nội dung chính

Adapters

Trong Casbin, việc lưu trữ chính sách được triển khai như một adapter (hay middleware cho Casbin). Người dùng Casbin có thể sử dụng một adapter để tải các quy tắc chính sách từ bộ lưu trữ (aka LoadPolicy()), hoặc lưu các quy tắc chính sách vào đó (aka SavePolicy()). Để giữ cho thư viện chính nhẹ nhàng, chúng tôi không đưa mã adapter vào thư viện chính.

Các adapter được hỗ trợ​

Danh sách đầy đủ các bộ điều hợp Casbin được cung cấp như sau. Bất kỳ đóng góp của bên thứ ba về một bộ điều hợp mới đều được hoan nghênh, vui lòng thông báo cho chúng tôi và chúng tôi sẽ đưa nó vào danh sách này:

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
ghi chú
  1. Nếu casbin.NewEnforcer() được gọi với một bộ điều hợp rõ ràng hoặc ngầm định, chính sách sẽ được tải tự động.
  2. Bạn có thể gọi e.LoadPolicy() để tải lại các quy tắc chính sách từ bộ nhớ.
  3. Nếu bộ điều hợp không hỗ trợ tính năng Tự động Lưu, các quy tắc chính sách không thể được lưu tự động trở lại bộ nhớ khi bạn thêm hoặc xóa chính sách. Bạn phải gọi SavePolicy() thủ công để lưu tất cả các quy tắc chính sách.

Ví dụ​

Dưới đây chúng tôi cung cấp một số ví dụ:

Bộ điều hợp tệp (tích hợp sẵn)​

Dưới đây chỉ ra cách khởi tạo một enforcer từ bộ điều hợp tệp tích hợp sẵn:

import "github.com/casbin/casbin"

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

Điều này giống với:

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​

Dưới đây chỉ ra cách khởi tạo một enforcer từ cơ sở dữ liệu MySQL. Nó kết nối đến một cơ sở dữ liệu MySQL trên 127.0.0.1:3306 với tên người dùng root và mật khẩu trống.

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)

Sử dụng adapter lưu trữ của riêng bạn​

Bạn có thể sử dụng adapter của riêng bạn như dưới đây:

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

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

Di chuyển/Chuyển đổi giữa các adapter khác nhau​

Nếu bạn muốn chuyển đổi adapter từ A sang B, bạn có thể làm như thế này:

  1. Tải chính sách từ A vào bộ nhớ
e, _ := NewEnforcer(m, A)

hoặc

e.SetAdapter(A)
e.LoadPolicy()

Chuyển đổi bộ chuyển đổi của bạn từ A sang B

e.SetAdapter(B)

Lưu chính sách từ bộ nhớ vào B

e.SavePolicy()

Tải/Lưu trong quá trình chạy​

Bạn cũng có thể muốn tải lại mô hình, tải lại chính sách hoặc lưu chính sách sau khi khởi tạo:

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

Tự động Lưu​

Có một tính năng gọi là Tự động Lưu cho các bộ chuyển đổi. Khi một bộ chuyển đổi hỗ trợ Tự động Lưu, điều đó có nghĩa là nó có thể hỗ trợ thêm một quy tắc chính sách vào bộ nhớ, hoặc xóa một quy tắc chính sách khỏi bộ nhớ. Điều này khác với LưuChínhSách(), bởi vì hàm sau sẽ xóa tất cả các quy tắc chính sách trong bộ nhớ và lưu tất cả các quy tắc chính sách từ trình thực thi Casbin vào bộ nhớ. Vì vậy, nó có thể gặp vấn đề về hiệu suất khi số lượng quy tắc chính sách lớn.

Khi bộ chuyển đổi hỗ trợ Tự động Lưu, bạn có thể chuyển đổi tùy chọn này thông qua hàm Enforcer.EnableAutoSave(). Tùy chọn này được bật theo mặc định (nếu bộ điều hợp hỗ trợ nó).

ghi chú
  1. Tính năng Auto-Save là tùy chọn. Một bộ điều hợp có thể chọn triển khai nó hoặc không.
  2. Auto-Save chỉ hoạt động cho một enforcer Casbin khi bộ điều hợp mà enforcer sử dụng hỗ trợ nó.
  3. Xem cột AutoSave trong danh sách bộ điều hợp ở trên để xem Auto-Save có được hỗ trợ bởi một bộ điều hợp hay không.

Đây là một ví dụ về cách sử dụng 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(...)

Để biết thêm ví dụ, vui lòng xem: https://github.com/casbin/xorm-adapter/blob/master/adapter_test.go

Cách viết một bộ điều hợp​

Tất cả các bộ điều hợp nên triển khai giao diện Adapter bằng cách cung cấp ít nhất hai phương thức bắt buộc: LoadPolicy(model model.Model) error và SavePolicy(model model.Model) error.

Ba chức năng khác là tùy chọn. Chúng nên được triển khai nếu adapter hỗ trợ tính năng Auto-Save.

Phương thứcKiểuMô tả
LoadPolicy()bắt buộcTải tất cả các quy tắc chính sách từ bộ nhớ
SavePolicy()bắt buộcLưu tất cả các quy tắc chính sách vào bộ nhớ
AddPolicy()tùy chọnThêm một quy tắc chính sách vào kho lưu trữ
RemovePolicy()tùy chọnXóa một quy tắc chính sách khỏi kho lưu trữ
RemoveFilteredPolicy()tùy chọnXóa các quy tắc chính sách khớp với bộ lọc khỏi kho lưu trữ
ghi chú

Nếu một bộ điều hợp không hỗ trợ Tự động Lưu, nó nên cung cấp một triển khai trống cho ba chức năng tùy chọn. Đây là một ví dụ cho 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")
}

Bộ thực thi Casbin sẽ bỏ qua lỗi not implemented khi gọi ba hàm tùy chọn này.

Có chi tiết về cách viết một adapter.

  • Cấu trúc dữ liệu. Adapter nên hỗ trợ đọc ít nhất sáu cột.
  • Tên cơ sở dữ liệu. Tên cơ sở dữ liệu mặc định nên là casbin.
  • Tên bảng. Tên bảng mặc định nên là casbin_rule.
  • Cột Ptype. Tên của cột này nên là ptype thay vì p_type hoặc Ptype.
  • Định nghĩa bảng nên là (id int primary key, ptype varchar, v0 varchar, v1 varchar, v2 varchar, v3 varchar, v4 varchar, v5 varchar).
  • Chỉ mục khóa duy nhất nên được xây dựng trên các cột ptype,v0,v1,v2,v3,v4,v5.
  • LoadFilteredPolicy yêu cầu một filter làm tham số. Bộ lọc nên là một cái gì đó như thế này.
{
    "p":[ [ "alice" ], [ "bob" ] ],
    "g":[ [ "", "book_group" ], [ "", "pen_group" ] ],
    "g2":[ [ "alice" ] ]
}

Ai là người chịu trách nhiệm tạo cơ sở dữ liệu?​

Theo quy ước, bộ điều hợp nên có khả năng tự động tạo một cơ sở dữ liệu có tên là casbin nếu nó chưa tồn tại và sử dụng nó để lưu trữ chính sách. Vui lòng sử dụng bộ điều hợp Xorm làm triển khai tham chiếu: https://github.com/casbin/xorm-adapter

Bộ điều hợp Context​

ContextAdapter cung cấp một giao diện nhận biết ngữ cảnh cho các bộ điều hợp Casbin.

Thông qua ngữ cảnh, bạn có thể triển khai các tính năng như kiểm soát thời gian chờ cho API của Adapter

Ví dụ​

gormadapter hỗ trợ adapter với ngữ cảnh, đoạn mã sau là một kiểm soát thời gian chờ được triển khai bằng cách sử dụng ngữ cảnh

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

Cách viết một adapter ngữ cảnh​

ContextAdapter API chỉ có một lớp xử lý ngữ cảnh bổ sung so với API Adapter thông thường,

Một tài liệu tham khảo đơn giản về gormadapter: adapter.go