# Модули Golang

> Организация модулей Golang проекта etcd

---

Индекс LLMS: [llms.txt](/ru/llms.txt)

---

Начиная с версии 3.5 проект etcd организован как несколько
[модулей Golang](https://golang.org/ref/mod), размещённых в [одном репозитории](https://golang.org/ref/mod#vcs-dir).

![Граф модулей](/docs/etcd/dev-internal/img/modules.svg)

Проект включает следующие модули:

  - **go.etcd.io/etcd/api/v3** — определения API, например protos и созданные из proto библиотеки, которые задают протокол взаимодействия между клиентами и сервером etcd.

  - **go.etcd.io/etcd/pkg/v3** — набор вспомогательных пакетов, используемых etcd, но не зависящих от его специфики. Пакет следует размещать здесь только в том случае, если в будущем его можно будет вынести в отдельный репозиторий. Не добавляйте сюда код с большим числом собственных зависимостей: они автоматически станут зависимостями клиентской библиотеки, которую важно сохранять легковесной.

  - **go.etcd.io/etcd/client/v3** — клиентская библиотека для сетевого обращения к etcd по grpc. Рекомендуется для всех новых применений etcd.

  - **go.etcd.io/etcd/client/v2** — устаревшая клиентская библиотека для обращения к etcd по протоколу HTTP. Новые проекты должны зависеть от библиотеки /v3.

  - **go.etcd.io/etcd/raft/v3** — реализация протокола распределённого консенсуса. Не должна содержать код, специфичный для etcd.

  - **go.etcd.io/etcd/server/v3** — реализация etcd. Код этого пакета является внутренним и не предназначен для внешних проектов. Структура пакета и API могут меняться между минорными версиями.

  - **go.etcd.io/etcd/etcdctl/v3** — инструмент командной строки для доступа к etcd и управления им.

  - **go.etcd.io/etcd/tests/v3** — модуль со всеми интеграционными тестами etcd. Обратите внимание: все модульные тесты — быстрые и не требующие межмодульных зависимостей — должны храниться в локальном модуле рядом с тестируемым кодом.

  - **go.etcd.io/bbolt** — реализация постоянного b-tree. Размещается в отдельном репозитории: https://github.com/etcd-io/bbolt.


### Операции {#operations}

1. Все модули etcd должны выпускаться с одинаковыми версиями; например,
   `go.etcd.io/etcd/client/v3@v3.5.10` должен зависеть от `go.etcd.io/etcd/api/v3@v3.5.10`.

   Согласованно обновить версии можно командой:
   ```shell script
   % DRY_RUN=false TARGET_VERSION="v3.5.10" ./scripts/release_mod.sh update_versions
   ```
2. Выпущенные модули должны получать теги по правилам https://golang.org/ref/mod#vcs-version,
   то есть каждому модулю требуется собственный тег.
   Создать теги можно командой:
   ```shell script
   % DRY_RUN=false REMOTE_REPO="origin" ./scripts/release_mod.sh push_mod_tags
   ```

3. Все модули etcd должны зависеть от одинаковых версий базовых зависимостей.
   Это проверяется командой:
   ```shell script
   % PASSES="dep" ./test.sh
   ```

4. Файлы go.mod не должны содержать неиспользуемых зависимостей и должны
   соответствовать формату `go mod tidy`.
   Проверка выполняется командой:
   ```
   % PASSES="mod_tidy" ./test.sh
   ```

5. Для запуска действий во всех модулях, например автоматического форматирования всех файлов,
   используйте или расширьте следующий скрипт:
   ```shell script
   % ./scripts/fix.sh
   ```

### Будущее {#future}

В качестве целевой модели предлагается развивать модули etcd следующим образом:

![Будущий граф модулей](/docs/etcd/dev-internal/img/modules-future.svg)

Предполагается:

  - Вынести etcdmigrate/etcdadm из бинарного файла etcdctl. Тогда etcdctl станет однозначной оболочкой командной строки над сетевым клиентским API, а etcdmigrate/etcdadm будет выполнять прямые физические операции с файлами хранилища etcd.
  - Вынести etcd-proxy из бинарного файла ./etcd: он содержит больше экспериментального кода, а значит несёт дополнительные риски и зависимости.
  - Прекратить поддержку протокола v2.