Mettre à niveau Casbin (Go) de v2 vers v3 : Guide complet de migration
Si vous exécutez Casbin v2 en production et vous interrogez sur la voie de mise à niveau vers v3, ce guide est fait pour vous. Nous couvrirons tout ce que vous devez savoir sur la transition, depuis la compréhension des changements jusqu'à l'exécution d'une migration sûre en production.
Qu'est-ce qui a changé dans v3 ?
La bonne nouvelle : v3 est principalement un changement de chemin de module avec une compatibilité ascendante complète. La logique d'autorisation principale, les API et les fonctionnalités restent inchangées. Il s'agissait d'une décision intentionnelle visant à minimiser les perturbations tout en suivant les conventions de versionnement sémantique de Go.
Le changement principal : Chemin du module
Le seul changement incompatible (breaking change) dans v3 est le chemin du module Go :
// v2
import "github.com/casbin/casbin/v2"
// v3
import "github.com/casbin/casbin/v3"
C'est tout. Vos politiques, modèles et logique de code existants n'ont pas besoin d'être modifiés. La migration est mécanique : mettez à jour les instructions d'importation et votre fichier go.mod.
Pourquoi publier v3 ?
Vous vous demandez peut-être pourquoi publier une nouvelle version majeure juste pour un changement de chemin d'importation. La réponse est le versionnement sémantique. Le système de modules de Go utilise le numéro de version majeure dans le chemin d'importation (/v2, /v3, etc.). Cela permet à plusieurs versions majeures de coexister dans le même arbre de dépendances, ce qui est crucial pour les grandes applications ayant de nombreuses dépendances.
En publiant v3, nous avons :
- Aligné Casbin avec le versionnement sémantique des importations de Go
- Permis une migration progressive dans les graphes de dépendances complexes
- Préparé le terrain pour les futures améliorations sans casser les utilisateurs existants de v2
Qu'est-ce qui est resté identique ?
Tout le reste. Sérieusement.
- Toutes les API restent identiques -
Enforce(),AddPolicy(),GetAllRoles()et toutes les autres méthodes fonctionnent exactement comme avant - Syntaxe des modèles et des politiques inchangée - Vos fichiers de modèle
.confet vos fichiers de politique.csvexistants fonctionnent sans modification - Interface Adapter inchangée - Les méthodes
persist.Adaptersont les mêmes ; les adaptateurs ont seulement besoin d'une version compilée contre le chemin du module v3 - Caractéristiques de performance - Aucune régression ni amélioration des performances ; c'est le même moteur
- Intégrations de middleware - Le middleware fonctionne de la même manière une fois qu'il importe la même version majeure que votre enforcer
Nouvelles fonctionnalités dans v3
Depuis la sortie de v3.0.0 en décembre 2025, plusieurs nouvelles fonctionnalités ont été ajoutées :
v3.7.0+ : Intégration avancée du Logger
Vous pouvez désormais intégrer des loggers personnalisés dans les opérations principales d'application des règles et de gestion des politiques de Casbin, offrant une meilleure observabilité :
enforcer.SetLogger(yourCustomLogger)
v3.8.0+ : API GetAllUsers()
Une nouvelle API pour distinguer les utilisateurs des rôles :
users, err := enforcer.GetAllUsers()
Ceci est particulièrement utile dans les systèmes RBAC où vous avez besoin de lister les utilisateurs réels séparément des définitions de rôles.
v3.9.0+ : Détection automatique des cycles intégrée
L'enforcer inclut désormais une détection automatique des cycles dans les hiérarchies de rôles, empêchant les boucles infinies :
// 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() pour des insights d'autorisation basés sur l'IA
La dernière fonctionnalité exploite les API LLM pour expliquer les décisions d'autorisation en langage naturel :
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..."
Ceci est particulièrement précieux pour déboguer des politiques complexes et aider les parties prenantes non techniques à comprendre les décisions d'autorisation.
Stratégie de migration
Pour les nouveaux projets
Simple : utilisez v3 dès le départ.
go get github.com/casbin/casbin/v3
import "github.com/casbin/casbin/v3"
Pour les projets v2 existants
La migration implique trois étapes :
Étape 1 : Mettre à jour votre go.mod
go get github.com/casbin/casbin/v3
go mod tidy
Étape 2 : Mettre à jour les instructions d'importation
Recherchez et remplacez toutes les importations Casbin dans votre base de code :
# 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
Étape 3 : Mettre à jour les imports des adaptateurs (si applicable)
Un adaptateur implémente persist.Adapter d'une version majeure spécifique, car model.Model dans casbin/v2 et casbin/v3 sont des types Go différents. Un enforceur v3 a donc besoin d'une release d'adaptateur qui importe github.com/casbin/casbin/v3. Vérifiez le go.mod de l'adaptateur :
// 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
Si votre adaptateur n'a pas encore été mis à jour, restez sur v2 pour ce service jusqu'à ce qu'il le soit, ou ouvrez une issue dans le dépôt de l'adaptateur.
Plan de retour en arrière
Si vous devez effectuer un retour en arrière :
- Niveau du code : annulez les modifications des imports (utilisez le contrôle de version)
- Niveau des dépendances :
go get github.com/casbin/casbin/v2@latest - Déploiement : utilisez votre processus de déploiement standard pour revenir en arrière
L'avantage de cette migration est que le retour en arrière est trivial - il suffit d'annuler les modifications des imports et de redéployer.
Dois-je migrer ma base de données de politiques ?
Non. Vos données de politiques existantes restent inchangées. Les politiques sont stockées sous forme de chaînes simples (sujet, objet, action, etc.) et n'ont aucune dépendance sur la version de Casbin.
Test de votre migration
Tests automatisés
Vos tests existants devraient passer sans modification :
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")
}
}
Tests d'intégration
Les middlewares qui prennent un *casbin.Enforcer sont liés à une version majeure de la même manière que les adaptateurs. Si votre middleware importe toujours casbin/v2, appeler l'enforceur directement ne prend que quelques lignes :
// 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()
}
}
Tests de charge
Exécutez vos tests de charge standards contre le build v3. Les caractéristiques de performance devraient être identiques à celles de v2.
Vérification des politiques
Comparez l'évaluation des politiques entre les versions :
# Export policies from v2
# Load into v3
# Run test cases against both
# Compare results
Si vous constatez des différences, c'est probablement un bug - veuillez le signaler !
Pièges courants
Piège 1 : Dépendances mixtes v2/v3
Problème : Certaines dépendances utilisent Casbin v2, d'autres utilisent v3, ce qui cause des conflits.
Solution : La compilation elle-même fonctionne bien : le système de modules de Go traite v2 et v3 comme des packages distincts, donc les deux peuvent coexister dans le même arbre de dépendances. Ce que vous ne pouvez pas faire, c'est passer un enforceur v3 à une bibliothèque qui attend un enforceur v2. Gardez l'enforceur, son adaptateur et ses middlewares sur la même version majeure.
Piège 2 : Incompatibilité de version de l'adaptateur
Problème : Utilisation d'un adaptateur v2 avec Casbin v3 (ou inversement).
Solution : Cela se manifeste par une erreur de compilation, et non par une surprise à l'exécution. Vérifiez quelle version majeure de Casbin le go.mod de l'adaptateur requiert et utilisez une release correspondant à votre enforceur.
Piège 3 : Oubli des packages internes
Problème : Vous avez mis à jour les imports de l'application principale mais oublié les packages internes ou les outils.
Solution : Utilisez go mod graph et go mod why pour trouver toutes les dépendances Casbin :
go mod graph | grep casbin
Piège 4 : Problèmes de compilation des adaptateurs personnalisés
Problème : L'adaptateur personnalisé ne compile plus après la mise à niveau.
Solution : L'interface de l'adaptateur n'a pas changé, ce qui suggère un problème d'importation. Vérifiez que toutes les importations Casbin dans votre adaptateur utilisent v3 :
import (
"github.com/casbin/casbin/v3"
"github.com/casbin/casbin/v3/persist"
)
FAQ
Q : La version 2 est-elle toujours maintenue ?
À l'heure actuelle, la version 2 reçoit des correctifs critiques pour les bugs, mais les nouvelles fonctionnalités sont développées pour la version 3. Prévoyez une migration dans les 6 à 12 prochains mois.
Q : Puis-je migrer progressivement en ayant certains services sur v2 et d'autres sur v3 ?
Oui ! Ils peuvent même partager la même base de données de politiques. C'est l'un des avantages des modifications minimales apportées dans v3.
Q : Mon middleware (Gin, Echo, Fiber, etc.) fonctionnera-t-il ?
Uniquement s'il importe la même version majeure que votre enforceur. Vérifiez le go.mod du middleware ; s'il est encore sur v2, appelez Enforce() depuis un petit gestionnaire à vous comme indiqué ci-dessus.
Q : Dois-je mettre à jour mes fichiers de modèle .conf ?
Non. La syntaxe des fichiers de modèle est inchangée.
Q : Dois-je mettre à jour mes fichiers de politique .csv ?
Non. Le format des fichiers de politique est inchangé.
Q : Qu'en est-il de WatcherEx, FilteredAdapter et des autres interfaces ?
Toutes les interfaces restent inchangées. Si votre code implémente ces interfaces, aucune modification n'est nécessaire (en dehors des chemins d'importation).
Q : Impact sur les performances ?
Aucun. v3 utilise le même moteur d'évaluation que v2.
Q : Puis-je utiliser v3 avec Go 1.16 ?
Vérifiez le go.mod dans le dépôt Casbin v3 pour connaître la version minimale de Go prise en charge. En général, il est recommandé d'utiliser la dernière version stable de Go.
Bonne mise à niveau !

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