🕸️
SiteMesh 치트시트

자바 웹 Decorator 패턴 레이아웃 엔진 완전 가이드: SiteMesh 3 & 2 아키텍처, 서블릿 필터(SiteMeshFilter) 가로채기, sitemesh.xml 데코레이터 매핑, Spring Boot 3 Java Config 연동, 관리자/사용자 다중 레이아웃 분기 및 AJAX 바이패스
#sitemesh#decorator-pattern#jsp#spring-boot#template#layout#servlet-filter#egovframe#java최종 업데이트: 2026-10-10
SiteMesh 치트시트 핵심 명령어 및 실전 가이드

## 1. SiteMesh 설치 & 아키텍처 가이드 (Architecture)

### 💻 시스템 설치 및 실행 요구사양 (System Requirements)

| 항목 | 최소 사양 (Minimum) | 권장 사양 (Recommended) | 참고 및 비고 |
| :--- | :--- | :--- | :--- |
| **운영체제 (OS)** | Windows, Linux (Ubuntu, RHEL, Alpine), macOS | Ubuntu 22.04 LTS, Windows Server, macOS | Java 서블릿 엔진이 동작하는 모든 OS |
| **CPU** | 1 코어 이상 (x86_64 / ARM64) | 2 코어 ~ 4 코어 이상 | 서블릿 필터 버퍼링 및 HTML DOM 파싱 연산 |
| **메모리 (RAM)** | 512 MB 이상 (JVM 힙 256 MB) | 2 GB ~ 4 GB 이상 | HTML 응답 버퍼 및 메모리 캐싱 |
| **디스크 (Storage)** | 200 MB 여유 공간 | 2 GB 이상의 여유 공간 | WAR 배포본, JSP 컴파일 캐시 및 로그 |
| **네트워크 / 런타임** | Java 8, 11, 17, 21 LTS & Servlet 3.1+ | OpenJDK 17 LTS 이상 & Tomcat 9/10+ | SiteMesh 2.x(`javax.*`), SiteMesh 3.x(`jakarta.*`) |

---

### 📦 의존성 설정 (Maven & Gradle)

```xml
<!-- [1] Maven (pom.xml) - SiteMesh 3.x (현대적 표준 권장) -->
<dependency>
    <groupId>org.sitemesh</groupId>
    <artifactId>sitemesh</artifactId>
    <version>3.0.1</version>
</dependency>

<!-- [2] Maven (pom.xml) - SiteMesh 2.x (전자정부프레임워크 / 레거시 유지보수용) -->
<dependency>
    <groupId>opensymphony</groupId>
    <artifactId>sitemesh</artifactId>
    <version>2.4.2</version>
</dependency>
```

```groovy
// [3] Gradle (build.gradle)
dependencies {
    // SiteMesh 3.x
    implementation 'org.sitemesh:sitemesh:3.0.1'

    // 또는 SiteMesh 2.4.2 레거시
    // implementation 'opensymphony:sitemesh:2.4.2'
}
```

---

## 2. SiteMesh 멘탈 모델 & 데코레이터 패턴 (Mental Model)

SiteMesh는 **Decorator(장식자) 패턴**을 서블릿 필터(Servlet Filter) 레벨에서 구현한 프레임워크입니다.  
개발자는 상/하단 레이아웃을 전혀 신경 쓰지 않고 **순수한 콘텐츠 HTML/JSP**만 작성하며, 서블릿 필터가 최종 응답을 가로채서 공통 템플릿(Header, Nav, Footer) 안에 본문을 끼워 넣습니다.

### 🧭 서블릿 필터 인터셉트 & 데코레이팅 흐름

```text
[클라이언트 브라우저] 
        │ (1) GET /board/list
        ▼
┌─────────────────────────────────────────────────────────────────┐
│                    서블릿 컨테이너 (Tomcat)                      │
│                                                                 │
│   [SiteMeshFilter] (요청 통과)                                   │
│          │                                                      │
│          ▼                                                      │
│   [Spring Controller ➔ board/list.jsp 렌더링]                    │
│   ┌─────────────────────────────────────────────────────────┐   │
│   │ <head><title>게시판 목록</title></head>                 │   │
│   │ <body><table class="list">...</table></body>            │   │
│   └─────────────────────────────────────────────────────────┘   │
│          │ (2) HTML 버퍼 가로채기 (Intercept Response)           │
│          ▼                                                      │
│   [SiteMesh HTML 파서 분석]                                     │
│     ├─ Title  : "게시판 목록"                                   │
│     ├─ Head   : CSS, 페이지 전용 메타 태그                      │
│     └─ Body   : 게시판 테이블 콘텐츠 본문                       │
│          │                                                      │
│          ▼                                                      │
│   [Decorator 템플릿 주입 (/WEB-INF/decorators/default.jsp)]     │
│   ┌─────────────────────────────────────────────────────────┐   │
│   │ <html>                                                  │   │
│   │   <head><sitemesh:write property='head'/></head>        │   │
│   │   <body>                                                │   │
│   │     <div class="header">공통 GNB 네비게이션</div>       │   │
│   │     <div class="main"><sitemesh:write property='body'/> │   │
│   │     <div class="footer">공통 푸터 카피라이트</div>      │   │
│   │   </body>                                               │   │
│   │ </html>                                                 │   │
│   └─────────────────────────────────────────────────────────┘   │
└────────────────────────────────┬────────────────────────────────┘
                                 │ (3) 최종 조립된 완성 HTML 전송
                                 ▼
                     [브라우저 화면 최종 표시]
```

### ⚖️ SiteMesh vs Apache Tiles vs Thymeleaf Layout 비교

| 비교 항목 | SiteMesh | Apache Tiles | Thymeleaf Layout Dialect |
| :--- | :--- | :--- | :--- |
| **핵심 패턴** | **Decorator 패턴** (응답 사후 장식) | **Composite View 패턴** (사전 조립) | **Template Inheritance** (템플릿 상속) |
| **동작 위치** | 서블릿 필터(`Servlet Filter`) | 스프링 뷰 리졸버(`ViewResolver`) | 템플릿 엔진 내부 파서 |
| **개별 페이지 코드** | **완전한 순수 HTML** (`<head>`, `<body>` 포함 가능) | 조각 JSP 조각 파일 (`<div>`만 작성) | `layout:decorate` 속성 선언 |
| **프레임워크 종속성** | 없음 (JSP, 서블릿, 스프링, 정적 HTML 모두 적용) | Spring MVC 및 JSP 강력 결합 | Thymeleaf 전용 |
| **적합한 환경** | 대규모 레거시 포털, 정적 페이지와 동적 페이지 혼합 환경 | 전자정부프레임워크 표준 엔터프라이즈 | 최신 Spring Boot 모던 웹 애플리케이션 |

---

## 3. [초보자 1단계] 3분 헬로월드: SiteMesh 3 무설정 빠른 연동

스프링 부트 환경에서 자바 설정(`FilterRegistrationBean`)으로 SiteMesh 3를 등록하고 기본 데코레이터를 적용합니다.

### ☕ 1. 자바 필터 설정 (`SiteMeshConfig.java`)

```java
package com.lucky.config;

import org.sitemesh.builder.SiteMeshFilterBuilder;
import org.sitemesh.config.ConfigurableSiteMeshFilter;
import org.springframework.boot.web.servlet.FilterRegistrationBean;
import org.springframework.context.annotation.Bean;
import org.springframework.context.annotation.Configuration;

@Configuration
public class SiteMeshConfig {

    @Bean
    public FilterRegistrationBean<ConfigurableSiteMeshFilter> siteMeshFilter() {
        FilterRegistrationBean<ConfigurableSiteMeshFilter> filter = new FilterRegistrationBean<>();
        
        // SiteMesh 설정 빌더 익명 클래스 정의
        filter.setFilter(new ConfigurableSiteMeshFilter() {
            @Override
            protected void applyCustomConfiguration(SiteMeshFilterBuilder builder) {
                // 1) 전체 기본 데코레이터 적용
                builder.addDecoratorPath("/*", "/WEB-INF/views/decorators/main-decorator.jsp");
                
                // 2) API 및 정적 자원은 데코레이터 제외
                builder.addExcludedPath("/api/*");
                builder.addExcludedPath("/static/*");
                builder.addExcludedPath("/resources/*");
            }
        });
        
        filter.addUrlPatterns("/*");
        filter.setOrder(1); // 인코딩 필터 다음으로 실행되도록 설정
        return filter;
    }
}
```

---

### 🎨 2. 공통 데코레이터 레이아웃 (`main-decorator.jsp`)

```jsp
<%@ page language="java" contentType="text/html; charset=UTF-8" pageEncoding="UTF-8"%>
<!DOCTYPE html>
<html lang="ko">
<head>
    <meta charset="UTF-8">
    <meta name="viewport" content="width=device-width, initial-scale=1.0">
    <!-- 원본 페이지의 <title> 태그 자동 주입 -->
    <title><sitemesh:write property='title'/> - LuckyTech World</title>
    
    <!-- 공통 글로벌 스타일시트 -->
    <link rel="stylesheet" href="/static/css/global.css">
    
    <!-- 원본 페이지의 <head> 안에 포함된 전용 CSS/스크립트 주입 -->
    <sitemesh:write property='head'/>
</head>
<body>
    <!-- 공통 헤더 -->
    <header class="site-header">
        <div class="logo">🍀 LuckyTech World</div>
        <nav class="gnb">
            <a href="/">홈</a>
            <a href="/board">게시판</a>
            <a href="/about">소개</a>
        </nav>
    </header>

    <!-- 원본 페이지의 <body> 내용 자동 주입 -->
    <main class="site-content">
        <sitemesh:write property='body'/>
    </main>

    <!-- 공통 푸터 -->
    <footer class="site-footer">
        <p>&copy; 2026 LuckyTech World. All rights reserved.</p>
    </footer>
</body>
</html>
```

---

### 📄 3. 개발자가 작성하는 실제 화면 (`content.jsp`)

헤더/푸터를 포함하지 않고 본인이 표시할 독립적인 HTML 페이지만 작성합니다.

```jsp
<%@ page language="java" contentType="text/html; charset=UTF-8" pageEncoding="UTF-8"%>
<!DOCTYPE html>
<html>
<head>
    <!-- 이 타이틀은 데코레이터의 <title> 자리에 자동 삽입됩니다 -->
    <title>서비스 소개</title>
    <style>
        .service-intro { color: #10b981; font-weight: bold; }
    </style>
</head>
<body>
    <div class="container">
        <h1 class="service-intro">SiteMesh 3 데코레이터 헬로월드!</h1>
        <p>개별 뷰 페이지에서는 레이아웃 include 코드를 일절 작성할 필요가 없습니다.</p>
    </div>
</body>
</html>
```

#### 🖥️ 브라우저 소스 보기 결과 (Final Rendered HTML)

```html
<!DOCTYPE html>
<html lang="ko">
<head>
    <meta charset="UTF-8">
    <meta name="viewport" content="width=device-width, initial-scale=1.0">
    <title>서비스 소개 - LuckyTech World</title>
    <link rel="stylesheet" href="/static/css/global.css">
    <style>
        .service-intro { color: #10b981; font-weight: bold; }
    </style>
</head>
<body>
    <header class="site-header">
        <div class="logo">🍀 LuckyTech World</div>
        <nav class="gnb">
            <a href="/">홈</a>
            <a href="/board">게시판</a>
            <a href="/about">소개</a>
        </nav>
    </header>
    <main class="site-content">
        <div class="container">
            <h1 class="service-intro">SiteMesh 3 데코레이터 헬로월드!</h1>
            <p>개별 뷰 페이지에서는 레이아웃 include 코드를 일절 작성할 필요가 없습니다.</p>
        </div>
    </main>
    <footer class="site-footer">
        <p>&copy; 2026 LuckyTech World. All rights reserved.</p>
    </footer>
</body>
</html>
```

---

## 4. [2단계] 핵심 기능: sitemesh.xml 매핑 규칙 & 프로퍼티 주입

### ⚙️ 1. XML 선언적 설정 (`WEB-INF/sitemesh.xml`)

자바 코드 대신 XML 파일로 매핑 규칙을 중앙 관리할 때 사용합니다.

```xml
<?xml version="1.0" encoding="UTF-8"?>
<sitemesh>
    <!-- 1. 기본 데코레이터 템플릿 지정 -->
    <mapping path="/*" decorator="/WEB-INF/views/decorators/default.jsp"/>

    <!-- 2. 관리자 경로 다중 데코레이터 분기 -->
    <mapping path="/admin/*" decorator="/WEB-INF/views/decorators/admin.jsp"/>

    <!-- 3. 모달/팝업 창 전용 심플 데코레이터 -->
    <mapping path="/popup/*" decorator="/WEB-INF/views/decorators/popup.jsp"/>

    <!-- 4. 데코레이터 적용 제외(Excludes) 패턴 -->
    <mapping path="/api/*" exclude="true"/>
    <mapping path="/rest/*" exclude="true"/>
    <mapping path="/download/*" exclude="true"/>
    <mapping path="*.json" exclude="true"/>
</sitemesh>
```

---

### 🏷️ 2. SiteMesh 3 태그와 프로퍼티 주입 문법

| 태그 | 역할 및 설명 |
| :--- | :--- |
| `<sitemesh:write property='title'/>` | 콘텐츠 페이지의 `<title>` 텍스트를 추출하여 삽입 |
| `<sitemesh:write property='body'/>` | 콘텐츠 페이지의 `<body>` 내부 전체 HTML을 추출하여 삽입 |
| `<sitemesh:write property='head'/>` | 콘텐츠 페이지의 `<head>` 내부 태그(스크립트, 인라인 스타일, 메타) 삽입 |
| `<sitemesh:write property='meta.author'/>` | 콘텐츠의 `<meta name="author" content="lucky">` 속성값 추출 |
| `<sitemesh:write property='body.class'/>` | 콘텐츠 `<body class="dark-mode">`의 클래스 속성값 주입 |

---

### 🧩 3. 커스텀 컨텐츠 태그 전달 (`<content tag="...">`)

페이지별로 특정 영역(예: 사이드바 위젯, 페이지 전용 JavaScript 하단 스크립트)을 데코레이터의 특정 위치에 꽂아 넣을 때 사용합니다.

#### 본문 페이지 (`detail.jsp`)
```jsp
<body>
    <h2>게시글 상세 페이지</h2>
    <p>본문 내용입니다.</p>

    <!-- 데코레이터 특정 슬롯으로 보낼 커스텀 블록 선언 -->
    <content tag="pageScripts">
        <script src="/static/js/chart.min.js"></script>
        <script>
            console.log("페이지 전용 하단 스크립트 실행");
        </script>
    </content>
</body>
```

#### 데코레이터 템플릿 (`default.jsp`)
```jsp
<body>
    <div class="content">
        <sitemesh:write property='body'/>
    </div>

    <!-- 하단 공통 스크립트 -->
    <script src="/static/js/jquery.min.js"></script>
    <script src="/static/js/common.js"></script>

    <!-- 개별 페이지에서 전달된 pageScripts 블록을 여기에 렌더링 -->
    <sitemesh:write property='page.pageScripts'/>
</body>
```

---

## 5. [3단계] 실무 응용: SiteMesh 2 레거시 & 다중 레이아웃

대한민국 공공기관 및 전자정부프레임워크(eGovFrame) 환경에서 널리 쓰이는 SiteMesh 2.x 설정 표준입니다.

### 🏛️ 1. SiteMesh 2.x 표준 구성 (`web.xml` & `decorators.xml`)

#### `WEB-INF/web.xml` 필터 등록
```xml
<filter>
    <filter-name>sitemesh</filter-name>
    <filter-class>com.opensymphony.sitemesh.webapp.SiteMeshFilter</filter-class>
</filter>
<filter-mapping>
    <filter-name>sitemesh</filter-name>
    <url-pattern>/*</url-pattern>
</filter-mapping>
```

#### `WEB-INF/decorators.xml` 데코레이터 정의
```xml
<?xml version="1.0" encoding="UTF-8"?>
<decorators defaultdir="/WEB-INF/views/decorators">
    <!-- 제외 경로 -->
    <excludes>
        <pattern>/api/*</pattern>
        <pattern>/rest/*</pattern>
        <pattern>/resources/*</pattern>
        <pattern>*.ajax</pattern>
    </excludes>

    <!-- 사용자 포털 기본 레이아웃 -->
    <decorator name="main" page="main-layout.jsp">
        <pattern>/*</pattern>
    </decorator>

    <!-- 관리자 어드민 전용 레이아웃 -->
    <decorator name="admin" page="admin-layout.jsp">
        <pattern>/admin/*</pattern>
        <pattern>/manage/*</pattern>
    </decorator>
</decorators>
```

#### SiteMesh 2 데코레이터 JSP 태그 라이브러리 (`main-layout.jsp`)
```jsp
<%@ page language="java" contentType="text/html; charset=UTF-8" pageEncoding="UTF-8"%>
<%@ taglib prefix="decorator" uri="http://www.opensymphony.com/sitemesh/decorator" %>
<%@ taglib prefix="page" uri="http://www.opensymphony.com/sitemesh/page" %>
<!DOCTYPE html>
<html>
<head>
    <title><decorator:title default="기본 시스템 명"/></title>
    <decorator:head/>
</head>
<body class="<decorator:getProperty property='body.class' default='normal'/>">
    <div id="header">
        <jsp:include page="/WEB-INF/views/layout/gnb.jsp"/>
    </div>
    <div id="container">
        <!-- 원본 본문 삽입 -->
        <decorator:body/>
    </div>
    <div id="footer">
        <jsp:include page="/WEB-INF/views/layout/footer.jsp"/>
    </div>
</body>
</html>
```

---

### 🛡️ 2. AJAX & REST JSON 응답 시 데코레이터 자동 바이패스 필터

비동기 Fetch/AJAX 요청 시 HTML 데코레이터가 감싸져 JSON 파싱 오류가 발생하는 문제를 원천 방지하는 커스텀 필터 구현입니다.

```java
package com.lucky.filter;

import jakarta.servlet.http.HttpServletRequest;
import org.sitemesh.builder.SiteMeshFilterBuilder;
import org.sitemesh.config.ConfigurableSiteMeshFilter;

public class CustomSiteMeshFilter extends ConfigurableSiteMeshFilter {

    @Override
    protected void applyCustomConfiguration(SiteMeshFilterBuilder builder) {
        // 기본 데코레이터
        builder.addDecoratorPath("/*", "/WEB-INF/views/decorators/default.jsp");
        builder.addDecoratorPath("/admin/*", "/WEB-INF/views/decorators/admin.jsp");
        
        // 정적 리소스 제외
        builder.addExcludedPath("/static/*");
        builder.addExcludedPath("/upload/*");
        
        // 커스텀 요청 검사 (AJAX 요청 헤더 감지 시 데코레이터 스킵)
        builder.addCustomRule(new org.sitemesh.content.tagrules.TagRuleBundle() {
            // 커스텀 태그 규칙 필요 시 구현
        });
    }

    // 또는 컨트롤러에서 헤더 전달 또는 URL 확장자(.json)로 분기 권장
}
```

---

## 6. 프로덕션 트러블슈팅 & 운영 체크리스트 (Troubleshooting)

### 🔍 자주 발생하는 오류 & 해결 가이드

#### 1. 한글 인코딩 깨짐 현상 (EUC-KR / 깨진 문자 출력)
- **원인**: 서블릿 필터 체인에서 `SiteMeshFilter`가 `CharacterEncodingFilter`보다 먼저 실행되면 요청/응답 인코딩이 깨집니다.
- **해결책**: 스프링 부트에서 `CharacterEncodingFilter`를 `Ordered.HIGHEST_PRECEDENCE`로 지정하고, SiteMesh는 그 이후(예: Order 1 또는 2)로 등록해야 합니다.
  ```java
  filterRegistrationBean.setOrder(2);
  ```

#### 2. Spring Boot 3 (Jakarta Servlet) 호환성 문제
- **원인**: SiteMesh 2.x와 SiteMesh 3.0.1 이전 버전은 과거 `javax.servlet.*` 패키지를 참조하므로 Spring Boot 3 (`jakarta.servlet.*`) 환경에서 `ClassNotFoundException`이 발생합니다.
- **해결책**:
  - Spring Boot 3 환경에서는 `org.sitemesh:sitemesh:3.0.1` 이상을 사용하거나 톰캣 마이그레이션 도구를 적용해야 합니다.
  - 최신 Spring Boot 3 신규 프로젝트라면 **Thymeleaf Layout Dialect** 도입을 권장합니다.

#### 3. 중복된 `<head>` 또는 스타일시트 다중 로딩 버그
- **원인**: `<sitemesh:write property='head'/>`를 사용하지 않고 개별 페이지에서 공통 CSS를 중복 임포트할 때 발생.
- **해결책**: 공통 라이브러리(Bootstrap, Tailwind, jQuery 등)는 **반드시 데코레이터 템플릿에만 1회 선언**하고, 각 페이지에는 고유한 페이지 전용 스크립트만 남겨둡니다.

#### 4. 페이지 특정 화면에서만 데코레이터 적용을 끄고 싶을 때 (임시 바이패스)
- JSP 상단에 메타 태그를 명시하여 SiteMesh 엔진에 스킵을 지시합니다:
  ```jsp
  <!-- SiteMesh 2.x 에서 데코레이터 비활성화 -->
  <meta name="decorator" content="none"/>
  ```
💬
SiteMesh 치트시트

의견 및 질문

댓글 수정

댓글 삭제
