Модули Go: v2 и более поздние версии

Go

Эта статья является переведенной статьей:blog.golang.org/V2-go-Module…
Оригинальный автор:Жан де Клерк и Тайлер Буи-ПалсуПереводчик:befovyВычитка:polaris1119
Перевод поGCTTоригинальная компиляция,Go language Китайский сайтЧесть запуска

Введение

Эта статья является четвертой частью системы модулей Go.

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

Для проектов, которые все еще находятся на ранних стадиях разработки (номер основной версииv0), пользователи будут ожидать случайных критических изменений. Для проектов, претендующих на стабильность (основная версияv1или новее), критические изменения должны быть внесены в новую основную версию. В этом посте рассматривается семантика основных версий, как создавать и публиковать новые основные версии и как поддерживать несколько основных версий модулей Go.

Основная версия и путь к модулю

Модули определяют важный принцип Go:Импорт правил совместимости"

Если путь импорта старого пакета и нового пакета совпадают, новый пакет должен быть обратно совместим со старым пакетом.

В соответствии с этим принципом новая основная версия пакета не имеет обратной совместимости с предыдущими версиями. Это означает, что в новых основных версиях этого пакета должен использоваться другой путь к модулю, чем в предыдущих версиях. отv2Для начала основной номер версии должен стоять в конце пути к модулю (в файле go.modmoduleутверждение). Например, когда модульgithub.com/googleapis/gax-goразработчикиv2, они использовали новый путь к модулюgithub.com/googleapis/gax-go/v2. хочу использоватьv2Пользователи должны изменить импорт пакетов и требования к модулям наgithub.com/googleapis/gax-go/v2

Требование суффикса основной версии — это одно из отличий модулей Go от большинства других систем управления зависимостями. суффикс для решенияпроблема алмазной зависимости. Перед модулями Go,gopkg.inРазрешить сопровождающим пакетов следовать тому, что мы теперь называем правилами совместимости импорта. При использовании gopkg.in, если вы зависите от импорта, которыйgopkg.in/yaml.v1пакет и другой импортныйgopkg.in/yaml.v2package, это не конфликтует, потому что дваyamlПакеты имеют разные пути импорта (они используют те же суффиксы версий, что и модули Go). Поскольку модули gopkg.in и Go используют один и тот же метод суффикса номера версии, команда Go принимаетgopkg.in/yaml.v2 середина.v2как действительный номер версии. Это особый случай совместимости с gopkg.in, когда модули, размещенные на других доменах, должны использовать что-то вроде/v2такой косой суффикс.

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

Рекомендуемая стратегия заключается в разработке в каталоге, названном в честь суффикса основной версии.v2+модуль.

github.com/googleapis/gax-go @ master branch
/go.mod    → module github.com/googleapis/gax-go
/v2/go.mod → module github.com/googleapis/gax-go/v2

Этот способ совместим с некоторыми инструментами, которые не поддерживают модули Go: путь к файлу в репозитории такой же, какGOPATHв режимеgo getОжидаемый путь команды совпадает. Эта стратегия также позволяет разрабатывать все основные версии вместе в разных каталогах.

Другой стратегией может быть размещение основной версии в отдельной ветке. Однако, еслиv2+Исходный код находится в ветке репозитория по умолчанию (обычно master), и инструменты, которые не поддерживают версии (включая команды Go в режиме GOPATH), могут не различать разные основные версии.

Примеры в этой статье соответствуют политике подкаталога основной версии, поэтому они обеспечивают максимальную совместимость. Мы рекомендуем авторам модулей следовать этой стратегии до тех пор, пока у них есть пользователи.GOPATHразработка узора.

Выпуск v2 и выше

Эта статья начинается сgithub.com/googleapis/gax-goНапример:

$ pwd
/tmp/gax-go
$ ls
CODE_OF_CONDUCT.md  call_option.go  internal
CONTRIBUTING.md     gax.go          invoke.go
LICENSE             go.mod          tools.go
README.md           go.sum          RELEASING.md
header.go
$ cat go.mod
module github.com/googleapis/gax-go

go 1.9

require (
    github.com/golang/protobuf v1.3.1
    golang.org/x/exp v0.0.0-20190221220918-438050ddec5e
    golang.org/x/lint v0.0.0-20181026193005-c67002cb31c3
    golang.org/x/tools v0.0.0-20190114222345-bf090417da8b
    google.golang.org/grpc v1.19.0
    honnef.co/go/tools v0.0.0-20190102054323-c2f93a96b099
)
$

начать разработкуgithub.com/googleapis/gax-go изv2версия, мы создадим новуюv2/каталог и скопируйте содержимое пакета в этот каталог.

$ mkdir v2
$ cp *.go v2/
building file list ... done
call_option.go
gax.go
header.go
invoke.go
tools.go

sent 10588 bytes  received 130 bytes  21436.00 bytes/sec
total size is 10208  speedup is 0.95
$

Теперь, скопировав текущийgo.modфайл и добавьте его в путь к модулю/v2суффикс для создания v2go.modдокумент.

$ cp go.mod v2/go.mod
$ go mod edit -module github.com/googleapis/gax-go/v2 v2/go.mod
$

Уведомление:v2версия трактуется какv0 / v1Модули с отдельными версиями, оба могут сосуществовать в одной сборке. Поэтому, если вашv2+Модуль имеет несколько пакетов, вы должны обновить их, чтобы использовать новые/v2путь импорта, в противном случае вашv2+модули будут зависеть от васv0 / v1модуль. Чтобы обновить всеgithub.com/my/project заgithub.com/my/project/v2 ,можно использоватьfind иsed Заказ:

$ find . -type f \
    -name '*.go' \
    -exec sed -i -e 's,github.com/my/project,github.com/my/project/v2,g' {} \;
$

Теперь у нас естьv2модулей, но мы хотим поэкспериментировать и внести изменения до релиза. Разместите в нашемv2.0.0(или любую другую версию без пререлизного суффикса), мы можем разрабатывать и вносить критические изменения, как если бы мы решили внедрить новый API. Если мы хотим, чтобы пользователи могли экспериментировать с новым API до его официального выпуска, мы можем опубликоватьv2Предварительная версия:

$ git tag v2.0.0-alpha.1
$ git push origin v2.0.0-alpha.1
$

Как только мыv2API удовлетворён и уверен, что других критических изменений не будет, мы можем пометить его с помощью Git.v2.0.0.

$ git tag v2.0.0
$ git push origin v2.0.0
$

На данный момент необходимо поддерживать две основные версии. Обратная совместимость изменений и исправлений ошибок выпускается с использованием новых второстепенных выпусков или выпусков исправлений (например,v1.1.0,v2.0.1 Ждать).

Суммировать

Основные изменения версий влекут за собой дополнительные затраты на разработку и обслуживание, а также требуют дополнительных усилий для миграции от нижестоящих пользователей. Чем больше проект, тем дороже обходится это основное изменение версии. Основные изменения версии следует вносить только после того, как будет установлена ​​веская причина. Как только будет определена убедительная причина критического изменения, мы рекомендуем разработать несколько основных версий в основной ветке, поскольку это совместимо с множеством существующих инструментов.

правильноv1+Критические изменения в модуле всегда должны происходить в новомvN+1в модуле. Когда выпускается новый модуль, это означает дополнительную работу для сопровождающих и пользователей, которым необходимо перейти на этот новый пакет. Поэтому сопровождающие должны проверять свой API перед выпуском стабильной версии и тщательноv1Нужны ли серьезные изменения после релиза.

Статьи по Теме

Категории