MyBatis에서 숫자 포함 Oracle 컬럼명 매핑 문제 해결하기

 

문제: 숫자 뒤 언더스코어 컬럼명 매핑 실패

Oracle 데이터베이스에서 컬럼명 CNT_100_SM을 Java MyBatis 프로젝트에서 카멜 케이스(cnt100Sm)로 매핑하려 했지만, 유독 숫자(예: 100) 뒤에 언더스코어(_)가 붙은 경우 매핑이 제대로 되지 않는 문제가 발생했습니다. 예를 들어, CNT_100_SM은 cnt100Sm으로 변환되어야 하지만, MyBatis가 이를 인식하지 못하거나 잘못된 필드에 매핑되는 경우가 있었습니다. 이로 인해 부득이하게 컬럼명을 CNT100_SM처럼 변경해 사용하는 불편함을 겪었습니다.

이 글에서는 이 문제의 원인을 분석하고, MyBatis에서 숫자 포함 컬럼명을 깔끔하게 처리하는 방법을 정리합니다.

---

원인 분석

MyBatis는 데이터베이스 컬럼명(스네이크 케이스)과 Java 객체 필드명(카멜 케이스)을 매핑할 때 mapUnderscoreToCamelCase 설정을 통해 자동 변환을 지원합니다. 하지만 CNT_100_SM처럼 숫자가 포함된 컬럼명, 특히 숫자 뒤에 언더스코어가 붙는 경우에는 다음과 같은 이유로 매핑이 실패할 수 있습니다:

1. MyBatis의 카멜 케이스 변환 로직 한계
   MyBatis의 mapUnderscoreToCamelCase는 일반적으로 _를 제거하고 다음 글자를 대문자로 변환합니다(예: CNT_SM → cntSm). 하지만 숫자 뒤 언더스코어(예: 100_SM)를 처리할 때, 숫자를 문자로 인식하지 않아 변환 규칙이 비표준적으로 적용될 수 있습니다. 이로 인해 CNT_100_SM이 cnt100Sm으로 정확히 매핑되지 않을 수 있습니다.
2. 컬럼명 대소문자 불일치
   Oracle은 컬럼명을 기본적으로 대문자(CNT_100_SM)로 처리합니다. MyBatis 쿼리나 매핑에서 컬럼명을 소문자(cnt_100_sm)로 잘못 지정하거나, 별칭(alias)을 사용하지 않으면 매핑이 실패할 수 있습니다.
3. Java DTO 필드명 또는 Getter/Setter 문제
   Java DTO에서 cnt100Sm 필드와 그에 맞는 getter/setter(getCnt100Sm, setCnt100Sm)가 정확히 정의되지 않았거나, 필드 타입이 Oracle 컬럼 타입과 맞지 않으면 매핑 오류가 발생합니다.
4. 쿼리에서 별칭 누락
   SQL 쿼리에서 CNT_100_SM을 cnt100Sm으로 명시적으로 매핑하지 않으면, MyBatis가 컬럼명을 Java 필드명으로 올바르게 연결하지 못할 수 있습니다.

---

 

 

해결 방법

위 문제를 해결하기 위해 다음 4가지 방법을 단계적으로 적용해 보세요. 이 방법들은 숫자 포함 컬럼명을 깔끔하게 처리하며, 코드의 일관성과 유지보수성을 높이는 데 도움이 됩니다.

1. MyBatis 설정에서 mapUnderscoreToCamelCase 활성화

MyBatis의 자동 카멜 케이스 변환 기능을 활성화하면, 대부분의 스네이크 케이스 컬럼명을 카멜 케이스로 변환할 수 있습니다. 하지만 숫자 뒤 언더스코어 처리에 문제가 있을 수 있으므로, 이 설정을 먼저 확인합니다.

설정 방법:

• MyBatis 설정 파일(mybatis-config.xml)에 추가:

  <configuration>
      <settings>
          <setting name="mapUnderscoreToCamelCase" value="true"/>
      </settings>
  </configuration>

• Spring Boot라면 application.properties에 추가:

  mybatis.configuration.map-underscore-to-camel-case=true

주의: 숫자 뒤 언더스코어(예: 100_SM)가 포함된 경우, 이 설정만으로는 매핑이 완벽하지 않을 수 있습니다. 이 경우 아래의 명시적 매핑 방법을 함께 사용하세요.

2. ResultMap으로 명시적 매핑 정의

mapUnderscoreToCamelCase가 숫자 포함 컬럼명을 처리하지 못할 때는, MyBatis의 ResultMap을 사용해 컬럼명과 Java 필드명을 명시적으로 매핑하는 것이 가장 확실한 방법입니다.

예시:

<resultMap id="myResultMap" type="com.example.MyDto">
    <result column="CNT_100_SM" property="cnt100Sm"/>
</resultMap>

<select id="selectData" resultMap="myResultMap">
    SELECT CNT_100_SM FROM my_table
</select>

장점:

• 숫자 포함 컬럼명에 상관없이 정확한 매핑 보장.
• 코드 가독성과 유지보수성이 향상됨.

3. SQL 쿼리에서 별칭(Alias) 사용

SQL 쿼리에서 컬럼명에 별칭을 지정해 MyBatis가 Java 필드명과 직접 매핑하도록 합니다. 이는 ResultMap을 작성하지 않고 간단히 문제를 해결할 수 있는 방법입니다.

예시:

<select id="selectData" resultType="com.example.MyDto">
    SELECT CNT_100_SM AS cnt100Sm FROM my_table
</select>

주의:

• 별칭은 Java 필드명(cnt100Sm)과 정확히 일치해야 합니다.
• 쿼리가 복잡해질수록 별칭 관리가 어려울 수 있으므로, ResultMap 사용을 권장합니다.

4. Java DTO와 Getter/Setter 점검

Java DTO 클래스에서 필드명과 getter/setter가 올바르게 정의되었는지 확인합니다. 특히, 숫자 포함 필드명(cnt100Sm)은 JavaBean 명명 규칙을 따라야 합니다.

예시:

public class MyDto {
    private int cnt100Sm; // Oracle NUMBER 타입 가정

    public int getCnt100Sm() {
        return cnt100Sm;
    }

    public void setCnt100Sm(int cnt100Sm) {
        this.cnt100Sm = cnt100Sm;
    }
}

확인 사항:

• 필드명(cnt100Sm)이 카멜 케이스 규칙을 따르는지.
• Getter/Setter 메서드 이름이 getCnt100Sm, setCnt100Sm처럼 정확한지.
• 필드 타입(예: int, String)이 Oracle 컬럼 타입과 호환되는지.

---

 

 

추가 팁: 코드 일관성 유지하기

1. EditorConfig 사용
   프로젝트에서 .editorconfig 파일을 사용해 들여쓰기(예: 4칸 공백)와 코드 스타일을 통일하세요. 이는 팀원 간 코드 가독성을 높입니다.

   [*]
   indent_style = space
   indent_size = 4

2. 린팅 도구 활용
   Java 코드에는 Checkstyle, MyBatis XML에는 MyBatis 플러그인을 사용해 매핑 오류를 사전에 잡아낼 수 있습니다.
3. 로그 활성화
   MyBatis 로그를 활성화해 매핑 오류의 원인을 추적하세요:

   logging.level.org.mybatis=DEBUG

4. 최신 MyBatis 버전 사용
   MyBatis 3.5.x 이상을 사용해 최신 버그 픽스와 호환성을 확보하세요:

   <dependency>
       <groupId>org.mybatis</groupId>
       <artifactId>mybatis</artifactId>
       <version>3.5.16</version>
   </dependency>

---

결론

숫자가 포함된 Oracle 컬럼명(예: CNT_100_SM)을 MyBatis에서 카멜 케이스(cnt100Sm)로 매핑할 때 발생하는 문제를 해결하려면, mapUnderscoreToCamelCase 설정을 시도한 후, ResultMap 또는 SQL 별칭으로 명시적 매핑을 적용하는 것이 가장 효과적입니다. Java DTO의 필드와 getter/setter를 정확히 정의하고, 로그와 린팅 도구를 활용해 오류를 빠르게 파악하세요.

이 방법을 적용하면 컬럼명을 CNT100_SM처럼 강제로 변경하지 않아도 깔끔하게 매핑할 수 있으며, 코드의 일관성과 가독성을 유지할 수 있습니다. 문제가 지속되면 MyBatis 로그를 확인하거나, 구체적인 에러 메시지를 바탕으로 추가 디버깅을 진행해 보세요.

---