Управление исходным кодом модуля
При разработке модулей для публикации, чтобы другие разработчики могли их использовать, вы можете помочь, следуя соглашениям репозитория, описанным в этой теме.
В этой теме описываются действия, которые можно выполнять при управлении репозиторием модуля. Информация о последовательности шагов рабочего процесса при переходе от одной версии к другой приведена в разделе Рабочий процесс выпуска и версионирования модулей.
Некоторые из описанных здесь соглашений обязательны для модулей, другие являются лучшими практиками. В данном материале предполагается, что вы знакомы с базовыми практиками использования модулей, описанными в разделе Управление зависимостями.
Go поддерживает следующие репозитории для публикации модулей: Git, Subversion, Mercurial, Bazaar и Fossil.
Обзор разработки модулей доступен в разделе Разработка и публикация модулей.
Как инструменты Go находят опубликованный модуль
В децентрализованной системе публикации модулей и получения их исходного кода в Go вы можете опубликовать свой модуль, оставив исходный код в репозитории. Инструменты Go полагаются на правила именования, в которых пути репозитория и теги репозитория указывают имя и номер версии модуля. Если ваш репозиторий соответствует этим требованиям, исходный код модуля можно будет загрузить из репозитория с помощью инструментов Go, таких как команда go get.
Когда разработчик использует команду go get для получения исходного кода пакетов, импортируемых в его код, команда выполняет следующие действия:
- Из инструкций
importв исходном коде Go, командаgo getопределяет путь модуля внутри пути пакета. - Используя URL, полученный из пути модуля, команда находит исходный код модуля на сервере прокси модулей или напрямую в репозитории.
- Находит исходный код нужной версии модуля, сопоставляя номер версии модуля с тегом репозитория, чтобы обнаружить код в репозитории. Если номер версии еще не известен,
go getнаходит последнюю версию релиза. - Получает исходный код модуля и загружает его в локальный кэш модулей разработчика.
Организация кода в репозитории
Вы можете упростить сопровождение и улучшить опыт разработчиков с вашим модулем, следуя описанным здесь соглашениям. Включение кода модуля в репозиторий обычно выполняется так же просто, как и с другими кодами.
Следующая диаграмма иллюстрирует иерархию исходного кода простого модуля с двумя пакетами.
Ваш первый коммит должен включать файлы, перечисленные в следующей таблице:
| Файл | Описание |
|---|---|
| LICENSE | Лицензия модуля. |
| go.mod | Описывает модуль, включая его путь модуля (по сути, его имя) и зависимости. Подробнее см. в справочнике по go.mod. Путь модуля указывается в директиве модуля, например: module example.com/mymodule Подробнее о выборе пути модуля см. в разделе Управление зависимостями. Хотя можно редактировать файл go.mod, будет надежнее вносить изменения с помощью команд |
| go.sum | Содержит криптографические хэши, представляющие зависимости модуля. Инструменты Go используют эти хэши для аутентификации загруженных модулей, пытаясь подтвердить, что загруженный модуль является подлинным. Если подтверждение не удается, Go отобразит ошибку безопасности.
Файл будет пустым или отсутствовать, если нет зависимостей. Редактировать этот файл следует только с помощью команды |
| Директории пакетов и исходные файлы .go. | Директории и файлы .go, составляющие Go-пакеты и исходные коды в модуле. |
С помощью командной строки можно создать пустой репозиторий, добавить в него файлы, которые войдут в начальный коммит, а затем зафиксировать их с сообщением. Ниже приведён пример использования git:
<code>$ git init $ git add --all $ git commit -m "mycode: initial commit" $ git push </code>
Выбор области репозитория
Вы публикуете код в модуле, когда код должен быть версионирован независимо от кода в других модулях.
Проектируя репозиторий таким образом, чтобы он содержал в корневой директории один модуль, вы поможете сохранить простоту сопровождения, особенно с течением времени, когда вы будете выпускать новые минорные и патч-версии, создавать ветки для новых мажорных версий и так далее. Однако, если это необходимо, вы можете вести коллекцию модулей в одном репозитории.
Источник одного модуля в репозитории
Вы можете вести репозиторий, в котором содержится исходный код одного модуля. В этом случае файл go.mod размещается в корне репозитория, а поддиректории с пакетами содержат исходный код на Go.
Это самый простой подход, который делает модуль более удобным для управления в долгосрочной перспективе. Он позволяет избежать необходимости добавлять префикс с путём к директории перед номером версии модуля.
Источник нескольких модулей в одном репозитории
Вы можете публиковать несколько модулей из одного репозитория. Например, у вас может быть код в одном репозитории, составляющий несколько модулей, но вы хотите версионировать их отдельно.
Каждая поддиректория, являющаяся корневой для модуля, должна иметь собственный файл go.mod.
Источник кода модуля в поддиректориях изменяет формат тега версии, который необходимо использовать при публикации модуля. Необходимо добавить префикс с именем поддиректории, которая является корневой для модуля, к части номера версии тега. Подробнее о номерах версий см. в разделе Нумерация версий модулей.
Например, для модуля example.com/mymodules/module1 ниже вы будете использовать следующее для версии v1.2.3:
- Путь модуля:
example.com/mymodules/module1 - Тег версии:
module1/v1.2.3 - Путь пакета, импортируемого пользователем:
example.com/mymodules/module1/package1 - Путь и версия модуля, указанные в директиве require пользователя:
example.com/mymodules/module1 v1.2.3
