path: root/content/pages/gostyleguide/google/best-practices.md

---
weight: 30
title: Лучшие практики
---

# Лучшие практики стиля Go (Go Style Best Practices)

Оригинал: https://google.github.io/styleguide/go/best-practices

**Примечание:** Это часть серии документов, описывающих [Стиль Go (Go
Style)](https://neonxp.ru/pages/gostyleguide/google/) в Google. Данный документ **не является ни [нормативным
(normative)](https://neonxp.ru/pages/gostyleguide/google/#normative), ни [каноническим (canonical)](https://neonxp.ru/pages/gostyleguide/google/#canonical)**,
а является вспомогательным документом к [основному руководству по стилю](https://neonxp.ru/pages/gostyleguide/google/guide/).
Подробнее см. [в обзоре](https://neonxp.ru/pages/gostyleguide/google/#about).

<a id="about"></a>

## О документе (About)

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

См. [обзор](https://neonxp.ru/pages/gostyleguide/google/#about) для полного набора документов руководства по стилю.

<a id="naming"></a>

## Именование (Naming)

<a id="function-names"></a>

### Имена функций и методов

<a id="function-name-repetition"></a>

#### Избегайте повторения (Avoid repetition)

При выборе имени для функции или метода учитывайте контекст, в котором это имя
будет прочитано. Рассмотрите следующие рекомендации, чтобы избежать избыточного
[повторения (repetition)](https://neonxp.ru/pages/gostyleguide/google/decisions/#repetition) в месте вызова (call site):

- Следующее, как правило, можно опустить в именах функций и методов:
    - Типы входных и выходных данных (если нет конфликта)
    - Тип получателя (receiver) метода
    - Является ли входной или выходной параметр указателем (pointer)

- Для функций не следует [повторять имя
  пакета](https://neonxp.ru/pages/gostyleguide/google/decisions/#repetitive-with-package).

    ```go
    // Плохо:
    package yamlconfig

    func ParseYAMLConfig(input string) (*Config, error)
    ```

    ```go
    // Хорошо:
    package yamlconfig

    func Parse(input string) (*Config, error)
    ```

- Для методов не следует повторять имя получателя метода.

    ```go
    // Плохо:
    func (c *Config) WriteConfigTo(w io.Writer) (int64, error)
    ```

    ```go
    // Хорошо:
    func (c *Config) WriteTo(w io.Writer) (int64, error)
    ```

- Не повторяйте имена переменных, передаваемых в качестве параметров.

    ```go
    // Плохо:
    func OverrideFirstWithSecond(dest, source *Config) error
    ```

    ```go
    // Хорошо:
    func Override(dest, source *Config) error
    ```

- Не повторяйте имена и типы возвращаемых значений.

    ```go
    // Плохо:
    func TransformToJSON(input *Config) *jsonconfig.Config
    ```

    ```go
    // Хорошо:
    func Transform(input *Config) *jsonconfig.Config
    ```

Когда необходимо устранить неоднозначность между функциями с похожими именами,
допустимо включить дополнительную информацию.

```go
// Хорошо:
func (c *Config) WriteTextTo(w io.Writer) (int64, error)
func (c *Config) WriteBinaryTo(w io.Writer) (int64, error)
```

<a id="function-name-conventions"></a>

#### Соглашения об именовании (Naming conventions)

Существуют и другие общие соглашения при выборе имен для функций и методов:

- Функции, которые что-то возвращают, получают имена, похожие на
  существительные.

    ```go
    // Хорошо:
    func (c *Config) JobName(key string) (value string, ok bool)
    ```

    Следствием этого является то, что имена функций и методов должны [избегать
    префикса `Get`](https://neonxp.ru/pages/gostyleguide/google/decisions/#getters).

    ```go
    // Плохо:
    func (c *Config) GetJobName(key string) (value string, ok bool)
    ```

- Функции, которые что-то делают, получают имена, похожие на глаголы.

    ```go
    // Хорошо:
    func (c *Config) WriteDetail(w io.Writer) (int64, error)
    ```

- Идентичные функции, которые отличаются только типами, включают имя типа в
  конце имени.

    ```go
    // Хорошо:
    func ParseInt(input string) (int, error)
    func ParseInt64(input string) (int64, error)
    func AppendInt(buf []byte, value int) []byte
    func AppendInt64(buf []byte, value int64) []byte
    ```

    Если существует ясная "основная" версия, тип может быть опущен в имени для
    этой версии:

    ```go
    // Хорошо:
    func (c *Config) Marshal() ([]byte, error)
    func (c *Config) MarshalText() (string, error)
    ```

<a id="naming-doubles"></a>

### Тестовые дубли (Test doubles) и вспомогательные пакеты (helper packages)

Существует несколько подходов, которые можно применить для [именования] пакетов
и типов, которые предоставляют тестовые вспомогательные средства и особенно
[тестовые дубли (test doubles)]. Тестовым дублем может быть заглушка (stub),
фейк (fake), мок (mock) или шпион (spy).

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

[именование]: guide#naming
[тестовые дубли (test doubles)]: https://abseil.io/resources/swe-book/html/ch13.html#basic_concepts

Предположим, у вас есть хорошо сфокусированный пакет, предоставляющий
production-код, подобный этому:

```go
package creditcard

import (
    "errors"

    "path/to/money"
)

// ErrDeclined указывает, что эмитент отклонил операцию.
var ErrDeclined = errors.New("creditcard: declined")

// Card содержит информацию о кредитной карте, такую как эмитент,
// срок действия и лимит.
type Card struct {
    // опущено
}

// Service позволяет выполнять операции с кредитными картами через внешние
// процессинговые системы, такие как списание, авторизация, возврат средств и подписка.
type Service struct {
    // опущено
}

func (s *Service) Charge(c *Card, amount money.Money) error { /* опущено */ }
```

<a id="naming-doubles-helper-package"></a>

#### Создание вспомогательных тестовых пакетов (Creating test helper packages)

Предположим, вы хотите создать пакет, содержащий тестовые дубли для другого
пакета. Воспользуемся `package creditcard` (из примера выше):

Один из подходов — создать новый Go-пакет на основе production-пакета для
тестирования. Безопасный выбор — добавить слово `test` к оригинальному имени
пакета ("creditcard" + "test"):

```go
// Хорошо:
package creditcardtest
```

Если явно не указано иное, все примеры в следующих разделах находятся в `package
creditcardtest`.

<a id="naming-doubles-simple"></a>

#### Простой случай (Simple case)

Вы хотите добавить набор тестовых дублей для `Service`. Поскольку `Card` по сути
является простым типом данных, похожим на сообщение Protocol Buffer, он не
требует специальной обработки в тестах, поэтому дубль не нужен. Если вы ожидаете
только тестовые дубли для одного типа (например, `Service`), вы можете
использовать лаконичный подход к именованию дублей:

```go
// Хорошо:
import (
    "path/to/creditcard"
    "path/to/money"
)

// Stub заглушает creditcard.Service и не предоставляет собственного поведения.
type Stub struct{}

func (Stub) Charge(*creditcard.Card, money.Money) error { return nil }
```

Это строго предпочтительнее, чем выбор имен типа `StubService` или очень плохого
`StubCreditCardService`, потому что базовое имя пакета и его доменные типы
подразумевают, что такое `creditcardtest.Stub`.

Наконец, если пакет собирается с помощью Bazel, убедитесь, что новое правило
`go_library` для пакета помечено как `testonly`:

```build
# Хорошо:
go_library(
    name = "creditcardtest",
    srcs = ["creditcardtest.go"],
    deps = [
        ":creditcard",
        ":money",
    ],
    testonly = True,
)
```

Приведенный выше подход является общепринятым и будет достаточно хорошо понят
другими инженерами.

См. также:

- [Go Tip #42: Authoring a Stub for
  Testing](/pages/gostyleguide/google/index.html#gotip)

<a id="naming-doubles-multiple-behaviors"></a>

#### Несколько вариантов поведения тестового дубля (Multiple test double behaviors)

Когда одного вида заглушки недостаточно (например, нужна еще одна, которая
всегда завершается ошибкой), мы рекомендуем называть заглушки в соответствии с
поведением, которое они эмулируют. Здесь мы переименовываем `Stub` в
`AlwaysCharges` и вводим новую заглушку `AlwaysDeclines`:

```go
// Хорошо:
// AlwaysCharges заглушает creditcard.Service и имитирует успех.
type AlwaysCharges struct{}

func (AlwaysCharges) Charge(*creditcard.Card, money.Money) error { return nil }

// AlwaysDeclines заглушает creditcard.Service и имитирует отклоненные операции.
type AlwaysDeclines struct{}

func (AlwaysDeclines) Charge(*creditcard.Card, money.Money) error {
    return creditcard.ErrDeclined
}
```

<a id="naming-doubles-multiple-types"></a>

#### Несколько дублей для нескольких типов (Multiple doubles for multiple types)

Но теперь предположим, что `package creditcard` содержит несколько типов, для
которых стоит создавать дубли, как показано ниже с `Service` и `StoredValue`:

```go
package creditcard

type Service struct {
    // опущено
}

type Card struct {
    // опущено
}

// StoredValue управляет кредитными балансами клиентов. Это применяется, когда
// возвращенный товар зачисляется на локальный счет клиента, а не обрабатывается
// эмитентом кредитной карты. По этой причине он реализован как отдельный сервис.
type StoredValue struct {
    // опущено
}

func (s *StoredValue) Credit(c *Card, amount money.Money) error { /* опущено */ }
```

В этом случае более явное именование тестовых дублей имеет смысл:

```go
// Хорошо:
type StubService struct{}

func (StubService) Charge(*creditcard.Card, money.Money) error { return nil }

type StubStoredValue struct{}

func (StubStoredValue) Credit(*creditcard.Card, money.Money) error { return nil }
```

<a id="naming-doubles-local-variables"></a>

#### Локальные переменные в тестах (Local variables in tests)

Когда переменные в ваших тестах ссылаются на дубли, выберите имя, которое
наиболее четко отличает дубль от других production-типов, исходя из контекста.
Рассмотрим некоторый production-код, который вы хотите протестировать:

```go
package payment

import (
    "path/to/creditcard"
    "path/to/money"
)

type CreditCard interface {
    Charge(*creditcard.Card, money.Money) error
}

type Processor struct {
    CC CreditCard
}

var ErrBadInstrument = errors.New("payment: instrument is invalid or expired")

func (p *Processor) Process(c *creditcard.Card, amount money.Money) error {
    if c.Expired() {
        return ErrBadInstrument
    }
    return p.CC.Charge(c, amount)
}
```

В тестах тестовой дубль типа "шпион" (spy) для `CreditCard` противопоставляется
production-типам, поэтому добавление префикса к имени может улучшить ясность.

```go
// Хорошо:
package payment

import "path/to/creditcardtest"

func TestProcessor(t *testing.T) {
    var spyCC creditcardtest.Spy
    proc := &Processor{CC: spyCC}

    // объявления опущены: card и amount
    if err := proc.Process(card, amount); err != nil {
        t.Errorf("proc.Process(card, amount) = %v, want nil", err)
    }

    charges := []creditcardtest.Charge{
        {Card: card, Amount: amount},
    }

    if got, want := spyCC.Charges, charges; !cmp.Equal(got, want) {
        t.Errorf("spyCC.Charges = %v, want %v", got, want)
    }
}
```

Это понятнее, чем когда имя не имеет префикса.

```go
// Плохо:
package payment

import "path/to/creditcardtest"

func TestProcessor(t *testing.T) {
    var cc creditcardtest.Spy

    proc := &Processor{CC: cc}

    // объявления опущены: card и amount
    if err := proc.Process(card, amount); err != nil {
        t.Errorf("proc.Process(card, amount) = %v, want nil", err)
    }

    charges := []creditcardtest.Charge{
        {Card: card, Amount: amount},
    }

    if got, want := cc.Charges, charges; !cmp.Equal(got, want) {
        t.Errorf("cc.Charges = %v, want %v", got, want)
    }
}
```

<a id="shadowing"></a>

### Затенение (Shadowing)

**Примечание:** Это объяснение использует два неформальных термина, _stomping_ и
_shadowing_. Они не являются официальными концепциями в спецификации языка Go.

Как и во многих языках программирования, в Go есть изменяемые переменные:
присваивание переменной меняет ее значение.

```go
// Хорошо:
func abs(i int) int {
    if i < 0 {
        i *= -1
    }
    return i
}
```

При использовании [короткого объявления переменных (short variable
declarations)] с оператором `:=` в некоторых случаях новая переменная не
создается. Мы можем назвать это _stomping_ (затирание). Это допустимо, когда
исходное значение больше не нужно.

```go
// Хорошо:
// innerHandler — это вспомогательная функция для некоторого обработчика запросов, который сам
// выполняет запросы к другим бэкендам.
func (s *Server) innerHandler(ctx context.Context, req *pb.MyRequest) *pb.MyResponse {
    // Безусловно ограничиваем срок действия (deadline) для этой части обработки запроса.
    ctx, cancel := context.WithTimeout(ctx, 3*time.Second)
    defer cancel()
    ctxlog.Info(ctx, "Capped deadline in inner request")

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

    // ...
}
```

Однако будьте осторожны с использованием короткого объявления переменных в новой
области видимости: это вводит новую переменную. Мы можем назвать это _shadowing_
(затенение) исходной переменной. Код после конца блока ссылается на оригинал.
Вот ошибочная попытка условно сократить срок действия (deadline):

```go
// Плохо:
func (s *Server) innerHandler(ctx context.Context, req *pb.MyRequest) *pb.MyResponse {
    // Попытка условно ограничить срок действия.
    if *shortenDeadlines {
        ctx, cancel := context.WithTimeout(ctx, 3*time.Second)
        defer cancel()
        ctxlog.Info(ctx, "Capped deadline in inner request")
    }

    // ОШИБКА: "ctx" здесь снова означает контекст, предоставленный вызывающей стороной.
    // Вышеуказанный ошибочный код скомпилировался, потому что и ctx, и cancel
    // использовались внутри оператора if.

    // ...
}
```

Правильная версия кода может быть такой:

```go
// Хорошо:
func (s *Server) innerHandler(ctx context.Context, req *pb.MyRequest) *pb.MyResponse {
    if *shortenDeadlines {
        var cancel func()
        // Обратите внимание на использование простого присваивания, =, а не :=.
        ctx, cancel = context.WithTimeout(ctx, 3*time.Second)
        defer cancel()
        ctxlog.Info(ctx, "Capped deadline in inner request")
    }
    // ...
}
```

В случае, который мы назвали stomping, поскольку нет новой переменной, тип
присваиваемого значения должен совпадать с типом исходной переменной. При
затенении вводится совершенно новая сущность, поэтому она может иметь другой
тип. Намеренное затенение может быть полезной практикой, но вы всегда можете
использовать новое имя, если это улучшает [ясность (clarity)](https://neonxp.ru/pages/gostyleguide/google/guide/#clarity).

Не рекомендуется использовать переменные с теми же именами, что и у стандартных
пакетов, за исключением очень маленьких областей видимости, потому что это
делает функции и значения из этого пакета недоступными. И наоборот, при выборе
имени для вашего пакета избегайте имен, которые, вероятно, потребуют
[переименования импорта (import renaming)](https://neonxp.ru/pages/gostyleguide/google/decisions/#import-renaming) или
вызовут затенение иначе хороших имен переменных на стороне клиента.

```go
// Плохо:
func LongFunction() {
    url := "https://example.com/"
    // Упс, теперь мы не можем использовать net/url в коде ниже.
}
```

[короткого объявления переменных (short variable declarations)]: https://go.dev/ref/spec#Short_variable_declarations

<a id="util-packages"></a>

### Пакеты `util` (Util packages)

Пакеты Go имеют имя, указанное в объявлении `package`, отдельное от пути
импорта. Имя пакета имеет большее значение для читаемости, чем путь.

Имена пакетов Go должны быть [связаны с тем, что предоставляет
пакет](https://neonxp.ru/pages/gostyleguide/google/decisions/#package-names). Называть пакет просто `util`, `helper`,
`common` или подобным обычно плохой выбор (хотя это может быть использовано как
_часть_ имени). Неинформативные имена затрудняют чтение кода, и если они
используются слишком широко, они могут вызывать ненужные [конфликты
импорта](https://neonxp.ru/pages/gostyleguide/google/decisions/#import-renaming).

Вместо этого подумайте, как будет выглядеть место вызова (callsite).

```go
// Хорошо:
db := spannertest.NewDatabaseFromFile(...)

_, err := f.Seek(0, io.SeekStart)

b := elliptic.Marshal(curve, x, y)
```

Вы можете примерно понять, что делает каждая из этих строк, даже не зная списка
импортов (`cloud.google.com/go/spanner/spannertest`, `io` и `crypto/elliptic`).
С менее сфокусированными именами они могли бы читаться так:

```go
// Плохо:
db := test.NewDatabaseFromFile(...)

_, err := f.Seek(0, common.SeekStart)

b := helper.Marshal(curve, x, y)
```

<a id="package-size"></a>

## Размер пакета (Package size)

Если вы задаетесь вопросом, насколько большими должны быть ваши пакеты Go и
следует ли помещать связанные типы в один пакет или разделять их на разные,
хорошим началом будет [пост в блоге Go об именах пакетов][blog-pkg-names].
Несмотря на название поста, он не только об именовании. Он содержит полезные
подсказки и ссылается на несколько полезных статей и докладов.

Вот некоторые другие соображения и примечания.

Пользователи видят [godoc] для пакета на одной странице, и любые
экспортированные методы типов, предоставляемых пакетом, группируются по их типу.
Godoc также группирует конструкторы вместе с типами, которые они возвращают.
Если _клиентскому коду_ (client code) вероятно потребуется, чтобы два значения
разных типов взаимодействовали друг с другом, может быть удобно для пользователя
иметь их в одном пакете.

Код внутри пакета имеет доступ к неэкспортированным идентификаторам пакета. Если
у вас есть несколько связанных типов, _реализация_ которых тесно связана,
размещение их в одном пакете позволяет достичь этой связи без загрязнения
публичного API этими деталями. Хороший тест для этой связи — представить
гипотетического пользователя двух пакетов, где пакеты охватывают тесно связанные
темы: если пользователь должен импортировать оба пакета, чтобы использовать
любой из них хоть сколько-нибудь значимо, обычно правильным решением будет
объединить их вместе. Стандартная библиотека в целом хорошо демонстрирует такую
область видимости (scoping) и слоистость (layering).

При всем сказанном, помещение всего вашего проекта в один пакет, вероятно,
сделает этот пакет слишком большим. Когда что-то концептуально отличается,
предоставление ему собственного небольшого пакета может облегчить его
использование. Короткое имя пакета, известное клиентам, вместе с именем
экспортированного типа работают вместе, чтобы создать значимый идентификатор:
например, `bytes.Buffer`, `ring.New`. [Пост об именах пакетов][blog-pkg-names]
содержит больше примеров.

Стиль Go гибок относительно размера файлов, потому что сопровождающие могут
перемещать код внутри пакета из одного файла в другой, не влияя на вызывающую
сторону. Но в качестве общего руководства: обычно не стоит иметь один файл с
тысячами строк или множество крошечных файлов. Нет такого соглашения, как "один
тип — один файл", как в некоторых других языках. Эмпирическое правило: файлы
должны быть достаточно сфокусированными, чтобы сопровождающий мог определить, в
каком файле что-то находится, и достаточно маленькими, чтобы было легко найти
это, когда вы там окажетесь. Стандартная библиотека часто разделяет большие
пакеты на несколько исходных файлов, группируя связанный код по файлам. Исходный
код [пакета `bytes`] является хорошим примером. Пакеты с длинной документацией
могут выбрать выделение одного файла с именем `doc.go`, который содержит
[документацию пакета](https://neonxp.ru/pages/gostyleguide/google/decisions/#package-comments), объявление пакета и больше
ничего, но это не обязательно.

Внутри кодовой базы Google и в проектах, использующих Bazel, структура каталогов
для кода Go отличается от таковой в open source проектах на Go: вы можете иметь
несколько целей `go_library` в одном каталоге. Хорошей причиной для выделения
каждому пакету собственного каталога является ожидание открытия исходного кода
вашего проекта в будущем.

Несколько неканонических справочных примеров, чтобы помочь продемонстрировать
эти идеи на практике:

- маленькие пакеты, содержащие одну связную идею, которая не требует
  добавления или удаления чего-либо еще:
    - [пакет `csv`][package `csv`]: кодирование и декодирование данных CSV с
      разделением ответственности соответственно между [reader.go] и
      [writer.go].
    - [пакет `expvar`][package `expvar`]: "белый ящик" (whitebox) телеметрии
      программы, полностью содержащийся в [expvar.go].

- пакеты умеренного размера, содержащие одну большую предметную область и
  несколько связанных с ней ответственностей:
    - [пакет `flag`][package `flag`]: управление флагами командной строки,
      полностью содержащееся в [flag.go].

- большие пакеты, которые разделяют несколько тесно связанных предметных
  областей по нескольким файлам:
    - [пакет `http`][package `http`]: ядро HTTP: [client.go][http-client],
      поддержка HTTP-клиентов; [server.go][http-server], поддержка
      HTTP-серверов; [cookie.go], управление куками.
    - [пакет `os`][package `os`]: кроссплатформенные абстракции операционной
      системы: [exec.go], управление подпроцессами; [file.go], управление
      файлами; [tempfile.go], временные файлы.

См. также:

- [Пакеты тестовых дублей (Test double packages)](#naming-doubles)
- [Organizing Go Code (Blog Post)]
- [Organizing Go Code (Presentation)]

[blog-pkg-names]: https://go.dev/blog/package-names
[пакет `bytes`]: https://go.dev/src/bytes/
[Organizing Go Code (Blog Post)]: https://go.dev/blog/organizing-go-code
[Organizing Go Code (Presentation)]: https://go.dev/talks/2014/organizeio.slide
[пакет `csv`]: https://pkg.go.dev/encoding/csv
[reader.go]: https://go.googlesource.com/go/+/refs/heads/master/src/encoding/csv/reader.go
[writer.go]: https://go.googlesource.com/go/+/refs/heads/master/src/encoding/csv/writer.go
[пакет `expvar`]: https://pkg.go.dev/expvar
[expvar.go]: https://go.googlesource.com/go/+/refs/heads/master/src/expvar/expvar.go
[пакет `flag`]: https://pkg.go.dev/flag
[flag.go]: https://go.googlesource.com/go/+/refs/heads/master/src/flag/flag.go
[godoc]: https://pkg.go.dev/
[пакет `http`]: https://pkg.go.dev/net/http
[http-client]: https://go.googlesource.com/go/+/refs/heads/master/src/net/http/client.go
[http-server]: https://go.googlesource.com/go/+/refs/heads/master/src/net/http/server.go
[cookie.go]: https://go.googlesource.com/go/+/refs/heads/master/src/net/http/cookie.go
[пакет `os`]: https://pkg.go.dev/os
[exec.go]: https://go.googlesource.com/go/+/refs/heads/master/src/os/exec.go
[file.go]: https://go.googlesource.com/go/+/refs/heads/master/src/os/file.go
[tempfile.go]: https://go.googlesource.com/go/+/refs/heads/master/src/os/tempfile.go

<a id="imports"></a>

## Импорт (Imports)

<a id="import-protos"></a>

### Сообщения Protocol Buffer и заглушки (Stubs)

Импорты библиотек proto обрабатываются иначе, чем стандартные импорты Go, из-за
их межъязыковой природы. Соглашение для переименованных импортов proto основано
на правиле, которое сгенерировало пакет:

- Суффикс `pb` обычно используется для правил `go_proto_library`.
- Суффикс `grpc` обычно используется для правил `go_grpc_library`.

Часто используется одно слово, описывающее пакет:

```go
// Хорошо:
import (
    foopb "path/to/package/foo_service_go_proto"
    foogrpc "path/to/package/foo_service_go_grpc"
)
```

Следуйте рекомендациям по стилю для [имен
пакетов](/pages/gostyleguide/google/decisions#package-names).
Предпочитайте целые слова. Короткие имена хороши, но избегайте неоднозначности.
В случае сомнений используйте имя пакета proto до \_go с суффиксом pb:

```go
// Хорошо:
import (
    pushqueueservicepb "path/to/package/push_queue_service_go_proto"
)
```

**Примечание:** Предыдущие рекомендации поощряли очень короткие имена, такие как
"xpb" или даже просто "pb". Новый код должен предпочитать более описательные
имена. Существующий код, использующий короткие имена, не должен использоваться в
качестве примера, но его не нужно менять.

<a id="import-order"></a>

### Порядок импорта (Import ordering)

См. [Go Style Decisions: Группировка импортов](https://neonxp.ru/pages/gostyleguide/google/decisions/.md#import-grouping).

<a id="error-handling"></a>

## Обработка ошибок (Error handling)

В Go [ошибки — это значения (errors are values)]; они создаются кодом и
потребляются кодом. Ошибки могут быть:

- Преобразованы в диагностическую информацию для отображения человеку
- Использованы сопровождающим
- Интерпретированы конечным пользователем

Сообщения об ошибках также появляются на самых разных поверхностях, включая
сообщения журнала (log messages), дампы ошибок и отрисованные пользовательские
интерфейсы.

Код, который обрабатывает (производит или потребляет) ошибки, должен делать это
осознанно. Может возникнуть соблазн проигнорировать или слепо распространить
возвращаемое значение ошибки. Однако всегда стоит подумать, находится ли текущая
функция в стеке вызовов в наилучшей позиции для обработки ошибки. Это обширная
тема, и трудно дать категоричные рекомендации. Используйте свое суждение, но
учитывайте следующие соображения:

- Создавая значение ошибки, решите, придавать ли ему какую-либо
  [структуру](#error-structure).
- Обрабатывая ошибку, рассмотрите возможность [добавления
  информации](#error-extra-info), которая есть у вас, но которой может не быть
  у вызывающей и/или вызываемой стороны.
- См. также рекомендации по [логированию ошибок](#error-logging).

Хотя обычно нецелесообразно игнорировать ошибку, разумным исключением из этого
является оркестрация связанных операций, где часто только первая ошибка полезна.
Пакет [`errgroup`] предоставляет удобную абстракцию для группы операций, которые
могут завершиться ошибкой или быть отменены как группа.

[ошибки — это значения (errors are values)]: https://go.dev/blog/errors-are-values
[`errgroup`]: https://pkg.go.dev/golang.org/x/sync/errgroup

См. также:

- [Effective Go об ошибках](https://go.dev/doc/effective_go#errors)
- [Пост в блоге Go об ошибках](https://go.dev/blog/go1.13-errors)
- [Пакет `errors`](https://pkg.go.dev/errors)
- [Пакет
  `upspin.io/errors`](https://commandcenter.blogspot.com/2017/12/error-handling-in-upspin.html)
- [GoTip #89: When to Use Canonical Status Codes as
  Errors](/pages/gostyleguide/google/index.html#gotip)
- [GoTip #48: Error Sentinel
  Values](/pages/gostyleguide/google/index.html#gotip)
- [GoTip #13: Designing Errors for
  Checking](/pages/gostyleguide/google/index.html#gotip)

<a id="error-structure"></a>

### Структура ошибок (Error structure)

Если вызывающим сторонам необходимо анализировать ошибку (например, различать
различные условия ошибки), придайте значению ошибки структуру, чтобы это можно
было сделать программно, а не заставлять вызывающую сторону выполнять
сопоставление строк. Этот совет применим как к production-коду, так и к тестам,
которые заботятся о разных условиях ошибок.

Простейшие структурированные ошибки — это непараметризованные глобальные
значения.

```go
type Animal string

var (
    // ErrDuplicate возникает, если это животное уже было замечено.
    ErrDuplicate = errors.New("duplicate")

    // ErrMarsupial возникает, потому что у нас аллергия на сумчатых за пределами Австралии.
    // Извините.
    ErrMarsupial = errors.New("marsupials are not supported")
)

func process(animal Animal) error {
    switch {
    case seen[animal]:
        return ErrDuplicate
    case marsupial(animal):
        return ErrMarsupial
    }
    seen[animal] = true
    // ...
    return nil
}
```

Вызывающая сторона может просто сравнить возвращенное значение ошибки функции с
одним из известных значений ошибок:

```go
// Хорошо:
func handlePet(...) {
    switch err := process(an); err {
    case ErrDuplicate:
        return fmt.Errorf("feed %q: %v", an, err)
    case ErrMarsupial:
        // Попробуем восстановиться с помощью друга.
        alternate = an.BackupAnimal()
        return handlePet(..., alternate, ...)
    }
}
```

Выше используются сторожевые (sentinel) значения, где ошибка должна быть равна
(в смысле `==`) ожидаемому значению. Во многих случаях это вполне адекватно.
Если `process` возвращает обернутые ошибки (wrapped errors) (обсуждается ниже),
вы можете использовать [`errors.Is`].

```go
// Хорошо:
func handlePet(...) {
    switch err := process(an); {
    case errors.Is(err, ErrDuplicate):
        return fmt.Errorf("feed %q: %v", an, err)
    case errors.Is(err, ErrMarsupial):
        // ...
    }
}
```

Не пытайтесь различать ошибки на основе их строковой формы. (См. [GoTip #13:
Designing Errors for
Checking](/pages/gostyleguide/google/index.html#gotip) для получения
дополнительной информации.)

```go
// Плохо:
func handlePet(...) {
    err := process(an)
    if regexp.MatchString(`duplicate`, err.Error()) {...}
    if regexp.MatchString(`marsupial`, err.Error()) {...}
}
```

Если в ошибке есть дополнительная информация, которая нужна вызывающей стороне
программно, ее, в идеале, следует представить структурно. Например, тип
[`os.PathError`] документирован так, что помещает путь к операции, завершившейся
неудачей, в поле структуры, к которому вызывающая сторона может легко получить
доступ.

Могут использоваться и другие структуры ошибок, например, структура проекта,
содержащая код ошибки и строку с деталями. [Пакет `status`][status] —
распространенная инкапсуляция; если вы выбираете этот подход (вы не обязаны это
делать), используйте [канонические коды (canonical codes)]. См. [GoTip #89:
When to Use Canonical Status Codes as
Errors](/pages/gostyleguide/google/index.html#gotip) чтобы понять,
является ли использование кодов статуса правильным выбором.

[`os.PathError`]: https://pkg.go.dev/os#PathError
[`errors.Is`]: https://pkg.go.dev/errors#Is
[`errors.As`]: https://pkg.go.dev/errors#As
[`package cmp`]: https://pkg.go.dev/github.com/google/go-cmp/cmp
[status]: https://pkg.go.dev/google.golang.org/grpc/status
[канонические коды (canonical codes)]: https://pkg.go.dev/google.golang.org/grpc/codes

<a id="error-extra-info"></a>

### Добавление информации к ошибкам (Adding information to errors)

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

```go
// Хорошо:
if err := os.Open("settings.txt"); err != nil {
  return fmt.Errorf("launch codes unavailable: %v", err)
}

// Вывод:
//
// launch codes unavailable: open settings.txt: no such file or directory
```

Здесь "launch codes unavailable" добавляет конкретный смысл ошибке `os.Open`,
релевантный для контекста текущей функции, без дублирования информации о пути к
файлу.

```go
// Плохо:
if err := os.Open("settings.txt"); err != nil {
  return fmt.Errorf("could not open settings.txt: %v", err)
}

// Вывод:
//
// could not open settings.txt: open settings.txt: no such file or directory
```

Не добавляйте аннотацию, если ее единственная цель — указать на сбой без
добавления новой информации. Наличие ошибки достаточно передает сбой вызывающей
стороне.

```go
// Плохо:
return fmt.Errorf("failed: %v", err) // просто верните err вместо этого
```

[Выбор между `%v` и `%w` при оборачивании ошибок (wrapping
errors)](https://go.dev/blog/go1.13-errors#whether-to-wrap) с помощью
`fmt.Errorf` — это тонкое решение, которое значительно влияет на то, как ошибки
распространяются, обрабатываются, проверяются и документируются в вашем
приложении. Основной принцип — сделать значения ошибок полезными для их
наблюдателей, будь то люди или код.

1.  **`%v` для простой аннотации или новой ошибки**

    Глагол `%v` — это ваш универсальный инструмент для строкового форматирования
    любого значения Go, включая ошибки. При использовании с `fmt.Errorf` он
    встраивает строковое представление ошибки (то, что возвращает ее метод
    `Error()`) в новое значение ошибки, отбрасывая любую структурированную
    информацию из исходной ошибки. Примеры использования `%v`:
    - Добавление интересного, не избыточного контекста: как в примере выше.

    - Логирование или отображение ошибок: Когда основная цель — представить
      удобочитаемое сообщение об ошибке в журналах или пользователю, и вы не
      планируете, чтобы вызывающая сторона программно проверяла ошибку с
      помощью `errors.Is` или `errors.As` (Примечание: `errors.Unwrap` здесь,
      как правило, не рекомендуется, так как он не обрабатывает множественные
      ошибки (multi-errors)).

    - Создание новых, независимых ошибок: Иногда необходимо преобразовать
      ошибку в новое сообщение об ошибке, тем самым скрывая специфику исходной
      ошибки. Эта практика особенно полезна на границах систем, включая,
      помимо прочего, RPC, IPC и хранилища, где мы переводим
      доменно-специфичные ошибки в каноническое пространство ошибок.

        ```go
        // Хорошо:
        func (*FortuneTeller) SuggestFortune(context.Context, *pb.SuggestionRequest) (*pb.SuggestionResponse, error) {
          // ...
          if err != nil {
            return nil, fmt.Errorf("couldn't find fortune database: %v", err)
          }
        }
        ```

        Мы также могли бы явно аннотировать RPC код `Internal` в примере выше.

        ```go
        // Хорошо:
        import (
          "google.golang.org/grpc/codes"
          "google.golang.org/grpc/status"
        )

        func (*FortuneTeller) SuggestFortune(context.Context, *pb.SuggestionRequest) (*pb.SuggestionResponse, error) {
          // ...
          if err != nil {
            // Или используйте fmt.Errorf с глаголом %w, если намеренно оборачиваете ошибку,
            // которую вызывающая сторона должна развернуть (unwrap).
            return nil, status.Errorf(codes.Internal, "couldn't find fortune database", status.ErrInternal)
          }
        }
        ```

1.  **`%w` (wrap) для программной проверки и цепочки ошибок (error chaining)**

        Глагол `%w` специально предназначен для оборачивания ошибок (error
        wrapping). Он создает новую ошибку, которая предоставляет метод `Unwrap()`,
        позволяя вызывающим сторонам программно проверять цепочку ошибок с помощью
        `errors.Is` и `errors.As`. Примеры использования `%w`:
        - Добавление контекста с сохранением исходной ошибки для программной
          проверки: Это основной случай использования во вспомогательных функциях
          (helpers) вашего приложения. Вы хотите обогатить ошибку дополнительным
          контекстом (например, какая операция выполнялась, когда она завершилась
          неудачей), но при этом позволить вызывающей стороне проверить, является
          ли лежащая в основе ошибка конкретной сторожевой ошибкой или типом.

            ```go
            // Хорошо:
            func (s *Server) internalFunction(ctx context.Context) error {
              // ...
              if err != nil {
                return fmt.Errorf("couldn't find remote file: %w", err)
              }
            }
            ```

            Это позволяет функции более высокого уровня выполнить `errors.Is(err,

    fs.ErrNotExist)`, даже если исходная ошибка была обернута.

            В точках, где ваша система взаимодействует с внешними системами, такими
            как RPC, IPC или хранилище, часто лучше переводить доменно-специфичные
            ошибки в стандартизированное пространство ошибок (например, коды статуса
            gRPC), а не просто оборачивать исходную ошибку с помощью `%w`. Клиента
            обычно не волнует точная внутренняя ошибка файловой системы; их волнует
            канонический результат (например, `Internal`, `NotFound`,
            `PermissionDenied`).

        - Когда вы явно документируете и тестируете лежащие в основе ошибки,
          которые вы раскрываете: Если API вашего пакета гарантирует, что
          определенные лежащие в основе ошибки могут быть развернуты и проверены
          вызывающими сторонами (например, "эта функция может вернуть
          `ErrInvalidConfig`, обернутый в более общую ошибку"), то `%w` уместен.
          Это становится частью контракта вашего пакета.

См. также:

- [Соглашения по документации ошибок (Error Documentation
  Conventions)](#documentation-conventions-errors)
- [Пост в блоге об оборачивании ошибок](https://blog.golang.org/go1.13-errors)

<a id="error-percent-w"></a>

### Размещение `%w` в ошибках (Placement of %w in errors)

Предпочитайте размещать `%w` в конце строки ошибки _если_ вы используете
[оборачивание ошибок (error wrapping)](https://go.dev/blog/go1.13-errors) с
глаголом форматирования `%w`.

Ошибки могут быть обернуты с помощью глагола `%w` или путем помещения их в
[структурированную
ошибку](/pages/gostyleguide/google/index.html#gotip), которая
реализует `Unwrap() error` (например,
[`fs.PathError`](https://pkg.go.dev/io/fs#PathError)).

Обернутые ошибки образуют цепочки ошибок (error chains): каждый новый слой
обертывания добавляет новую запись в начало цепочки ошибок. Цепочку ошибок можно
обойти с помощью метода `Unwrap() error`. Например:

```go
err1 := fmt.Errorf("err1")
err2 := fmt.Errorf("err2: %w", err1)
err3 := fmt.Errorf("err3: %w", err2)
```

Это формирует цепочку ошибок следующего вида:

```mermaid
flowchart LR
  err3 == err3 wraps err2 ==> err2;
  err2 == err2 wraps err1 ==> err1;
```

Независимо от того, где размещен глагол `%w`, возвращаемая ошибка всегда
представляет начало цепочки ошибок, а `%w` — это следующий дочерний элемент.
Аналогично, `Unwrap() error` всегда обходит цепочку ошибок от самой новой к
самой старой ошибке.

Однако размещение глагола `%w` влияет на то, печатается ли цепочка ошибок от
самой новой к самой старой, от самой старой к самой новой или ни то, ни другое:

```go
// Хорошо:
err1 := fmt.Errorf("err1")
err2 := fmt.Errorf("err2: %w", err1)
err3 := fmt.Errorf("err3: %w", err2)
fmt.Println(err3) // err3: err2: err1
// err3 — это цепочка ошибок от самой новой к самой старой, которая печатается от самой новой к самой старой.
```

```go
// Плохо:
err1 := fmt.Errorf("err1")
err2 := fmt.Errorf("%w: err2", err1)
err3 := fmt.Errorf("%w: err3", err2)
fmt.Println(err3) // err1: err2: err3
// err3 — это цепочка ошибок от самой новой к самой старой, которая печатается от самой старой к самой новой.
```

```go
// Плохо:
err1 := fmt.Errorf("err1")
err2 := fmt.Errorf("err2-1 %w err2-2", err1)
err3 := fmt.Errorf("err3-1 %w err3-2", err2)
fmt.Println(err3) // err3-1 err2-1 err1 err2-2 err3-2
// err3 — это цепочка ошибок от самой новой к самой старой, которая печатается ни от самой новой к самой старой,
// ни от самой старой к самой новой.
```

Поэтому, чтобы текст ошибки отражал структуру цепочки ошибок, предпочитайте
размещать глагол `%w` в конце в форме `[...]: %w`.

<a id="error-logging"></a>

### Логирование ошибок (Logging errors)

Иногда функциям необходимо сообщить внешней системе об ошибке, не передавая ее
своим вызывающим сторонам. Логирование — очевидный выбор здесь; но будьте
внимательны к тому, что и как вы логируете.

- Как и [хорошие сообщения о неудачных тестах (good test failure messages)],
  сообщения журнала должны четко выражать, что пошло не так, и помогать
  сопровождающему, включая соответствующую информацию для диагностики
  проблемы.

- Избегайте дублирования. Если вы возвращаете ошибку, обычно лучше не
  логировать ее самостоятельно, а позволить вызывающей стороне обработать ее.
  Вызывающая сторона может выбрать логирование ошибки или, возможно,
  ограничить частоту логирования с помощью [`rate.Sometimes`]. Другие варианты
  включают попытку восстановления или даже [остановку программы]. В любом
  случае, предоставление контроля вызывающей стороне помогает избежать спама в
  журналах.

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

- Будьте осторожны с [PII]. Многие приемники журналов (log sinks) не являются
  подходящими местами назначения для конфиденциальной информации конечных
  пользователей.

- Используйте `log.Error` скупо. Логирование уровня ERROR вызывает сброс
  (flush) и является более дорогостоящим, чем более низкие уровни логирования.
  Это может серьезно повлиять на производительность вашего кода. Принимая
  решение между уровнями error и warning, учитывайте лучшую практику:
  сообщения на уровне error должны быть actionable (то есть требовать
  действий), а не просто "более серьезными", чем warning.

- Внутри Google у нас есть системы мониторинга, которые можно настроить для
  более эффективного оповещения, чем просто запись в файл журнала в надежде,
  что кто-то его заметит. Это похоже, но не идентично стандартной библиотеке
  [пакету `expvar`].

[хорошие сообщения о неудачных тестах (good test failure messages)]: /pages/gostyleguide/google/decisions#useful-test-failures
[остановку программы]: #checks-and-panics
[`rate.Sometimes`]: https://pkg.go.dev/golang.org/x/time/rate#Sometimes
[PII]: https://en.wikipedia.org/wiki/Personal_data
[пакет `expvar`]: https://pkg.go.dev/expvar

<a id="vlog"></a>

#### Пользовательские уровни детализации (Custom verbosity levels)

Используйте детальное логирование ([`log.V`]) с пользой. Детальное логирование
может быть полезно для разработки и трассировки. Установление соглашения об
уровнях детализации может быть полезным. Например:

- Записывайте небольшое количество дополнительной информации на `V(1)`
- Трассируйте больше информации на `V(2)`
- Выводите большие внутренние состояния на `V(3)`

Чтобы минимизировать стоимость детального логирования, вы должны убедиться, что
случайно не вызываете дорогие функции, даже когда `log.V` выключен. `log.V`
предлагает два API. Более удобный из них несет риск этих случайных затрат. В
случае сомнений используйте немного более многословный стиль.

```go
// Хорошо:
for _, sql := range queries {
  log.V(1).Infof("Handling %v", sql)
  if log.V(2) {
    log.Infof("Handling %v", sql.Explain())
  }
  sql.Run(...)
}
```

```go
// Плохо:
// sql.Explain вызывается даже когда это сообщение не печатается.
log.V(2).Infof("Handling %v", sql.Explain())
```

[`log.V`]: https://pkg.go.dev/github.com/golang/glog#V

<a id="program-init"></a>

### Инициализация программы (Program initialization)

Ошибки инициализации программы (например, неправильные флаги и конфигурация)
должны передаваться вверх в `main`, который должен вызвать `log.Exit` с ошибкой,
объясняющей, как исправить ошибку. В этих случаях `log.Fatal` обычно не следует
использовать, потому что трассировка стека, указывающая на проверку, вряд ли
будет так полезна, как сгенерированное человеком, actionable сообщение.

<a id="checks-and-panics"></a>

### Проверки программы и паники (Program checks and panics)

Как указано в [решении против паник (decision against panics)], стандартная
обработка ошибок должна быть структурирована вокруг возвращаемых значений
ошибок. Библиотеки должны предпочитать возвращать ошибку вызывающей стороне, а
не завершать программу, особенно для временных ошибок.

Иногда необходимо выполнить проверку согласованности (consistency check)
инварианта и завершить программу, если он нарушен. Как правило, это делается
только в том случае, если сбой проверки инварианта означает, что внутреннее
состояние стало невосстановимым. Наиболее надежный способ сделать это в кодовой
базе Google — вызвать `log.Fatal`. Использование `panic` в этих случаях
ненадежно, потому что возможно, что отложенные (deferred) функции заблокируют
или еще больше повредят внутреннее или внешнее состояние.

Аналогично, сопротивляйтесь искушению восстановить паники (recover panics),
чтобы избежать сбоев, так как это может привести к распространению поврежденного
состояния. Чем дальше вы от паники, тем меньше вы знаете о состоянии программы,
которая может удерживать блокировки или другие ресурсы. Затем программа может
развить другие неожиданные режимы сбоев, которые могут еще больше затруднить
диагностику проблемы. Вместо того чтобы пытаться обрабатывать неожиданные паники
в коде, используйте инструменты мониторинга для выявления неожиданных сбоев и
исправляйте связанные ошибки с высоким приоритетом.

**Примечание:** Стандартный [`net/http` server] нарушает этот совет и
восстанавливает паники из обработчиков запросов. Консенсус среди опытных
инженеров Go заключается в том, что это была историческая ошибка. Если вы
исследуете журналы серверов приложений на других языках, часто можно найти
большие трассировки стека, которые остаются необработанными. Избегайте этой
ловушки в своих серверах.

[решении против паник (decision against panics)]: /pages/gostyleguide/google/decisions#dont-panic
[`net/http` server]: https://pkg.go.dev/net/http#Server

<a id="when-to-panic"></a>

### Когда использовать panic (When to panic)

Стандартная библиотека вызывает panic при неправильном использовании API.
Например, [`reflect`] вызывает panic во многих случаях, когда значение доступно
таким образом, что предполагает его неправильную интерпретацию. Это аналогично
паникам на ошибки ядра языка, такие как доступ к элементу среза вне его границ.
Проверка кода и тесты должны обнаруживать такие ошибки, которые не ожидаются в
production-коде. Эти паники действуют как проверки инвариантов, которые не
зависят от библиотеки, поскольку стандартная библиотека не имеет доступа к
[уровневому пакету `log`], который используется в кодовой базе Google.

[`reflect`]: https://pkg.go.dev/reflect
[уровневому пакету `log`]: decisions#logging

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

Ключевой атрибут этого дизайна заключается в том, что эти **паники никогда не
должны выходить за границы пакета** и не должны быть частью API пакета. Обычно
это достигается с помощью функции верхнего уровня с отложенным вызовом
(deferred), которая использует `recover` для преобразования распространенной
паники в возвращаемую ошибку на публичной границе API. Это требует, чтобы код,
который вызывает panic и восстанавливается, отличал паники, которые код вызывает
сам, от тех, которые он не вызывает:

```go
// Хорошо:
type syntaxError struct {
  msg string
}

func parseInt(in string) int {
  n, err := strconv.Atoi(in)
  if err != nil {
    panic(&syntaxError{"not a valid integer"})
  }
}

func Parse(in string) (_ *Node, err error) {
  defer func() {
    if p := recover(); p != nil {
      sErr, ok := p.(*syntaxError)
      if !ok {
        panic(p) // Распространяем panic, поскольку он находится вне области нашего кода.
      }
      err = fmt.Errorf("syntax error: %v", sErr.msg)
    }
  }()
  ... // Парсим входные данные, вызывая parseInt внутри для парсинга целых чисел
}
```

> **Предупреждение:** Код, использующий этот шаблон, должен позаботиться об
> управлении любыми ресурсами, связанными с кодом, запущенным в таких разделах,
> управляемых defer (например, закрыть, освободить или разблокировать).
>
> См.: [Go Tip #81: Avoiding Resource Leaks in API Design]

Паника также используется, когда компилятор не может идентифицировать
недостижимый код, например, при использовании функции типа `log.Fatal`, которая
не вернется:

```go
// Хорошо:
func answer(i int) string {
    switch i {
    case 42:
        return "yup"
    case 54:
        return "base 13, huh"
    default:
        log.Fatalf("Sorry, %d is not the answer.", i)
        panic("unreachable")
    }
}
```

[Не вызывайте функции `log` до того, как флаги будут
распарсены.](https://pkg.go.dev/github.com/golang/glog#pkg-overview) Если вы
должны завершиться в функции инициализации пакета (в `init` или
["must"-функции](https://neonxp.ru/pages/gostyleguide/google/decisions/#must-functions)), panic допустима вместо вызова
фатального логирования.

См. также:

- [Handling panics](https://go.dev/ref/spec#Handling_panics) и [Run-time
  Panics](https://go.dev/ref/spec#Run_time_panics) в спецификации языка
- [Defer, Panic, and Recover](https://go.dev/blog/defer-panic-and-recover)
- [On the uses and misuses of panics in
  Go](https://eli.thegreenplace.net/2018/on-the-uses-and-misuses-of-panics-in-go/)

[Go Tip #81: Avoiding Resource Leaks in API Design]: /pages/gostyleguide/google/index.html#gotip

<a id="documentation"></a>

## Документация (Documentation)

<a id="documentation-conventions"></a>

### Соглашения (Conventions)

Этот раздел дополняет раздел [комментариев (commentary)] в документе решений.

Код на Go, который документирован в знакомом стиле, легче читать и менее
вероятно, что его будут использовать неправильно, по сравнению с тем, что плохо
задокументировано или не задокументировано вовсе. Запускаемые [примеры
(examples)] появляются в Godoc и Code Search и являются отличным способом
объяснить, как использовать ваш код.

[комментариев (commentary)]: decisions#commentary
[примеры (examples)]: decisions#examples

<a id="documentation-conventions-params"></a>

#### Параметры и конфигурация (Parameters and configuration)

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

- параметрам функций и методов
- полям структур (struct fields)
- API для опций (options)

Документируйте подверженные ошибкам или неочевидные поля и параметры, объясняя,
почему они интересны.

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

```go
// Плохо:
// Sprintf форматирует в соответствии со спецификатором формата и возвращает результирующую строку.
//
// format — это формат, а data — данные для интерполяции.
func Sprintf(format string, data ...any) string
```

Однако этот фрагмент демонстрирует сценарий кода, похожий на предыдущий, где
комментарий вместо этого говорит что-то неочевидное или существенно полезное для
читателя:

```go
// Хорошо:
// Sprintf форматирует в соответствии со спецификатором формата и возвращает результирующую строку.
//
// Предоставленные данные используются для интерполяции строки формата. Если данные не соответствуют
// ожидаемым глаголам формата или количество данных не удовлетворяет спецификации формата,
// функция будет встраивать предупреждения об ошибках форматирования в выходную строку, как описано
// в разделе "Format errors" выше.
func Sprintf(format string, data ...any) string
```

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

См. также:

- [GoTip #41: Identify Function Call Parameters]
- [GoTip #51: Patterns for Configuration]

[GoTip #41: Identify Function Call Parameters]: /pages/gostyleguide/google/index.html#gotip
[GoTip #51: Patterns for Configuration]: /pages/gostyleguide/google/index.html#gotip

<a id="documentation-conventions-contexts"></a>

#### Контексты (Contexts)

Подразумевается, что отмена (cancellation) аргумента контекста прерывает
функцию, которой он предоставлен. Если функция может возвращать ошибку, по
соглашению это `ctx.Err()`.

Этот факт не нужно повторять:

```go
// Плохо:
// Run выполняет рабочий цикл (run loop) воркера.
//
// Метод будет обрабатывать работу до отмены контекста и соответственно возвращает ошибку.
func (Worker) Run(ctx context.Context) error
```

Поскольку это подразумевается, следующее лучше:

```go
// Хорошо:
// Run выполняет рабочий цикл воркера.
func (Worker) Run(ctx context.Context) error
```

Когда поведение контекста отличается или неочевидно, его следует прямо
задокументировать, если верно любое из следующего.

- Функция возвращает ошибку, отличную от `ctx.Err()`, когда контекст отменен:

    ```go
    // Хорошо:
    // Run выполняет рабочий цикл воркера.
    //
    // Если контекст отменен, Run возвращает nil ошибку.
    func (Worker) Run(ctx context.Context) error
    ```

- Функция имеет другие механизмы, которые могут ее прервать или повлиять на
  время жизни:

    ```go
    // Хорошо:
    // Run выполняет рабочий цикл воркера.
    //
    // Run обрабатывает работу до отмены контекста или вызова Stop.
    // Отмена контекста обрабатывается асинхронно внутри: run может вернуться до того,
    // как вся работа остановится. Метод Stop является синхронным и ожидает завершения
    // всех операций из рабочего цикла. Используйте Stop для плавного завершения работы.
    func (Worker) Run(ctx context.Context) error

    func (Worker) Stop()
    ```

- Функция имеет особые ожидания относительно времени жизни контекста, его
  происхождения (lineage) или прикрепленных значений (attached values):

    ```go
    // Хорошо:
    // NewReceiver начинает получать сообщения, отправленные в указанную очередь.
    // Контекст не должен иметь дедлайна (deadline).
    func NewReceiver(ctx context.Context) *Receiver

    // Principal возвращает человеко-читаемое имя стороны, совершившей вызов.
    // Контекст должен иметь прикрепленное к нему значение из security.NewContext.
    func Principal(ctx context.Context) (name string, ok bool)
    ```

    **Предупреждение:** Избегайте разработки API, которые предъявляют такие
    требования (например, отсутствие дедлайнов у контекстов) от своих вызывающих
    сторон. Вышеприведенное — лишь пример того, как это задокументировать, если
    этого нельзя избежать, а не одобрение такого шаблона.

<a id="documentation-conventions-concurrency"></a>

#### Параллелизм (Concurrency)

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

Дополнительное замечание о параллелизме можно безопасно удалить в этой Godoc:

```go
// Хорошо:
// Len возвращает количество байт непрочитанной части буфера;
// b.Len() == len(b.Bytes()).
//
// Безопасно для вызова несколькими горутинами одновременно.
func (*Buffer) Len() int
```

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

Аналогично, дополнительное замечание о параллелизме можно безопасно удалить
здесь:

```go
// Хорошо:
// Grow увеличивает емкость буфера.
//
// Не безопасно для вызова несколькими горутинами одновременно.
func (*Buffer) Grow(n int)
```

Настоятельно рекомендуется документировать, если верно любое из следующего.

- Непонятно, является ли операция доступной только для чтения или мутирующей:

    ```go
    // Хорошо:
    package lrucache

    // Lookup возвращает данные, связанные с ключом, из кэша.
    //
    // Эта операция не безопасна для параллельного использования.
    func (*Cache) Lookup(key string) (data []byte, ok bool)
    ```

    Почему? При попадании в кэш (cache hit) при поиске ключа внутреннее
    состояние LRU-кэша мутирует. Как это реализовано, может быть неочевидно для
    всех читателей.

- Синхронизация предоставляется API:

    ```go
    // Хорошо:
    package fortune_go_proto

    // NewFortuneTellerClient возвращает *rpc.Client для сервиса FortuneTeller.
    // Безопасно для одновременного использования несколькими горутинами.
    func NewFortuneTellerClient(cc *rpc.ClientConn) *FortuneTellerClient
    ```

    Почему? Stubby предоставляет синхронизацию.

    **Примечание:** Если API является типом и API предоставляет синхронизацию в
    целом, по соглашению только определение типа документирует семантику.

- API потребляет пользовательские реализации типов или интерфейсов, и
  потребитель интерфейса имеет особые требования к параллелизму:

    ```go
    // Хорошо:
    package health

    // Watcher сообщает о состоянии здоровья некоторой сущности (обычно серверной службы).
    //
    // Методы Watcher безопасны для одновременного использования несколькими горутинами.
    type Watcher interface {
        // Watch отправляет true на переданный канал, когда статус Watcher изменился.
        Watch(changed chan<- bool) (unwatch func())

        // Health возвращает nil, если за которой следят сущность здорова, или
        // ненулевую ошибку, объясняющую, почему сущность нездорова.
        Health() error
    }
    ```

    Почему? Является ли API безопасным для использования несколькими горутинами
    — это часть его контракта.

<a id="documentation-conventions-cleanup"></a>

#### Очистка (Cleanup)

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

Указывайте очистки, которые зависят от вызывающей стороны:

```go
// Хорошо:
// NewTicker возвращает новый Ticker, содержащий канал, который будет отправлять
// текущее время на канал после каждого тика.
//
// Вызовите Stop, чтобы освободить ресурсы, связанные с Ticker, когда закончите.
func NewTicker(d Duration) *Ticker

func (*Ticker) Stop()
```

Если может быть неясно, как очистить ресурсы, объясните, как:

```go
// Хорошо:
// Get выполняет GET к указанному URL.
//
// Когда err равен nil, resp всегда содержит ненулевой resp.Body.
// Вызывающая сторона должна закрыть resp.Body, когда закончит читать из него.
//
//    resp, err := http.Get("http://example.com/")
//    if err != nil {
//        // обработать ошибку
//    }
//    defer resp.Body.Close()
//    body, err := io.ReadAll(resp.Body)
func (c *Client) Get(url string) (resp *Response, err error)
```

См. также:

- [GoTip #110: Don’t Mix Exit With Defer]

[GoTip #110: Don’t Mix Exit With Defer]: /pages/gostyleguide/google/index.html#gotip

<a id="documentation-conventions-errors"></a>

#### Ошибки (Errors)

Документируйте значимые сторожевые значения ошибок (error sentinel values) или
типы ошибок, которые ваши функции возвращают вызывающим сторонам, чтобы
вызывающие стороны могли предвидеть, какие типы условий они могут обработать в
своем коде.

```go
// Хорошо:
package os

// Read читает до len(b) байт из File и сохраняет их в b. Он возвращает
// количество прочитанных байт и любую встреченную ошибку.
//
// При достижении конца файла Read возвращает 0, io.EOF.
func (*File) Read(b []byte) (n int, err error) {
```

Когда функция возвращает определенный тип ошибки, правильно укажите, является ли
ошибка указателем (pointer receiver) или нет:

```go
// Хорошо:
package os

type PathError struct {
    Op   string
    Path string
    Err  error
}

// Chdir меняет текущий рабочий каталог на указанный каталог.
//
// Если есть ошибка, она будет типа *PathError.
func Chdir(dir string) error {
```

Документирование того, являются ли возвращаемые значения указателями, позволяет
вызывающим сторонам правильно сравнивать ошибки с помощью [`errors.Is`],
[`errors.As`] и [`package cmp`]. Это связано с тем, что не указатель
(non-pointer value) не эквивалентен указателю (pointer value).

**Примечание:** В примере `Chdir` тип возвращаемого значения записан как
`error`, а не `*PathError`, из-за [как работают нулевые значения интерфейса (nil
interface values)](https://go.dev/doc/faq#nil_error).

Документируйте общие соглашения об ошибках в [документации
пакета](https://neonxp.ru/pages/gostyleguide/google/decisions/#package-comments), когда поведение применимо к большинству
ошибок, встречающихся в пакете:

```go
// Хорошо:
// Пакет os предоставляет независимый от платформы интерфейс к функциям операционной системы.
//
// Часто доступно больше информации внутри ошибки. Например, если вызов, принимающий имя файла,
// завершается неудачей, такой как Open или Stat, ошибка будет включать имя файла, которое
// не удалось, когда она печатается, и будет иметь тип *PathError, который может быть распакован
// для получения дополнительной информации.
package os
```

Вдумчивое применение этих подходов может добавить [дополнительную информацию к
ошибкам](#error-extra-info) без особых усилий и помочь вызывающим сторонам
избежать добавления избыточных аннотаций.

См. также:

- [Go Tip #106: Error Naming
  Conventions](/pages/gostyleguide/google/index.html#gotip)
- [Go Tip #89: When to Use Canonical Status Codes as
  Errors](/pages/gostyleguide/google/index.html#gotip)

<a id="documentation-preview"></a>

### Предварительный просмотр (Preview)

Go имеет [сервер
документации](https://pkg.go.dev/golang.org/x/pkgsite/cmd/pkgsite).
Рекомендуется предварительно просматривать документацию, которую производит ваш
код, как до, так и во время процесса ревью кода. Это помогает проверить, что
[форматирование godoc] отображается правильно.

[форматирование godoc]: #godoc-formatting

<a id="godoc-formatting"></a>

### Форматирование Godoc (Godoc formatting)

[Godoc] предоставляет специальный синтаксис для [форматирования документации].

- Требуется пустая строка для разделения абзацев:

    ```go
    // Хорошо:
    // LoadConfig читает конфигурацию из указанного файла.
    //
    // См. some/shortlink для подробностей о формате файла конфигурации.
    ```

- Файлы тестов могут содержать [запускаемые примеры (runnable examples)],
  которые появляются прикрепленными к соответствующей документации в godoc:

    ```go
    // Хорошо:
    func ExampleConfig_WriteTo() {
      cfg := &Config{
        Name: "example",
      }
      if err := cfg.WriteTo(os.Stdout); err != nil {
        log.Exitf("Failed to write config: %s", err)
      }
      // Output:
      // {
      //   "name": "example"
      // }
    }
    ```

- Отступ строк на два дополнительных пробела форматирует их буквально
  (verbatim):

    ```go
    // Хорошо:
    // Update выполняет функцию в атомарной транзакции.
    //
    // Обычно это используется с анонимной TransactionFunc:
    //
    //   if err := db.Update(func(state *State) { state.Foo = bar }); err != nil {
    //     //...
    //   }
    ```

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

    Это буквальное форматирование может быть использовано для форматирования, не
    родного для godoc, такого как списки и таблицы:

    ```go
    // Хорошо:
    // LoadConfig читает конфигурацию из указанного файла.
    //
    // LoadConfig обрабатывает следующие ключи особым образом:
    //   "import" заставит эту конфигурацию наследовать из указанного файла.
    //   "env" если присутствует, будет заполнен системным окружением.
    ```

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

    ```go
    // Хорошо:
    // Следующая строка форматируется как заголовок.
    //
    // Использование заголовков
    //
    // Заголовки поставляются с автоматически сгенерированными якорными тегами для удобного связывания.
    ```

[Godoc]: https://pkg.go.dev/
[форматирования документации]: https://go.dev/doc/comment
[запускаемые примеры (runnable examples)]: decisions#examples

<a id="signal-boost"></a>

### Усиление сигнала (Signal boosting)

Иногда строка кода выглядит как нечто обычное, но на самом деле это не так. Один
из лучших примеров этого — проверка `err == nil` (поскольку `err != nil`
встречается гораздо чаще). Следующие две условные проверки трудно различить:

```go
// Хорошо:
if err := doSomething(); err != nil {
    // ...
}
```

```go
// Плохо:
if err := doSomething(); err == nil {
    // ...
}
```

Вы можете вместо этого "усилить" сигнал условного оператора, добавив
комментарий:

```go
// Хорошо:
if err := doSomething(); err == nil { // если ошибки НЕТ
    // ...
}
```

Комментарий привлекает внимание к различию в условном операторе.

<a id="vardecls"></a>

## Объявление переменных (Variable declarations)

<a id="vardeclinitialization"></a>

### Инициализация (Initialization)

Для единообразия предпочитайте `:=` вместо `var` при инициализации новой
переменной ненулевым значением.

```go
// Хорошо:
i := 42
```

```go
// Плохо:
var i = 42
```

<a id="vardeclzero"></a>

### Объявление переменных с нулевыми значениями (Declaring variables with zero values)

Следующие объявления используют [нулевое значение (zero value)]:

```go
// Хорошо:
var (
    coords Point
    magic  [4]byte
    primes []int
)
```

[нулевое значение (zero value)]: https://golang.org/ref/spec#The_zero_value

Вы должны объявлять значения, используя нулевое значение, когда хотите передать
пустое значение, которое **готово к использованию позже**. Использование
составных литералов (composite literals) с явной инициализацией может быть
громоздким:

```go
// Плохо:
var (
    coords = Point{X: 0, Y: 0}
    magic  = [4]byte{0, 0, 0, 0}
    primes = []int(nil)
)
```

Распространенное применение объявления с нулевым значением — когда переменная
используется как выход при демаршалинге (unmarshalling):

```go
// Хорошо:
var coords Point
if err := json.Unmarshal(data, &coords); err != nil {
```

Также допустимо использовать нулевое значение в следующей форме, когда вам нужна
переменная типа указателя:

```go
// Хорошо:
msg := new(pb.Bar) // или "&pb.Bar{}"
if err := proto.Unmarshal(data, msg); err != nil {
```

Если в вашей структуре нужна блокировка (lock) или другое поле, которое [не
должно копироваться](https://neonxp.ru/pages/gostyleguide/google/decisions/#copying), вы можете сделать его типом значения
(value type), чтобы воспользоваться преимуществами инициализации нулевым
значением. Это означает, что содержащий тип теперь должен передаваться по
указателю, а не по значению. Методы этого типа должны принимать
получатели-указатели (pointer receivers).

```go
// Хорошо:
type Counter struct {
    // Это поле не обязательно должно быть "*sync.Mutex". Однако
    // пользователи теперь должны передавать *Counter объекты между собой, а не Counter.
    mu   sync.Mutex
    data map[string]int64
}

// Обратите внимание, что это должен быть получатель-указатель, чтобы предотвратить копирование.
func (c *Counter) IncrementBy(name string, n int64)
```

Допустимо использовать типы значений для локальных переменных составных типов
(таких как структуры и массивы), даже если они содержат такие некопируемые поля.
Однако, если составной тип возвращается функцией, или если все обращения к нему
в конечном итоге требуют взятия адреса, предпочтительнее объявить переменную как
тип указателя с самого начала. Аналогично, сообщения protobuf должны объявляться
как типы указателей.

```go
// Хорошо:
func NewCounter(name string) *Counter {
    c := new(Counter) // "&Counter{}" тоже подходит.
    registerCounter(name, c)
    return c
}

var msg = new(pb.Bar) // или "&pb.Bar{}".
```

Это потому, что `*pb.Something` удовлетворяет [`proto.Message`], а
`pb.Something` — нет.

```go
// Плохо:
func NewCounter(name string) *Counter {
    var c Counter
    registerCounter(name, &c)
    return &c
}

var msg = pb.Bar{}
```

[`proto.Message`]: https://pkg.go.dev/google.golang.org/protobuf/proto#Message

> **Важно:** Типы map должны быть явно инициализированы перед тем, как их можно
> будет изменять. Однако чтение из map с нулевым значением вполне допустимо.
>
> Для типов map и slice, если код особенно чувствителен к производительности и
> если вы заранее знаете размеры, см. раздел [подсказки по размеру (size
> hints)](#vardeclsize).

<a id="vardeclcomposite"></a>

### Составные литералы (Composite literals)

Следующие объявления являются [составными литералами (composite literal)]:

```go
// Хорошо:
var (
    coords   = Point{X: x, Y: y}
    magic    = [4]byte{'I', 'W', 'A', 'D'}
    primes   = []int{2, 3, 5, 7, 11}
    captains = map[string]string{"Kirk": "James Tiberius", "Picard": "Jean-Luc"}
)
```

Вы должны объявлять значение с помощью составного литерала, когда знаете
начальные элементы или члены.

В отличие от этого, использование составных литералов для объявления пустых
значений или значений без членов может быть визуально шумным по сравнению с
[инициализацией нулевым значением](#vardeclzero).

Когда вам нужен указатель на нулевое значение, у вас есть два варианта: пустые
составные литералы и `new`. Оба варианта допустимы, но ключевое слово `new`
может служить напоминанием читателю, что если бы потребовалось ненулевое
значение, составной литерал не сработал бы:

```go
// Хорошо:
var (
  buf = new(bytes.Buffer) // непустые Buffers инициализируются конструкторами.
  msg = new(pb.Message) // непустые proto сообщения инициализируются билдерами или установкой полей по одному.
)
```

[составные литералы (composite literal)]: https://golang.org/ref/spec#Composite_literals

<a id="vardeclsize"></a>

### Подсказки по размеру (Size hints)

Следующие объявления используют подсказки по размеру, чтобы предварительно
выделить емкость:

```go
// Хорошо:
var (
    // Предпочтительный размер буфера для целевой файловой системы: st_blksize.
    buf = make([]byte, 131072)
    // Обычно обрабатывается до 8-10 элементов за запуск (16 — безопасное предположение).
    q = make([]Node, 0, 16)
    // Каждый шард обрабатывает shardSize (обычно 32000+) элементов.
    seen = make(map[string]bool, shardSize)
)
```

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

Большинству кода не нужны подсказки по размеру или предварительное выделение, и
он может позволить среде выполнения увеличивать срез или карту по мере
необходимости. Допустимо предварительно выделять память, когда окончательный
размер известен (например, при преобразовании между map и срезом), но это не
является требованием читаемости и может не стоить загромождения в простых
случаях.

**Предупреждение:** Предварительное выделение больше памяти, чем нужно, может
тратить память в парке (fleet) или даже вредить производительности. В случае
сомнений см. [GoTip #3: Benchmarking Go Code] и по умолчанию используйте
[инициализацию нулевым значением](#vardeclzero) или [объявление составным
литералом](#vardeclcomposite).

[GoTip #3: Benchmarking Go Code]: /pages/gostyleguide/google/index.html#gotip

<a id="decl-chan"></a>

### Направление каналов (Channel direction)

Указывайте [направление канала (channel direction)] там, где это возможно.

```go
// Хорошо:
// sum вычисляет сумму всех значений. Она читает из канала до тех пор,
// пока канал не закроется.
func sum(values <-chan int) int {
    // ...
}
```

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

```go
// Плохо:
func sum(values chan int) (out int) {
    for v := range values {
        out += v
    }
    // values уже должен быть закрыт для достижения этого кода, что означает,
    // что второе закрытие вызовет панику.
    close(values)
}
```

Когда направление указано, компилятор перехватывает простые ошибки, подобные
этой. Это также помогает передать меру владения (ownership) типу.

См. также доклад Брайана Миллса "Rethinking Classical Concurrency Patterns":
[слайды][rethinking-concurrency-slides] [видео][rethinking-concurrency-video].

[rethinking-concurrency-slides]: https://drive.google.com/file/d/1nPdvhB0PutEJzdCq5ms6UI58dp50fcAN/view?usp=sharing
[rethinking-concurrency-video]: https://www.youtube.com/watch?v=5zXAHh5tJqQ
[направление канала (channel direction)]: https://go.dev/ref/spec#Channel_types

<a id="funcargs"></a>

## Списки аргументов функций (Function argument lists)

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

При проектировании API рассмотрите возможность разделения высоконастраиваемой
функции, сигнатура которой становится сложной, на несколько более простых. Они
могут использовать общую (неэкспортируемую) реализацию, если это необходимо.

Если функции требуется много входных данных, рассмотрите возможность введения
[структуры опций (option struct)] для некоторых аргументов или использование
более продвинутой техники [вариативных опций (variadic options)]. Основным
критерием выбора стратегии должно быть то, как выглядит вызов функции во всех
ожидаемых случаях использования.

Приведенные ниже рекомендации в первую очередь применяются к экспортированным
API, к которым предъявляются более высокие стандарты, чем к неэкспортированным.
Эти методы могут быть не нужны для вашего случая использования. Используйте свое
суждение и балансируйте между принципами [ясности (clarity)] и [наименьшей
механизации (least mechanism)].

См. также: [Go Tip #24: Use Case-Specific
Constructions](/pages/gostyleguide/google/index.html#gotip)

[структуры опций (option struct)]: #option-structure
[вариативных опций (variadic options)]: #variadic-options
[ясности (clarity)]: guide#clarity
[наименьшей механизации (least mechanism)]: guide#least-mechanism

<a id="option-structure"></a>

### Структура опций (Option structure)

Структура опций (option structure) — это тип struct, который собирает некоторые
или все аргументы функции или метода, а затем передается в качестве последнего
аргумента функции или методу. (Структура должна быть экспортирована только если
она используется в экспортированной функции.)

Использование структуры опций имеет ряд преимуществ:

- Литерал структуры включает как поля, так и значения для каждого аргумента,
  что делает их самодокументированными и затрудняет их перестановку.
- Несущественные или "значения по умолчанию" поля могут быть опущены.
- Вызывающие стороны могут совместно использовать структуру опций и писать
  вспомогательные функции для работы с ней.
- Структуры обеспечивают более чистую документацию для каждого поля, чем
  аргументы функций.
- Структуры опций могут расти со временем без влияния на места вызова.

Вот пример функции, которую можно улучшить:

```go
// Плохо:
func EnableReplication(ctx context.Context, config *replicator.Config, primaryRegions, readonlyRegions []string, replicateExisting, overwritePolicies bool, replicationInterval time.Duration, copyWorkers int, healthWatcher health.Watcher) {
    // ...
}
```

Функция выше может быть переписана со структурой опций следующим образом:

```go
// Хорошо:
type ReplicationOptions struct {
    Config              *replicator.Config
    PrimaryRegions      []string
    ReadonlyRegions     []string
    ReplicateExisting   bool
    OverwritePolicies   bool
    ReplicationInterval time.Duration
    CopyWorkers         int
    HealthWatcher       health.Watcher
}

func EnableReplication(ctx context.Context, opts ReplicationOptions) {
    // ...
}
```

Затем функцию можно вызвать в другом пакете:

```go
// Хорошо:
func foo(ctx context.Context) {
    // Сложный вызов:
    storage.EnableReplication(ctx, storage.ReplicationOptions{
        Config:              config,
        PrimaryRegions:      []string{"us-east1", "us-central2", "us-west3"},
        ReadonlyRegions:     []string{"us-east5", "us-central6"},
        OverwritePolicies:   true,
        ReplicationInterval: 1 * time.Hour,
        CopyWorkers:         100,
        HealthWatcher:       watcher,
    })

    // Простой вызов:
    storage.EnableReplication(ctx, storage.ReplicationOptions{
        Config:         config,
        PrimaryRegions: []string{"us-east1", "us-central2", "us-west3"},
    })
}
```

**Примечание:** [Контексты никогда не включаются в структуры
опций](https://neonxp.ru/pages/gostyleguide/google/decisions/#contexts).

Этот вариант часто предпочтителен, когда применимо одно из следующих условий:

- Все вызывающие стороны должны указать одну или несколько опций.
- Большому количеству вызывающих сторон необходимо предоставить множество
  опций.
- Опции используются совместно несколькими функциями, которые будет вызывать
  пользователь.

<a id="variadic-options"></a>

### Вариативные опции (Variadic options)

Используя вариативные опции, создаются экспортированные функции, которые
возвращают замыкания (closures), которые могут быть переданы в [вариативный
(`...`) параметр] функции. Функция принимает в качестве параметров значения
опции (если есть), а возвращаемое замыкание принимает изменяемую ссылку (обычно
указатель на тип struct), которая будет обновлена на основе входных данных.

[вариативный (`...`) параметр]: https://golang.org/ref/spec#Passing_arguments_to_..._parameters

Использование вариативных опций может предоставить ряд преимуществ:

- Опции не занимают места в месте вызова, когда конфигурация не нужна.
- Опции все еще являются значениями, поэтому вызывающие стороны могут делиться
  ими, писать вспомогательные функции и накапливать их.
- Опции могут принимать несколько параметров (например,
  `cartesian.Translate(dx, dy int) TransformOption`).
- Функции опций могут возвращать именованный тип, чтобы группировать опции
  вместе в godoc.
- Пакеты могут разрешать (или запрещать) сторонним пакетам определять (или
  запрещать определение) свои собственные опции.

**Примечание:** Использование вариативных опций требует значительного количества
дополнительного кода (см. следующий пример), поэтому их следует использовать
только тогда, когда преимущества перевешивают накладные расходы.

Вот пример функции, которую можно улучшить:

```go
// Плохо:
func EnableReplication(ctx context.Context, config *placer.Config, primaryCells, readonlyCells []string, replicateExisting, overwritePolicies bool, replicationInterval time.Duration, copyWorkers int, healthWatcher health.Watcher) {
  ...
}
```

Пример выше может быть переписан с вариативными опциями следующим образом:

```go
// Хорошо:
type replicationOptions struct {
    readonlyCells       []string
    replicateExisting   bool
    overwritePolicies   bool
    replicationInterval time.Duration
    copyWorkers         int
    healthWatcher       health.Watcher
}

// ReplicationOption настраивает EnableReplication.
type ReplicationOption func(*replicationOptions)

// ReadonlyCells добавляет дополнительные ячейки, которые дополнительно
// должны содержать реплики только для чтения данных.
//
// Передача этой опции несколько раз добавит дополнительные
// ячейки только для чтения.
//
// По умолчанию: нет
func ReadonlyCells(cells ...string) ReplicationOption {
    return func(opts *replicationOptions) {
        opts.readonlyCells = append(opts.readonlyCells, cells...)
    }
}

// ReplicateExisting контролирует, будут ли файлы, уже существующие в
// первичных ячейках, реплицированы. В противном случае только недавно добавленные
// файлы будут кандидатами на репликацию.
//
// Повторная передача этой опции перезапишет предыдущие значения.
//
// По умолчанию: false
func ReplicateExisting(enabled bool) ReplicationOption {
    return func(opts *replicationOptions) {
        opts.replicateExisting = enabled
    }
}

// ... другие опции ...

// DefaultReplicationOptions управляют значениями по умолчанию перед
// применением опций, переданных в EnableReplication.
var DefaultReplicationOptions = []ReplicationOption{
    OverwritePolicies(true),
    ReplicationInterval(12 * time.Hour),
    CopyWorkers(10),
}

func EnableReplication(ctx context.Context, config *placer.Config, primaryCells []string, opts ...ReplicationOption) {
    var options replicationOptions
    for _, opt := range DefaultReplicationOptions {
        opt(&options)
    }
    for _, opt := range opts {
        opt(&options)
    }
}
```

Затем функцию можно вызвать в другом пакете:

```go
// Хорошо:
func foo(ctx context.Context) {
    // Сложный вызов:
    storage.EnableReplication(ctx, config, []string{"po", "is", "ea"},
        storage.ReadonlyCells("ix", "gg"),
        storage.OverwritePolicies(true),
        storage.ReplicationInterval(1*time.Hour),
        storage.CopyWorkers(100),
        storage.HealthWatcher(watcher),
    )

    // Простой вызов:
    storage.EnableReplication(ctx, config, []string{"po", "is", "ea"})
}
```

Предпочитайте этот вариант, когда применимо большинство из следующего:

- Большинству вызывающих сторон не нужно указывать никакие опции.
- Большинство опций используется редко.
- Существует большое количество опций.
- Опции требуют аргументов.
- Опции могут завершиться неудачей или быть установлены неправильно (в этом
  случае функция опции возвращает `error`).
- Опции требуют большого количества документации, которую трудно уместить в
  структуре.
- Пользователи или другие пакеты могут предоставлять пользовательские опции.

Опции в этом стиле должны принимать параметры, а не использовать наличие
(presence) для сигнализации своего значения; последнее может значительно
усложнить динамическое составление аргументов. Например, двоичные настройки
должны принимать логическое значение (например, `rpc.FailFast(enable bool)`
предпочтительнее, чем `rpc.EnableFailFast()`). Перечисляемая опция должна
принимать перечисляемую константу (например, `log.Format(log.Capacitor)`
предпочтительнее, чем `log.CapacitorFormat()`). Альтернатива значительно
усложняет жизнь пользователям, которые должны программно выбирать, какие опции
передавать; такие пользователи вынуждены изменять фактический состав параметров,
а не просто изменять аргументы опций. Не предполагайте, что все пользователи
будут статически знать полный набор опций.

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

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

См. [оригинальный пост в блоге Роба Пайка] и [доклад Дейва Ченея] для более
глубокого изучения того, как эти опции могут быть использованы.

[оригинальный пост в блоге Роба Пайка]: http://commandcenter.blogspot.com/2014/01/self-referential-functions-and-design.html
[доклад Дейва Ченея]: https://dave.cheney.net/2014/10/17/functional-options-for-friendly-apis

<a id="complex-clis"></a>

## Сложные интерфейсы командной строки (Complex command-line interfaces)

Некоторые программы хотят предоставить пользователям богатый интерфейс командной
строки, включающий подкоманды. Например, `kubectl create`, `kubectl run` и
многие другие подкоманды предоставляются программой `kubectl`. Существует по
крайней мере следующие общеупотребительные библиотеки для достижения этого.

Если у вас нет предпочтений или другие соображения равны, рекомендуется
[subcommands], поскольку она самая простая и с ней легко работать правильно.
Однако, если вам нужны другие функции, которые она не предоставляет, выберите
один из других вариантов.

- **[cobra]**
    - Соглашение о флагах: getopt
    - Распространена за пределами кодовой базы Google.
    - Много дополнительных функций.
    - Подводные камни в использовании (см. ниже).

- **[subcommands]**
    - Соглашение о флагах: Go
    - Проста и с ней легко работать правильно.
    - Рекомендуется, если вам не нужны дополнительные функции.

**Предупреждение**: функции команд cobra должны использовать `cmd.Context()` для
получения контекста, а не создавать свой собственный корневой контекст с помощью
`context.Background`. Код, использующий пакет subcommands, уже получает
правильный контекст как параметр функции.

Вы не обязаны помещать каждую подкоманду в отдельный пакет, и часто в этом нет
необходимости. Применяйте те же соображения о границах пакетов, что и в любой
кодовой базе Go. Если ваш код может использоваться как библиотека и как бинарный
файл, обычно полезно отделить CLI-код от библиотеки, делая CLI просто еще одним
из ее клиентов. (Это не специфично для CLI с подкомандами, но упоминается здесь,
потому что это частое место, где это возникает.)

[subcommands]: https://pkg.go.dev/github.com/google/subcommands
[cobra]: https://pkg.go.dev/github.com/spf13/cobra

<a id="tests"></a>

## Тесты (Tests)

<a id="test-functions"></a>

### Оставляйте тестирование функции `Test`

<!-- Примечание для сопровождающих: Этот раздел пересекается с decisions#assert и
decisions#mark-test-helpers. Цель не в том, чтобы повторять информацию, а
в том, чтобы иметь одно место, которое суммирует различие, о котором часто
задумываются новички в языке. -->

Go различает "тестовые помощники (test helpers)" и "помощники утверждений
(assertion helpers)":

- **Тестовые помощники** — это функции, которые выполняют задачи настройки или
  очистки. Все сбои, которые происходят в тестовых помощниках, ожидаемо
  являются сбоями окружения (а не тестируемого кода) — например, когда
  тестовая база данных не может быть запущена, потому что на этой машине
  больше нет свободных портов. Для таких функций часто уместно вызывать
  `t.Helper`, чтобы [пометить их как тестовый помощник]. См. [обработку ошибок
  в тестовых помощниках] для более подробной информации.

- **Помощники утверждений** — это функции, которые проверяют правильность
  системы и завершают тест с ошибкой, если ожидание не выполняется. Помощники
  утверждений [не считаются идиоматичными] в Go.

Цель теста — сообщить о условиях прохождения/непрохождения тестируемого кода.
Идеальное место для завершения теста с ошибкой — внутри самой функции `Test`,
так как это обеспечивает ясность [сообщений об ошибках] и логики теста.

[пометить их как тестовый помощник]: decisions#mark-test-helpers
[обработку ошибок в тестовых помощниках]: #test-helper-error-handling
[не считаются идиоматичными]: decisions#assert
[сообщений об ошибках]: decisions#useful-test-failures

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

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

- Встройте логику (и валидацию, и завершение с ошибкой) в функцию `Test`, даже
  если это повторяется. Это лучше всего работает в простых случаях.
- Если входные данные похожи, рассмотрите возможность объединения их в
  [табличный тест (table-driven test)], сохраняя логику встроенной в цикл. Это
  помогает избежать повторения, сохраняя валидацию и завершение с ошибкой в
  `Test`.
- Если есть несколько вызывающих сторон, которым нужна одна и та же функция
  валидации, но табличные тесты не подходят (обычно потому, что входные данные
  недостаточно просты или валидация требуется как часть последовательности
  операций), организуйте функцию валидации так, чтобы она возвращала значение
  (обычно `error`), а не принимала параметр `testing.T` и использовала его для
  завершения теста с ошибкой. Используйте логику внутри `Test`, чтобы решить,
  завершать ли тест с ошибкой, и предоставить [полезные сообщения об ошибках
  теста]. Вы также можете создать тестовые помощники для выноса общего
  шаблонного кода настройки.

Дизайн, описанный в последнем пункте, сохраняет ортогональность. Например,
[пакет `cmp`] не предназначен для завершения тестов с ошибкой, а для сравнения
(и вычисления различий) значений. Поэтому ему не нужно знать о контексте, в
котором было сделано сравнение, поскольку вызывающая сторона может предоставить
его. Если ваш общий тестовый код предоставляет `cmp.Transformer` для вашего типа
данных, это часто может быть самым простым дизайном. Для других проверок
рассмотрите возможность возврата значения `error`.

```go
// Хорошо:
// polygonCmp возвращает cmp.Option, которое приравнивает объекты геометрии s2
// с некоторой небольшой ошибкой с плавающей точкой.
func polygonCmp() cmp.Option {
    return cmp.Options{
        cmp.Transformer("polygon", func(p *s2.Polygon) []*s2.Loop { return p.Loops() }),
        cmp.Transformer("loop", func(l *s2.Loop) []s2.Point { return l.Vertices() }),
        cmpopts.EquateApprox(0.00000001, 0),
        cmpopts.EquateEmpty(),
    }
}

func TestFenceposts(t *testing.T) {
    // Это тест для вымышленной функции Fenceposts, которая рисует забор
    // вокруг некоторого объекта Place. Детали не важны, за исключением того,
    // что результат — это некоторый объект, имеющий геометрию s2 (github.com/golang/geo/s2)
    got := Fencepost(tomsDiner, 1*meter)
    if diff := cmp.Diff(want, got, polygonCmp()); diff != "" {
        t.Errorf("Fencepost(tomsDiner, 1m) returned unexpected diff (-want+got):\n%v", diff)
    }
}

func FuzzFencepost(f *testing.F) {
    // Фаззинг-тест (https://go.dev/doc/fuzz) для того же.

    f.Add(tomsDiner, 1*meter)
    f.Add(school, 3*meter)

    f.Fuzz(func(t *testing.T, geo Place, padding Length) {
        got := Fencepost(geo, padding)
        // Простая эталонная реализация: не используется в prod, но проста для
        // понимания и поэтому полезна для проверки в случайных тестах.
        reference := slowFencepost(geo, padding)

        // Во фаззинг-тесте входные и выходные данные могут быть большими, поэтому
        // не беспокойтесь о печати diff. cmp.Equal достаточно.
        if !cmp.Equal(got, reference, polygonCmp()) {
            t.Errorf("Fencepost returned wrong placement")
        }
    })
}
```

Функция `polygonCmp` агностична относительно того, как ее вызывают; она не
принимает конкретный тип входных данных и не контролирует, что делать, если два
объекта не совпадают. Поэтому больше вызывающих сторон могут использовать ее.

**Примечание:** Существует аналогия между тестовыми помощниками и обычным
библиотечным кодом. Код в библиотеках обычно [не должен вызывать panic] за
редкими исключениями; код, вызываемый из теста, не должен останавливать тест,
если нет [смысла продолжать].

[табличный тест (table-driven test)]: decisions#table-driven-tests
[полезные сообщения об ошибках теста]: decisions#useful-test-failures
[пакет `cmp`]: https://pkg.go.dev/github.com/google/go-cmp/cmp
[не должен вызывать panic]: decisions#dont-panic
[смысла продолжать]: #t-fatal

<a id="test-validation-apis"></a>

### Проектирование расширяемых API валидации (Designing extensible validation APIs)

Большая часть советов о тестировании в руководстве по стилю касается
тестирования вашего собственного кода. Этот раздел о том, как предоставить
средства для других людей тестировать код, который они пишут, чтобы убедиться,
что он соответствует требованиям вашей библиотеки.

<a id="test-validation-apis-what"></a>

#### Приемочное тестирование (Acceptance testing)

Такое тестирование называется [приемочным тестированием (acceptance testing)].
Предпосылка такого тестирования заключается в том, что человек, использующий
тест, не знает всех деталей того, что происходит в тесте; он просто передает
входные данные в тестовое средство, чтобы оно выполнило работу. Это можно
рассматривать как форму [инверсии управления (inversion of control)].

В типичном тесте Go тестовая функция контролирует поток программы, и
рекомендации [без утверждений (no assert)](https://neonxp.ru/pages/gostyleguide/google/decisions/#assert) и [тестовые
функции](#test-functions) побуждают вас сохранять это так. Этот раздел
объясняет, как создавать поддержку для таких тестов способом, согласующимся со
стилем Go.

Прежде чем углубляться в "как", рассмотрим пример из [`io/fs`], приведенный
ниже:

```go
type FS interface {
    Open(name string) (File, error)
}
```

Хотя существуют хорошо известные реализации `fs.FS`, от разработчика Go может
потребоваться создать свою. Чтобы помочь проверить правильность пользовательской
реализации `fs.FS`, была предоставлена универсальная библиотека в
[`testing/fstest`] под названием [`fstest.TestFS`]. Этот API рассматривает
реализацию как черный ящик (blackbox), чтобы убедиться, что она соблюдает самые
основные части контракта `io/fs`.

[приемочным тестированием (acceptance testing)]: https://en.wikipedia.org/wiki/Acceptance_testing
[инверсии управления (inversion of control)]: https://en.wikipedia.org/wiki/Inversion_of_control
[`io/fs`]: https://pkg.go.dev/io/fs
[`testing/fstest`]: https://pkg.go.dev/testing/fstest
[`fstest.TestFS`]: https://pkg.go.dev/testing/fstest#TestFS

<a id="test-validation-apis-writing"></a>

#### Написание приемочного теста (Writing an acceptance test)

Теперь, когда мы знаем, что такое приемочный тест и почему вы можете его
использовать, давайте рассмотрим создание приемочного теста для `package chess`,
пакета, используемого для симуляции шахматных игр. Пользователи `chess` должны
реализовать интерфейс `chess.Player`. Эти реализации — основное, что мы будем
проверять. Наш приемочный тест касается того, делает ли реализация игрока
легальные ходы, а не того, являются ли ходы умными.

1.  Создайте новый пакет для поведения валидации, [обычно
    именуемый](#naming-doubles-helper-package) добавлением слова `test` к имени
    пакета (например, `chesstest`).

1.  Создайте функцию, которая выполняет валидацию, принимая тестируемую
    реализацию в качестве аргумента и проверяя ее:

    ```go
    // ExercisePlayer тестирует реализацию Player за один ход на доске.
    // Сама доска выборочно проверяется на разумность и правильность.
    //
    // Возвращает nil ошибку, если игрок делает правильный ход в контексте
    // предоставленной доски. В противном случае ExercisePlayer возвращает одну из
    // ошибок этого пакета, чтобы указать, как и почему игрок не прошел валидацию.
    func ExercisePlayer(b *chess.Board, p chess.Player) error
    ```

    Тест должен отмечать, какие инварианты нарушены и как. Ваш дизайн может
    выбрать одну из двух дисциплин для сообщения о сбоях:
    - **Завершение при первой ошибке (Fail fast)**: возвращать ошибку, как
      только реализация нарушает инвариант.

        Это самый простой подход, и он хорошо работает, если ожидается, что
        приемочный тест будет выполняться быстро. Простые [сторожевые ошибки
        (sentinels)] и [пользовательские типы] могут быть легко использованы
        здесь, что, в свою очередь, облегчает тестирование самого приемочного
        теста.

        ```go
        for color, army := range b.Armies {
            // Король никогда не должен покидать доску, потому что игра заканчивается
            // матом.
            if army.King == nil {
                return &MissingPieceError{Color: color, Piece: chess.King}
            }
        }
        ```

    - **Агрегация всех сбоев (Aggregate all failures)**: собирать все сбои и
      сообщать о них всех.

        Этот подход напоминает рекомендацию [продолжать выполнение (keep going)]
        и может быть предпочтительнее, если ожидается, что приемочный тест будет
        выполняться медленно.

        То, как вы агрегируете сбои, должно определяться тем, хотите ли вы дать
        пользователям или себе возможность исследовать отдельные сбои (например,
        для тестирования вашего приемочного теста). Ниже демонстрируется
        использование [пользовательского типа ошибки][пользовательские типы],
        который [агрегирует ошибки]:

        ```go
        var badMoves []error

        move := p.Move()
        if putsOwnKingIntoCheck(b, move) {
            badMoves = append(badMoves, PutsSelfIntoCheckError{Move: move})
        }

        if len(badMoves) > 0 {
            return SimulationError{BadMoves: badMoves}
        }
        return nil
        ```

Приемочный тест должен соблюдать рекомендацию [продолжать выполнение (keep
going)], не вызывая `t.Fatal`, если тест не обнаруживает нарушение инварианта в
системе, которая тестируется.

Например, `t.Fatal` должен быть зарезервирован для исключительных случаев, таких
как [сбой настройки](#test-helper-error-handling), как обычно:

```go
func ExerciseGame(t *testing.T, cfg *Config, p chess.Player) error {
    t.Helper()

    if cfg.Simulation == Modem {
        conn, err := modempool.Allocate()
        if err != nil {
            t.Fatalf("No modem for the opponent could be provisioned: %v", err)
        }
        t.Cleanup(func() { modempool.Return(conn) })
    }
    // Запустить приемочный тест (целую игру).
}
```

Эта техника может помочь вам создавать лаконичные, каноничные проверки. Но не
пытайтесь использовать ее, чтобы обойти [рекомендации об
утверждениях](https://neonxp.ru/pages/gostyleguide/google/decisions/#assert).

Конечный продукт должен быть похож на этот для конечных пользователей:

```go
// Хорошо:
package deepblue_test

import (
    "chesstest"
    "deepblue"
)

func TestAcceptance(t *testing.T) {
    player := deepblue.New()
    err := chesstest.ExerciseGame(t, chesstest.SimpleGame, player)
    if err != nil {
        t.Errorf("Deep Blue player failed acceptance test: %v", err)
    }
}
```

[сторожевые ошибки (sentinels)]: /pages/gostyleguide/google/index.html#gotip
[пользовательские типы]: /pages/gostyleguide/google/index.html#gotip
[агрегирует ошибки]: /pages/gostyleguide/google/index.html#gotip

<a id="use-real-transports"></a>

### Используйте реальные транспорты (Use real transports)

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

Например, предположим, что код, который вы хотите протестировать (иногда
называемый "системой под тестом" или SUT), взаимодействует с бэкендом,
реализующим API [долго выполняющихся операций (long running operations)]. Чтобы
протестировать ваш SUT, используйте реальный [OperationsClient], подключенный к
[тестовому двойнику (test
double)](https://abseil.io/resources/swe-book/html/ch13.html#basic_concepts)
(например, моку, заглушке или фейку) [OperationsServer].

[тестовому двойнику (test double)]: https://abseil.io/resources/swe-book/html/ch13.html#basic_concepts
[долго выполняющихся операций (long running operations)]: https://pkg.go.dev/google.golang.org/genproto/googleapis/longrunning
[OperationsClient]: https://pkg.go.dev/google.golang.org/genproto/googleapis/longrunning#OperationsClient
[OperationsServer]: https://pkg.go.dev/google.golang.org/genproto/googleapis/longrunning#OperationsServer

Это рекомендуется вместо ручной реализации клиента из-за сложности правильной
имитации поведения клиента. Используя production-клиент с тестовым сервером, вы
гарантируете, что ваш тест использует как можно больше реального кода.

**Совет:** По возможности используйте тестовую библиотеку, предоставленную
авторами тестируемого сервиса.

<a id="t-fatal"></a>

### `t.Error` против `t.Fatal`

Как обсуждалось в [решениях](https://neonxp.ru/pages/gostyleguide/google/decisions/#keep-going), тесты, как правило, не
должны прерываться при первой встреченной проблеме.

Однако некоторые ситуации требуют, чтобы тест не продолжался. Вызов `t.Fatal`
уместен, когда какая-то часть настройки теста завершается неудачей, особенно во
[вспомогательных функциях настройки теста], без которых вы не можете запустить
остальную часть теста. В табличном тесте `t.Fatal` уместен для сбоев, которые
настраивают всю тестовую функцию до начала цикла теста. Сбои, которые
затрагивают одну запись в таблице теста и делают невозможным продолжение работы
с этой записью, должны сообщаться следующим образом:

- Если вы не используете подтесты `t.Run`, используйте `t.Error`, за которым
  следует оператор `continue` для перехода к следующей записи таблицы.
- Если вы используете подтесты (и вы внутри вызова `t.Run`), используйте
  `t.Fatal`, который завершает текущий подтест и позволяет вашему тестовому
  случаю перейти к следующему подтесту.

**Предупреждение:** Не всегда безопасно вызывать `t.Fatal` и подобные функции.
[Подробнее здесь](#t-fatal-goroutine).

[вспомогательных функциях настройки теста]: #test-helper-error-handling

<a id="test-helper-error-handling"></a>

### Обработка ошибок во вспомогательных тестовых функциях (Error handling in test helpers)

**Примечание:** В этом разделе обсуждаются [тестовые помощники (test helpers)] в
том смысле, в котором Go использует этот термин: функции, которые выполняют
настройку и очистку теста, а не общие средства утверждений. См. раздел [тестовые
функции](#test-functions) для более подробного обсуждения.

[тестовые помощники (test helpers)]: decisions#mark-test-helpers

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

```go
// Хорошо:
func mustAddGameAssets(t *testing.T, dir string) {
    t.Helper()
    if err := os.WriteFile(path.Join(dir, "pak0.pak"), pak0, 0644); err != nil {
        t.Fatalf("Setup failed: could not write pak0 asset: %v", err)
    }
    if err := os.WriteFile(path.Join(dir, "pak1.pak"), pak1, 0644); err != nil {
        t.Fatalf("Setup failed: could not write pak1 asset: %v", err)
    }
}
```

Это делает вызывающую сторону чище, чем если бы помощник возвращал ошибку самому
тесту:

```go
// Плохо:
func addGameAssets(t *testing.T, dir string) error {
    t.Helper()
    if err := os.WriteFile(path.Join(d, "pak0.pak"), pak0, 0644); err != nil {
        return err
    }
    if err := os.WriteFile(path.Join(d, "pak1.pak"), pak1, 0644); err != nil {
        return err
    }
    return nil
}
```

**Предупреждение:** Не всегда безопасно вызывать `t.Fatal` и подобные функции.
[Подробнее](#t-fatal-goroutine) здесь.

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

**Совет:** Go 1.14 представила функцию [`t.Cleanup`], которую можно использовать
для регистрации функций очистки, которые запускаются при завершении вашего
теста. Функция также работает с тестовыми помощниками. См. [GoTip #4: Cleaning
Up Your Tests](/pages/gostyleguide/google/index.html#gotip) для
рекомендаций по упрощению тестовых помощников.

Сниппет ниже в вымышленном файле `paint_test.go` демонстрирует, как
`(*testing.T).Helper` влияет на сообщение об ошибке в тесте Go:

```go
package paint_test

import (
    "fmt"
    "testing"
)

func paint(color string) error {
    return fmt.Errorf("no %q paint today", color)
}

func badSetup(t *testing.T) {
    // Здесь должен быть вызов t.Helper, но его нет.
    if err := paint("taupe"); err != nil {
        t.Fatalf("Could not paint the house under test: %v", err) // строка 15
    }
}

func goodSetup(t *testing.T) {
    t.Helper()
    if err := paint("lilac"); err != nil {
        t.Fatalf("Could not paint the house under test: %v", err)
    }
}

func TestBad(t *testing.T) {
    badSetup(t)
    // ...
}

func TestGood(t *testing.T) {
    goodSetup(t) // строка 32
    // ...
}
```

Вот пример вывода при запуске. Обратите внимание на выделенный текст и на то,
как он отличается:

```text
=== RUN   TestBad
    paint_test.go:15: Could not paint the house under test: no "taupe" paint today
--- FAIL: TestBad (0.00s)
=== RUN   TestGood
    paint_test.go:32: Could not paint the house under test: no "lilac" paint today
--- FAIL: TestGood (0.00s)
FAIL
```

Ошибка с `paint_test.go:15` относится к строке функции настройки, которая
завершилась неудачей в `badSetup`:

`t.Fatalf("Could not paint the house under test: %v", err)`

Тогда как `paint_test.go:32` относится к строке теста, которая завершилась
неудачей в `TestGood`:

`goodSetup(t)`

Правильное использование `(*testing.T).Helper` гораздо лучше определяет
местоположение сбоя, когда:

- вспомогательные функции растут
- вспомогательные функции вызывают другие вспомогательные функции
- количество использований вспомогательных функций в тестовых функциях растет

**Совет:** Если вспомогательная функция вызывает `(*testing.T).Error` или
`(*testing.T).Fatal`, предоставьте некоторый контекст в строке формата, чтобы
помочь определить, что пошло не так и почему.

**Совет:** Если ничто из того, что делает помощник, не может привести к неудаче
теста, ему не нужно вызывать `t.Helper`. Упростите его сигнатуру, удалив `t` из
списка параметров функции.

[`t.Cleanup`]: https://pkg.go.dev/testing#T.Cleanup

<a id="t-fatal-goroutine"></a>

### Не вызывайте `t.Fatal` из отдельных горутин (Don't call `t.Fatal` from separate goroutines)

Как [документировано в пакете testing](https://pkg.go.dev/testing#T),
неправильно вызывать `t.FailNow`, `t.Fatal` и т.д. из любой горутины, кроме той,
которая запускает функцию Test (или подтест). Если ваш тест запускает новые
горутины, они не должны вызывать эти функции внутри этих горутин.

[Тестовые помощники](#test-functions) обычно не сигнализируют о сбое из новых
горутин, поэтому для них допустимо использовать `t.Fatal`. В случае сомнений
вызовите `t.Error` и вернитесь.

```go
// Хорошо:
func TestRevEngine(t *testing.T) {
    engine, err := Start()
    if err != nil {
        t.Fatalf("Engine failed to start: %v", err)
    }

    num := 11
    var wg sync.WaitGroup
    wg.Add(num)
    for i := 0; i < num; i++ {
        go func() {
            defer wg.Done()
            if err := engine.Vroom(); err != nil {
                // Здесь нельзя использовать t.Fatalf.
                t.Errorf("No vroom left on engine: %v", err)
                return
            }
            if rpm := engine.Tachometer(); rpm > 1e6 {
                t.Errorf("Inconceivable engine rate: %d", rpm)
            }
        }()
    }
    wg.Wait()

    if seen := engine.NumVrooms(); seen != num {
        t.Errorf("engine.NumVrooms() = %d, want %d", seen, num)
    }
}
```

Добавление `t.Parallel` к тесту или подтесту не делает небезопасным вызов
`t.Fatal`.

Когда все вызовы API `testing` находятся в [тестовой функции](#test-functions),
обычно легко заметить неправильное использование, потому что ключевое слово `go`
легко увидеть. Передача аргументов `testing.T` усложняет отслеживание такого
использования. Обычно причина передачи этих аргументов — введение тестового
помощника, и они не должны зависеть от тестируемой системы. Поэтому, если
тестовый помощник [регистрирует фатальную ошибку
теста](#test-helper-error-handling), он может и должен делать это из горутины
теста.

<a id="t-field-names"></a>

### Используйте имена полей в литералах структур (Use field names in struct literals)

<a id="t-field-labels"></a>

В табличных тестах предпочитайте указывать имена полей при инициализации
литералов структур тестовых случаев. Это полезно, когда тестовые случаи
охватывают большое вертикальное пространство (например, более 20-30 строк),
когда есть соседние поля с одинаковым типом, а также когда вы хотите опустить
поля, имеющие нулевое значение. Например:

```go
// Хорошо:
func TestStrJoin(t *testing.T) {
    tests := []struct {
        slice     []string
        separator string
        skipEmpty bool
        want      string
    }{
        {
            slice:     []string{"a", "b", ""},
            separator: ",",
            want:      "a,b,",
        },
        {
            slice:     []string{"a", "b", ""},
            separator: ",",
            skipEmpty: true,
            want:      "a,b",
        },
        // ...
    }
    // ...
}
```

<a id="t-common-setup-scope"></a>

### Ограничивайте код настройки конкретными тестами (Keep setup code scoped to specific tests)

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

```go
// mustLoadDataSet загружает набор данных для тестов.
//
// Этот пример очень прост и легко читается. Часто реалистичная настройка более
// сложная, подверженная ошибкам и потенциально медленная.
func mustLoadDataset(t *testing.T) []byte {
    t.Helper()
    data, err := os.ReadFile("path/to/your/project/testdata/dataset")

    if err != nil {
        t.Fatalf("Could not load dataset: %v", err)
    }
    return data
}
```

Вызовите `mustLoadDataset` явно в тестовых функциях, которые в этом нуждаются:

```go
// Хорошо:
func TestParseData(t *testing.T) {
    data := mustLoadDataset(t)
    parsed, err := ParseData(data)
    if err != nil {
        t.Fatalf("Unexpected error parsing data: %v", err)
    }
    want := &DataTable{ /* ... */ }
    if got := parsed; !cmp.Equal(got, want) {
        t.Errorf("ParseData(data) = %v, want %v", got, want)
    }
}

func TestListContents(t *testing.T) {
    data := mustLoadDataset(t)
    contents, err := ListContents(data)
    if err != nil {
        t.Fatalf("Unexpected error listing contents: %v", err)
    }
    want := []string{ /* ... */ }
    if got := contents; !cmp.Equal(got, want) {
        t.Errorf("ListContents(data) = %v, want %v", got, want)
    }
}

func TestRegression682831(t *testing.T) {
    if got, want := guessOS("zpc79.example.com"), "grhat"; got != want {
        t.Errorf(`guessOS("zpc79.example.com") = %q, want %q`, got, want)
    }
}
```

Тестовая функция `TestRegression682831` не использует набор данных и поэтому не
вызывает `mustLoadDataset`, которая может быть медленной и подверженной сбоям:

```go
// Плохо:
var dataset []byte

func TestParseData(t *testing.T) {
    // Как описано выше без вызова mustLoadDataset напрямую.
}

func TestListContents(t *testing.T) {
    // Как описано выше без вызова mustLoadDataset напрямую.
}

func TestRegression682831(t *testing.T) {
    if got, want := guessOS("zpc79.example.com"), "grhat"; got != want {
        t.Errorf(`guessOS("zpc79.example.com") = %q, want %q`, got, want)
    }
}

func init() {
    dataset = mustLoadDataset()
}
```

Пользователь может захотеть запустить функцию изолированно от других и не должен
быть наказан этими факторами:

```shell
# Нет причин для выполнения дорогой инициализации.
$ go test -run TestRegression682831
```

<a id="t-custom-main"></a>

#### Когда использовать пользовательскую точку входа `TestMain` (When to use a custom `TestMain` entrypoint)

Если **все тесты в пакете** требуют общей настройки и **настройка требует
очистки (teardown)**, вы можете использовать [пользовательскую точку входа
testmain]. Это может произойти, если ресурс, требующийся тестовым случаям,
особенно дорог в настройке, и стоимость должна быть амортизирована. Обычно к
этому моменту вы уже убрали несвязанные тесты из набора тестов. Обычно это
используется только для [функциональных тестов (functional tests)].

Использование пользовательского `TestMain` **не должно быть вашим первым
выбором** из-за количества осторожности, которое требуется для правильного
использования. Сначала рассмотрите, достаточно ли решения в разделе
[*амортизация общей настройки теста*] или обычного [тестового помощника] для
ваших нужд.

[пользовательскую точку входа testmain]: https://golang.org/pkg/testing/#hdr-Main
[функциональных тестов (functional tests)]: https://en.wikipedia.org/wiki/Functional_testing
[*амортизация общей настройки теста*]: #t-setup-amortization
[тестового помощника]: #t-common-setup-scope

```go
// Хорошо:
var db *sql.DB

func TestInsert(t *testing.T) { /* omitted */ }

func TestSelect(t *testing.T) { /* omitted */ }

func TestUpdate(t *testing.T) { /* omitted */ }

func TestDelete(t *testing.T) { /* omitted */ }

// runMain устанавливает зависимости теста и в конечном итоге выполняет тесты.
// Она определена как отдельная функция, чтобы этапы настройки могли четко
// откладывать (defer) свои шаги очистки.
func runMain(ctx context.Context, m *testing.M) (code int, err error) {
    ctx, cancel := context.WithCancel(ctx)
    defer cancel()

    d, err := setupDatabase(ctx)
    if err != nil {
        return 0, err
    }
    defer d.Close() // Явно очищаем базу данных.
    db = d          // db определена как переменная на уровне пакета.

    // m.Run() выполняет обычные, определенные пользователем тестовые функции.
    // Любые операторы defer, которые были сделаны, будут выполнены после завершения m.Run().
    return m.Run(), nil
}

func TestMain(m *testing.M) {
    code, err := runMain(context.Background(), m)
    if err != nil {
        // Сообщения о сбоях должны записываться в STDERR, что и использует log.Fatal.
        log.Fatal(err)
    }
    // ПРИМЕЧАНИЕ: операторы defer не выполняются после здесь из-за os.Exit
    //       завершающего процесс.
    os.Exit(code)
}
```

В идеале тестовый случай является герметичным (hermetic) между вызовами самого
себя и между другими тестовыми случаями.

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

<a id="t-setup-amortization"></a>

#### Амортизация общей настройки теста (Amortizing common test setup)

Использование `sync.Once` может быть уместным, хотя и не обязательно, если все
из следующего верно для общей настройки:

- Она дорогая.
- Она применяется только к некоторым тестам.
- Она не требует очистки.

```go
// Хорошо:
var dataset struct {
    once sync.Once
    data []byte
    err  error
}

func mustLoadDataset(t *testing.T) []byte {
    t.Helper()
    dataset.once.Do(func() {
        data, err := os.ReadFile("path/to/your/project/testdata/dataset")
        // dataset определена как переменная на уровне пакета.
        dataset.data = data
        dataset.err = err
    })
    if err := dataset.err; err != nil {
        t.Fatalf("Could not load dataset: %v", err)
    }
    return dataset.data
}
```

Когда `mustLoadDataset` используется в нескольких тестовых функциях, ее
стоимость амортизируется:

```go
// Хорошо:
func TestParseData(t *testing.T) {
    data := mustLoadDataset(t)

    // Как описано выше.
}

func TestListContents(t *testing.T) {
    data := mustLoadDataset(t)

    // Как описано выше.
}

func TestRegression682831(t *testing.T) {
    if got, want := guessOS("zpc79.example.com"), "grhat"; got != want {
        t.Errorf(`guessOS("zpc79.example.com") = %q, want %q`, got, want)
    }
}
```

Причина, по которой общая очистка сложна, заключается в том, что нет единого
места для регистрации процедур очистки. Если функция настройки (в данном случае
`mustLoadDataset`) полагается на контекст, `sync.Once` может быть
проблематичным. Это потому, что второй из двух конкурентных вызовов функции
настройки должен будет ждать завершения первого вызова, прежде чем вернуться.
Этот период ожидания нельзя легко заставить уважать отмену контекста.

<a id="string-concat"></a>

## Конкатенация строк (String concatenation)

Есть несколько способов конкатенации строк в Go. Некоторые примеры включают:

- Оператор "+"
- `fmt.Sprintf`
- `strings.Builder`
- `text/template`
- `safehtml/template`

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

<a id="string-concat-simple"></a>

### Предпочитайте "+" для простых случаев (Prefer "+" for simple cases)

Предпочитайте использовать "+" при конкатенации нескольких строк. Этот метод
синтаксически самый простой и не требует импорта.

```go
// Хорошо:
key := "projectid: " + p
```

<a id="string-concat-fmt"></a>

### Предпочитайте `fmt.Sprintf` при форматировании (Prefer `fmt.Sprintf` when formatting)

Предпочитайте использовать `fmt.Sprintf` при построении сложной строки с
форматированием. Использование многих операторов "+" может затмить конечный
результат.

```go
// Хорошо:
str := fmt.Sprintf("%s [%s:%d]-> %s", src, qos, mtu, dst)
```

```go
// Плохо:
bad := src.String() + " [" + qos.String() + ":" + strconv.Itoa(mtu) + "]-> " + dst.String()
```

**Лучшая практика:** Когда результатом операции построения строки является
`io.Writer`, не конструируйте временную строку с помощью `fmt.Sprintf`, чтобы
просто отправить ее в Writer. Вместо этого используйте `fmt.Fprintf`, чтобы
отправлять прямо в Writer.

Когда форматирование еще сложнее, предпочитайте [`text/template`] или
[`safehtml/template`] по мере необходимости.

[`text/template`]: https://pkg.go.dev/text/template
[`safehtml/template`]: https://pkg.go.dev/github.com/google/safehtml/template

<a id="string-concat-piecemeal"></a>

### Предпочитайте `strings.Builder` для построения строки по частям (Prefer `strings.Builder` for constructing a string piecemeal)

Предпочитайте использовать `strings.Builder` при построении строки по частям.
`strings.Builder` занимает амортизированное линейное время, тогда как "+" и
`fmt.Sprintf` занимают квадратичное время при последовательном вызове для
формирования большей строки.

```go
// Хорошо:
b := new(strings.Builder)
for i, d := range digitsOfPi {
    fmt.Fprintf(b, "the %d digit of pi is: %d\n", i, d)
}
str := b.String()
```

**Примечание:** Для более подробного обсуждения см. [GoTip #29: Building
Strings Efficiently](/pages/gostyleguide/google/index.html#gotip).

<a id="string-constants"></a>

### Константные строки (Constant strings)

Предпочитайте использовать обратные кавычки (\`) при создании константных,
многострочных строковых литералов.

```go
// Хорошо:
usage := `Usage:

custom_tool [args]`
```

```go
// Плохо:
usage := "" +
  "Usage:\n" +
  "\n" +
  "custom_tool [args]"
```

<a id="globals"></a>

## Глобальное состояние (Global state)

Библиотеки не должны заставлять своих клиентов использовать API, которые
полагаются на [глобальное состояние (global
state)](https://en.wikipedia.org/wiki/Global_variable). Им рекомендуется не
раскрывать API или экспортировать переменные на [уровне пакета (package level)],
которые контролируют поведение для всех клиентов как часть их API. В остальной
части раздела "глобальное" и "состояние на уровне пакета" используются как
синонимы.

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

**Важно:** Хотя это руководство применимо ко всем разработчикам, оно наиболее
критично для поставщиков инфраструктуры, которые предлагают библиотеки,
интеграции и сервисы другим командам.

[глобальное состояние (global state)]: https://en.wikipedia.org/wiki/Global_variable
[уровне пакета (package level)]: https://go.dev/ref/spec#TopLevelDecl

```go
// Хорошо:
// Пакет sidecar управляет подпроцессами, которые предоставляют функции для приложений.
package sidecar

type Registry struct { plugins map[string]*Plugin }

func New() *Registry { return &Registry{plugins: make(map[string]*Plugin)} }

func (r *Registry) Register(name string, p *Plugin) error { ... }
```

Ваши пользователи будут создавать необходимые им данные (`*sidecar.Registry`), а
затем передавать их как явную зависимость:

```go
// Хорошо:
package main

func main() {
  sidecars := sidecar.New()
  if err := sidecars.Register("Cloud Logger", cloudlogger.New()); err != nil {
    log.Exitf("Could not setup cloud logger: %v", err)
  }
  cfg := &myapp.Config{Sidecars: sidecars}
  myapp.Run(context.Background(), cfg)
}
```

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

См. также:

- [Go Tip #5: Slimming Your Client
  Libraries](/pages/gostyleguide/google/index.html#gotip)
- [Go Tip #24: Use Case-Specific
  Constructions](/pages/gostyleguide/google/index.html#gotip)
- [Go Tip #40: Improving Time Testability with Function
  Parameters](/pages/gostyleguide/google/index.html#gotip)
- [Go Tip #41: Identify Function Call
  Parameters](/pages/gostyleguide/google/index.html#gotip)
- [Go Tip #44: Improving Time Testability with Struct
  Fields](/pages/gostyleguide/google/index.html#gotip)
- [Go Tip #80: Dependency Injection
  Principles](/pages/gostyleguide/google/index.html#gotip)

API, которые не поддерживают явную передачу зависимостей, становятся хрупкими с
увеличением числа клиентов:

```go
// Плохо:
package sidecar

var registry = make(map[string]*Plugin)

func Register(name string, p *Plugin) error { /* регистрирует плагин в registry */ }
```

Рассмотрим, что происходит в случае тестов, проверяющих код, который транзитивно
зависит от sidecar для облачного логирования.

```go
// Плохо:
package app

import (
  "cloudlogger"
  "sidecar"
  "testing"
)

func TestEndToEnd(t *testing.T) {
  // Система под тестом (SUT) полагается на sidecar для production облачного
  // логгера, который уже зарегистрирован.
  ... // Проверяем SUT и проверяем инварианты.
}

func TestRegression_NetworkUnavailability(t *testing.T) {
  // У нас был сбой из-за сетевого раздела, который сделал облачный логгер
  // неработоспособным, поэтому мы добавили регрессионный тест для проверки SUT с
  // тестовым двойником, имитирующим недоступность сети для логгера.
  sidecar.Register("cloudlogger", cloudloggertest.UnavailableLogger)
  ... // Проверяем SUT и проверяем инварианты.
}

func TestRegression_InvalidUser(t *testing.T) {
  // Система под тестом (SUT) полагается на sidecar для production облачного
  // логгера, который уже зарегистрирован.
  //
  // Упс. cloudloggertest.UnavailableLogger все еще зарегистрирован с
  // предыдущего теста.
  ... // Проверяем SUT и проверяем инварианты.
}
```

Тесты Go выполняются последовательно по умолчанию, поэтому вышеуказанные тесты
выполняются как:

1.  `TestEndToEnd`
2.  `TestRegression_NetworkUnavailability`, который переопределяет значение по
    умолчанию cloudlogger
3.  `TestRegression_InvalidUser`, который требует значения по умолчанию
    cloudlogger, зарегистрированного в `package sidecar`

Это создает тестовый случай, зависящий от порядка, что нарушает запуск с
фильтрами тестов и не позволяет тестам запускаться параллельно или
шардироваться.

Использование глобального состояния создает проблемы, на которые нет простых
ответов для вас и клиентов API:

- Что произойдет, если клиенту нужно использовать разные и отдельно работающие
  наборы `Plugin` (например, для поддержки нескольких серверов) в одном
  процессе?

- Что произойдет, если клиент захочет заменить зарегистрированный `Plugin`
  альтернативной реализацией в тесте, например, [тестовым двойником]?

    Что произойдет, если тестам клиента требуется герметичность между
    экземплярами `Plugin` или между всеми зарегистрированными плагинами?

- Что произойдет, если несколько клиентов `Register` плагин `Plugin` под одним
  и тем же именем? Кто победит, если вообще победит?

    Как следует [обрабатывать](https://neonxp.ru/pages/gostyleguide/google/decisions/#handle-errors) ошибки? Если код
    вызывает panic или `log.Fatal`, будет ли это всегда [уместно для всех мест,
    в которых может быть вызван API](https://neonxp.ru/pages/gostyleguide/google/decisions/#dont-panic)? Может ли клиент
    проверить, что он не делает ничего плохого, прежде чем сделать это?

- Существуют ли определенные этапы начальной загрузки программы или ее
  жизненного цикла, во время которых можно вызывать `Register`, а когда нет?

            Что произойдет, если `Register` будет вызван в неподходящее время? Клиент
            может вызвать `Register` в [`func

    init`](https://go.dev/ref/spec#Package_initialization), до разбора флагов
или после `main`. Этап, на котором вызывается функция, влияет на обработку
ошибок. Если автор API предполагает, что API вызывается _только_ во время
инициализации программы без требования, чтобы это было так, это
предположение может подтолкнуть автора к проектированию обработки ошибок для
[завершения программы](https://neonxp.ru/pages/gostyleguide/google/best-practices/#program-init), моделируя API как
функцию типа `Must`. Завершение не подходит для библиотечных функций общего
    назначения, которые могут использоваться на любом этапе.

- Что, если потребности в параллелизме клиента и дизайнера не совпадают?

См. также:

- [Go Tip #36: Enclosing Package-Level
  State](/pages/gostyleguide/google/index.html#gotip)
- [Go Tip #71: Reducing Parallel Test
  Flakiness](/pages/gostyleguide/google/index.html#gotip)
- [Go Tip #80: Dependency Injection
  Principles](/pages/gostyleguide/google/index.html#gotip)
- Обработка ошибок: [Look Before You
  Leap](https://docs.python.org/3/glossary.html#term-LBYL) против [Easier to
  Ask for Forgiveness than
  Permission](https://docs.python.org/3/glossary.html#term-EAFP)
- [Unit Testing Practices on Public APIs]

Глобальное состояние имеет каскадные эффекты на [здоровье кодовой базы
Google](https://neonxp.ru/pages/gostyleguide/google/guide/.md#maintainability). К глобальному состоянию следует подходить с
**крайней тщательностью**.

[Глобальное состояние бывает нескольких форм](#globals-forms), и вы можете
использовать несколько [лакмусовых тестов, чтобы определить, когда оно
безопасно](#globals-litmus-tests).

[Unit Testing Practices on Public APIs]: index.md#unit-testing-practices

<a id="globals-forms"></a>

### Основные формы API состояния пакета (Major forms of package state APIs)

Ниже перечислены несколько наиболее распространенных проблемных форм API:

- Переменные верхнего уровня, независимо от того, экспортируются они или нет.

    ```go
    // Плохо:
    package logger

    // Sinks управляет выходными источниками по умолчанию для API логирования этого пакета.
    // Эта переменная должна быть установлена во время инициализации пакета и никогда после этого.
    var Sinks []Sink
    ```

    См. [лакмусовые тесты](#globals-litmus-tests), чтобы узнать, когда они
    безопасны.

- Шаблон [локатора служб (service locator
  pattern)](https://en.wikipedia.org/wiki/Service_locator_pattern). См.
  [первый пример](#globals). Сам шаблон локатора служб не является
  проблематичным, а проблема в том, что локатор определен как глобальный.

- Реестры для [обратных вызовов
  (callbacks)](<https://en.wikipedia.org/wiki/Callback_(computer_programming)>)
  и подобного поведения.

    ```go
    // Плохо:
    package health

    var unhealthyFuncs []func

    func OnUnhealthy(f func()) {
      unhealthyFuncs = append(unhealthyFuncs, f)
    }
    ```

- "Толстые" (thick) клиентские синглтоны для таких вещей, как бэкенды,
  хранилища, уровни доступа к данным и другие системные ресурсы. Они часто
  создают дополнительные проблемы с надежностью служб.

    ```go
    // Плохо:
    package useradmin

    var client pb.UserAdminServiceClientInterface

    func Client() *pb.UserAdminServiceClient {
        if client == nil {
            client = ...  // Настройка клиента.
        }
        return client
    }
    ```

> **Примечание:** Многие устаревшие API в кодовой базе Google не следуют этому
> руководству; фактически, некоторые стандартные библиотеки Go позволяют
> настраивать поведение через глобальные значения. Тем не менее, нарушение
> этого руководства устаревшим API **[не должно использоваться как
> прецедент](https://neonxp.ru/pages/gostyleguide/google/guide/#local-consistency)** для продолжения шаблона.
>
> Лучше инвестировать в правильный дизайн API сегодня, чем платить за его
> перепроектирование позже.

<a id="globals-litmus-tests"></a>

### Лакмусовые тесты (Litmus tests)

[API, использующие шаблоны выше](#globals-forms), небезопасны, когда:

- Несколько функций взаимодействуют через глобальное состояние при выполнении
  в одной программе, несмотря на то, что в остальном они независимы (например,
  написаны разными авторами в совершенно разных каталогах).
- Независимые тестовые случаи взаимодействуют друг с другом через глобальное
  состояние.
- Пользователи API склонны заменять или подменять глобальное состояние для
  целей тестирования, особенно чтобы заменить любую часть состояния [тестовым
  двойником], например, заглушкой, фейком, шпионом или моком.
- Пользователи должны учитывать особые требования к порядку при взаимодействии
  с глобальным состоянием: `func init`, разобраны ли уже флаги и т.д.

При условии, что вышеуказанные условия избегаются, существует **несколько
ограниченных обстоятельств, при которых эти API безопасны**, а именно, когда
верно любое из следующего:

- Глобальное состояние логически постоянно
  ([пример](https://github.com/klauspost/compress/blob/290f4cfacb3eff892555a491e3eeb569a48665e7/zstd/snappy.go#L413)).
- Наблюдаемое поведение пакета является бессостоятельным (stateless).
  Например, общедоступная функция может использовать частную глобальную
  переменную в качестве кэша, но пока вызывающая сторона не может отличить
  попадания в кэш от промахов, функция является бессостоятельной.
- Глобальное состояние не просачивается в вещи, внешние по отношению к
  программе, такие как sidecar-процессы или файлы в общей файловой системе.
- Нет ожидания предсказуемого поведения
  ([пример](https://pkg.go.dev/math/rand)).

> **Примечание:**
> [Sidecar-процессы](https://www.oreilly.com/library/view/designing-distributed-systems/9781491983638/ch02.html)
> могут **не** быть строго локальными для процесса. Они могут и часто
> используются совместно более чем одним процессом приложения. Более того, эти
> sidecar часто взаимодействуют с внешними распределенными системами.
>
> Кроме того, те же правила бессостоятельности, идемпотентности и локальности в
> дополнение к базовым соображениям выше применялись бы к коду самого
> sidecar-процесса!

Пример одной из таких безопасных ситуаций — [`package
image`](https://pkg.go.dev/image) с его функцией
[`image.RegisterFormat`](https://pkg.go.dev/image#RegisterFormat). Рассмотрим
лакмусовые тесты, примененные к типичному декодеру, например, для обработки
формата [PNG](https://pkg.go.dev/image/png):

- Множественные вызовы API `package image`, использующие зарегистрированные
  декодеры (например, `image.Decode`), не могут мешать друг другу, аналогично
  и для тестов. Единственное исключение — `image.RegisterFormat`, но это
  смягчается пунктами ниже.
- Крайне маловероятно, что пользователь захочет заменить декодер [тестовым
  двойником], так как декодер PNG является примером случая, когда предпочтение
  нашей кодовой базы реальным объектам применяется. Однако пользователь с
  большей вероятностью заменит декодер тестовым двойником, если декодер
  состоятельно взаимодействует с ресурсами операционной системы (например,
  сетью).
- Коллизии при регистрации возможны, хотя на практике они, вероятно, редки.
- Декодеры являются бессостоятельными, идемпотентными и чистыми (pure).

<a id="globals-default-instance"></a>

### Предоставление экземпляра по умолчанию (Providing a default instance)

Хотя и не рекомендуется, допустимо предоставить упрощенный API, использующий
состояние на уровне пакета, если вам нужно максимизировать удобство для
пользователя.

Следуйте [лакмусовым тестам](#globals-litmus-tests) с этими рекомендациями в
таких случаях:

1.  Пакет должен предлагать клиентам возможность создавать изолированные
    экземпляры типов пакета, как [описано выше](#globals-forms).
2.  Общедоступные API, использующие глобальное состояние, должны быть тонкой
    прослойкой (thin proxy) к предыдущему API. Хороший пример этого —
    [`http.Handle`](https://pkg.go.dev/net/http#Handle), внутренне вызывающий
    [`(*http.ServeMux).Handle`](https://pkg.go.dev/net/http#ServeMux.Handle) на
    переменной пакета
    [`http.DefaultServeMux`](https://pkg.go.dev/net/http#DefaultServeMux).
3.  Этот API уровня пакета должен использоваться только [целями сборки
    бинарников (binary build targets)], а не [библиотеками (libraries)], если
    только библиотеки не предпринимают рефакторинг для поддержки передачи
    зависимостей. Инфраструктурные библиотеки, которые могут быть импортированы
    другими пакетами, не должны полагаться на состояние на уровне пакета
    импортируемых ими пакетов.

    Например, поставщик инфраструктуры, реализующий sidecar, который должен
    использоваться совместно с другими командами, использующими API сверху,
    должен предложить API для этого:

    ```go
    // Хорошо:
    package cloudlogger

    func New() *Logger { ... }

    func Register(r *sidecar.Registry, l *Logger) {
      r.Register("Cloud Logging", l)
    }
    ```

4.  Этот API уровня пакета должен [документировать](#documentation-conventions)
    и обеспечивать соблюдение своих инвариантов (например, на каком этапе
    жизненного цикла программы его можно вызывать, можно ли использовать его
    параллельно). Кроме того, он должен предоставлять API для сброса глобального
    состояния к известному хорошему значению по умолчанию (например, для
    облегчения тестирования).

[целями сборки бинарников (binary build targets)]: https://github.com/bazelbuild/rules_go/blob/master/docs/go/core/rules.md#go_binary
[библиотеками (libraries)]: https://github.com/bazelbuild/rules_go/blob/master/docs/go/core/rules.md#go_library

См. также:

- [Go Tip #36: Enclosing Package-Level
  State](/pages/gostyleguide/google/index.html#gotip)
- [Go Tip #80: Dependency Injection
  Principles](/pages/gostyleguide/google/index.html#gotip)