EF Core Global Query Filter 기반 쿼리 수정 없는 Multi-Tenant 전환

Migrating a Single-Tenant SaaS to Multi-Tenant Workspaces with EF Core Global Query Filters

Nicolas Florez2026년 5월 5일7분intermediate

AI 요약

Context

UserId 기반의 Single-Tenant 구조에서 기업 단위 데이터 공유를 위한 Multi-Tenant Workspace 모델로의 전환 필요성 발생. 60개 이상의 파일에 분산된 기존 쿼리 호출부를 직접 수정하는 방식의 높은 공수와 리스크가 병목 지점으로 작용.

ITenantedEntity 인터페이스 정의를 통한 테넌트 적용 대상 엔티티의 명시적 관리
EF Core HasQueryFilter 도입으로 모든 Read 쿼리에 WorkspaceId 필터링 조건을 자동 주입하는 추상화 계층 설계
IWorkspaceContext 인터페이스 구현을 통해 HTTP JWT Claim 및 Background Worker의 컨텍스트를 분리하여 런타임 Tenant ID 동적 결정
데이터 일관성 보장을 위해 Personal Workspace 생성, 데이터 Backfill, NOT NULL 제약 조건 추가를 단일 트랜잭션 내에서 처리하는 Atomic Migration 수행
NullReferenceException 방지를 위해 필터 내에서 Nullable 타입을 반환하여 EF Core가 SQL의 IS NULL 체크를 생성하도록 유도

실천 포인트

1. 기존 쿼리 수정 최소화가 필요할 때 EF Core Global Query Filter 검토

2. 테넌트 식별자 적용 시 모든 엔티티가 아닌 인터페이스 기반의 Opt-in 방식 채택

3. 마이그레이션 시 Backfill과 NOT NULL 설정을 단일 Migration 파일 내에 구성하여 원자성 확보

4. JWT Claim을 통한 stateless한 테넌트 컨텍스트 관리로 수평 확장성 확보

태그