187 lines
7.5 KiB
Markdown
187 lines
7.5 KiB
Markdown
# Встраиваем веб-GUI в консольную утилиту: практический гайд
|
||
|
||
```metadata
|
||
id: 10
|
||
readTime: 15-20 минут
|
||
date: 2025-09-10 18:00
|
||
author: Direct-Dev (aka Антон Кузнецов)
|
||
level: Средний
|
||
tags: #go #angular #spa #embed #static #cli #webui #devops
|
||
version: 1.0.0
|
||
```
|
||
|
||
## Содержание
|
||
|
||
- [Встраиваем веб-GUI в консольную утилиту: практический гайд](#встраиваем-веб-gui-в-консольную-утилиту-практический-гайд)
|
||
- [Содержание](#содержание)
|
||
- [Введение](#введение)
|
||
- [Идея и архитектура](#идея-и-архитектура)
|
||
- [Минимальный GUI](#минимальный-gui)
|
||
- [Сборка фронтенда](#сборка-фронтенда)
|
||
- [Встраивание в Go-сервис](#встраивание-в-go-сервис)
|
||
- [API: контракт и примеры](#api-контракт-и-примеры)
|
||
- [Запуск и проверка](#запуск-и-проверка)
|
||
- [FAQ и типичные ошибки](#faq-и-типичные-ошибки)
|
||
|
||
## Введение
|
||
|
||
Задача: добавить простой веб-интерфейс к консольной утилите, собрать его один раз и отдавать статические файлы прямо из бинарника или из каталога рядом. В качестве примера используем минимальный UI со следующими полями:
|
||
|
||
- Targets (строка вида `tcp:host:port;udp:host:port...`)
|
||
- Delay (например `1s`)
|
||
- Флаг Wait connection
|
||
- Кнопка Execute
|
||
|
||
## Идея и архитектура
|
||
|
||
- **Фронтенд (Angular SPA)** собирается в статический набор файлов (`index.html`, `main-*.js`, `styles-*.css`, и т.д.).
|
||
- **Бэкенд (Go, Gin/Chi/Stdlib)** отдаёт эти файлы по `/` и реализует API по `/api/...`.
|
||
- Раздача статики может быть:
|
||
- из файловой системы (проще для разработки);
|
||
- через `embed.FS` (удобно для единого бинарника).
|
||
|
||
## Минимальный GUI
|
||
|
||
Мы упростили компонент до минимума в ветке `for-article`. Основной экран — одна форма и кнопка запуска.
|
||
|
||
Ключевой шаблон компонента:
|
||
|
||
```12:60:/home/su/projects/articles/embed-gui-article/ui/src/app/knock/knock-page.component.html
|
||
<div class="container">
|
||
<p-card header="Port Knocker (Минимальный UI)">
|
||
<form [formGroup]="form" (ngSubmit)="execute()" class="p-fluid">
|
||
<div class="grid">
|
||
<div class="col-12">
|
||
<label>Targets</label>
|
||
<input pInputText type="text" formControlName="targets" placeholder="tcp:host:port;udp:host:port" class="w-full" />
|
||
</div>
|
||
<div class="col-12 md:col-6">
|
||
<label>Delay</label>
|
||
<input pInputText type="text" formControlName="delay" placeholder="1s" class="w-full" />
|
||
</div>
|
||
<div class="col-12 md:col-6 flex align-items-center gap-2">
|
||
<p-checkbox formControlName="waitConnection" [binary]="true"></p-checkbox>
|
||
<label class="checkbox-label">Wait connection</label>
|
||
</div>
|
||
<div class="col-12">
|
||
<button pButton type="submit" label="Execute" class="w-full" [loading]="executing" [disabled]="executing || form.invalid"></button>
|
||
</div>
|
||
</div>
|
||
</form>
|
||
</p-card>
|
||
</div>
|
||
```
|
||
|
||
Логика отправки запроса:
|
||
|
||
```1:40:/home/su/projects/articles/embed-gui-article/ui/src/app/knock/knock-page.component.ts
|
||
this.http.post('/api/v1/knock-actions/execute', {
|
||
targets: v.targets,
|
||
delay: v.delay,
|
||
waitConnection: v.waitConnection
|
||
}).subscribe(...)
|
||
```
|
||
|
||
## Сборка фронтенда
|
||
|
||
Собираем Angular-приложение и копируем артефакты в каталог, из которого Go-сервис будет обслуживать статику.
|
||
|
||
Скрипт сборки:
|
||
|
||
```1:20:/home/su/projects/articles/embed-gui-article/ui/build-for-embeding.sh
|
||
#!/bin/bash
|
||
# Использование: ./build-for-embeding.sh /abs/path/to/back/cmd/public
|
||
npx ng build --configuration production
|
||
mkdir -p "$DESTINATION_DIR"
|
||
cp -r /home/su/projects/angular/project-front/dist/project-front/browser/* "$DESTINATION_DIR"
|
||
```
|
||
|
||
- Артефакты после `ng build` лежат в `ui/dist/project-front/browser/`.
|
||
- Рекомендуемая папка для копирования: `back/cmd/public/` (в проекте уже есть пример статики).
|
||
|
||
## Встраивание в Go-сервис
|
||
|
||
Вариант А: раздача файлов из папки (`back/cmd/public`).
|
||
|
||
- Положите файлы фронта в `back/cmd/public`.
|
||
- Убедитесь, что роутер отдаёт `/` и `/*` из этой папки.
|
||
|
||
Вариант Б: `embed.FS` в бинарник.
|
||
|
||
Пример (концептуально):
|
||
|
||
```go
|
||
package main
|
||
|
||
import (
|
||
"embed"
|
||
"net/http"
|
||
)
|
||
|
||
//go:embed public/**
|
||
var webFS embed.FS
|
||
|
||
func main() {
|
||
// http.FileServerFS доступен в Go 1.22+, иначе используйте fs.Sub
|
||
http.Handle("/", http.FileServer(http.FS(webFS)))
|
||
http.HandleFunc("/api/v1/knock-actions/execute", executeHandler)
|
||
http.ListenAndServe(":8080", nil)
|
||
}
|
||
```
|
||
|
||
В репозитории уже есть бэкенд с маршрутами и готовой статикой в `back/cmd/public/`. Для статьи достаточно положить собранный фронт туда.
|
||
|
||
## API: контракт и примеры
|
||
|
||
Endpoint: `POST /api/v1/knock-actions/execute`
|
||
|
||
Request JSON:
|
||
|
||
```json
|
||
{
|
||
"targets": "tcp:127.0.0.1:22;udp:1.2.3.4:53",
|
||
"delay": "1s",
|
||
"waitConnection": false
|
||
}
|
||
```
|
||
|
||
Response 200:
|
||
|
||
```json
|
||
{ "status": "ok" }
|
||
```
|
||
|
||
Пример curl:
|
||
|
||
```bash
|
||
curl -X POST http://localhost:8080/api/v1/knock-actions/execute \
|
||
-H 'Content-Type: application/json' \
|
||
-d '{"targets":"tcp:127.0.0.1:22","delay":"1s","waitConnection":false}'
|
||
```
|
||
|
||
## Запуск и проверка
|
||
|
||
1 Собрать фронт и скопировать файлы:
|
||
|
||
```bash
|
||
cd /home/su/projects/articles/embed-gui-article/ui
|
||
./build-for-embeding.sh /home/su/projects/articles/embed-gui-article/back/cmd/public
|
||
```
|
||
|
||
2 Запустить бэкенд (варианты):
|
||
|
||
- Через make/скрипт, если есть.
|
||
- Локально `go run ./back` (или соответствующая команда в вашем проекте).
|
||
|
||
3 Открыть в браузере `/` и проверить, что форма грузится, а `Execute` бьёт в API.
|
||
|
||
## FAQ и типичные ошибки
|
||
|
||
- Статика не находится: проверьте путь копирования и что сервер обслуживает каталог.
|
||
- SPA роуты дают 404 при F5: настройте отдачу `index.html` по умолчанию.
|
||
- CORS при раздельных портах: либо проксируйте, либо включите CORS в сервере.
|
||
|
||
---
|
||
|
||
Этот гайд показывает минимальный путь: собрать веб-UI, скопировать в папку статики бэкенда и обеспечить один API‑эндпоинт. Для production можно добавить `embed.FS`, версионирование артефактов и CI/CD.
|