381 lines
12 KiB
Markdown
381 lines
12 KiB
Markdown
# 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. Скачайте бинарный файл для вашей платформы из [релизов](https://direct-dev.ru/gitea/GiteaAdmin/hello_gitea/releases)
|
||
2. Распакуйте архив
|
||
3. Запустите: `./hello-api-<platform>`
|
||
|
||
### Из Docker образа
|
||
|
||
```bash
|
||
docker pull <username>/hello-api:latest
|
||
docker run -p 8080:8080 <username>/hello-api:latest
|
||
```
|
||
|
||
### Из исходного кода
|
||
|
||
```bash
|
||
git clone https://direct-dev.ru/gitea/GiteaAdmin/hello_gitea.git
|
||
cd hello_gitea
|
||
go mod download
|
||
go run main.go
|
||
```
|
||
|
||
## 🔧 Конфигурация
|
||
|
||
### Основные настройки
|
||
|
||
Сервер запускается на порту 8080 по умолчанию. Можно изменить через переменную окружения:
|
||
|
||
```bash
|
||
export PORT=3000
|
||
./hello-api
|
||
```
|
||
|
||
### Настройка логирования
|
||
|
||
Приложение поддерживает гибкую настройку логирования через переменные окружения:
|
||
|
||
#### Уровни логирования (`LOG_LEVEL`)
|
||
|
||
```bash
|
||
# Доступные уровни (по возрастанию важности):
|
||
export LOG_LEVEL=DEBUG # Все сообщения
|
||
export LOG_LEVEL=INFO # Информационные и выше
|
||
export LOG_LEVEL=WARN # Предупреждения и выше
|
||
export LOG_LEVEL=ERROR # Только ошибки
|
||
```
|
||
|
||
#### Форматы логирования (`LOG_FORMAT`)
|
||
|
||
```bash
|
||
# JSON формат (по умолчанию) - для production
|
||
export LOG_FORMAT=json
|
||
|
||
# Текстовый формат - для разработки
|
||
export LOG_FORMAT=text
|
||
```
|
||
|
||
#### Примеры конфигурации
|
||
|
||
**Для разработки:**
|
||
|
||
```bash
|
||
export LOG_LEVEL=DEBUG
|
||
export LOG_FORMAT=text
|
||
export PORT=8080
|
||
go run main.go
|
||
```
|
||
|
||
**Для production:**
|
||
|
||
```bash
|
||
export LOG_LEVEL=INFO
|
||
export LOG_FORMAT=json
|
||
export PORT=8080
|
||
./hello-api
|
||
```
|
||
|
||
## 📡 API Endpoints
|
||
|
||
### GET /
|
||
|
||
Основной endpoint
|
||
|
||
**Ответ:**
|
||
|
||
```json
|
||
{
|
||
"message": "Hello, World!",
|
||
"version": "1.0.33"
|
||
}
|
||
```
|
||
|
||
### GET /healthz
|
||
|
||
Health check endpoint
|
||
|
||
**Ответ:**
|
||
|
||
```json
|
||
{
|
||
"status": "ok",
|
||
"version": "1.0.33"
|
||
}
|
||
```
|
||
|
||
### GET /api/v1/info
|
||
|
||
Информация о сервисе
|
||
|
||
**Ответ:**
|
||
|
||
```json
|
||
{
|
||
"service": "hello-api",
|
||
"status": "running",
|
||
"version": "1.0.33"
|
||
}
|
||
```
|
||
|
||
### POST /api/v1/echo
|
||
|
||
Echo endpoint - возвращает отправленное сообщение
|
||
|
||
**Запрос:**
|
||
|
||
```json
|
||
{
|
||
"message": "Hello from client!"
|
||
}
|
||
```
|
||
|
||
**Ответ:**
|
||
|
||
```json
|
||
{
|
||
"echo": "Hello from client!",
|
||
"version": "1.0.33"
|
||
}
|
||
```
|
||
|
||
### GET /api/v1/config
|
||
|
||
**Новый endpoint** - системная информация и конфигурация
|
||
|
||
**Ответ:**
|
||
|
||
```json
|
||
{
|
||
"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** - тестирование уровней логирования
|
||
|
||
**Запрос:**
|
||
|
||
```json
|
||
{
|
||
"level": "debug",
|
||
"message": "Test log message"
|
||
}
|
||
```
|
||
|
||
**Ответ:**
|
||
|
||
```json
|
||
{
|
||
"status": "logged",
|
||
"level": "debug",
|
||
"message": "Test log message"
|
||
}
|
||
```
|
||
|
||
## 📊 Логирование
|
||
|
||
### Структурированное логирование
|
||
|
||
Приложение использует современную систему логирования Go 1.24+ (`log/slog`) с поддержкой:
|
||
|
||
- **Структурированных логов** в JSON и текстовом формате
|
||
- **Уровней логирования** (DEBUG, INFO, WARN, ERROR)
|
||
- **Контекстной информации** (IP клиента, User-Agent, время запроса)
|
||
- **Автоматического форматирования** времени
|
||
- **Фильтрации чувствительных данных**
|
||
|
||
### Примеры логов
|
||
|
||
#### JSON формат (production)
|
||
|
||
```json
|
||
{
|
||
"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)
|
||
|
||
``` text
|
||
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
|
||
|
||
### Сборка
|
||
|
||
```bash
|
||
# Для текущей платформы
|
||
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
|
||
```
|
||
|
||
### Тестирование
|
||
|
||
```bash
|
||
# Запуск сервера с отладочным логированием
|
||
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"}'
|
||
```
|
||
|
||
### Отладка
|
||
|
||
Для детального анализа работы приложения:
|
||
|
||
```bash
|
||
# Включить отладочное логирование
|
||
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
|