Опубликовано в Профессии

Учебный проект на Go: что написать и как довести до рабочего сервиса

Фарфоровая рука держит синюю закладку над отделением коробки с другими закладками.

Время чтения: 6 мин.

Для первого учебного проекта на Go подойдёт сервис закладок. Пользователь сохраняет ссылку, видит свой список и удаляет ненужное. Этого достаточно, чтобы поработать с HTTP, хранением данных и проверкой доступа. При этом задачу можно удержать в голове без сложной предметной области.

Ниже разбираем проект, который можно довести до воспроизводимого локального запуска и показать на разборе кода. Это задание с критериями готовности, а не готовый код для копирования.

Фигура подносит последнюю синюю деталь к небольшому пазлу; рядом закрытая коробка с другими деталями.

Зафиксируй границы первой версии

Представь: ты читаешь документацию, находишь полезную статью и хочешь вернуться к ней позже. Закладка содержит адрес, название и дату добавления. У каждого пользователя свой список.

Для первой версии достаточно пяти операций: создать закладку, получить список, открыть одну запись, переименовать и удалить её. Оставь теги, поиск по содержимому и совместные коллекции на потом. Проверять доступность сохранённого сайта тоже пока не нужно: сервис хранит адрес и не ходит по нему сам.

Запиши эти ограничения в README. Они помогут закончить проект, когда появится соблазн прикрутить очередь или рекомендательную систему. Новую функцию добавляй, когда сможешь объяснить, какой пользовательский сценарий без неё не работает.

Сначала договорись, как ведёт себя API

Составь небольшой контракт до написания обработчиков. Например:

  • Запрос: POST /bookmarks; Что происходит: Создать свою закладку; Успешный ответ: 201, объект с идентификатором
  • Запрос: GET /bookmarks; Что происходит: Получить свои закладки; Успешный ответ: 200, список
  • Запрос: GET /bookmarks/{id}; Что происходит: Открыть свою запись; Успешный ответ: 200, объект
  • Запрос: PATCH /bookmarks/{id}; Что происходит: Изменить название; Успешный ответ: 200, обновлённый объект
  • Запрос: DELETE /bookmarks/{id}; Что происходит: Удалить свою запись; Успешный ответ: 204, без тела

Выбери единый формат JSON. Для ошибки хватит машинного кода и понятного сообщения: например, invalid_url и «Укажи полный адрес с http или https». Текст нужен человеку, код пригодится клиентскому приложению.

Зафиксируй правила ввода. Название после удаления пробелов по краям содержит от 1 до 200 символов, адрес не длиннее 2048 символов. Разрешены схемы http и https, обязательна непустая часть с именем хоста. Это ограничения нашего задания, а не универсальные лимиты интернета.

Некорректный JSON и ошибку полей возвращай с 400. Отсутствие подтверждённого пользователя даёт 401. Для неизвестной или чужой закладки выберем одинаковый 404: клиенту не нужно сообщать, что такая запись существует у другого человека.

Проверь, кто имеет право менять данные

Для локального стенда заведи два тестовых аккаунта. Механизм входа можно взять готовый; его самостоятельная разработка заметно расширит задачу. Если пока используешь тестовые токены, храни соответствие токена и пользователя на сервере, а сами значения вынеси из репозитория. Такой стенд запускай локально, без публичного доступа.

Главное правило: владелец берётся из проверенного сервером контекста пользователя. Поле owner_id, переданное в JSON, не должно позволять выбрать чужой аккаунт. Иначе человек сможет создать или изменить запись от чужого имени.

Проверку владельца включай в запрос к базе. При чтении и удалении ищи запись одновременно по её идентификатору и идентификатору текущего пользователя. UUID вместо последовательного номера не заменяет эту проверку.

Сразу сделай ручную проверку: создай запись первым аккаунтом и попробуй прочитать её вторым. Повтори с изменением и удалением. Именно такой сценарий полезнее очередной проверки, что сервер вообще отвечает.

Фарфоровая рука держит синюю закладку над открытым ящиком с другими закладками.

Подключи базу и доведи один сценарий до конца

Для упражнения выбери PostgreSQL. Создай миграцию с таблицей пользователей и таблицей закладок. У закладки нужны идентификатор, владелец, адрес, название и время создания. Внешний ключ свяжет запись с существующим пользователем.

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

Работу через database/sql показывает официальный учебник Go по доступу к базе. Для PostgreSQL понадобится совместимый драйвер. Версии Go и драйвера зафиксируй в проекте, чтобы другой человек мог повторить запуск.

Данные пользователя передавай аргументами SQL-запроса, отдельно от его текста. Не собирай SQL через подстановку строки с адресом или названием. В документации Go о SQL-инъекциях разобран этот случай; конкретный вид параметров зависит от драйвера.

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

На первом этапе разреши сохранять один адрес несколько раз. Это понятное правило, которое не требует спорной нормализации URL. Позже можно решить, считать ли адреса с разными параметрами одной закладкой, и отдельно проверить новое поведение.

Сделай отказ понятным

Остановленная база не должна превращаться в успешный ответ с пустым списком. Пользователь иначе решит, что потерял закладки. Для временной недоступности базы предусмотрим 503 и короткое сообщение о невозможности выполнить запрос.

Не отправляй клиенту SQL, строку подключения или внутренний стек ошибки. В серверном журнале достаточно типа операции, безопасных диагностических деталей и идентификатора запроса. Полный адрес закладки тоже лучше не записывать: в его параметрах могут оказаться личные данные.

Передавай контекст HTTP-запроса в операции базы и ограничивай их длительность. Например, для локального задания можно начать с трёх секунд и проверить поведение на задержке. У входящего запроса контекст отменяется в предусмотренных net/http случаях, в том числе при закрытии соединения клиентом. Поддержка отмены операции базы зависит и от драйвера, поэтому проверь выбранный вариант.

Для небольшого сервиса хватит понятного разделения обработчиков HTTP, правил закладок и запросов к базе. Если одна и та же проверка повторилась в нескольких обработчиках, вынеси её. Отдельный интерфейс и пакет на каждую функцию здесь не обязательны.

Хочешь разобрать первую версию сервиса?

Подготовь README, проверку владельца и один сценарий отказа. Выбери ментора по Go, с которым можно обсудить именно этот участок проекта.

Выбрать ментора
Белая рука держит за верх наклонённую синюю костяшку; остальные костяшки стоят вертикально.

Какие сценарии покрыть тестами

Начни с правил, которые легко проверить без работающей базы: пустое название, слишком длинное поле, адрес без хоста, запрещённая схема. В учебнике Go по тестированию показано, как устроены тестовые функции и запуск через go test.

Затем проверь сервис с настоящей тестовой базой. Для каждой проверки используй подготовленные данные, которые не зависят от прошлого запуска. Особенно важны такие случаи:

  • созданная закладка читается после нового подключения к базе;
  • второй пользователь не видит запись в списке и не может изменить её по известному идентификатору;
  • невалидный запрос не оставляет новую строку;
  • повторное удаление возвращает выбранный 404;
  • недоступная база даёт ошибку, а не пустой успешный результат.

Проверь HTTP-статус и содержимое ответа. Тест, который проверяет только отсутствие ошибки функции, может пропустить возврат чужих данных.

Когда проект можно показать

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

Приложи описание API и перечисли известные ограничения. Например: сервис доступен только локально, теги ещё не реализованы, публичного входа нет. Это поможет проверяющему оценить сделанную часть, не угадывая замысел.

Для разговора с ментором подготовь конкретные вопросы: где лучше проверять владельца, как проверить отказ базы и почему выбран такой формат ошибки. Покажи один тест, который сначала обнаруживал ошибку, и изменение, после которого он проходит.

Когда сможешь объяснить путь от HTTP-запроса до сохранённой строки и воспроизвести отказ, у тебя появится законченный учебный сервис. Следующее улучшение выбирай по найденной проблеме, а не по длине списка технологий в описании проекта.

Продолжи изучать Go

Создай бесплатный аккаунт в LMS hitalent и посмотри теорию опубликованных курсов и открытые роадмапы для подготовки. Выбери следующий шаг по тому, чего не хватает твоему сервису закладок.

Зарегистрироваться бесплатно