Go Notes

Репозиторий для изучения языка Go, демонстрирующий создание веб-сервера и gRPC-сервера с возможностью управления заметками и пользователями.

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

Веб-API: RESTful API с использованием фреймворка Gin
gRPC-сервер: Реализация gRPC-сервисов для заметок и пользователей
Аутентификация: JWT-токены для защиты маршрутов
Хранение данных: Поддержка различных хранилищ (PostgreSQL для основных данных и Redis для токенов)
Документация API: Swagger UI для веб-API
Protocol Buffers: Для определения gRPC-сервисов
Тестирование: Модульные тесты

Структура проекта

go-notes/
├── api/                    # Определения API (protobuf)
├── cmd/                    # Основные приложения
│   ├── grpc-client/        # Клиент gRPC
│   ├── grpc-server/        # Сервер gRPC
│   └── web-server/         # Веб-сервер (REST API)
├── config/                 # Конфигурационные файлы
├── docs/                   # Документация Swagger
├── internal/               # Внутренний код приложения
│   ├── app/                # Входные точки приложения
│   ├── auth/               # Аутентификация и токены
│   ├── config/             # Управление конфигурацией
│   ├── database/           # Подключения к базам данных
│   ├── delivery/           # Контроллеры/обработчики HTTP и gRPC
│   ├── domain/             # Бизнес-логика и модели
│   │   ├── model/          # Определения структур данных
│   │   └── repository/     # Интерфейсы репозиториев
│   ├── middleware/         # HTTP-мидлвары (например, аутентификация)
│   ├── repository/         # Реализации репозиториев (PostgreSQL, Redis)
│   ├── service/            # Бизнес-сервисы
│   └── util/               # Вспомогательные утилиты
├── migrations/             # SQL-скрипты миграций
├── pkg/                    # Публичные пакеты (сгенерированный protobuf-код)
├── scripts/                # Скрипты для генерации кода
├── test/                   # Тесты
├── docker-compose.yml      # Конфигурация Docker Compose
├── go.mod                  # Зависимости Go
├── go.sum                  # Чек-суммы зависимостей
├── LICENSE                 # Лицензия
├── Makefile                # Сборочные команды
└── README.md               # Документация проекта

Функциональность

Веб-сервер (REST API)

Аутентификация пользователей через JWT
CRUD-операции для заметок и пользователей
Swagger UI доступен по адресу /swagger/index.html
Защищенные маршруты для изменения данных
Открытые маршруты для чтения данных

gRPC-сервер

Сервис для управления заметками
Сервис для управления пользователями
Поддержка всех CRUD-операций через gRPC

Хранение данных

PostgreSQL для хранения пользователей и заметок
Redis для хранения отозванных токенов и кэширования

Запуск приложения

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

Go 1.25.4 или выше
protoc (компилятор Protocol Buffers)
make

Установка зависимостей

# Установка зависимостей для protobuf
make proto-deps

# Генерация protobuf-кода
make proto

# Установка зависимостей для Swagger
make swag-deps

# Генерация документации Swagger
make swag

Запуск веб-сервера

go run cmd/web-server/main.go

Сервер будет доступен по адресу http://localhost:8080, Swagger UI по адресу http://localhost:8080/swagger/index.html.

Запуск gRPC-сервера

go run cmd/grpc-server/main.go

Сервер будет доступен по адресу localhost:5051.

Запуск gRPC-клиента

go run cmd/grpc-client/main.go

Клиент выполнит тестовые операции с gRPC-сервером.

Запуск с Docker

# Запуск PostgreSQL и Redis с помощью Docker Compose
make docker-up

# Запуск миграций базы данных
make migrate

# Откат всех миграций базы данных
make cleanup-db

# Полный перезапуск с Docker и миграции
make setup-db

Примеры использования API

Работа с пользователями

Регистрация пользователя

curl -X POST http://localhost:8080/api/users \
  -H "Content-Type: application/json" \
  -d '{"username": "testuser", "email": "test@example.com", "password": "password123"}'

Аутентификация пользователя (получение JWT-токена)

curl -X POST http://localhost:8080/api/auth/login \
  -H "Content-Type: application/json" \
  -d '{"username": "testuser", "password": "password123"}'

Выход пользователя (отзыв refresh токена)

curl -X POST http://localhost:8080/api/auth/logout \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer {jwt_token}" \
  -d '{"refresh_token": "{refresh_token}"}'

Обновление токенов

curl -X POST http://localhost:8080/api/auth/refresh \
  -H "Content-Type: application/json" \
  -d '{"refresh_token": "{refresh_token}"}'

Проверка валидности токена

curl -X POST http://localhost:8080/api/auth/validate \
  -H "Content-Type: application/json" \
  -d '{"token": "{jwt_token}"}'

После успешной аутентификации вы получите JWT-токен. При использовании токена в других запросах не включайте фигурные скобки {} - они используются только для обозначения плейсхолдера в примерах.

Получение всех пользователей

curl -X GET http://localhost:8080/api/users

Получение пользователя по ID

curl -X GET http://localhost:8080/api/users/{user_id}

Обновление пользователя (требует JWT-токен)

curl -X PUT http://localhost:8080/api/users/{user_id} \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer {jwt_token}" \
  -d '{"username": "updateduser", "email": "updated@example.com", "password": ""}'

Удаление пользователя (требует JWT-токен)

curl -X DELETE http://localhost:8080/api/users/{user_id} \
  -H "Authorization: Bearer {jwt_token}"

Работа с заметками

Создание заметки (требует JWT-токен)

curl -X POST http://localhost:8080/api/notes \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer {jwt_token}" \
  -d '{"title": "Моя заметка", "content": "Содержимое заметки"}'

Получение всех заметок (открытый маршрут)

curl -X GET http://localhost:8080/api/notes

Получение заметки по ID (требует JWT-токен)

curl -X GET http://localhost:8080/api/notes/{note_id} \
  -H "Authorization: Bearer {jwt_token}"

Обновление заметки (требует JWT-токен)

curl -X PUT http://localhost:8080/api/notes/{note_id} \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer {jwt_token}" \
  -d '{"id": "{note_id}", "title": "Обновленная заметка", "content": "Обновленное содержимое"}'

Удаление заметки (требует JWT-токен)

curl -X DELETE http://localhost:8080/api/notes/{note_id} \
  -H "Authorization: Bearer {jwt_token}"

Используемые технологии

Gin - веб-фреймворк
gRPC - фреймворк для RPC
Protocol Buffers - язык описания схемы данных
JWT - токены для аутентификации
Swaggo - генерация документации Swagger
Testify - библиотека для тестирования

Make-цели

make proto - генерация protobuf-кода
make proto-deps - установка зависимостей protobuf
make swag - генерация документации Swagger
make swag-deps - установка зависимостей Swagger
make test - запуск тестов
make build - сборка приложения
make docker-down-v - остановка контейнеров и удаление volumes с БД
make docker-up - запуск сервисов с Docker Compose
make migrate - запуск миграций базы данных
make cleanup-db - откат всех миграций базы данных
make setup-db - полный перезапуск с Docker и запуск миграций
make help - список всех целей

Переменные окружения

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

Общие настройки

ENV - окружение (development, production, staging) (по умолчанию: development)
LOG_LEVEL - уровень логирования (по умолчанию: info)

Сервер

SERVER_PORT - порт для HTTP сервера (по умолчанию: :8080)
GRPC_PORT - порт для gRPC сервера (по умолчанию: :5051)
SERVER_READ_TIMEOUT - таймаут чтения запроса в секундах (по умолчанию: 15)
SERVER_WRITE_TIMEOUT - таймаут записи ответа в секундах (по умолчанию: 15)

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

AUTH_ENABLE_HTTPS - включить HTTPS (по умолчанию: false)

PostgreSQL

POSTGRES_HOST - хост PostgreSQL (по умолчанию: localhost)
POSTGRES_PORT - порт PostgreSQL (по умолчанию: 5432)
POSTGRES_NAME - имя базы данных (по умолчанию: go_notes)
POSTGRES_USER - имя пользователя базы данных (по умолчанию: postgres)
POSTGRES_PASSWORD - пароль базы данных
POSTGRES_SSL_MODE - режим SSL для PostgreSQL (по умолчанию: disable)
POSTGRES_POOL_SIZE - размер пула подключений (по умолчанию: 10)
POSTGRES_PARAMETERS - дополнительные параметры подключения

Redis

REDIS_HOST - хост Redis (по умолчанию: localhost)
REDIS_PORT - порт Redis (по умолчанию: 6379)
REDIS_PASSWORD - пароль Redis
REDIS_DB - номер базы данных Redis (по умолчанию: 0)
REDIS_POOL_SIZE - размер пула подключений (по умолчанию: 10)
REDIS_URL - альтернативный способ указания подключения

JWT

JWT_SECRET_KEY - секретный ключ для подписи JWT токенов (по умолчанию: my_secret_key)
JWT_ALGORITHM - алгоритм подписи токена (по умолчанию: HS256)
BCRYPT_COST - стоимость хеширования паролей (по умолчанию: 10)
ACCESS_TOKEN_TTL - время жизни access токена (по умолчанию: 15m)
REFRESH_TOKEN_TTL - время жизни refresh токена (по умолчанию: 168h)

Refresh токены

REFRESH_SECRET_KEY - секретный ключ для подписи Refresh токенов (по умолчанию: refresh_secret_key)
REFRESH_REVOCATION_ENABLED - включено ли отслеживание отозванных токенов (по умолчанию: true)

Репозиторий

REPO_TYPE - тип репозитория (postgres, redis) (по умолчанию: postgres)
REPO_PATH - путь к файлу/директории для хранения данных (по умолчанию: ./data)

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

PASSWORD_MIN_LENGTH - минимальная длина пароля (по умолчанию: 8)
MAX_LOGIN_ATTEMPTS - максимальное количество попыток входа (по умолчанию: 5)
LOGIN_BLOCK_TIME - время блокировки после неудачных попыток (по умолчанию: 30m)
BCRYPT_COST_SEC - стоимость хеширования паролей (по умолчанию: 10)

Завершение работы

SHUTDOWN_TIMEOUT - таймаут завершения работы (по умолчанию: 25s)
SHUTDOWN_WAIT - время ожидания перед завершением (по умолчанию: 3s)

Name		Name	Last commit message	Last commit date
Latest commit History 70 Commits
.github/workflows		.github/workflows
api/proto		api/proto
cmd		cmd
config		config
docs		docs
etc/systemd/system		etc/systemd/system
internal		internal
migrations		migrations
pkg/proto		pkg/proto
scripts		scripts
test		test
.dockerignore		.dockerignore
.gitignore		.gitignore
.goreleaser.yml		.goreleaser.yml
Dockerfile.grpc		Dockerfile.grpc
Dockerfile.web		Dockerfile.web
LICENSE		LICENSE
Makefile		Makefile
README.md		README.md
docker-compose.yml		docker-compose.yml
go.mod		go.mod
go.sum		go.sum

Folders and files

Latest commit

History

Repository files navigation