HTTP API - Система Электронных Очередей и Единого Входа (SSO) на Go

[](

📋 Описание проекта

HTTP API - это RESTful веб-сервис для системы единого входа (Single Sign-On) с управлением пользователями, очередями на консультации и группами студентов. Проект реализован на Go с использованием архитектуры Clean Architecture.

🏗️ Архитектура проекта

Проект следует принципам Clean Architecture с четким разделением слоев:

├── cmd/                    # Точка входа в приложение
├── configs/               # Конфигурационные файлы
├── migrations/            # SQL миграции базы данных
├── models/                # Модели данных (DTO)
├── pkg/                   # Основная бизнес-логика
│   ├── config/           # Управление конфигурацией
│   ├── handler/          # HTTP обработчики (Presentation Layer)
│   ├── repository/       # Слой доступа к данным (Data Layer)
│   └── services/         # Бизнес-логика (Use Cases)
├── testing/              # Функциональные тесты
└── README.md             # Документация API

🛠️ Технологический стек

• Язык: Go 1.19+
• Веб-фреймворк: Gin
• База данных: PostgreSQL
• ORM: sqlx
• Аутентификация: JWT токены
• Хеширование паролей: bcrypt
• Конфигурация: Viper
• Контейнеризация: Docker
• Тестирование: Go testing package

📊 Основные компоненты

1. Модели данных (models/)

• User - пользователи системы
• Group - группы студентов
• Queue - очереди на консультации
• QueueParticipant - участники очередей
• Config - конфигурация приложения

2. HTTP обработчики (pkg/handler/)

• handler.go - основные маршруты и middleware
• user.go - управление пользователями
• queue.go - управление очередями
• groups.go - управление группами

3. Бизнес-логика (pkg/services/)

• service.go - интерфейсы и основная логика
• jwt.go - работа с JWT токенами
• users.go - логика работы с пользователями
• queue.go - логика работы с очередями

4. Слой данных (pkg/repository/)

• repository.go - интерфейсы репозитория
• repository_postgres.go - подключение к PostgreSQL
• users.go - операции с пользователями
• groups.go - операции с группами
• queue.go - операции с очередями
• queue_participants.go - операции с участниками очередей

🔐 Система аутентификации

• JWT токены для аутентификации
• bcrypt для хеширования паролей
• Middleware для проверки токенов
• Роли пользователей (обычный пользователь/администратор)

📡 API Endpoints

Аутентификация

• POST /auth/sign-up - регистрация пользователя
• POST /auth/sign-in - вход в систему

Пользователи

• GET /api/profile - профиль пользователя
• PUT /api/profile - обновление профиля
• GET /api/admin - проверка статуса админа
• GET /api/admin/users - список пользователей (админ)
• DELETE /api/admin/users/:id - удаление пользователя (админ)

Очереди

• GET /api/queues - список очередей
• POST /api/queues - создание очереди (админ)
• GET /api/queues/:id - получение очереди
• PUT /api/queues/:id - обновление очереди (админ)
• DELETE /api/queues/:id - удаление очереди (админ)
• POST /api/queues/:id/join - присоединение к очереди
• DELETE /api/queues/:id/leave - покидание очереди
• GET /api/queues/:id/participants - участники очереди
• POST /api/queues/:id/shift - сдвиг очереди (админ)

Группы

• GET /api/groups - список групп
• POST /api/groups - создание группы (админ)
• GET /api/groups/:id - получение группы
• PUT /api/groups/:id - обновление группы (админ)
• DELETE /api/groups/:id - удаление группы (админ)

🗄️ База данных

Таблицы:

• users - пользователи системы
• groups - группы студентов
• queues - очереди на консультации
• queue_participants - участники очередей

Миграции:

• 000001_create_initial_tables.up.sql - создание таблиц
• 000001_create_initial_tables.down.sql - удаление таблиц

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

Проект включает полный набор функциональных тестов:

• 65 тестов покрывающих все 21 endpoint
• Позитивные и негативные сценарии
• Проверка авторизации и прав доступа
• Граничные случаи и валидация данных

Структура тестов:

• functional_test.go - базовые функции
• auth_functional_test.go - тесты аутентификации
• user_functional_test.go - тесты пользователей
• queue_functional_test.go - тесты очередей
• group_functional_test.go - тесты групп
• api_status_test.go - тесты статуса API

🚀 Запуск проекта

Предварительные требования:

• Go 1.19+
• PostgreSQL 12+
• Docker (опционально)

Локальный запуск:

# Установка зависимостей
go mod download

# Настройка базы данных
# Создать базу данных и применить миграции

# Запуск приложения
go run cmd/main.go

Docker:

# Запуск с Docker Compose
docker-compose up -d

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

Конфигурация приложения находится в configs/config.yml:

port: "8080"
db:
host: "localhost"
port: "5432"
username: "postgres"
password: "password"
dbname: "sso_db"
sslmode: "disable"

🔧 Разработка

Структура кода:

• Чистая архитектура с разделением слоев
• Интерфейсы для всех основных компонентов
• Dependency Injection для тестируемости
• Подробные комментарии на русском языке

Стандарты кодирования:

• Go fmt для форматирования
• Go vet для статического анализа
• Комментарии для всех публичных функций
• Обработка ошибок на всех уровнях

📚 Документация

• README.md - подробная документация API с примерами
• Комментарии в коде - описание всех функций и структур
• Тесты - примеры использования API

🎯 Особенности реализации

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

• JWT токены с временем истечения
• Хеширование паролей с bcrypt
• Валидация входных данных
• Проверка прав доступа

Производительность:

• Connection pooling для PostgreSQL
• Эффективные SQL запросы
• Минимальное использование памяти

Надежность:

• Graceful shutdown
• Обработка ошибок на всех уровнях
• Валидация данных
• Логирование операций

📈 Статистика проекта

• 21 endpoint для полного CRUD функционала
• 65 функциональных тестов с 100% покрытием endpoints
• 4 основных сущности (пользователи, группы, очереди, участники)
• Clean Architecture с четким разделением ответственности
• Полная документация API и кода

🏆 Готовность к продакшену

Проект готов к развертыванию в продакшене и включает:

• ✅ Полную документацию API
• ✅ Функциональные тесты
• ✅ Docker контейнеризацию
• ✅ Graceful shutdown
• ✅ Обработку ошибок
• ✅ Валидацию данных
• ✅ Безопасность (JWT, bcrypt)
• ✅ Логирование
• ✅ Конфигурацию через файлы

Проект демонстрирует профессиональный подход к разработке веб-API с использованием современных практик Go разработки.