Тема 1/3: Пакет net/http. Работа с HTTP → Урок 2/10
Саша
Знаешь такой мем? 👆
Что-то он мне напоминает 😏
Саша
Основан на реальных событиях! Но как бы мы ни мечтали о домике на дереве, стоит чуть более серьёзно относиться к архитектуре проекта. С неё и начнём — это будет первый урок первой темы.

Пакет net/http. Работа с HTTP

Вы приступаете к теме net/http — одной из самых объёмных и сложных в программе. От вас потребуется максимум концентрации, чтобы изучить теорию и в первых кодовых инкрементах реализовать поставленные задачи. В этой теме вы создадите HTTP-сервер на Go и заложите фундамент вашего проекта.
Вначале вы познакомитесь с принципами организации Go-пакетов — это поможет правильно сформировать структуру проекта. Затем вы узнаете, как отправлять HTTP-запросы и обрабатывать ответы, — это пригодится при тестировании HTTP-сервера. В конце вы перепишете первую версию сервиса, используя сторонний HTTP-пакет, и добавите набор тестов для проверки работоспособности кода.
Итого вы реализуете клиентскую и серверную часть для HTTP-протокола, а также:
  • изучите основы тестирования Go-программ и напишете первые тесты;
  • научитесь тестировать сервер с помощью пакета httptest;
  • перепишете тесты, используя стороннюю библиотеку testify;
  • узнаете, как работать с клиентскими и серверными HTTP-библиотеками.

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

В этом уроке речь пойдёт о файловой структуре проекта на Go. Расскажем, как выстраивать иерархию директорий и где размещать исходные файлы.
Саша
Первые ТЗ по проекту Гоша скинет тебе уже совсем скоро. Для стажёров мы сделали шаблон репозитория с вот такой структурой директорий:
— project
  |
  — cmd
  — internal
О, интересно.
Саша
Как ты думаешь, почему структура именно такая?
Хм, чтобы разграничить код приложений и внутренних библиотек. 
Саша
В cmd размещается код приложений, а в internal — код внутренних библиотек.
В процессе реализации вашего проекта структура директорий будет расширяться и изменяться в соответствии с возрастающим объёмом кода.

Задание 1/3

Зачем нужно несколько директорий и файлов? Почему бы не писать весь код приложения в одном файле?
В спецификации языка Go нет жёстких требований к структуре директорий. Но команды, которые начинаются с go ..., например go get, в их текущей реализации работают только с репозиториями, где соблюдается ряд условий.
В репозитории обычно размещают не больше одного модуля, а в корневой директории этого модуля — файл go.mod.
В модуль включают один или несколько пакетов, и для каждого пакета создают свою директорию с файлами. Имя пакета должно быть идентично имени директории — для исполняемых приложений в исходных файлах достаточно внутреннего именования package main.
Команда go build, запущенная без аргументов, собирает пакет из файлов той директории, в которой вызвана, — это основное правило. Если вы пишете черновик или совсем маленький пакет, то вполне можете обойтись одной директорией.
Директория пакета может содержать поддиректории с другими пакетами. Например, в директории пакета net исходников стандартной библиотеки находится поддиректория http. Соответственно, их пути импорта — net и net/http. Файлы пакета net/http не могут использовать функции пакета net, не импортировав его, — и наоборот.

Директория cmd

В директорию cmd помещают пакеты исполняемых команд. Если вы откроете директорию с установленным Go, то в src/cmd вы найдёте, к примеру, пакеты команд go и gofmt.

Директория internal

В директории internal размещают внутренние пакеты проекта.
Из этой директории можно импортировать только в те пакеты, которые расположены в соседних директориях, то есть у соседей должен быть общий с internal родитель. Например, пакет /a/b/c/internal/d/e/f можно импортировать только из /a/b/c и /a/b/c/... и нельзя из /a/b/g.
Начиная с версии Go 1.4, пакеты internal нельзя импортировать во внешние репозитории. Это сделано для гранулированного доступа и «подчистки» API в большой базе кода. Например, в директории net/internal в исходниках Go лежит непубличный пакет socktest, функции которого используют пакеты net/http и net/http/httputil.
Если вы опубликуете свой проект на GitHub, учитывайте, что пакеты из директории internal не будут доступны для импорта в другие Go-проекты.

Директория vendor

В корневой директории модуля иногда создают поддиректорию vendor и сохраняют туда локальные копии зависимостей. Копии нужны для того, чтобы обезопасить свой проект от удаления или некачественной поддержки внешних библиотек. Если внешние репозитории вдруг станут недоступны, это не вызовет проблем при сборке проекта.
Курс построен так, чтобы, кроме стандартной библиотеки, вы обходились минимумом зависимостей и использовали только надёжные. Поэтому директория vendor в задачах курса вам не понадобится. И всё же, чтобы попрактиковаться, вы можете воспользоваться командой go mod vendor и создать такую директорию.

Задание 2/3

Сможет ли код из pkg2 импортировать util при такой файловой структуре на вашем компьютере?
— MyProject
    |
    — pkg1
         |
         — internal
               |
               — util
    — pkg2
Вы можете организовать структуру вашего проекта с учётом приведённых выше особенностей и ограничений. Вот один из возможных примеров:
— project
    |
    — go.mod
    — cmd
        |
        — client
            |
            — main.go
            — main_test.go
        — server
            |
            — main.go
            — main_test.go
    — internal
        |
        — handlers
            |
            — handlers.go
        |
        — util
            |
            — util.go
Кроме технических условий, которые должны соблюдаться для правильной работы команд, есть принятые в Go-сообществе соглашения по организации проектов. Они описаны на странице Standard Go Project Layout. Единообразие в структуре проектов облегчает их понимание и поддержку. Но не все разработчики используют предложенные шаблоны, так как эта инициатива носит рекомендательный, а не обязательный характер.

Задание 3/3

Могут ли файлы одного пакета лежать в разных директориях?
Чтобы лучше представлять себе, как выглядит структура директорий в Go, изучите несколько популярных проектов:
  • Syncthing — приложение для синхронизации файлов. Заметьте, что для служебных пакетов вместо internal используется директория lib.
  • Kubernetes — программное обеспечение для развёртывания и управления контейнерами. Пакеты размещены в директории pkg, что позволяет использовать их в других проектах.
  • Rclone — программа для синхронизации файлов с облачными хранилищами. Есть директория cmd с командами приложения и lib со служебными пакетами.
Эти примеры подтверждают отсутствие единого стандарта: структура в них совпадает хорошо если на 10%. Старайтесь планировать структуру вашего проекта так, чтобы расположение файлов и директорий было понятно другим разработчикам и не требовало от них много времени на поиски и исследования.
Саша
Первый урок на этом окончен. Я подумал, будет круто иногда делиться с тобой тем, что ещё можно почитать. И это не только ссылки на официальную документацию, хотя, конечно, для разработчика важно уметь в ней разбираться, — этот навык очень ценят работодатели, и, кроме как на практике, его никак не прокачать.
Но изучение Go этим не ограничивается. Для погружения в специфику языка можно читать блоги и статьи, смотреть отрывки из выступлений на конференциях, слушать авторитетных разработчиков и лидеров Go-сообщества. А это целый мир! И да, многие из этих материалов на английском — заодно и в нём можно практиковаться. Так или иначе, большая часть русскоязычных материалов по Go — это переводы статей англоязычных коллег. Читать первоисточник всегда лучше.
А ещё в Go очень хорошо написана стандартная библиотека — если вы откроете исходники, то увидите адекватный читаемый код. Его полезно изучать, чтобы, во-первых, лучше понимать, как работают библиотечные функции. А во-вторых, чтобы знать приёмчики по написанию Go-шного кода, ведь изменения в стандартной библиотеке контролируются Go-сообществом, поэтому там, можно сказать, эталонный код. Навык поиска, навигации и чтения документации будет большим плюсом в вашем резюме.

Дополнительные материалы