Go Templ+HTMX+Tailwind全棧實戰：不用前端框架構建現代Web應用的5個核心模式

2026年，前端疲勞已經到了頂峰。React 19的Server Components、Next.js 15的App Router、Vue 3.5的Suspense——每個框架都在變得越來越複雜。而Go社群給出了一個截然不同的答案：Templ + HTMX + Tailwind。Templ用型別安全的Go模板替代JSX，HTMX用HTML屬性替代JavaScript互動，Tailwind用原子化CSS替代組件庫。三者組合，你不需要寫一行JavaScript，就能構建出互動豐富、效能卓越的現代Web應用。本文將從5個核心模式出發，帶你掌握這套全棧開發方案。

核心概念

概念	說明	關鍵包/工具
Templ組件	型別安全的Go模板引擎，編譯時檢查	`github.com/a-h/templ`
HTMX互動	透過HTML屬性實現AJAX互動，無需JS	`htmx.org`
Tailwind CSS	原子化CSS框架，實用優先	`tailwindcss`
服務端渲染	Go服務端直接渲染HTML，無需SPA	`net/http`
局部更新	HTMX實現頁面局部刷新，無需全頁重載	`hx-get/hx-post`

問題分析：傳統全棧開發的5大痛點

痛點1：JavaScript框架複雜度失控

一個簡單的CRUD應用，React + TypeScript + Webpack + Babel + ESLint的配置文件就有十幾個，新人上手成本極高。

痛點2：前後端型別不一致

後端Go struct和前端TypeScript interface需要手動同步，API變更時經常遺漏，導致執行時錯誤。

痛點3：SPA首屏載入慢

單頁應用需要載入大量JavaScript才能渲染首屏，SEO不友好，使用者體驗差。

痛點4：狀態管理複雜

Redux、Pinia、Zustand——每個專案都在糾結用哪個狀態管理庫，簡單功能被過度設計。

痛點5：構建工具鏈脆弱

Webpack配置、Vite插件、PostCSS處理——任何一個環節出錯都會導致構建失敗，排查困難。

核心模式1：Templ組件定義與型別安全模板

Templ是Go語言的型別安全模板引擎，它在編譯時檢查模板語法和型別，徹底消除了執行時模板錯誤。每個Templ組件都是一個Go函式，可以接受參數、調用其他組件、組合成複雜頁面。

// components/layout.templ
package components

// LayoutProps 頁面佈局屬性
type LayoutProps struct {
	Title       string
	Description string
}

// Layout 頁面基礎佈局組件
templ Layout(props LayoutProps) {
	<!DOCTYPE html>
	<html lang="zh-TW">
	<head>
		<meta charset="UTF-8"/>
		<meta name="viewport" content="width=device-width, initial-scale=1.0"/>
		<title>{ props.Title }</title>
		<meta name="description" content={ props.Description }/>
		<script src="https://unpkg.com/htmx.org@2.0.4"></script>
		<script src="https://unpkg.com/htmx.org/dist/ext/response-targets.js"></script>
		<link href="/assets/css/app.css" rel="stylesheet"/>
	</head>
	<body class="bg-gray-50 min-h-screen">
		<nav class="bg-white shadow-sm border-b border-gray-200">
			<div class="max-w-7xl mx-auto px-4 sm:px-6 lg:px-8">
				<div class="flex justify-between h-16">
					<div class="flex items-center">
						<a href="/" class="text-xl font-bold text-indigo-600">ToolsKu</a>
					</div>
					<div class="flex items-center space-x-4">
						<a href="/tools" class="text-gray-600 hover:text-indigo-600">工具</a>
						<a href="/blog" class="text-gray-600 hover:text-indigo-600">部落格</a>
						<a href="/about" class="text-gray-600 hover:text-indigo-600">關於</a>
					</div>
				</div>
			</div>
		</nav>
		<main class="max-w-7xl mx-auto px-4 sm:px-6 lg:px-8 py-8">
			{ children... }
		</main>
		<footer class="bg-white border-t border-gray-200 mt-12">
			<div class="max-w-7xl mx-auto px-4 py-6 text-center text-gray-500 text-sm">
				© 2026 ToolsKu. All rights reserved.
			</div>
		</footer>
	</body>
	</html>
}

// PageProps 頁面屬性
type PageProps struct {
	Title       string
	Description string
	Content     templ.Component
}

// Page 帶佈局的頁面組件
templ Page(props PageProps) {
	@Layout(LayoutProps{
		Title:       props.Title,
		Description: props.Description,
	}) {
		{ props.Content }
	}
}

// components/user.templ
package components

import "time"

// User 使用者資料模型
type User struct {
	ID        string    `json:"id"`
	Name      string    `json:"name"`
	Email     string    `json:"email"`
	Role      string    `json:"role"`
	CreatedAt time.Time `json:"created_at"`
	AvatarURL string    `json:"avatar_url"`
}

// UserCard 使用者卡片組件
templ UserCard(user User) {
	<div class="bg-white rounded-lg shadow-sm border border-gray-200 p-6 hover:shadow-md transition-shadow">
		<div class="flex items-center space-x-4">
			<img
				src={ user.AvatarURL }
				alt={ user.Name }
				class="w-12 h-12 rounded-full object-cover"
			/>
			<div class="flex-1 min-w-0">
				<h3 class="text-lg font-semibold text-gray-900 truncate">{ user.Name }</h3>
				<p class="text-sm text-gray-500 truncate">{ user.Email }</p>
			</div>
			<span class={ "px-2.5 py-0.5 rounded-full text-xs font-medium",
				templ.KV(user.Role == "admin", "bg-red-100 text-red-800", "bg-green-100 text-green-800") }>
				{ user.Role }
			</span>
		</div>
		<div class="mt-4 flex items-center justify-between">
			<span class="text-xs text-gray-400">
				加入於 { user.CreatedAt.Format("2006-01-02") }
			</span>
			<div class="flex space-x-2">
				<button
					hx-get={ "/users/" + user.ID + "/edit" }
					hx-target="#modal-container"
					hx-swap="innerHTML"
					class="text-sm text-indigo-600 hover:text-indigo-800"
				>
					編輯
				</button>
				<button
					hx-delete={ "/users/" + user.ID }
					hx-target="closest div"
					hx-swap="outerHTML swap:0.3s"
					hx-confirm="確定要刪除此使用者嗎？"
					class="text-sm text-red-600 hover:text-red-800"
				>
					刪除
				</button>
			</div>
		</div>
	</div>
}

// UserList 使用者列表組件
templ UserList(users []User) {
	<div id="user-list" class="space-y-4">
		for _, user := range users {
			@UserCard(user)
		}
	</div>
}

// UserListPage 使用者列表頁面
templ UserListPage(users []User) {
	@Page(PageProps{
		Title:       "使用者管理 - ToolsKu",
		Description: "管理所有使用者",
		Content: userListContent(users),
	})
}

templ userListContent(users []User) {
	<div class="space-y-6">
		<div class="flex items-center justify-between">
			<h1 class="text-2xl font-bold text-gray-900">使用者管理</h1>
			<button
				hx-get="/users/new"
				hx-target="#modal-container"
				hx-swap="innerHTML"
				class="bg-indigo-600 text-white px-4 py-2 rounded-lg hover:bg-indigo-700 transition-colors"
			>
				新增使用者
			</button>
		</div>

		<!-- 搜尋欄 -->
		<div class="flex gap-4">
			<input
				type="text"
				name="q"
				placeholder="搜尋使用者..."
				hx-get="/users/search"
				hx-trigger="input changed delay:300ms"
				hx-target="#user-list"
				hx-swap="innerHTML"
				hx-indicator="#search-spinner"
				class="flex-1 rounded-lg border border-gray-300 px-4 py-2 focus:border-indigo-500 focus:ring-1 focus:ring-indigo-500"
			/>
			<div id="search-spinner" class="htmx-indicator">
				<svg class="animate-spin h-5 w-5 text-indigo-600" xmlns="http://www.w3.org/2000/svg" fill="none" viewBox="0 0 24 24">
					<circle class="opacity-25" cx="12" cy="12" r="10" stroke="currentColor" stroke-width="4"/>
					<path class="opacity-75" fill="currentColor" d="M4 12a8 8 0 018-8V0C5.373 0 0 5.373 0 12h4z"/>
				</svg>
			</div>
		</div>

		@UserList(users)
	</div>
}

關鍵要點：

Templ組件在編譯時生成Go代碼，型別錯誤在編譯階段就被捕獲
templ.KV()條件表達式替代模板中的if/else，保持模板簡潔
組件透過@ComponentName()語法組合，形成清晰的組件樹
HTMX屬性直接寫在HTML元素上，無需額外JavaScript

核心模式2：HTMX動態互動與局部更新

HTMX透過HTML屬性（hx-get、hx-post、hx-swap等）實現AJAX互動，服務端返回HTML片段替換頁面局部內容。這種模式讓Go後端完全掌控渲染邏輯，前端無需任何JavaScript框架。

// handlers/user_handler.go
package handlers

import (
	"net/http"
	"strings"

	"github.com/a-h/templ"
	"toolsku/components"
	"toolsku/repository"
)

// UserHandler 使用者相關HTTP處理器
type UserHandler struct {
	userRepo *repository.UserRepository
}

// NewUserHandler 創建UserHandler
func NewUserHandler(userRepo *repository.UserRepository) *UserHandler {
	return &UserHandler{userRepo: userRepo}
}

// List 顯示使用者列表頁面（完整頁面）
func (h *UserHandler) List(w http.ResponseWriter, r *http.Request) {
	users, err := h.userRepo.List(r.Context(), 20, 0)
	if err != nil {
		http.Error(w, err.Error(), http.StatusInternalServerError)
		return
	}

	// 檢查是否為HTMX請求（局部更新）
	if isHTMXRequest(r) {
		templ.Handler(components.UserList(users)).ServeHTTP(w, r)
		return
	}

	// 普通請求返回完整頁面
	templ.Handler(components.UserListPage(users)).ServeHTTP(w, r)
}

// Search 搜尋使用者（HTMX局部更新）
func (h *UserHandler) Search(w http.ResponseWriter, r *http.Request) {
	query := r.URL.Query().Get("q")

	var users []components.User
	var err error

	if query != "" {
		users, err = h.userRepo.Search(r.Context(), query)
	} else {
		users, err = h.userRepo.List(r.Context(), 20, 0)
	}

	if err != nil {
		http.Error(w, err.Error(), http.StatusInternalServerError)
		return
	}

	templ.Handler(components.UserList(users)).ServeHTTP(w, r)
}

// Create 創建使用者（HTMX表單提交）
func (h *UserHandler) Create(w http.ResponseWriter, r *http.Request) {
	if err := r.ParseForm(); err != nil {
		http.Error(w, err.Error(), http.StatusBadRequest)
		return
	}

	user := components.User{
		Name:  r.FormValue("name"),
		Email: r.FormValue("email"),
		Role:  r.FormValue("role"),
	}

	created, err := h.userRepo.Create(r.Context(), user)
	if err != nil {
		templ.Handler(components.ErrorAlert("創建使用者失敗: " + err.Error())).ServeHTTP(w, r)
		return
	}

	w.Header().Set("HX-Trigger", `{"userCreated": {"id": "`+created.ID+`"}}`)
	templ.Handler(components.UserCard(*created)).ServeHTTP(w, r)
}

// Delete 刪除使用者（HTMX刪除）
func (h *UserHandler) Delete(w http.ResponseWriter, r *http.Request) {
	userID := r.PathValue("id")

	if err := h.userRepo.Delete(r.Context(), userID); err != nil {
		w.WriteHeader(http.StatusInternalServerError)
		return
	}

	w.WriteHeader(http.StatusOK)
}

// EditForm 編輯使用者表單（HTMX模態框）
func (h *UserHandler) EditForm(w http.ResponseWriter, r *http.Request) {
	userID := r.PathValue("id")

	user, err := h.userRepo.Get(r.Context(), userID)
	if err != nil {
		http.Error(w, err.Error(), http.StatusNotFound)
		return
	}

	templ.Handler(components.UserEditModal(*user)).ServeHTTP(w, r)
}

// Update 更新使用者（HTMX表單提交）
func (h *UserHandler) Update(w http.ResponseWriter, r *http.Request) {
	userID := r.PathValue("id")

	if err := r.ParseForm(); err != nil {
		http.Error(w, err.Error(), http.StatusBadRequest)
		return
	}

	user, err := h.userRepo.Get(r.Context(), userID)
	if err != nil {
		http.Error(w, err.Error(), http.StatusNotFound)
		return
	}

	user.Name = r.FormValue("name")
	user.Email = r.FormValue("email")
	user.Role = r.FormValue("role")

	updated, err := h.userRepo.Update(r.Context(), *user)
	if err != nil {
		templ.Handler(components.ErrorAlert("更新使用者失敗: " + err.Error())).ServeHTTP(w, r)
		return
	}

	w.Header().Set("HX-Trigger", `{"userUpdated": {"id": "`+updated.ID+`"}}`)
	templ.Handler(components.UserCard(*updated)).ServeHTTP(w, r)
}

// isHTMXRequest 檢查是否為HTMX請求
func isHTMXRequest(r *http.Request) bool {
	return r.Header.Get("HX-Request") == "true"
}

關鍵要點：

isHTMXRequest()區分完整頁面請求和局部更新請求，同一Handler處理兩種場景
HTMX的hx-trigger事件響應（userCreated、userUpdated）實現跨組件通訊
hx-swap="outerHTML swap:0.3s"實現刪除動畫效果
hx-indicator顯示請求載入狀態，提升使用者體驗

核心模式3：Tailwind CSS原子化樣式整合

Tailwind CSS與Templ的整合非常自然——Templ生成純HTML，Tailwind處理純CSS類名。透過Tailwind的JIT編譯器，只打包使用到的樣式，最終CSS檔案極小。

/* assets/css/app.css - Tailwind入口檔案 */
@tailwind base;
@tailwind components;
@tailwind utilities;

/* 自定義組件樣式 */
@layer components {
	.btn-primary {
		@apply bg-indigo-600 text-white px-4 py-2 rounded-lg hover:bg-indigo-700
		transition-colors font-medium;
	}

	.btn-secondary {
		@apply bg-gray-100 text-gray-700 px-4 py-2 rounded-lg hover:bg-gray-200
		transition-colors font-medium;
	}

	.btn-danger {
		@apply bg-red-600 text-white px-4 py-2 rounded-lg hover:bg-red-700
		transition-colors font-medium;
	}

	.input-field {
		@apply w-full rounded-lg border border-gray-300 px-3 py-2
		focus:border-indigo-500 focus:ring-1 focus:ring-indigo-500
		placeholder-gray-400;
	}

	.card {
		@apply bg-white rounded-lg shadow-sm border border-gray-200 p-6
		hover:shadow-md transition-shadow;
	}
}

/* HTMX指示器樣式 */
.htmx-indicator {
	display: none;
}
.htmx-request .htmx-indicator {
	display: inline-block;
}
.htmx-request.htmx-indicator {
	display: inline-block;
}

/* HTMX過渡動畫 */
.htmx-swapping {
	opacity: 0;
	transition: opacity 0.3s ease-out;
}
.htmx-settling {
	opacity: 1;
	transition: opacity 0.3s ease-in;
}

// components/shared.templ - 可複用的樣式組件
package components

// BadgeProps 徽章屬性
type BadgeProps struct {
	Text  string
	Color string
}

// Badge 徽章組件
templ Badge(props BadgeProps) {
	<span class={ "px-2.5 py-0.5 rounded-full text-xs font-medium",
		badgeColorClass(props.Color) }>
		{ props.Text }
	</span>
}

func badgeColorClass(color string) string {
	colors := map[string]string{
		"red":    "bg-red-100 text-red-800",
		"green":  "bg-green-100 text-green-800",
		"blue":   "bg-blue-100 text-blue-800",
		"yellow": "bg-yellow-100 text-yellow-800",
		"gray":   "bg-gray-100 text-gray-800",
	}
	if c, ok := colors[color]; ok {
		return c
	}
	return colors["gray"]
}

// StatCard 統計卡片組件
templ StatCard(title string, value string, change string, changeType string) {
	<div class="card">
		<div class="flex items-center justify-between">
			<p class="text-sm font-medium text-gray-500">{ title }</p>
			if change != "" {
				<span class={ "text-xs font-medium px-2 py-0.5 rounded-full",
					templ.KV(changeType == "positive", "bg-green-100 text-green-800",
						templ.KV(changeType == "negative", "bg-red-100 text-red-800",
							"bg-gray-100 text-gray-800")) }>
					{ change }
				</span>
			}
		</div>
		<p class="mt-2 text-3xl font-bold text-gray-900">{ value }</p>
	</div>
}

// Pagination 分頁組件
templ Pagination(currentPage, totalPages int, baseURL string) {
	<div class="flex items-center justify-between mt-6">
		<p class="text-sm text-gray-500">
			第 { currentPage } 頁，共 { totalPages } 頁
		</p>
		<div class="flex space-x-2">
			if currentPage > 1 {
				<button
					hx-get={ baseURL + "?page=1" }
					hx-target="#content-area"
					hx-swap="innerHTML"
					class="btn-secondary text-sm"
				>
					首頁
				</button>
				<button
					hx-get={ fmt.Sprintf("%s?page=%d", baseURL, currentPage-1) }
					hx-target="#content-area"
					hx-swap="innerHTML"
					class="btn-secondary text-sm"
				>
					上一頁
				</button>
			}
			if currentPage < totalPages {
				<button
					hx-get={ fmt.Sprintf("%s?page=%d", baseURL, currentPage+1) }
					hx-target="#content-area"
					hx-swap="innerHTML"
					class="btn-primary text-sm"
				>
					下一頁
				</button>
			}
		</div>
	</div>
}

關鍵要點：

@layer components提取常用樣式組合為組件類，減少重複
HTMX指示器樣式（.htmx-indicator）確保載入狀態正確顯示
Go函式（badgeColorClass）處理動態樣式邏輯，比模板條件更清晰
templ.KV()巢狀實現多條件樣式選擇

核心模式4：表單處理與驗證回饋

表單是Web應用的核心互動。Templ + HTMX的組合讓表單處理變得極其簡潔：服務端驗證、即時回饋、無刷新提交，全部透過HTML屬性和Go代碼實現。

// components/form.templ
package components

// UserFormProps 使用者表單屬性
type UserFormProps struct {
	User      User
	Errors    map[string]string
	IsEditing bool
}

// UserForm 使用者創建/編輯表單
templ UserForm(props UserFormProps) {
	<form
		if props.IsEditing {
			hx-put={ "/users/" + props.User.ID }
		} else {
			hx-post="/users"
		}
		hx-target="#form-container"
		hx-swap="innerHTML"
		hx-indicator="#form-spinner"
		class="space-y-6"
	>
		<!-- 姓名欄位 -->
		<div>
			<label for="name" class="block text-sm font-medium text-gray-700 mb-1">
				姓名 <span class="text-red-500">*</span>
			</label>
			<input
				type="text"
				id="name"
				name="name"
				value={ props.User.Name }
				required
				hx-post="/users/validate"
				hx-trigger="change"
				hx-target="#name-error"
				hx-swap="innerHTML"
				class={ "input-field",
					templ.KV(hasError(props.Errors, "name"), "border-red-500 focus:border-red-500 focus:ring-red-500") }
			/>
			if err, ok := props.Errors["name"]; ok {
				<p id="name-error" class="mt-1 text-sm text-red-600">{ err }</p>
			} else {
				<p id="name-error" class="mt-1 text-sm text-red-600"></p>
			}
		</div>

		<!-- 電子郵件欄位 -->
		<div>
			<label for="email" class="block text-sm font-medium text-gray-700 mb-1">
				電子郵件 <span class="text-red-500">*</span>
			</label>
			<input
				type="email"
				id="email"
				name="email"
				value={ props.User.Email }
				required
				hx-post="/users/validate"
				hx-trigger="change"
				hx-target="#email-error"
				hx-swap="innerHTML"
				class={ "input-field",
					templ.KV(hasError(props.Errors, "email"), "border-red-500 focus:border-red-500 focus:ring-red-500") }
			/>
			if err, ok := props.Errors["email"]; ok {
				<p id="email-error" class="mt-1 text-sm text-red-600">{ err }</p>
			} else {
				<p id="email-error" class="mt-1 text-sm text-red-600"></p>
			}
		</div>

		<!-- 提交按鈕 -->
		<div class="flex items-center space-x-3">
			<button type="submit" class="btn-primary flex items-center space-x-2">
				<span if={ props.IsEditing }>更新使用者</span>
				<span if={ !props.IsEditing }>創建使用者</span>
				<div id="form-spinner" class="htmx-indicator">
					<svg class="animate-spin h-4 w-4" xmlns="http://www.w3.org/2000/svg" fill="none" viewBox="0 0 24 24">
						<circle class="opacity-25" cx="12" cy="12" r="10" stroke="currentColor" stroke-width="4"/>
						<path class="opacity-75" fill="currentColor" d="M4 12a8 8 0 018-8V0C5.373 0 0 5.373 0 12h4z"/>
					</svg>
				</div>
			</button>
			<a href="/users" class="btn-secondary inline-block">取消</a>
		</div>
	</form>
}

func hasError(errors map[string]string, field string) bool {
	_, ok := errors[field]
	return ok
}

// handlers/validation_handler.go
package handlers

import (
	"net/http"
	"net/mail"
	"strings"

	"github.com/a-h/templ"
	"toolsku/components"
)

// Validator 表單驗證器
type Validator struct {
	Errors map[string]string
}

func NewValidator() *Validator {
	return &Validator{Errors: make(map[string]string)}
}

func (v *Validator) ValidateField(field, value string, rules ...func(string) string) {
	for _, rule := range rules {
		if msg := rule(value); msg != "" {
			v.Errors[field] = msg
			return
		}
	}
}

func Required(field string) func(string) string {
	return func(value string) string {
		if strings.TrimSpace(value) == "" {
			return field + "不能為空"
		}
		return ""
	}
}

func EmailFormat() func(string) string {
	return func(value string) string {
		if _, err := mail.ParseAddress(value); err != nil {
			return "電子郵件格式不正確"
		}
		return ""
	}
}

func MinLength(min int) func(string) string {
	return func(value string) string {
		if len(value) < min {
			return fmt.Sprintf("長度不能少於%d個字元", min)
		}
		return ""
	}
}

// ValidateField 即時欄位驗證（HTMX）
func (h *UserHandler) ValidateField(w http.ResponseWriter, r *http.Request) {
	if err := r.ParseForm(); err != nil {
		return
	}

	validator := NewValidator()

	if name := r.FormValue("name"); name != "" {
		validator.ValidateField("name", name, Required("姓名"), MinLength(2))
	}

	if email := r.FormValue("email"); email != "" {
		validator.ValidateField("email", email, Required("電子郵件"), EmailFormat())
	}

	for field, msg := range validator.Errors {
		templ.Handler(components.FieldError(field, msg)).ServeHTTP(w, r)
		return
	}

	w.WriteHeader(http.StatusOK)
}

關鍵要點：

hx-trigger="change"實現欄位級即時驗證，無需等待表單提交
驗證器模式（Required、EmailFormat、MinLength）可組合複用
錯誤訊息透過HTMX局部更新顯示在對應欄位下方
templ.KV()根據錯誤狀態動態切換輸入框邊框顏色

核心模式5：全棧CRUD應用完整實現

將前4個模式整合為一個完整的CRUD應用，包含路由註冊、中介軟體、資料庫操作、錯誤處理等生產級要素。

// main.go - 完整應用入口
package main

import (
	"context"
	"database/sql"
	"fmt"
	"log"
	"net/http"
	"os"
	"os/signal"
	"syscall"
	"time"

	_ "github.com/lib/pq"
	"toolsku/handlers"
	"toolsku/repository"
)

func main() {
	db, err := sql.Open("postgres", os.Getenv("DATABASE_URL"))
	if err != nil {
		log.Fatalf("connect database: %v", err)
	}
	defer db.Close()

	if err := db.Ping(); err != nil {
		log.Fatalf("ping database: %v", err)
	}

	userRepo := repository.NewUserRepository(db)
	userHandler := handlers.NewUserHandler(userRepo)

	mux := http.NewServeMux()

	mux.Handle("/assets/", http.StripPrefix("/assets/", http.FileServer(http.Dir("assets"))))

	mux.HandleFunc("GET /users", userHandler.List)
	mux.HandleFunc("GET /users/search", userHandler.Search)
	mux.HandleFunc("GET /users/new", userHandler.NewForm)
	mux.HandleFunc("POST /users", userHandler.Create)
	mux.HandleFunc("GET /users/{id}/edit", userHandler.EditForm)
	mux.HandleFunc("PUT /users/{id}", userHandler.Update)
	mux.HandleFunc("DELETE /users/{id}", userHandler.Delete)
	mux.HandleFunc("POST /users/validate", userHandler.ValidateField)

	mux.HandleFunc("GET /", func(w http.ResponseWriter, r *http.Request) {
		http.Redirect(w, r, "/users", http.StatusFound)
	})

	var handler http.Handler = mux
	handler = middlewareLogging(handler)
	handler = middlewareRecovery(handler)
	handler = middlewareCORS(handler)

	server := &http.Server{
		Addr:         ":8080",
		Handler:      handler,
		ReadTimeout:  10 * time.Second,
		WriteTimeout: 30 * time.Second,
		IdleTimeout:  60 * time.Second,
	}

	go func() {
		sigCh := make(chan os.Signal, 1)
		signal.Notify(sigCh, syscall.SIGINT, syscall.SIGTERM)
		<-sigCh

		ctx, cancel := context.WithTimeout(context.Background(), 10*time.Second)
		defer cancel()

		log.Println("shutting down server...")
		server.Shutdown(ctx)
	}()

	log.Printf("server starting on %s", server.Addr)
	if err := server.ListenAndServe(); err != http.ErrServerClosed {
		log.Fatalf("server error: %v", err)
	}
}

func middlewareLogging(next http.Handler) http.Handler {
	return http.HandlerFunc(func(w http.ResponseWriter, r *http.Request) {
		start := time.Now()
		next.ServeHTTP(w, r)
		log.Printf("%s %s %s %v", r.Method, r.URL.Path, r.RemoteAddr, time.Since(start))
	})
}

func middlewareRecovery(next http.Handler) http.Handler {
	return http.HandlerFunc(func(w http.ResponseWriter, r *http.Request) {
		defer func() {
			if err := recover(); err != nil {
				log.Printf("panic recovered: %v", err)
				http.Error(w, "Internal Server Error", http.StatusInternalServerError)
			}
		}()
		next.ServeHTTP(w, r)
	})
}

func middlewareCORS(next http.Handler) http.Handler {
	return http.HandlerFunc(func(w http.ResponseWriter, r *http.Request) {
		w.Header().Set("Access-Control-Allow-Origin", "*")
		w.Header().Set("Access-Control-Allow-Methods", "GET, POST, PUT, DELETE, OPTIONS")
		w.Header().Set("Access-Control-Allow-Headers", "Content-Type, HX-Request, HX-Target, HX-Trigger")
		if r.Method == http.MethodOptions {
			w.WriteHeader(http.StatusOK)
			return
		}
		next.ServeHTTP(w, r)
	})
}

// repository/user_repository.go - 資料庫操作層
package repository

import (
	"context"
	"database/sql"
	"fmt"
	"strings"

	"toolsku/components"
)

type UserRepository struct {
	db *sql.DB
}

func NewUserRepository(db *sql.DB) *UserRepository {
	return &UserRepository{db: db}
}

func (r *UserRepository) List(ctx context.Context, limit, offset int) ([]components.User, error) {
	rows, err := r.db.QueryContext(ctx,
		`SELECT id, name, email, role, created_at, avatar_url
		 FROM users ORDER BY created_at DESC LIMIT $1 OFFSET $2`,
		limit, offset,
	)
	if err != nil {
		return nil, fmt.Errorf("query users: %w", err)
	}
	defer rows.Close()

	var users []components.User
	for rows.Next() {
		var u components.User
		if err := rows.Scan(&u.ID, &u.Name, &u.Email, &u.Role, &u.CreatedAt, &u.AvatarURL); err != nil {
			return nil, fmt.Errorf("scan user: %w", err)
		}
		users = append(users, u)
	}

	return users, rows.Err()
}

func (r *UserRepository) Search(ctx context.Context, query string) ([]components.User, error) {
	pattern := "%" + strings.ToLower(query) + "%"
	rows, err := r.db.QueryContext(ctx,
		`SELECT id, name, email, role, created_at, avatar_url
		 FROM users WHERE LOWER(name) LIKE $1 OR LOWER(email) LIKE $2
		 ORDER BY created_at DESC LIMIT 20`,
		pattern, pattern,
	)
	if err != nil {
		return nil, fmt.Errorf("search users: %w", err)
	}
	defer rows.Close()

	var users []components.User
	for rows.Next() {
		var u components.User
		if err := rows.Scan(&u.ID, &u.Name, &u.Email, &u.Role, &u.CreatedAt, &u.AvatarURL); err != nil {
			return nil, fmt.Errorf("scan user: %w", err)
		}
		users = append(users, u)
	}

	return users, rows.Err()
}

func (r *UserRepository) Get(ctx context.Context, id string) (*components.User, error) {
	var u components.User
	err := r.db.QueryRowContext(ctx,
		`SELECT id, name, email, role, created_at, avatar_url
		 FROM users WHERE id = $1`, id,
	).Scan(&u.ID, &u.Name, &u.Email, &u.Role, &u.CreatedAt, &u.AvatarURL)

	if err == sql.ErrNoRows {
		return nil, fmt.Errorf("user not found: %s", id)
	}
	if err != nil {
		return nil, fmt.Errorf("get user: %w", err)
	}
	return &u, nil
}

func (r *UserRepository) Create(ctx context.Context, user components.User) (*components.User, error) {
	var created components.User
	err := r.db.QueryRowContext(ctx,
		`INSERT INTO users (name, email, role, avatar_url)
		 VALUES ($1, $2, $3, $4)
		 RETURNING id, name, email, role, created_at, avatar_url`,
		user.Name, user.Email, user.Role, user.AvatarURL,
	).Scan(&created.ID, &created.Name, &created.Email, &created.Role, &created.CreatedAt, &created.AvatarURL)

	if err != nil {
		return nil, fmt.Errorf("create user: %w", err)
	}
	return &created, nil
}

func (r *UserRepository) Update(ctx context.Context, user components.User) (*components.User, error) {
	var updated components.User
	err := r.db.QueryRowContext(ctx,
		`UPDATE users SET name = $1, email = $2, role = $3
		 WHERE id = $4
		 RETURNING id, name, email, role, created_at, avatar_url`,
		user.Name, user.Email, user.Role, user.ID,
	).Scan(&updated.ID, &updated.Name, &updated.Email, &updated.Role, &updated.CreatedAt, &updated.AvatarURL)

	if err != nil {
		return nil, fmt.Errorf("update user: %w", err)
	}
	return &updated, nil
}

func (r *UserRepository) Delete(ctx context.Context, id string) error {
	result, err := r.db.ExecContext(ctx, `DELETE FROM users WHERE id = $1`, id)
	if err != nil {
		return fmt.Errorf("delete user: %w", err)
	}
	if n, _ := result.RowsAffected(); n == 0 {
		return fmt.Errorf("user not found: %s", id)
	}
	return nil
}

關鍵要點：

Go 1.22增強路由模式（GET /users/{id}）替代第三方路由庫
中介軟體鏈處理日誌、panic恢復、CORS等橫切關注點
Repository模式封裝資料庫操作，Handler只關心HTTP邏輯
HTMX請求與普通請求共用同一Handler，透過isHTMXRequest()區分響應

常見陷阱

陷阱1：Templ組件中忘記轉義使用者輸入

// ❌ 錯誤：直接輸出使用者輸入，XSS風險
templ UnsafeOutput(content string) {
	<div>{ content }</div>
}

// ✅ 正確：Templ預設對所有字串進行HTML轉義，無需額外處理
templ SafeOutput(content string) {
	<div>{ content }</div>  // Templ自動轉義
}

// 如果確實需要輸出原始HTML，使用templ.Raw
templ RawHTML(html string) {
	<div>{ templ.Raw(html) }</div>  // 僅在可信內容時使用
}

陷阱2：HTMX請求返回完整頁面

// ❌ 錯誤：HTMX請求也返回完整頁面，浪費頻寬
func (h *UserHandler) List(w http.ResponseWriter, r *http.Request) {
	users, _ := h.userRepo.List(r.Context(), 20, 0)
	templ.Handler(components.UserListPage(users)).ServeHTTP(w, r)
}

// ✅ 正確：區分HTMX請求和普通請求
func (h *UserHandler) List(w http.ResponseWriter, r *http.Request) {
	users, _ := h.userRepo.List(r.Context(), 20, 0)
	if isHTMXRequest(r) {
		templ.Handler(components.UserList(users)).ServeHTTP(w, r)
		return
	}
	templ.Handler(components.UserListPage(users)).ServeHTTP(w, r)
}

陷阱3：Tailwind類名拼接導致JIT無法識別

// ❌ 錯誤：動態拼接Tailwind類名，JIT編譯器無法識別
templ DynamicClass(color string) {
	<div class={ "bg-" + color + "-500 text-white" }>內容</div>
}

// ✅ 正確：使用完整類名，確保JIT能識別
templ CorrectClass(color string) {
	<div class={ badgeColorClass(color) }>內容</div>
}

func badgeColorClass(color string) string {
	switch color {
	case "red":
		return "bg-red-500 text-white"
	case "green":
		return "bg-green-500 text-white"
	default:
		return "bg-gray-500 text-white"
	}
}

陷阱4：HTMX事件未正確觸發

// ❌ 錯誤：HX-Trigger頭格式不正確
w.Header().Set("HX-Trigger", "userCreated")

// ✅ 正確：使用JSON格式傳遞事件資料
w.Header().Set("HX-Trigger", `{"userCreated": {"id": "123"}}`)

陷阱5：Templ生成代碼未納入構建流程

# ❌ 錯誤：忘記運行templ generate，導致Go編譯失敗
go build -o app .

# ✅ 正確：先生成Templ代碼再編譯
templ generate && go build -o app .

錯誤排查

錯誤現象	可能原因	排查方法	解決方案
Templ編譯失敗	語法錯誤或型別不匹配	檢查`templ generate`輸出	修復模板語法和型別
HTMX請求無回應	未正確設置hx-target	檢查瀏覽器網路請求	確認target元素ID存在
Tailwind樣式缺失	JIT未掃描到類名	檢查content配置	確保templ檔案在掃描路徑中
表單提交404	路由未註冊	檢查mux註冊路徑	確認HTTP方法匹配
模態框不關閉	缺少關閉邏輯	檢查HTMX響應頭	添加HX-Trigger關閉事件
搜尋延遲明顯	未設置debounce	檢查hx-trigger配置	添加`delay:300ms`
刪除動畫不生效	hx-swap配置錯誤	檢查swap參數	使用`outerHTML swap:0.3s`
CSS檔案過大	未啟用minify	檢查構建命令	添加`--minify`參數
頁面閃爍	HTMX載入時內容跳動	檢查indicator樣式	添加htmx-indicator
驗證不觸發	hx-trigger配置錯誤	檢查trigger事件名	使用`change`或`input`

進階優化

1. Templ代碼熱重載

使用air或cosmtrek/air實現Go代碼熱重載，配合templ generate --watch實現模板熱更新，開發體驗媲美前端HMR。

2. HTMX擴展整合

利用HTMX擴展（response-targets、loading-states、path-params）增強互動能力，實現更複雜的UI模式如無限滾動、拖拽排序等。

3. 組件快取與串流渲染

對靜態組件使用templ.Handler快取渲染結果，對長列表使用templ.Handler串流輸出HTML片段，提升首屏渲染速度。

4. 漸進增強策略

為HTMX互動添加noscript回退，確保JavaScript禁用時應用仍可正常使用。表單使用標準action屬性，HTMX增強覆蓋。

5. 構建優化與部署

使用esbuild打包少量客戶端JavaScript（如Alpine.js），Go編譯為單一二進位檔案，Docker多階段構建最小化映像體積。

對比

維度	Templ+HTMX+Tailwind	React+Next.js	Vue+Nuxt
語言統一性	✅ 全棧Go	❌ Go+TypeScript	❌ Go+TypeScript
型別安全	✅ 編譯時檢查	✅ TypeScript	✅ TypeScript
首屏效能	✅ 服務端渲染	⚠️ 需優化SSR	⚠️ 需優化SSR
互動複雜度	⚠️ 中等	✅ 複雜互動	✅ 複雜互動
構建複雜度	✅ 極簡	❌ 複雜	❌ 複雜
學習曲線	✅ 低	❌ 高	⚠️ 中
SEO友好	✅ 服務端渲染	✅ SSR支持	✅ SSR支持
包體積	✅ 極小	❌ 較大	⚠️ 中等
生態豐富度	⚠️ 成長中	✅ 非常豐富	✅ 豐富

總結

Templ + HTMX + Tailwind不是要替代React或Vue，而是為那些不需要複雜前端互動的應用提供了一種更簡單的選擇。當你的應用以CRUD為主、互動以表單和列表為主、團隊以Go開發者為主時，這套方案能讓你用最少的代碼、最少的依賴、最少的構建步驟，構建出效能卓越的現代Web應用。少即是多，這不僅是設計哲學，也是工程哲學。

線上工具推薦

JSON格式化 — 格式化API回應JSON，快速驗證Templ組件資料
cURL轉代碼 — 將cURL命令轉為Go HTTP代碼，快速測試HTMX端點
哈希計算 — 計算使用者ID哈希值，用於頭像URL生成和資料脫敏