Шаблоны HTML

Пока наш трекер отвечал только JSON: Envelope для API, NOT_FOUND для промахов, статика из прошлого урока обслуживала файлы, но не страницы. Пришло время gin шаблонов — серверного HTML, который собирается на лету из данных. Сценарий знакомый: страница со списком задач, где каждая строка приходит из хендлера, а разметка живёт в отдельном файле. Gin не пишет свой шаблонизатор — он оборачивает html/template из стандартной библиотеки, тот самый, с auto-escaping: любая строка из данных вставляется в разметку безопасно, теги и скрипты экранируются автоматически. Если вы уже работали с html/template — всё знакомо; если нет — разберём по ходу, для gin-специфики достаточно трёх действий. Первое: загрузить шаблоны один раз при старте — LoadHTMLGlob или LoadHTMLFiles. Второе: отдавать страницы через c.HTML(код, имя, данные) — собрат c.JSON, который вместо конверта рендерит файл. Третье: при необходимости зарегистрировать свои функции шаблонов через SetFuncMap — даты, плюрализация, любые преобразования прямо в разметке. Архитектурно это выглядит так: хендлеры /api/v1/todos продолжают отдавать JSON из прошлого урока, а новые маршруты — /, /tasks, /tasks/:id — рендерят страницы. Один движок, два формата: JSON для машин, HTML для людей — и вся связка html gin держится на трёх действиях из начала урока. В этом уроке мы соберём страницу трекера на gin.H и структуре, разберём экранирование на живом примере, подключим кастомные функции и раскладки, а на выходе получим приложение, у которого есть и API, и интерфейс.

Заглянем в gin.go — там два метода, и они ближе к стандартной библиотеке, чем кажется. LoadHTMLGlob(pattern) делает ровно одно: template.Must(template.New("").Delims(...).Funcs(engine.FuncMap).ParseGlob(pattern)) — это чистый html/template: ParseGlob находит файлы по маске через filepath.Glob и парсит каждый, а template.Must паникует, если файл не читается или разметка битая. То есть опечатка в шаблоне роняет приложение на старте, до первого запроса — и это хорошо: битая разметка должна ловиться при запуске, а не в проде у пользователя. Имена шаблонов — базовые имена файлов: templates/index.html становится index.html, и c.HTML ищет именно по этому имени. LoadHTMLFiles делает то же самое по явному списку: r.LoadHTMLFiles("templates/index.html", "templates/form.html") — удобно, когда каталог замусорен частями, которые не должны попадать в набор. Раскладки и подпапки требуют блока define: маска templates/ не заходит в подкаталоги, а маска templates// (две звёздочки в filepath.Glob — это просто один уровень) собирает файлы из подпапок, но тогда каждое имя объявляют вручную: {{ define "posts/index.html" }} в начале файла и соответствующее имя в c.HTML — так делают в официальных примерах gin. Теперь главное, что почти все упускают: результат парсинга зависит от gin.Mode(). В release-режиме отрендеренный набор кладётся в HTMLProduction — один раз спарсенный, навсегда закэшированный. А в debug-режиме — режиме по умолчанию — gin ставит HTMLDebug, который перечитывает и перепарсивает шаблоны на каждый запрос: правка файла видна по F5, без перезапуска. Это удобно в разработке и незаметно дорого в бою: перепарс на каждый запрос плюс паники template.Must уже внутри обслуживания. Отсюда правило: gin.SetMode(gin.ReleaseMode) перед LoadHTMLGlob в проде — и шаблоны спарсятся ровно один раз.

Данные в шаблон попадают любым значением — c.HTML принимает any. Для быстрого прототипа используют gin.H — это псевдоним map[string]any, тот же тип, что и в c.JSON: gin.H{"title": "Задачи", "tasks": tasks} — и точка в разметке ходит по ключам карты. Для боевого кода лучше структуры: поля типизированы, поля подсказывают в IDE, а json-теги, которые мы расставляли в уроке про привязку, работают и здесь — только в шаблонах тегом по умолчанию считается form, а имена полей html/template берёт по-другому. Ключевое правило: шаблон видит только экспортированные поля. Структура Todo с полем title (со строчной) отдаст пустоту — интерполяция {{ .title }} или {{ .Title }} вернёт нулевое значение; с полем Title — всё отрисуется. Методы тоже работают, если они экспортированы: {{ .DueFmt }} вызовет метод с таким именем — это законный способ класть вычисления рядом с данными вместо размножения функций. А вот экранирование — главная причина, почему html/template, а не text/template. Контекстный анализатор понимает, где именно вставляется значение: в HTML-тексте экранирует &lt;b&gt;, в атрибуте — кавычки, в JavaScript-блоке — спецсимволы строк, в URL — пробелы и кавычки. Практический тест: передайте в title строку с <script>alert(1)</script> — на странице отобразится текстом ровно то, что ввёл пользователь, а в HTML-исходнике будут экранированные сущности. XSS-векторы через данные гибнут на ровном месте. Побег есть всегда — кроме одного: значение типа template.HTML html/template вставит как есть, без экранирования, потому что вы явно заявили «это уже HTML». Такой тип — осознанный костыль для заранее sanitized-контента; если он добирается до шаблона из пользовательского ввода, вы только что собрали XSS своими руками, поэтому держите template.HTML подальше от форм.

Рано или поздно разметке нужны вычисления: дата в человеческом формате, правильная форма слова «задача/задачи/задач», цена с копейками, урезанный текст. В html/template это решается функциями: FuncMap — карта имя-функция, и шаблон вызывает их как {{ fmtDate .Due }}. В gin за это отвечает r.SetFuncMap(template.FuncMap{...}) — метод движка, который кладёт карту в engine.FuncMap, и дальше её подхватывают оба загрузчика. Обратите внимание на порядок — это самая частая ошибка темы: SetFuncMap должен быть вызван до LoadHTMLGlob и LoadHTMLFiles. Причина в механике парсинга: при разборе шаблона имена функций фиксируются, и если функции ещё не зарегистрированы, ParseGlob упадёт с «function "fmtDate" not defined» — template.Must превратит это в панику на старте. Зарегистрируете после — та же паника, только в запутанной формулировке; держите SetFuncMap первой строкой после gin.Default() и не отделяйте его от загрузки шаблонов. Что класть в карту: функции чистые, быстрые и про представление — форматирование дат через t.Format, плюрализация по правилам русского языка (n%10, группы исключений), обрезка строк с многоточием, экранирование уже не нужно — оно контекстное. Что класть не стоит: обращения к базе и любые I/O — шаблон должен собирать строку из готовых данных, а не ходить за ними; готовьте значения в хендлере или сервисном слое. Функции в карте типизированы по-обычному: fmtDate func(time.Time) string, plural func(int, string) string — компилятор проверит сигнатуры, а шаблон просто вызовет по имени.

Штатные разделители {{ }} — источник конфликтов с фронтенд-шаблонизаторами. Vue, Alpine.js и целый зоопарк мини-фреймворков используют те же двойные фигурные: страница собирается на сервере gin-ом, а затем «оживает» на клиенте, и обе машины претендуют на одни скобки. Реакция предсказуема: Vue выдернет из {{ .title }} значение, получит пустую строку и швырнёт warning в консоль, а ваша серверная интерполяция окажется съеденной. Решение в gin — r.Delims("[[", "]]"): метод движка меняет разделители для всех загружаемых после него шаблонов, и в разметке пишете [[ .title ]]. Обратите внимание на два требования. Первое: Delims тоже до загрузки — парсер расставляет границы по разделителям, менять их после ParseGlob поздно. Второе: возвращаемое значение — Engine, метод цепочный: r.Delims("[[", "]]").LoadHTMLGlob("templates/") — хотя читается такая цепочка тяжеловато, лучше отдельной строкой. Бэкенд и фронтенд расходятся по зонам: серверные интерполяции в [[ ]], клиентские {{ }} остаются Vue — конфликт снят без escaping-танцев. Из той же серии — точечная гигиена: если скобки нужны в тексте как литералы (фрагменты кода в статье, документация по шаблонам), вынесите их в данные и вставляйте значением — или используйте пользовательские функции, возвращающие нужный текст. И помните про predict ниже: смена Delims делает старый синтаксис просто текстом, и никакой ошибки парсинга не случится — файл с {{ .title }} при Delims("[[", "]]") спарсится тихо, а на странице отобразится фигурная запись дословно. Проверяйте визуально после миграции, а не по логам.

Одна страница — редкость; хочется общего каркаса: head с stylesheet, шапка с навигацией, подвал. В html/template это делается блоками define и template, и gin здесь не добавляет ничего — это чистая стандартная библиотека. Блок {{ define "head" }}...{{ end }} объявляет именованный фрагмент внутри файла, а {{ template "head" . }} вставляет его в точке вызова, передавая те же данные — точка в конце не опечатка, это передача контекста. Классическая раскладка: layout.html держит каркас с двумя template-вставками — head и footer, — а page-файлы объявляют эти блоки своим содержимым. Порядок загрузки в gin: LoadHTMLGlob("templates/*") соберёт все файлы в один набор, и имена блоков станут общими для набора — template ищет блок по имени во всём наборе, а не только в своём файле. Отсюда следствие, которое стоит проговорить: имена define уникальны в рамках набора — два файла с {{ define "head" }} перезапишут друг друга без предупреждений; добавьте зону в имя: {{ define "site/head" }}, {{ define "admin/head" }}. Для вложенных страниц из подпапок действует правило из прошлого блока: {{ define "posts/index.html" }} и c.HTML с тем же именем — маска с двумя звёздочками собирает подпапки, define даёт им предсказуемые имена. И тонкость передачи данных: {{ template "head" . }} передаёт весь контекст, а {{ template "head" .Title }} — только значение; внутри блока точка уже будет строкой, а не картой. Это удобно для узких фрагментов, но ловит на рефакторинге: поменяли контекст — блоки молча отрисуют пустоту. Держите передачу контекста явной и одинаковой во всех раскладках проекта.

Загрузчики gin дают один набор шаблонов на приложение — и этого хватает, пока все страницы живут в общем каркасе. Как только появляются принципиально разные раскладки — админка с боковой панелью и публичные страницы с меню, письмо-шаблон, лендинг, — наборный подход трещит: имена define расползаются, общий head переопределяется, layout-логика превращается в условия. Официальное решение — HTMLRender интерфейс: у движка есть поле HTMLRender с методом Instance(name string, data any) Render, и c.HTML просто делегирует ему. Подмените HTMLRender — и c.HTML начнёт отдавать то, что вы решите. Пакет gin-contrib/multitemplate делает подмену за вас: multitemplate.NewRenderer() создаёт рендерер, методы AddFromFiles и AddFromGlob регистрируют именованные наборы — каждый со своим каркасом и своими файлами, — а присвоение r.HTMLRender = renderer включает его. Дальше c.HTML(http.StatusOK, "user", data) рендерит набор user с раскладкой пользователя, c.HTML(..., "admin", data) — набор admin с панелью администратора; JSON-API это не трогает. Собирайте рендерер фабричной функцией — createRender() — и передавайте движку до старта: HTMLRender назначается один раз, как и FuncMap. Плата очевидна и мала: каждый набор парсится отдельно, дубли общих фрагментов можно разрулить общими define-блоками с зональными именами. Альтернатива без внешнего пакета — свой тип с тем же методом Instance поверх html/template: интерфейс крошечный, а понимание, что за ним стоит, у вас теперь есть. В трекере multitemplate закрывает ровно одну развилку — публичная страница и будущая админка — но решает её чисто, без условий в разметке.

Теперь у трекера два лица, и стоит зафиксировать критерий выбора. JSON — когда потребителя нельзя предсказать: мобильное приложение, чужой скрипт, публичный API; контракт из урока про ответы — Envelope с полем Error — остаётся сетевым стандартом проекта. HTML — когда потребитель человек и SEO важнее интерактивности: публичные страницы, документация, панель со списком задач — серверный рендер даёт готовую разметку без ожидания и запросов данных с клиента, а поисковик индексирует её без выкручиваний. Смешивать — нормально и типично: страницы рендерятся на /, /tasks и /tasks/:id через c.HTML, а под группой /api/v1 живут JSON-эндпоинты того же трекера — группы маршрутов из прошлого урока как раз разводят эти зоны, и middleware на группе API не мешает страницам. Опасная зона одна: не начинайте выдавать HTML за JSON-клиента. У API нет шаблонов: если фронтенд — SPA на webpack/vite, ваши c.HTML-страницы никому не нужны, а полноценный HTML-слой удвоит работу. Признак, что серверный рендер вам показан: ссылки должны открываться с нуля, поиск должен видеть контент, интерактив минимален. Признак против: страница — это приложение с состоянием, список фильтруется без перезагрузки, офлайн-режим. В учебном трекере скучно ни то ни другое, поэтому берём обе стороны: страница списка — HTML, операции — JSON. Так проект честно упражняет оба режима ответа, и на собеседовании вы не будете делать вид, что «HTML для веба не нужен».