Перейти к основному содержимому

Обновление Casbin (Go) с v2 до v3: Полное руководство по миграции

· 8 мин. чтения
Yang Luo
Creator of Casbin

Если вы используете Casbin v2 в продакшене и задумываетесь о переходе на v3, это руководство для вас. Мы расскажем всё, что нужно знать о переходе: от понимания изменений до безопасной миграции в production-среде.

Что изменилось в v3?​

Хорошая новость: v3 — это преимущественно изменение пути модуля при полной обратной совместимости. Основная логика авторизации, API и функциональность остаются неизменными. Это было осознанное решение, чтобы минимизировать сбои при соблюдении соглашений о семантическом версионировании Go.

Главное изменение: Путь модуля​

Единственное ломающее изменение в v3 — это путь модуля Go:

// v2
import "github.com/casbin/casbin/v2"

// v3
import "github.com/casbin/casbin/v3"

Вот и всё. Вашим существующим политикам, моделям и логике кода не нужны изменения. Миграция носит механический характер: обновите инструкции импорта и файл go.mod.

Зачем выпускать v3?​

Вы можете удивиться, зачем выпускать новую мажорную версию только ради изменения пути импорта. Ответ кроется в семантическом версионировании. Система модулей Go использует номер мажорной версии в пути импорта (/v2, /v3 и т. д.). Это позволяет нескольким мажорным версиям сосуществовать в одном дереве зависимостей, что критично для крупных приложений со множеством зависимостей.

Выпустив v3, мы:

  • Привели проект в соответствие с правилами семантического импорта версий Go
  • Обеспечили возможность постепенной миграции в сложных графах зависимостей
  • Заложили основу для будущих улучшений без нарушения работы текущих пользователей v2

Что осталось прежним?​

Всё остальное. Серьёзно.

  • Все API остались идентичными — Enforce(), AddPolicy(), GetAllRoles() и все остальные методы работают точно так же, как раньше
  • Синтаксис моделей и политик не изменился — Ваши существующие файлы моделей .conf и файлы политик .csv работают без модификаций
  • Интерфейс адаптера не изменился — Методы persist.Adapter те же самые; адаптерам требуется только релиз, собранный под путь модуля v3
  • Характеристики производительности — Нет регрессий или улучшений производительности; это тот же самый движок
  • Интеграции middleware — Middleware работает так же, как раньше, после того как он импортирует ту же мажорную версию, что и ваш энфорсер

Новые функции в v3​

С момента релиза v3.0.0 в декабре 2025 года было добавлено несколько новых функций:

v3.7.0+: Улучшенная интеграция Logger​

Теперь вы можете интегрировать пользовательские логгеры в основные операции принудительного применения и управления политиками Casbin, обеспечивая лучшую наблюдаемость:

enforcer.SetLogger(yourCustomLogger)

v3.8.0+: API GetAllUsers()​

Новый API для различения пользователей и ролей:

users, err := enforcer.GetAllUsers()

Это особенно полезно в системах RBAC, где нужно отдельно перечислять реальных пользователей и определения ролей.

v3.9.0+: Встроенное обнаружение циклов​

Энфорсер теперь включает автоматическое обнаружение циклов в иерархии ролей, предотвращая бесконечные циклы:

// Automatically detects and prevents circular role assignments
enforcer.AddGroupingPolicy("alice", "admin")
enforcer.AddGroupingPolicy("admin", "alice") // Will be detected as a cycle

v3.10.0+: API Explain() для получения инсайтов об авторизации с помощью ИИ​

Последняя функция использует LLM API для объяснения решений авторизации на естественном языке:

enforcer.SetAIConfig(casbin.AIConfig{
Endpoint: "https://api.openai.com/v1/chat/completions",
APIKey: os.Getenv("OPENAI_API_KEY"),
Model: "gpt-4",
})

explanation, err := enforcer.Explain("alice", "data1", "read")
// e.g. "Alice can read data1 because she has the 'reader' role..."

Это особенно ценно для отладки сложных политик и помощи нетехническим заинтересованным сторонам в понимании решений авторизации.

Стратегия миграции​

Для новых проектов​

Просто: используйте v3 с самого начала.

go get github.com/casbin/casbin/v3
import "github.com/casbin/casbin/v3"

Для существующих проектов на v2​

Миграция включает три шага:

Шаг 1. Обновите go.mod​

go get github.com/casbin/casbin/v3
go mod tidy

Шаг 2. Обновите инструкции импорта​

Найдите и замените все импорты Casbin в вашей кодовой базе:

# Using sed on Unix/Linux/Mac
find . -type f -name '*.go' -exec sed -i 's|github.com/casbin/casbin/v2|github.com/casbin/casbin/v3|g' {} +

# Or manually in your editor
# Find: github.com/casbin/casbin/v2
# Replace: github.com/casbin/casbin/v3

Шаг 3. Обновите импорты адаптеров (если применимо)​

Адаптер реализует persist.Adapter от одной конкретной мажорной версии, поскольку model.Model в casbin/v2 и casbin/v3 — это разные типы Go. Следовательно, для enforcer из v3 требуется релиз адаптера, который импортирует github.com/casbin/casbin/v3. Проверьте go.mod адаптера:

// Example: the PostgreSQL adapter already depends on casbin/v3
import pgadapter "github.com/apache/casbin-pg-adapter"

// The file adapter is built in and ships with each major version

Если ваш адаптер ещё не обновлён, оставайтесь на v2 для этого сервиса до обновления или создайте issue в репозитории адаптера.

План отката​

Если вам нужно выполнить откат:

  1. Уровень кода: Отмените изменения в импортах (используйте контроль версий)
  2. Уровень зависимостей: go get github.com/casbin/casbin/v2@latest
  3. Развёртывание: Используйте стандартный процесс развёртывания для возврата к предыдущей версии

Прелесть этой миграции в том, что откат тривиален — просто отмените изменения в импортах и передеплойте приложение.

Нужно ли мигрировать базу данных политик?​

Нет. Ваши существующие данные политик остаются неизменными. Политики хранятся в виде простых строк (subject, object, action и т.д.) и не зависят от версии Casbin.

Тестирование миграции​

Автоматизированное тестирование​

Ваши существующие тесты должны проходить без изменений:

func TestPolicyEnforcement(t *testing.T) {
// This test works identically in v2 and v3
e, _ := casbin.NewEnforcer("model.conf", "policy.csv")

ok, _ := e.Enforce("alice", "data1", "read")
if !ok {
t.Error("Expected alice to have read access to data1")
}
}

Интеграционное тестирование​

Middleware, принимающий *casbin.Enforcer, привязан к одной мажорной версии так же, как и адаптеры. Если ваш middleware всё ещё импортирует casbin/v2, прямой вызов enforcer требует всего нескольких строк кода:

// Example with Gin
import (
"net/http"

"github.com/casbin/casbin/v3"
"github.com/gin-gonic/gin"
)

func Authorizer(e *casbin.Enforcer) gin.HandlerFunc {
return func(c *gin.Context) {
ok, err := e.Enforce(c.GetString("user"), c.Request.URL.Path, c.Request.Method)
if err != nil || !ok {
c.AbortWithStatus(http.StatusForbidden)
return
}
c.Next()
}
}

Нагрузочное тестирование​

Запустите стандартные нагрузочные тесты против сборки v3. Характеристики производительности должны быть идентичны v2.

Верификация политик​

Сравните вычисление политик между версиями:

# Export policies from v2
# Load into v3
# Run test cases against both
# Compare results

Если вы видите какие-либо различия, скорее всего, это ошибка — пожалуйста, сообщите о ней!

Частые подводные камни​

Подводный камень 1: Смешанные зависимости v2/v3​

Проблема: Некоторые зависимости используют Casbin v2, другие — v3, что вызывает конфликты.

Решение: Сама сборка проходит успешно: система модулей Go рассматривает v2 и v3 как отдельные пакеты, поэтому оба могут находиться в одном дереве зависимостей. Однако нельзя передать enforcer из v3 библиотеке, ожидающей enforcer из v2. Убедитесь, что enforcer, его адаптер и его middleware используют одну и ту же мажорную версию.

Подводный камень 2: Несовпадение версий адаптера​

Проблема: Использование адаптера v2 с Casbin v3 (или наоборот).

Решение: Это проявляется как ошибка компиляции, а не как неожиданность во время выполнения. Проверьте, какая мажорная версия Casbin требуется в go.mod адаптера, и используйте релиз, соответствующий вашему enforcer.

Подводный камень 3: Забытые внутренние пакеты​

Проблема: Импорты в основном приложении обновлены, но забыты внутренние пакеты или инструменты.

Решение: Используйте go mod graph и go mod why, чтобы найти все зависимости Casbin:

go mod graph | grep casbin

Подводный камень 4: Проблемы компиляции пользовательских адаптеров​

Проблема: Пользовательский адаптер не компилируется после обновления.

Решение: Интерфейс адаптера не изменился, поэтому проблема, скорее всего, связана с импортами. Проверьте, что все импорты Casbin в вашем адаптере используют v3:

import (
"github.com/casbin/casbin/v3"
"github.com/casbin/casbin/v3/persist"
)

FAQ​

Вопрос: Поддерживается ли v2?​

На момент написания этого текста версия v2 получает исправления критических ошибок, но новые разрабатываются для v3. Планируйте миграцию в течение следующих 6–12 месяцев.

Вопрос: Можно ли мигрировать постепенно, оставив одни сервисы на v2, а другие переведя на v3?​

Да! Они могут даже использовать одну и ту же базу данных политик. Это одно из преимуществ минимальных изменений в v3.

Вопрос: Будет ли работать мой middleware (Gin, Echo, Fiber и т. д.)?​

Только если он импортирует ту же основную версию, что и ваш enforcer. Проверьте go.mod middleware; если там всё ещё v2, вызывайте Enforce() из собственного небольшого обработчика, как показано выше.

Вопрос: Нужно ли обновлять мои файлы моделей .conf?​

Нет. Синтаксис файлов модели не изменился.

Вопрос: Нужно ли обновлять мои файлы политик .csv?​

Нет. Формат файлов политик не изменился.

Вопрос: Что насчёт WatcherEx, FilteredAdapter и других интерфейсов?​

Все интерфейсы остались без изменений. Если ваш код реализует эти интерфейсы, модификации не требуются (кроме путей импорта).

Вопрос: Есть ли влияние на производительность?​

Никакого. В v3 используется тот же движок оценки, что и в v2.

Вопрос: Могу ли я использовать v3 с Go 1.16?​

Проверьте go.mod в репозитории Casbin v3, чтобы узнать минимально поддерживаемую версию Go. Как правило, рекомендуется использовать последнюю стабильную версию Go.

Удачного обновления!

Comments are powered by giscus and GitHub Discussions. They load from giscus.app and GitHub only after you click the button below.