업무에 사용하는 Go 언어 썸네일

Go html template – 업무에 사용하는 Go 언어 응용편 4

로
Go html template
Go html template

Go 언어의 기본 문법을 익힌 후 웹 개발로 나아가는 과정에서 꼭 해보면 좋은 것이 바로 템플릿 렌더링입니다. Go html template은 Go 언어에서 HTML 문서를 동적으로 생성할 수 있는 강력한 도구로, 웹 애플리케이션 개발의 핵심 요소 중 하나입니다.

필자는 go언어를 활용하여 웹 사이트를 구성한 경험이 있으며, 처음 템플릿을 다룰 때 많은 시행착오를 겪었습니다. 이후 gin 웹 프레임워크를 통해 고도화된 사이트를 만들면서 템플릿의 중요성을 더욱 깨닫게 되었죠.

html/template 패키지 이해하기

Go 언어에서 제공하는 html/template 패키지는 HTML 출력을 위한 특화된 템플릿 엔진입니다. 일반적인 text/template 패키지와 달리 HTML 특성을 고려한 보안 기능이 내장되어 있어 XSS(Cross-Site Scripting) 공격을 자동으로 방지합니다.

이 패키지의 가장 큰 장점은 템플릿 구문이 직관적이면서도 강력한 기능을 제공한다는 점입니다. 변수 삽입, 조건문, 반복문 등을 통해 복잡한 HTML 구조도 효율적으로 생성할 수 있습니다.

기본적인 Go html template 사용법

가장 간단한 예제부터 시작해보겠습니다.

Go
package main

import (
    "html/template"
    "os"
)

func main() {
    // 템플릿 문자열 정의
    tmplStr := `<h1>안녕하세요, {{.Name}}님!</h1>
<p>오늘은 {{.Date}}입니다.</p>`
    
    // 템플릿 파싱
    tmpl, err := template.New("greeting").Parse(tmplStr)
    if err != nil {
        panic(err)
    }
    
    // 데이터 구조체 정의
    data := struct {
        Name string
        Date string
    }{
        Name: "홍길동",
        Date: "2025년 06월",
    }
    
    // 템플릿 실행
    err = tmpl.Execute(os.Stdout, data)
    if err != nil {
        panic(err)
    }
}

위 예제에서 {{.Name}}과 {{.Date}}는 템플릿 액션(action)입니다. 점(.)은 현재 데이터 객체를 의미하며, 그 뒤에 오는 필드명을 통해 해당 값에 접근합니다. 템플릿이 실행되면 이 액션들이 실제 데이터로 치환되어 최종 HTML이 생성됩니다.

template.New() 함수는 새로운 템플릿을 생성하고, Parse() 메서드는 템플릿 문자열을 파싱합니다. 마지막으로 Execute() 메서드가 데이터와 템플릿을 결합하여 결과를 출력합니다.

파일 기반 템플릿 작업하기

실제 웹 개발에서는 템플릿을 별도 파일로 관리하는 것이 일반적입니다. 다음과 같이 HTML 파일을 생성해보겠습니다.

index.html 파일:

HTML
<!DOCTYPE html>
<html>
<head>
    <title>{{.Title}}</title>
</head>
<body>
    <h1>{{.Heading}}</h1>
    <div>
        {{range .Items}}
        <p>- {{.}}</p>
        {{end}}
    </div>
</body>
</html>

이를 활용하는 Go 코드:

Go
package main

import (
    "html/template"
    "net/http"
)

type PageData struct {
    Title   string
    Heading string
    Items   []string
}

func homeHandler(w http.ResponseWriter, r *http.Request) {
    // 템플릿 파일 파싱
    tmpl, err := template.ParseFiles("index.html")
    if err != nil {
        http.Error(w, err.Error(), http.StatusInternalServerError)
        return
    }
    
    // 페이지 데이터 준비
    data := PageData{
        Title:   "Go 템플릿 예제",
        Heading: "항목 목록",
        Items:   []string{"첫 번째 항목", "두 번째 항목", "세 번째 항목"},
    }
    
    // 템플릿 실행 및 응답
    err = tmpl.Execute(w, data)
    if err != nil {
        http.Error(w, err.Error(), http.StatusInternalServerError)
    }
}

func main() {
    http.HandleFunc("/", homeHandler)
    http.ListenAndServe(":8080", nil)
}

여기서 주목할 점은 {{range .Items}}...{{end}} 구문입니다. 이는 Go 템플릿의 반복문으로, 슬라이스나 배열의 각 요소에 대해 반복 실행됩니다. 반복문 내부에서는 현재 요소가 .으로 참조됩니다.

template.ParseFiles() 함수는 파일에서 직접 템플릿을 읽어와 파싱하는 편리한 방법입니다. 웹 핸들러에서 http.ResponseWriter에 직접 템플릿 결과를 출력할 수 있어 웹 개발에 최적화되어 있습니다.

go언어 html 조건문과 반복문 활용

go언어 html 템플릿에서는 다양한 제어 구조를 제공합니다. 조건문과 반복문을 조합하면 복잡한 동적 콘텐츠도 쉽게 생성할 수 있습니다.

Go
// 사용자 정보 구조체
type User struct {
    Name     string
    Age      int
    IsAdmin  bool
    Hobbies  []string
}

// 템플릿 문자열
tmplStr := `
<div class="user-info">
    <h2>{{.Name}}님의 정보</h2>
    
    {{if .IsAdmin}}
    <span class="admin-badge">관리자</span>
    {{else}}
    <span class="user-badge">일반 사용자</span>
    {{end}}
    
    <p>나이: {{.Age}}세</p>
    
    {{if gt .Age 20}}
    <p>성인입니다.</p>
    {{else}}
    <p>미성년자입니다.</p>
    {{end}}
    
    {{if .Hobbies}}
    <h3>취미 목록:</h3>
    <ul>
        {{range $index, $hobby := .Hobbies}}
        <li>{{$index | printf "%d"}}: {{$hobby}}</li>
        {{end}}
    </ul>
    {{else}}
    <p>등록된 취미가 없습니다.</p>
    {{end}}
</div>
`

이 예제에서 사용된 템플릿 기능들을 자세히 살펴보겠습니다:

  • {{if .IsAdmin}}: 불린 값에 따른 조건 분기
  • {{if gt .Age 20}}: gt(greater than) 함수를 사용한 숫자 비교
  • {{range $index, $hobby := .Hobbies}}: 인덱스와 값을 동시에 받는 반복문
  • {{$index | printf "%d"}}: 파이프라인을 통한 함수 적용

필자는 처음에 이런 복잡한 로직을 Go 코드에서 모두 처리하려 했었는데, 템플릿 내에서 직접 처리하는 것이 훨씬 직관적이고 유지보수가 쉽다는 것을 경험을 통해 알게 되었습니다.

템플릿 함수와 파이프라인

Go 템플릿은 내장 함수뿐만 아니라 사용자 정의 함수도 지원합니다. 이를 통해 템플릿의 표현력을 크게 향상시킬 수 있습니다.

Go
package main

import (
    "html/template"
    "net/http"
    "strings"
    "time"
)

// 사용자 정의 함수 맵
var funcMap = template.FuncMap{
    "upper":      strings.ToUpper,
    "lower":      strings.ToLower,
    "formatDate": formatDate,
    "add":        add,
}

func formatDate(t time.Time) string {
    return t.Format("2006년 01월 02일")
}

func add(a, b int) int {
    return a + b
}

func templateHandler(w http.ResponseWriter, r *http.Request) {
    tmplStr := `
    <h1>{{.Title | upper}}</h1>
    <p>작성자: {{.Author | lower}}</p>
    <p>작성일: {{.CreatedAt | formatDate}}</p>
    <p>조회수: {{.Views}}, 좋아요: {{.Likes}}, 총합: {{add .Views .Likes}}</p>
    `
    
    // 함수 맵을 포함한 템플릿 생성
    tmpl, err := template.New("post").Funcs(funcMap).Parse(tmplStr)
    if err != nil {
        http.Error(w, err.Error(), http.StatusInternalServerError)
        return
    }
    
    data := struct {
        Title     string
        Author    string
        CreatedAt time.Time
        Views     int
        Likes     int
    }{
        Title:     "go 템플릿 가이드",
        Author:    "개발자Kim",
        CreatedAt: time.Now(),
        Views:     150,
        Likes:     23,
    }
    
    tmpl.Execute(w, data)
}

이 예제에서 파이프라인(|) 연산자의 사용법을 주목해보세요. {{.Title | upper}}는 Title 값을 upper 함수에 전달하여 대문자로 변환합니다. 여러 함수를 연결할 수도 있어서 {{.Title | lower | upper}}와 같은 체이닝도 가능합니다.

사용자 정의 함수를 등록할 때는 반드시 Parse() 호출 전에 Funcs() 메서드를 사용해야 합니다. 이는 Go 템플릿 엔진이 파싱 시점에 함수 정보를 필요로 하기 때문입니다.

템플릿 상속과 조합

대규모 웹 애플리케이션에서는 템플릿 재사용성이 매우 중요합니다. go언어 template에서는 템플릿 상속과 블록 정의를 통해 이를 해결할 수 있습니다.

기본 레이아웃 템플릿 (layout.html):

HTML
<!DOCTYPE html>
<html>
<head>
    <title>{{block "title" .}}기본 제목{{end}}</title>
    <meta charset="UTF-8">
</head>
<body>
    <header>
        <nav>공통 네비게이션</nav>
    </header>
    
    <main>
        {{block "content" .}}
        <p>기본 콘텐츠</p>
        {{end}}
    </main>
    
    <footer>
        {{block "footer" .}}
        <p>© 2024 My Website</p>
        {{end}}
    </footer>
</body>
</html>

페이지별 템플릿 (home.html):

HTML
{{define "title"}}홈페이지 - {{.SiteName}}{{end}}

{{define "content"}}
<h1>{{.WelcomeMessage}}</h1>
<div class="recent-posts">
    {{range .RecentPosts}}
    <article>
        <h2>{{.Title}}</h2>
        <p>{{.Summary}}</p>
    </article>
    {{end}}
</div>
{{end}}

이를 사용하는 Go 코드:

Go
func homePageHandler(w http.ResponseWriter, r *http.Request) {
    // 여러 템플릿 파일을 동시에 파싱
    tmpl, err := template.ParseFiles("layout.html", "home.html")
    if err != nil {
        http.Error(w, err.Error(), http.StatusInternalServerError)
        return
    }
    
    data := struct {
        SiteName       string
        WelcomeMessage string
        RecentPosts    []Post
    }{
        SiteName:       "내 블로그",
        WelcomeMessage: "블로그에 오신 것을 환영합니다!",
        RecentPosts: []Post{
            {Title: "첫 번째 포스트", Summary: "첫 포스트 요약"},
            {Title: "두 번째 포스트", Summary: "두 번째 포스트 요약"},
        },
    }
    
    // layout.html을 기본 템플릿으로 실행
    err = tmpl.ExecuteTemplate(w, "layout.html", data)
    if err != nil {
        http.Error(w, err.Error(), http.StatusInternalServerError)
    }
}

템플릿 상속에서 핵심은 {{block}} 과 {{define}} 구문입니다. block은 기본값을 가진 재정의 가능한 영역을 선언하고, define은 해당 블록의 구체적인 내용을 정의합니다. 이를 통해 공통 레이아웃을 유지하면서 페이지별 특화 내용을 삽입할 수 있습니다.

보안과 이스케이핑

Go html template의 가장 큰 장점 중 하나는 자동 HTML 이스케이핑입니다. 이는 XSS 공격을 방지하는 핵심 보안 기능입니다.

Go
func securityDemo(w http.ResponseWriter, r *http.Request) {
    tmplStr := `
    <h1>사용자 입력 테스트</h1>
    <p>일반 출력: {{.UserInput}}</p>
    <p>HTML 출력: {{.HTMLContent}}</p>
    <p>안전한 HTML: {{.SafeHTML}}</p>
    `
    
    tmpl, err := template.New("security").Parse(tmplStr)
    if err != nil {
        http.Error(w, err.Error(), http.StatusInternalServerError)
        return
    }
    
    data := struct {
        UserInput   string
        HTMLContent string
        SafeHTML    template.HTML
    }{
        UserInput:   "<script>alert('XSS')</script>",
        HTMLContent: "<em>강조된 텍스트</em>",
        SafeHTML:    template.HTML("<em>안전한 강조 텍스트</em>"),
    }
    
    tmpl.Execute(w, data)
}

이 예제에서 UserInput과 HTMLContent는 자동으로 HTML 엔티티로 변환됩니다. <script> 태그는 &lt;script&gt;로, <em> 태그는 &lt;em&gt;으로 출력되어 브라우저에서 실행되지 않습니다.

반면 template.HTML 타입으로 래핑된 SafeHTML은 이스케이핑되지 않고 그대로 HTML로 렌더링됩니다. 이는 신뢰할 수 있는 HTML 콘텐츠를 출력할 때만 사용해야 합니다.

필자는 초기에 이 자동 이스케이핑 기능을 모르고 수동으로 HTML을 이스케이프하는 코드를 작성했었는데,
Go 템플릿이 이미 안전한 출력을 보장한다는 것을 알고 나서 코드를 훨씬 간결하게 변경할 수 있었다.

성능 최적화와 Best Practice!

실제 프로덕션 환경에서 템플릿을 사용할 때는 성능을 고려해야 합니다.
템플릿 파싱은 상대적으로 비용이 큰 작업이므로, 애플리케이션 시작 시점에 미리 파싱해두는 것이 좋습니다.

Go
package main

import (
    "html/template"
    "net/http"
    "sync"
)

// 전역 템플릿 저장소
var (
    templates *template.Template
    once      sync.Once
)

// 템플릿 초기화 (한 번만 실행)
func initTemplates() {
    once.Do(func() {
        var err error
        templates = template.New("").Funcs(funcMap)
        templates, err = templates.ParseGlob("templates/*.html")
        if err != nil {
            panic(err)
        }
    })
}

func renderTemplate(w http.ResponseWriter, name string, data interface{}) error {
    initTemplates()
    return templates.ExecuteTemplate(w, name, data)
}

func homeHandler(w http.ResponseWriter, r *http.Request) {
    data := map[string]interface{}{
        "Title":   "홈페이지",
        "Message": "환영합니다!",
    }
    
    if err := renderTemplate(w, "home.html", data); err != nil {
        http.Error(w, err.Error(), http.StatusInternalServerError)
    }
}

이 패턴의 장점은 다음과 같습니다:

  1. 성능 향상: 템플릿을 한 번만 파싱하여 메모리에 캐시
  2. 에러 조기 감지: 애플리케이션 시작 시 템플릿 문법 오류 확인
  3. 메모리 효율성: 동일한 템플릿을 여러 요청에서 재사용
  4. 동시성 안전: sync.Once를 통한 안전한 초기화

ParseGlob() 함수는 와일드카드 패턴을 사용하여 여러 템플릿 파일을 한 번에 파싱하는 편리한 방법입니다. “templates/*.html” 패턴은 templates 디렉토리의 모든 HTML 파일을 자동으로 포함시킵니다.

실제 웹 애플리케이션 구조

마지막으로 실제 웹 애플리케이션에서 사용할 수 있는 완전한 예제를 살펴보겠습니다.

Go
package main

import (
    "html/template"
    "log"
    "net/http"
    "time"
)

type Article struct {
    ID        int
    Title     string
    Content   string
    Author    string
    CreatedAt time.Time
    Tags      []string
}

type PageData struct {
    Title    string
    Articles []Article
    User     *User
}

type User struct {
    Name      string
    IsLoggedIn bool
}

var articleTemplate = `
<!DOCTYPE html>
<html>
<head>
    <title>{{.Title}}</title>
    <style>
        body { font-family: Arial, sans-serif; margin: 40px; }
        .article { border: 1px solid #ddd; margin: 20px 0; padding: 20px; }
        .tags { color: #666; font-size: 0.9em; }
        .meta { color: #888; font-size: 0.8em; }
    </style>
</head>
<body>
    <header>
        <h1>{{.Title}}</h1>
        {{if .User.IsLoggedIn}}
        <p>안녕하세요, {{.User.Name}}님!</p>
        {{else}}
        <p><a href="/login">로그인</a></p>
        {{end}}
    </header>
    
    <main>
        {{range .Articles}}
        <article class="article">
            <h2>{{.Title}}</h2>
            <div class="meta">
                작성자: {{.Author}} | 
                작성일: {{.CreatedAt.Format "2006-01-02"}}
            </div>
            <p>{{.Content}}</p>
            {{if .Tags}}
            <div class="tags">
                태그: 
                {{range $i, $tag := .Tags}}
                    {{if $i}}, {{end}}{{$tag}}
                {{end}}
            </div>
            {{end}}
        </article>
        {{else}}
        <p>등록된 게시글이 없습니다.</p>
        {{end}}
    </main>
</body>
</html>
`

func articleHandler(w http.ResponseWriter, r *http.Request) {
    tmpl, err := template.New("articles").Parse(articleTemplate)
    if err != nil {
        http.Error(w, err.Error(), http.StatusInternalServerError)
        return
    }
    
    // 샘플 데이터
    data := PageData{
        Title: "기술 블로그",
        User: &User{
            Name:      "개발자Kim",
            IsLoggedIn: true,
        },
        Articles: []Article{
            {
                ID:        1,
                Title:     "Go 템플릿 마스터하기",
                Content:   "Go html/template 패키지를 활용한 웹 개발 가이드입니다.",
                Author:    "김개발",
                CreatedAt: time.Now().AddDate(0, 0, -1),
                Tags:      []string{"Go", "웹개발", "템플릿"},
            },
            {
                ID:        2,
                Title:     "효율적인 웹 서버 구축",
                Content:   "성능 최적화를 고려한 Go 웹 서버 아키텍처를 살펴봅니다.",
                Author:    "이백엔드",
                CreatedAt: time.Now().AddDate(0, 0, -3),
                Tags:      []string{"Go", "성능", "서버"},
            },
        },
    }
    
    err = tmpl.Execute(w, data)
    if err != nil {
        http.Error(w, err.Error(), http.StatusInternalServerError)
    }
}

func main() {
    http.HandleFunc("/", articleHandler)
    log.Println("서버가 :8080 포트에서 시작되었습니다.")
    log.Fatal(http.ListenAndServe(":8080", nil))
}

이 완전한 예제에서는 실제 블로그 시스템에서 볼 수 있는 다양한 요소들을 구현했습니다:

  • 사용자 로그인 상태에 따른 조건부 표시
  • 게시글 목록의 반복 출력
  • 날짜 포맷팅을 위한 내장 메서드 활용
  • 태그 목록의 쉼표 구분 출력
  • 빈 목록에 대한 대체 메시지

특히 {{range $i, $tag := .Tags}}에서 인덱스를 활용하여 태그 사이에 쉼표를 삽입하는 기법과, {{.CreatedAt.Format "2006-01-02"}}로 시간 객체의 메서드를 직접 호출하는 방법은 실무에서 자주 사용되는 패턴입니다.

요약

지금까지 Go html template의 핵심 기능들을 살펴보았습니다.
기본적인 템플릿 문법부터 고급 기능인 템플릿 상속, 보안 이스케이핑, 성능 최적화까지 다양한 측면을 다뤄보았습니다.

go언어 html 템플릿은 단순해 보이지만 실제로는 매우 강력한 도구입니다.
적절히 활용하면 유지보수가 용이하고 보안성이 뛰어난 웹 애플리케이션을 구축할 수 있습니다.

처음에는 복잡해 보일 수 있지만, 기본 원리를 이해하고 나면 매우 직관적이다.
특히 추후 gin 웹 프레임워크나 다른 Go 웹 프레임워크를 사용할 때도 이 지식이 그대로 활용되므로, 지금 확실히 익혀두는 것이 중요하다.

다음 단계로는 실제 데이터베이스와 연동하거나, JSON API와 함께 사용하는 방법을 학습해보겠습니다. go언어 template 시스템은 이런 고급 기능들과도 완벽하게 호환되어 복잡한 웹 애플리케이션 개발의 든든한 기반이 될 것입니다.