Firo MyBatis 통합 가이드

개요

Firo MyBatis 모듈은 외부 프로젝트의 SqlSessionFactory를 사욥하여 MyBatis 설정 충돌을 방지합니다. 이 가이드는 외부 프로젝트(예: iflex)와 안전하게 통합하는 방법을 설명합니다.

통합 원칙

1. 외부 SqlSessionFactory 사용

Firo MyBatis 모듈은 자체 SqlSessionFactory를 생성하지 않고, 외부 프로젝트에서 제공하는 SqlSessionFactory를 사용합니다.

2. Mapper 스캔 방식

Firo Mapper들은 @MapperScan을 통해 외부 SqlSessionFactory에 등록되어야 합니다.

3. Type Alias 관리

Firo에서 사용하는 Type Alias들은 사용자가 직접 등록해야 합니다:

• FiroFile → com.unvus.firo.core.module.service.domain.FiroFile
• AttachBag → com.unvus.firo.core.module.service.domain.AttachBag

통합 설정 방법

1. MapperScan 설정

외부 프로젝트에서 Firo Mapper들을 스캔하도록 설정합니다:

@Configuration
@MapperScans({
    // 기존 프로젝트 Mapper들
    @MapperScan(
        basePackages = "com.unvus.iflex.core",
        annotationClass = DefaultMapper.class,
        sqlSessionFactoryRef = "defaultSqlSessionFactory"
    ),
    // Firo Mapper 추가
    @MapperScan(
        basePackages = "com.unvus.firo.mybatis.mapper",
        annotationClass = Mapper.class,
        sqlSessionFactoryRef = "defaultSqlSessionFactory" // 동일한 SqlSessionFactory 사용
    ),
    // 기타 모듈 Mapper들
    @MapperScan(
        basePackages = "com.unvus.sendy.module",
        annotationClass = Repository.class,
        sqlSessionFactoryRef = "defaultSqlSessionFactory"
    )
})
public class MyBatisConfiguration {
    
    @Primary
    @Bean("defaultSqlSessionFactory")
    public SqlSessionFactory defaultSqlSessionFactory(
        @Qualifier("defaultDataSource") DataSource defaultDataSource) throws Exception {
        
        SqlSessionFactoryBean sessionFactory = new SqlSessionFactoryBean();
        sessionFactory.setDataSource(defaultDataSource);
        
        // Mapper XML 위치 설정 (모든 모듈의 Mapper XML 포함)
        Resource[] mapperResources = new PathMatchingResourcePatternResolver()
            .getResources("classpath*:mapper/*.xml");
        sessionFactory.setMapperLocations(mapperResources);
        
        // MyBatis Configuration
        org.apache.ibatis.session.Configuration configuration = new org.apache.ibatis.session.Configuration();
        configuration.setMapUnderscoreToCamelCase(true);
        configuration.setUseGeneratedKeys(true);
        
        // Type Alias 등록
        registerTypeAliases(configuration);
        
        sessionFactory.setConfiguration(configuration);
        
        return sessionFactory.getObject();
    }
    
    private void registerTypeAliases(org.apache.ibatis.session.Configuration configuration) {
        // Firo Type Alias 등록 (간단한 방법)
        configuration.getTypeAliasRegistry().registerAlias("FiroFile", 
            com.unvus.firo.core.module.service.domain.FiroFile.class);
        configuration.getTypeAliasRegistry().registerAlias("AttachBag", 
            com.unvus.firo.core.module.service.domain.AttachBag.class);
        
        // 기존 프로젝트 Type Alias도 등록
        configuration.getTypeAliasRegistry().registerAliases(
            "com.yourproject.domain");
    }
}

2. 간단한 설정 방법 (Properties 기반)

Spring Boot의 기본 MyBatis Auto Configuration을 사용하는 경우:

# MyBatis 기본 설정
mybatis.mapper-locations=classpath*:mapper/*.xml
mybatis.type-aliases-package=com.unvus.firo.core.module.service.domain,com.yourproject.domain
mybatis.configuration.map-underscore-to-camel-case=true

그리고 Component Scan에 Firo Mapper 패키지를 추가:

@SpringBootApplication
@MapperScan(basePackages = {
    "com.yourproject.mapper",
    "com.unvus.firo.mybatis.mapper" // Firo Mapper 추가
})
public class YourApplication {
    public static void main(String[] args) {
        SpringApplication.run(YourApplication.class, args);
    }
}

3. Firo Mapper XML 예시

Firo의 FiroFileMapper.xml은 이미 완성되어 있으므로 별도 수정이 필요하지 않습니다:

<!-- Firo의 FiroFileMapper.xml (별도 수정 불필요) -->
<mapper namespace="com.unvus.firo.mybatis.mapper.FiroFileMapper">
    <resultMap id="FiroFileResultMap" type="FiroFile">
        <id property="id" column="attach_id"/>
        <result property="refDomain" column="attach_ref_domain"/>
        <result property="refKey" column="attach_ref_key"/>
        <result property="refCategory" column="attach_ref_category"/>
        <result property="displayName" column="attach_display_name"/>
        <result property="savedName" column="attach_saved_name"/>
        <result property="savedDir" column="attach_saved_dir"/>
        <result property="fileType" column="attach_file_type"/>
        <result property="fileSize" column="attach_file_size"/>
        <result property="deleted" column="attach_deleted"/>
        <result property="ext" column="attach_ext"/>
        <result property="createdBy" column="attach_created_by"/>
        <result property="createdDt" column="attach_created_dt"/>
    </resultMap>
    
    <!-- Firo 내부 쿼리들 -->
    <select id="findById" resultMap="FiroFileResultMap">
        SELECT * FROM ${tableName} WHERE attach_id = #{id}
    </select>
    
    <!-- 기타 Firo 쿼리들... -->
</mapper>

주의사항: 위 XML에서 type="FiroFile"이 정상적으로 동작하려면 Type Alias가 올바르게 등록되어 있어야 합니다.

4. 사용자 정의 Mapper에서 Firo Type 사용

사용자가 직접 Firo 타입을 사용하는 Mapper를 작성할 수도 있습니다:

<!-- 사용자 정의 Mapper -->
<mapper namespace="com.yourproject.mapper.CustomFileMapper">
    <select id="findUserFiles" resultType="FiroFile">
        SELECT * FROM attach 
        WHERE attach_ref_domain = #{domain} 
        AND attach_ref_key = #{userId}
    </select>
    
    <select id="getAttachBag" resultType="AttachBag">
        <!-- 커스텀 쿼리 -->
    </select>
</mapper>

문제 해결

"Result Maps collection does not contain value" 오류 해결

이 오류는 Type Alias 충돌로 인해 발생할 수 있습니다. 다음 단계를 확인하세요:

1. Firo 모듈 버전 확인: 최신 버전의 Firo를 사용하고 있는지 확인
2. Type Alias 중복 확인: 기존 프로젝트에 동일한 이름의 Type Alias가 없는지 확인
3. 패키지 경로 확인: com.unvus.firo.core.module.service.domain 패키지가 올바르게 설정되었는지 확인

테이블 스키마 호환성

기본 테이블 구조

-- Firo에서 사용하는 기본 테이블 구조
CREATE TABLE attach (
    attach_id BIGINT AUTO_INCREMENT PRIMARY KEY,
    attach_ref_domain VARCHAR(50) NOT NULL,
    attach_ref_key BIGINT NOT NULL,
    attach_ref_category VARCHAR(50) NOT NULL DEFAULT 'default',
    attach_display_name VARCHAR(255) NOT NULL,
    attach_saved_name VARCHAR(255) NOT NULL,
    attach_saved_dir VARCHAR(500) NOT NULL,
    attach_file_type VARCHAR(100),
    attach_file_size BIGINT,
    attach_deleted BOOLEAN DEFAULT FALSE,
    attach_ext VARCHAR(100),
    attach_created_by BIGINT,
    attach_created_dt TIMESTAMP DEFAULT CURRENT_TIMESTAMP,
    
    INDEX idx_attach_ref (attach_ref_domain, attach_ref_key, attach_ref_category),
    INDEX idx_attach_deleted (attach_deleted)
);

테이블 프리픽스 지원

# 테이블 프리픽스 설정
firo.database.table-prefix=ha_  # ha_attach 테이블 사용
firo.database.table-prefix=nv_  # nv_attach 테이블 사용

업그레이드 노트

기존 Firo 버전에서 업그레이드할 때:

1. 이전 버전 호환성: 기존의 클래스명 기반 Type Alias도 계속 지원됩니다.
2. 권장 사항: 새로운 Firo 접두사를 가진 Type Alias 사용을 권장합니다.
3. 점진적 마이그레이션: 기존 코드를 단계적으로 새로운 Type Alias로 변경할 수 있습니다.
4. 동적 테이블명: TableNameUtil을 통해 런타임에 테이블명 결정