Casbin (Go) v2에서 v3로 업그레이드: 완전한 마이그레이션 가이드
프로덕션 환경에서 Casbin v2를 운영하며 v3로의 업그레이드 경로가 궁금하다면, 이 가이드가 여러분을 위한 것입니다. 변경 사항 이해부터 안전한 프로덕션 마이그레이션 실행까지 전환 과정에 필요한 모든 내용을 다룰 것입니다.
v3에서 무엇이 변경되었나요?
좋은 소식입니다: v3는 주로 모듈 경로 변경이며 완전한 하위 호환성을 유지합니다. 핵심 인가 로직, API 및 기능은 변경되지 않았습니다. 이는 Go의 시맨틱 버전 관리 규약을 따르면서 혼란을 최소화하기 위한 의도적인 결정이었습니다.
주요 변경 사항: 모듈 경로
v3에서의 유일한 파괴적 변경 사항은 Go 모듈 경로입니다:
// v2
import "github.com/casbin/casbin/v2"
// v3
import "github.com/casbin/casbin/v3"
이것이 전부입니다. 기존 정책, 모델 및 코드 로직은 변경할 필요가 없습니다. 마이그레이션은 기계적입니다: import 문과 go.mod 파일을 업데이트하세요.
왜 v3를 릴리스했나요?
단순한 import 경로 변경만으로 새로운 주요 버전을 릴리스한 이유에 대해 의문이 들 수 있습니다. 정답은 시맨틱 버전 관리입니다. Go의 모듈 시스템은 import 경로(/v2, /v3 등)에 주요 버전 번호를 사용합니다. 이를 통해 동일한 의존성 트리에 여러 주요 버전이 공존할 수 있으며, 이는 많은 의존성을 가진 대규모 애플리케이션에 매우 중요합니다.
v3를 릴리스함으로써 저희는 다음을 수행했습니다:
- Go의 시맨틱 import 버전 관리와 정렬
- 복잡한 의존성 그래프에서의 점진적 마이그레이션 활성화
- 기존 v2 사용자를 깨뜨리지 않으면서 향후 향상을 위한 기반 마련
무엇이 동일하게 유지되었나요?
그 외 모든 것. 진심입니다.
- 모든 API는 동일하게 유지됩니다 -
Enforce(),AddPolicy(),GetAllRoles()및 기타 모든 메서드는 이전과 정확히 동일하게 작동합니다 - 모델 및 정책 구문 변경 없음 - 기존
.conf모델 파일과.csv정책 파일은 수정 없이 작동합니다 - Adapter 인터페이스 변경 없음 -
persist.Adapter메서드는 동일합니다; 어댑터에는 v3 모듈 경로를 기준으로 빌드된 릴리스만 필요합니다 - 성능 특성 - 성능 저하나 향상 없음; 동일한 엔진입니다
- 미들웨어 통합 - 미들웨어는 enforcer와 동일한 주요 버전을 import하면 동일한 방식으로 작동합니다
v3의 새로운 기능
2025년 12월 v3.0.0 릴리스 이후 몇 가지 새로운 기능이 추가되었습니다:
v3.7.0+: 강화된 Logger 통합
이제 Casbin의 핵심 인가 및 정책 관리 작업에 사용자 지정 로거를 통합하여 가시성을 높일 수 있습니다:
enforcer.SetLogger(yourCustomLogger)
v3.8.0+: GetAllUsers() API
사용자와 역할을 구분하기 위한 새로운 API:
users, err := enforcer.GetAllUsers()
역할 정의와 별도로 실제 사용자 목록을 표시해야 하는 RBAC 시스템에서 특히 유용합니다.
v3.9.0+: 내장 순환 검출
enforcer는 이제 역할 계층 구조의 순환을 자동으로 감지하여 무한 루프를 방지합니다:
// Automatically detects and prevents circular role assignments
enforcer.AddGroupingPolicy("alice", "admin")
enforcer.AddGroupingPolicy("admin", "alice") // Will be detected as a cycle
v3.10.0+: AI 기반 인가 통찰력을 위한 Explain() API
최신 기능은 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..."
이는 복잡한 정책을 디버깅하고 비기술적 이해관계자가 인가 결정을 이해하는 데 특히 가치가 있습니다.
Migration Strategy
For New Projects
간단합니다. 처음부터 v3을 사용하세요.
go get github.com/casbin/casbin/v3
import "github.com/casbin/casbin/v3"
For Existing v2 Projects
마이그레이션에는 세 단계가 포함됩니다:
Step 1: Update Your go.mod
go get github.com/casbin/casbin/v3
go mod tidy
Step 2: Update Import Statements
코드베이스 전체에서 모든 Casbin import를 찾아 교체하세요:
# 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
Step 3: Update Adapter Imports (If Applicable)
Adapter는 특정 주요 버전의 persist.Adapter를 구현합니다. 왜냐하면 casbin/v2와 casbin/v3의 model.Model은 서로 다른 Go 타입이기 때문입니다. 따라서 v3 enforcer는 github.com/casbin/casbin/v3를 import하는 adapter 릴리스가 필요합니다. adapter의 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
adapter가 아직 업데이트되지 않았다면, 업데이트될 때까지 해당 서비스는 v2에 유지하거나 adapter 저장소에 issue를 등록하세요.
Rollback Plan
롤백이 필요한 경우:
- Code level: import 변경 사항을 되돌립니다(버전 컨트롤 사용).
- Dependency level:
go get github.com/casbin/casbin/v2@latest - Deploy: 표준 배포 프로세스를 사용하여 되돌립니다.
이 마이그레이션의 장점은 롤백이 매우 간단하다는 점입니다. import 변경 사항을 되돌리고 다시 배포하기만 하면 됩니다.
Do I Need to Migrate My Policy Database?
아니요. 기존 정책 데이터는 변경되지 않습니다. 정책은 간단한 문자열(subject, object, action 등)로 저장되며 Casbin 버전에 의존하지 않습니다.
Testing Your Migration
Automated Testing
기존 테스트는 수정 없이 통과해야 합니다:
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")
}
}
Integration Testing
*casbin.Enforcer를 사용하는 middleware는 adapter와 마찬가지로 하나의 주요 버전에 종속됩니다. middleware가 여전히 casbin/v2를 import한다면, 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()
}
}
Load Testing
v3 빌드에 대해 표준 부하 테스트를 실행하세요. 성능 특성은 v2와 동일해야 합니다.
Policy Verification
버전 간 정책 평가를 비교하세요:
# Export policies from v2
# Load into v3
# Run test cases against both
# Compare results
차이가 발견되면 버그일 가능성이 높습니다. 신고해 주세요!
Common Pitfalls
Pitfall 1: Mixed v2/v3 Dependencies
Problem: 일부 의존성은 Casbin v2를 사용하고 다른 의존성은 v3를 사용하여 충돌이 발생합니다.
Solution: 빌드 자체는 문제없습니다. Go 모듈 시스템은 v2와 v3를 별도의 패키지로 처리하므로 둘 다 동일한 의존성 트리에 존재할 수 있습니다. 하지만 v3 enforcer를 v2를 기대하는 라이브러리에 전달하는 것은 불가능합니다. enforcer, adapter 및 middleware를 동일한 주요 버전으로 유지하세요.
Pitfall 2: Adapter Version Mismatch
Problem: Casbin v3와 함께 v2 adapter를 사용하거나 그 반대의 경우입니다.
Solution: 이는 런타임 예외가 아닌 컴파일 오류로 나타납니다. adapter의 go.mod가 요구하는 Casbin 주요 버전을 확인하고 enforcer와 일치하는 릴리스를 사용하세요.
Pitfall 3: Forgetting Internal Packages
Problem: 메인 애플리케이션의 import는 업데이 트했지만 내부 패키지나 도구를 잊어버린 경우입니다.
Solution: go mod graph와 go mod why를 사용하여 모든 Casbin 의존성을 찾으세요:
go mod graph | grep casbin
Pitfall 4: Custom Adapter Compilation Issues
문제: 업그레이드 후 커스텀 어댑터가 컴파일되지 않습니다.
해결책: 어댑터 인터페이스는 변경되지 않았으므로 이는 import 문제일 가능성이 높습니다. 어댑터의 모든 Casbin import가 v3를 사용하는지 확인하세요:
import (
"github.com/casbin/casbin/v3"
"github.com/casbin/casbin/v3/persist"
)
FAQ
Q: v2는 여전히 유지보수되나요?
현재 시점에서 v2는 중요한 버그 수정을 받고 있지만, 새로운 기능은 v3용으로 개발되고 있습니다. 향후 6-12개월 내에 마이그레이션을 계획하세요.
