🧱
Apache Tiles 치트시트

Composite View 패턴, tiles.xml 레이아웃 정의, 와일드카드 매핑(*/*), Base Layout 상속, Spring MVC TilesViewResolver 및 실무 트러블슈팅 레퍼런스
#apache-tiles#tiles#jsp#spring-mvc#template#layout#egovframe#java최종 업데이트: 2026-09-27
Apache Tiles 치트시트 핵심 명령어 및 실전 가이드

Composite View 패턴, tiles.xml 레이아웃 정의, 와일드카드 매핑(*/*), Base Layout 상속, Spring MVC TilesViewResolver 및 실무 트러블슈팅 레퍼런스
## 1. 기본 아키텍처 & Composite View 패턴 (Architecture)
```text
[클라이언트 요청] ──> [Spring Controller] ──> [TilesViewResolver]
                                                        │
                      ┌─────────────────────────────────┴─────────────────────────────────┐
                      ▼                                                                   ▼
       [tiles.xml Definition 매핑]                                          [최종 조립 브라우저 출력]
       ┌────────────────────────────────────────────────────────┐            ┌────────────────────────────────────┐
       │ Definition: "board/list" (extends "baseLayout")        │            │ Header (header.jsp)                │
       │  - header  : /WEB-INF/views/layout/header.jsp          │  ───────>  ├────────────────────────────────────┤
       │  - sidebar : /WEB-INF/views/layout/sidebar.jsp         │            │ Sidebar  │ Body (board/list.jsp)   │
       │  - body    : /WEB-INF/views/board/list.jsp             │            │          │                         │
       │  - footer  : /WEB-INF/views/layout/footer.jsp          │            ├────────────────────────────────────┤
       └────────────────────────────────────────────────────────┘            │ Footer (footer.jsp)                │
                                                                             └────────────────────────────────────┘
```

## 2. 의존성 설정 (Maven & Gradle)
```xml
<!-- Maven (pom.xml) - Tiles 3.x 표준 라이브러리 -->
<dependency>
    <groupId>org.apache.tiles</groupId>
    <artifactId>tiles-jsp</artifactId>
    <version>3.0.8</version>
</dependency>
<dependency>
    <groupId>org.apache.tiles</groupId>
    <artifactId>tiles-core</artifactId>
    <version>3.0.8</version>
</dependency>
<dependency>
    <groupId>org.apache.tiles</groupId>
    <artifactId>tiles-servlet</artifactId>
    <version>3.0.8</version>
</dependency>
```
```groovy
// Gradle (build.gradle)
implementation 'org.apache.tiles:tiles-jsp:3.0.8'
implementation 'org.apache.tiles:tiles-core:3.0.8'
implementation 'org.apache.tiles:tiles-servlet:3.0.8'
```

## 3. Spring MVC 설정 (TilesConfigurer & ViewResolver)
```java
// Spring Java Config 설정 클래스
@Configuration
public class TilesConfig {

    // [1] tiles.xml 파일 경로 지정 및 설정 로더
    @Bean
    public TilesConfigurer tilesConfigurer() {
        TilesConfigurer configurer = new TilesConfigurer();
        configurer.setDefinitions(new String[] {
            "/WEB-INF/tiles/tiles.xml",
            "/WEB-INF/tiles/tiles-*.xml" // 모듈별 분할 설정 지원
        });
        configurer.setCheckRefresh(true); // 개발 환경: XML 수정 시 서버 재시작 없이 실시간 리로드
        return configurer;
    }

    // [2] 컨트롤러가 반환한 View 이름을 Tiles Definition과 매핑
    @Bean
    public TilesViewResolver tilesViewResolver() {
        TilesViewResolver resolver = new TilesViewResolver();
        resolver.setViewClass(TilesView.class);
        resolver.setOrder(1); // InternalResourceViewResolver(JSP 직접호출)보다 우선순위 높게 설정
        return resolver;
    }
}
```

## 4. tiles.xml 기본 골격 & 레이아웃 정의 (tiles.xml)
```xml
<?xml version="1.0" encoding="UTF-8"?>
<!DOCTYPE tiles-definitions PUBLIC
       "-//Apache Software Foundation//DTD Tiles Configuration 3.0//EN"
       "http://tiles.apache.org/dtds/tiles-config_3_0.dtd">

<tiles-definitions>

    <!-- [1] 공통 기본 레이아웃 정의 (모든 페이지의 부모 템플릿) -->
    <definition name="baseLayout" template="/WEB-INF/views/layout/baseLayout.jsp">
        <put-attribute name="title" value="기본 시스템 타이틀" />
        <put-attribute name="header" value="/WEB-INF/views/layout/header.jsp" />
        <put-attribute name="sidebar" value="/WEB-INF/views/layout/sidebar.jsp" />
        <put-attribute name="body" value="" /> <!-- 각 자식 페이지에서 오버라이드 -->
        <put-attribute name="footer" value="/WEB-INF/views/layout/footer.jsp" />
    </definition>

    <!-- [2] 개별 정적 페이지 정의 (baseLayout 상속) -->
    <definition name="home" extends="baseLayout">
        <put-attribute name="title" value="홈 화면 - LuckyTechWorld" />
        <put-attribute name="body" value="/WEB-INF/views/home.jsp" />
    </definition>

</tiles-definitions>
```

## 5. 실무 필수: 와일드카드 자동 매핑 (Wildcard Patterns)
```xml
<!-- 와일드카드(*)를 사용하여 페이지가 추가될 때마다 매번 XML을 수정할 필요가 없도록 자동화 -->
<tiles-definitions>

    <!-- 1단계 디렉토리 매핑: "user/list" -> body: "/WEB-INF/views/user/list.jsp" -->
    <definition name="*/*" extends="baseLayout">
        <put-attribute name="title" value="{1} - {2}" />
        <put-attribute name="body" value="/WEB-INF/views/{1}/{2}.jsp" />
    </definition>

    <!-- 2단계 하위 디렉토리 매핑: "admin/member/detail" -> body: "/WEB-INF/views/admin/member/detail.jsp" -->
    <definition name="*/*/*" extends="baseLayout">
        <put-attribute name="title" value="{1} - {2} - {3}" />
        <put-attribute name="body" value="/WEB-INF/views/{1}/{2}/{3}.jsp" />
    </definition>

</tiles-definitions>
```

## 6. Base Layout JSP 작성 (baseLayout.jsp)
```html
<%@ page language="java" contentType="text/html; charset=UTF-8" pageEncoding="UTF-8"%>
<!-- Tiles 태그 라이브러리 선언 필수 -->
<%@ taglib uri="http://tiles.apache.org/tags-tiles" prefix="tiles" %>
<!DOCTYPE html>
<html lang="ko">
<head>
    <meta charset="UTF-8">
    <!-- 문자열 속성 단순 출력 (getAsString) -->
    <title><tiles:getAsString name="title" /></title>
    <link rel="stylesheet" href="${pageContext.request.contextPath}/css/layout.css">
</head>
<body>
    <div id="wrapper">
        <!-- 1. 헤더 조각 삽입 -->
        <header id="header">
            <tiles:insertAttribute name="header" />
        </header>

        <div id="container">
            <!-- 2. 좌측 사이드바 삽입 -->
            <aside id="sidebar">
                <tiles:insertAttribute name="sidebar" />
            </aside>

            <!-- 3. 본문 메인 콘텐츠 영역 삽입 (매 페이지마다 교체됨) -->
            <main id="content">
                <tiles:insertAttribute name="body" />
            </main>
        </div>

        <!-- 4. 푸터 조각 삽입 -->
        <footer id="footer">
            <tiles:insertAttribute name="footer" />
        </footer>
    </div>
</body>
</html>
```

## 7. 컨트롤러 연동 & View 반환 (Spring Controller)
```java
@Controller
public class BoardController {

    // 1. "board/list" 문자열 반환
    @GetMapping("/board/list")
    public String list(Model model) {
        model.addAttribute("articles", boardService.getArticles());
        // TilesResolver에 의해 tiles.xml의 "board/list" 또는 "*/*" 와일드카드 정의에 매핑됨
        return "board/list"; 
    }

    // 2. 관리자 페이지 반환 (adminLayout 적용)
    @GetMapping("/admin/users")
    public String adminUsers(Model model) {
        return "admin/users"; // "admin/*" 정의에 매핑
    }
}
```

## 8. 다중 레이아웃 분기 (Multiple Layouts: User vs Admin)
```xml
<tiles-definitions>

    <!-- [사용자 공통 레이아웃] -->
    <definition name="userBaseLayout" template="/WEB-INF/views/layout/userLayout.jsp">
        <put-attribute name="header" value="/WEB-INF/views/layout/userHeader.jsp" />
        <put-attribute name="footer" value="/WEB-INF/views/layout/userFooter.jsp" />
    </definition>

    <!-- [관리자 전용 레이아웃 (어두운 테마 + 전용 관리 메뉴)] -->
    <definition name="adminBaseLayout" template="/WEB-INF/views/admin/layout/adminLayout.jsp">
        <put-attribute name="adminHeader" value="/WEB-INF/views/admin/layout/adminHeader.jsp" />
        <put-attribute name="adminSidebar" value="/WEB-INF/views/admin/layout/adminSidebar.jsp" />
        <put-attribute name="footer" value="/WEB-INF/views/layout/userFooter.jsp" />
    </definition>

    <!-- 관리자 경로 매핑 접두사 분기 -->
    <definition name="admin/*/*" extends="adminBaseLayout">
        <put-attribute name="body" value="/WEB-INF/views/admin/{1}/{2}.jsp" />
    </definition>

</tiles-definitions>
```

## 9. 팝업 / 레이아웃 없는 단독 뷰 (Popup & Clean View)
```xml
<tiles-definitions>

    <!-- 헤더, 푸터 없이 본문 팝업 내용만 출력하는 빈 껍데기 레이아웃 -->
    <definition name="emptyLayout" template="/WEB-INF/views/layout/emptyLayout.jsp">
        <put-attribute name="body" value="" />
    </definition>

    <definition name="popup/*" extends="emptyLayout">
        <put-attribute name="body" value="/WEB-INF/views/popup/{1}.jsp" />
    </definition>

</tiles-definitions>
```
```html
<!-- emptyLayout.jsp -->
<%@ page language="java" contentType="text/html; charset=UTF-8" pageEncoding="UTF-8"%>
<%@ taglib uri="http://tiles.apache.org/tags-tiles" prefix="tiles" %>
<!DOCTYPE html>
<html>
<head><title>팝업</title></head>
<body>
    <tiles:insertAttribute name="body" />
</body>
</html>
```

## 10. 동적 속성 주입 (Dynamic Attribute Passing)
```html
<!-- 부모 레이아웃에서 자식 조각으로 동적 파라미터 전달 -->
<tiles:insertAttribute name="header">
    <tiles:putAttribute name="currentMenu" value="BOARD" />
    <tiles:putAttribute name="showSearch" value="true" />
</tiles:insertAttribute>

<!-- header.jsp 내부에서 전달받은 속성 접근 -->
<%@ taglib uri="http://tiles.apache.org/tags-tiles" prefix="tiles" %>
<tiles:importAttribute name="currentMenu" />
<c:if test="${currentMenu eq 'BOARD'}">
    <span class="active">게시판 활성화</span>
</c:if>
```

## 11. Spring Boot 3.x / Jakarta 주의사항 (Migration Tips)
```text
# ⚠️ Spring Boot 3.x (Jakarta EE 9+) 호환성 이슈
- 공식 Apache Tiles는 2018년(3.0.8) 이후 새로운 버전이 릴리즈되지 않아 jakarta.servlet.* 네임스페이스를 기본 지원하지 않음.
- Spring Boot 3.x에서 Tiles를 사용할 경우 NoSuchMethodError 또는 ClassNotFoundException(javax.servlet.*) 발생.

# [해결 방안 3가지]
1. 최신 프로젝트: Thymeleaf, JSP 단독 템플릿(jsp:include), 또는 프론트 SPA(Vue/React) 도입 권장
2. 기존 시스템 유지보수: Spring Framework 5.3.x (Spring Boot 2.7.x) LTS 버전 유지
3. 변환 라이브러리: 커뮤니티 오픈소스 jakarta-tiles 포크 프로젝트 또는 Eclipse Transformer 활용
```

## 12. 실무 트러블슈팅 & 체크리스트 (Troubleshooting)
```text
# [1] NoSuchDefinitionException 발생 시
- 원인 1: 컨트롤러에서 반환한 뷰 이름과 tiles.xml의 <definition name="..."> 불일치
- 원인 2: tiles.xml의 DTD 선언 URL 오타 또는 XML 파싱 에러
- 확인: TilesConfigurer의 setDefinitions 경로 매핑이 올바른지 확인

# [2] JSP 화면 수정 내용이 바로 반영되지 않을 때
- 원인: tiles.xml 및 JSP 파일 캐싱
- 해결: TilesConfigurer에 configurer.setCheckRefresh(true) 설정 확인

# [3] ViewResolver 우선순위 충돌
- TilesViewResolver의 order(1)가 InternalResourceViewResolver의 order(2)보다 앞서야 함.
```
💬
Apache Tiles 치트시트

의견 및 질문

댓글 수정

댓글 삭제
