Hello Gitea API

Современный REST API сервер, построенный на Go с использованием Gin framework и структурированного логирования.

🚀 Возможности

• ✅ REST API с JSON ответами
• ✅ Health check endpoint
• ✅ CORS поддержка
• ✅ Современное структурированное логирование (Go 1.24+)
• ✅ Настраиваемые уровни и форматы логирования
• ✅ Системная информация и мониторинг
• ✅ Мультиплатформенная сборка
• ✅ Docker образы для Linux AMD64/ARM64
• ✅ Автоматические релизы через Gitea Actions

📦 Установка

Из бинарного файла

1. Скачайте бинарный файл для вашей платформы из релизов
2. Распакуйте архив
3. Запустите: ./hello-api-<platform>

Из Docker образа

docker pull <username>/hello-api:latest
docker run -p 8080:8080 <username>/hello-api:latest

Из исходного кода

git clone https://direct-dev.ru/gitea/GiteaAdmin/hello_gitea.git
cd hello_gitea
go mod download
go run main.go

🔧 Конфигурация

Основные настройки

Сервер запускается на порту 8080 по умолчанию. Можно изменить через переменную окружения:

export PORT=3000
./hello-api

Настройка логирования

Приложение поддерживает гибкую настройку логирования через переменные окружения:

Уровни логирования (LOG_LEVEL)

# Доступные уровни (по возрастанию важности):
export LOG_LEVEL=DEBUG    # Все сообщения
export LOG_LEVEL=INFO     # Информационные и выше
export LOG_LEVEL=WARN     # Предупреждения и выше
export LOG_LEVEL=ERROR    # Только ошибки

Форматы логирования (LOG_FORMAT)

# JSON формат (по умолчанию) - для production
export LOG_FORMAT=json

# Текстовый формат - для разработки
export LOG_FORMAT=text

Примеры конфигурации

Для разработки:

export LOG_LEVEL=DEBUG
export LOG_FORMAT=text
export PORT=8080
go run main.go

Для production:

export LOG_LEVEL=INFO
export LOG_FORMAT=json
export PORT=8080
./hello-api

📡 API Endpoints

GET /

Основной endpoint

Ответ:

{
  "message": "Hello, World!",
  "version": "1.0.33"
}

GET /healthz

Health check endpoint

Ответ:

{
  "status": "ok",
  "version": "1.0.33"
}

GET /api/v1/info

Информация о сервисе

Ответ:

{
  "service": "hello-api",
  "status": "running",
  "version": "1.0.33"
}

POST /api/v1/echo

Echo endpoint - возвращает отправленное сообщение

Запрос:

{
  "message": "Hello from client!"
}

Ответ:

{
  "echo": "Hello from client!",
  "version": "1.0.33"
}

GET /api/v1/config

Новый endpoint - системная информация и конфигурация

Ответ:

{
  "version": "1.0.33",
  "system_info": {
    "go_version": "go1.24.0",
    "os": "linux",
    "architecture": "amd64",
    "num_cpu": 8,
    "start_time": "2024-01-15T10:30:45Z"
  },
  "environment": {
    "PATH": "/usr/local/bin:/usr/bin:/bin",
    "PORT": "8080",
    "LOG_LEVEL": "INFO"
  },
  "uptime": "2h30m15s"
}

POST /api/v1/log-test

Новый endpoint - тестирование уровней логирования

Запрос:

{
  "level": "debug",
  "message": "Test log message"
}

Ответ:

{
  "status": "logged",
  "level": "debug",
  "message": "Test log message"
}

📊 Логирование

Структурированное логирование

Приложение использует современную систему логирования Go 1.24+ (log/slog) с поддержкой:

• Структурированных логов в JSON и текстовом формате
• Уровней логирования (DEBUG, INFO, WARN, ERROR)
• Контекстной информации (IP клиента, User-Agent, время запроса)
• Автоматического форматирования времени
• Фильтрации чувствительных данных

Примеры логов

JSON формат (production)

{
  "time": "2024-01-15T10:30:45.123Z",
  "level": "INFO",
  "msg": "HTTP Request",
  "method": "GET",
  "path": "/api/v1/config",
  "status": 200,
  "latency": "1.234ms",
  "client_ip": "192.168.1.100",
  "user_agent": "curl/7.68.0",
  "timestamp": "2024-01-15T10:30:45.123Z"
}

Текстовый формат (development)

2024-01-15T10:30:45.123Z INFO HTTP Request method=GET path=/api/v1/config status=200 latency=1.234ms client_ip=192.168.1.100 user_agent="curl/7.68.0"

Основные изменения в README

🆕 Новые разделы:

1. Конфигурация логирования - подробное описание переменных окружения
2. Форматы логирования - примеры JSON и текстового формата
3. Новые API endpoints - /api/v1/config и /api/v1/log-test
4. Безопасность логирования - фильтрация чувствительных данных

📊 Детальное описание логирования:

• Уровни логирования (DEBUG, INFO, WARN, ERROR)
• Форматы (JSON для production, text для разработки)
• Примеры логов с реальными данными
• Контекстная информация в логах

🔧 Практические примеры:

• Настройка для разработки и production
• Команды для тестирования
• Отладочные приемы

📦 Улучшенная структура:

• Четкое разделение возможностей
• Пошаговые инструкции
• Примеры конфигурации
• Команды для тестирования

Теперь README полностью отражает современные возможности приложения с детальным описанием системы логирования! 🎉

Логируемые события

• HTTP запросы с детальной информацией
• Ошибки приложения с контекстом
• Системные события (запуск, остановка)
• API вызовы с параметрами
• Конфигурационные изменения

Безопасность

• Автоматическая фильтрация чувствительных переменных окружения
• Безопасное логирование без утечки секретов
• Контролируемые уровни для разных сред

Разработка

Зависимости

• Go 1.24+
• Gin framework

Сборка

# Для текущей платформы
go build -o hello-api main.go

# Для Linux AMD64
GOOS=linux GOARCH=amd64 go build -o hello-api-linux-amd64 main.go

# Для Linux ARM64
GOOS=linux GOARCH=arm64 go build -o hello-api-linux-arm64 main.go

# Для Windows
GOOS=windows GOARCH=amd64 go build -o hello-api-windows-amd64.exe main.go

# Для macOS
GOOS=darwin GOARCH=amd64 go build -o hello-api-darwin-amd64 main.go
GOOS=darwin GOARCH=arm64 go build -o hello-api-darwin-arm64 main.go

Тестирование

# Запуск сервера с отладочным логированием
export LOG_LEVEL=DEBUG
export LOG_FORMAT=text
go run main.go

# Тестирование API
curl http://localhost:8080/
curl http://localhost:8080/healthz
curl http://localhost:8080/api/v1/info
curl http://localhost:8080/api/v1/config

# Тестирование echo
curl -X POST http://localhost:8080/api/v1/echo \
  -H "Content-Type: application/json" \
  -d '{"message":"Hello!"}'

# Тестирование логирования
curl -X POST http://localhost:8080/api/v1/log-test \
  -H "Content-Type: application/json" \
  -d '{"level": "debug", "message": "Test log message"}'

Отладка

Для детального анализа работы приложения:

# Включить отладочное логирование
export LOG_LEVEL=DEBUG
export LOG_FORMAT=text

# Запустить приложение
go run main.go

# В другом терминале - мониторинг логов
tail -f /var/log/application.log  # если логи в файл

🚀 CI/CD

При создании тега (например, v1.1.20) автоматически:

1. Собираются бинарники для всех платформ
2. Создается Docker образ для Linux AMD64/ARM64
3. Образ публикуется в Docker Hub
4. Создается релиз в Gitea с бинарниками

Дополнительно .gitea/workflows/build_build.yaml предназначен для автоматизации процесса сборки и публикации Docker-образов билдера - то есть образа который будет использоваться в основном процессе сборки и релиза. Этот workflow запускается (триггерится) автоматически при пуше тега, начинающегося с builder- (например, builder-v1.2.3), в репозиторий на сервере Gitea.

Когда такой тег появляется, workflow выполняет следующие задачи:

• Клонирует репозиторий и переключается на соответствующую версию кода.
• Настраивает окружение для сборки Docker-образов с поддержкой мультиплатформенности (amd64 и arm64).
• Выполняет аутентификацию в Docker Hub.
• Собирает и публикует Docker-образы для разных архитектур (tag DOCKERHUB_USERNAME/my-build-golang-runnerr:builder-v1.2.3 и tag DOCKERHUB_USERNAME/my-build-golang-runner:latest.
• Для сборки используется специальный Dockerfile (Dockerfile.builder) для создания образа билдера.

Таким образом, данный файл обеспечивает автоматическую сборку и публикацию артефактов проекта при выпуске новых версий, что упрощает процесс релиза и гарантирует наличие актуальных образов и бинарников для пользователей.

📄 Лицензия

MIT Licens