Перейти к основному содержимому

Рекомендации по разработке на Go

ОБЯЗАТЕЛЬНОДЛЯ НОВИЧКОВ
Разработчику Архитектору

Рекомендации по разработке на Go​

Введение в культуру кода Go​

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

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

Требования по именованию​

Стили именования в Go​

Go использует два основных стиля именования:

  • PascalCase для экспортируемых идентификаторов (начинаются с заглавной буквы)
  • camelCase для неэкспортируемых идентификаторов (начинаются со строчной буквы)

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

Элемент языкаСтильПримерЭкспорт
Пакетsnake_casenet/httpВсегда
Тип (структура)PascalCaseUserRepositoryДа
ИнтерфейсPascalCaseReaderДа
КонстантаPascalCaseMaxConnectionsДа
ПеременнаяcamelCaseuserCountНет
Функция/методPascalCaseCalculateTotalДа
Функция/методcamelCasecalculateInternalНет
Поле структурыPascalCaseUserNameДа
Поле структурыcamelCaseinternalStateНет

Правила именования пакетов​

Имена пакетов должны быть короткими, лаконичными и описательными. Используйте единственное число без подчеркиваний. Хорошие примеры — http, json, time, bytes. Избегайте имен вроде util, common, helper — такие пакеты часто становятся сборником несвязанных функций.

Пакет представляет собой пространство имен для своих содержимых. При использовании пакета его имя становится частью идентификатора: bytes.Buffer, time.Duration. Поэтому избыточные имена пакетов создают шум: user.User вместо простого user.Model.

Именование переменных и параметров​

Имена должны отражать назначение переменной в контексте. Для локальных переменных допустимы короткие имена (i, r, w), когда их назначение очевидно из контекста. Для глобальных переменных и параметров функций используйте полные, описательные имена.

Хорошие примеры:

// Короткие имена в узком контексте
for i := 0; i < len(items); i++ {
    process(items[i])
}

// Полные имена для параметров
func CreateUser(email string, passwordHash []byte) error

Избегайте избыточных префиксов и суффиксов. Не нужно добавлять str к строкам или num к числам — тип уже виден из объявления.

Именование интерфейсов​

Интерфейсы в Go обычно имеют одно-два метода и получают имена, оканчивающиеся на -er — Reader, Writer, Stringer, Formatter. Для интерфейсов с несколькими методами или специфическим назначением используйте описательные имена без суффикса -er — FileSystem, Database, Cache.

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

Требования по оформлению​

Форматирование с помощью gofmt​

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

  • Отступы — символ табуляции (в редакторе часто отображаются как 4 или 8 пробелов); gofmt не переводит табы в пробелы
  • Открывающая фигурная скобка размещается в той же строке, что и объявление
  • После открывающей скобки всегда следует перевод строки
  • Перед закрывающей скобкой всегда следует перевод строки
  • Операторы разделяются пробелами для улучшения читаемости

Пример корректного форматирования:

func CalculateTotal(items []Item) float64 {
    var total float64
    for _, item := range items {
        total += item.Price * float64(item.Quantity)
    }
    return total
}

Никогда не изменяйте поведение gofmt через кастомные настройки редактора. Единообразие форматирования — ключевое преимущество экосистемы Go.

Правила оформления выражений​

Окружайте бинарные операторы пробелами:

// Хорошо
x := a + b
result := value > threshold

// Плохо
x:=a+b
result:=value>threshold

Условие if без скобок вокруг выражения (в отличие от C/Java):

// Хорошо
if x > 0 && y < 10 {
    process()
}

// Синтаксическая ошибка
if (x > 0) && (y < 10) {
    process()
}

Размещайте открывающую скобку блока на той же строке, что и управляющая конструкция:

// Хорошо
if err != nil {
    return err
}

// Плохо
if err != nil
{
    return err
}

Длина строк и переносы​

Стремитесь удерживать длину строк в пределах 100 символов. При необходимости переноса аргументов функции или элементов выражения выравнивайте их по открывающей скобке:

// Хорошо
result, err := database.Query(
    "SELECT id, name, email FROM users WHERE active = ?",
    true,
)

// Хорошо для длинных цепочек
value := strings.TrimSpace(
    strings.ToLower(
        strings.ReplaceAll(input, "\n", " "),
    ),
)

Для переноса условий в if используйте явные блоки:

if err != nil ||
   result == nil ||
   len(items) == 0 {
    return errors.New("invalid state")
}

Оформление комментариев​

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

Однострочные комментарии начинаются с // и отделяются пробелом от текста:

// Calculate total price including tax
total := calculateTotal(items)

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

/*
Package http provides HTTP client and server implementations.

The client and server implementations are designed to be minimal
and extensible through middleware patterns.
*/
package http

Структура проекта и организация файлов​

Стандартная структура модуля​

Современные проекты на Go используют модули (Go Modules). Корневая структура проекта:

myapp/
├── go.mod
├── go.sum
├── main.go
├── cmd/
│   └── myapp/
│       └── main.go
├── internal/
│   ├── service/
│   │   └── user.go
│   ├── repository/
│   │   └── postgres.go
│   └── model/
│       └── user.go
├── pkg/
│   └── validator/
│       └── validator.go
├── api/
│   └── openapi.yaml
├── migrations/
│   └── 001_init.sql
├── scripts/
│   └── deploy.sh
├── testdata/
│   └── fixtures.json
└── Makefile

Назначение директорий​

  • cmd/ — точки входа приложения. Каждое исполняемое приложение получает отдельную поддиректорию.
  • internal/ — приватный код, доступный только внутри модуля. Разделяется по функциональным областям.
  • pkg/ — общедоступные библиотеки, которые могут использоваться другими проектами.
  • api/ — описание интерфейсов (OpenAPI, Protocol Buffers).
  • migrations/ — файлы миграций базы данных.
  • testdata/ — данные для тестов, исключенные из сборки.

Организация файлов внутри пакета​

Каждый файл должен иметь четкую ответственность. Типичная структура пакета:

user/
├── user.go        // Основные типы и структуры
├── service.go     // Бизнес-логика
├── repository.go  // Работа с хранилищем данных
├── errors.go      // Специфичные ошибки пакета
└── user_test.go   // Тесты

Избегайте файлов с именами вроде utils.go или helpers.go. Такие файлы становятся мусорными ведрами для несвязанного кода. Каждая функция должна иметь четкое место в архитектуре приложения.

Обработка ошибок​

Возврат ошибок​

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

func LoadConfig(path string) (*Config, error) {
    data, err := os.ReadFile(path)
    if err != nil {
        return nil, fmt.Errorf("failed to read config file: %w", err)
    }
    // ...
}

Используйте fmt.Errorf с директивой %w для оборачивания ошибок. Это сохраняет стек вызовов и позволяет использовать errors.Is и errors.As для проверки типов ошибок.

Проверка ошибок​

Всегда проверяйте возвращаемые ошибки. Не игнорируйте их с пустым блоком if:

// Хорошо
if err != nil {
    return fmt.Errorf("operation failed: %w", err)
}

// Плохо
if err != nil {
    // игнорируем ошибку
}

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

Создание кастомных ошибок​

Определяйте типы ошибок как структуры с методом Error():

type ValidationError struct {
    Field string
    Msg   string
}

func (e *ValidationError) Error() string {
    return fmt.Sprintf("validation failed for field %s: %s", e.Field, e.Msg)
}

Это позволяет проводить точную проверку типов ошибок с помощью errors.As.

Обработка ошибок на границах​

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

Комментарии и документация​

Документация пакетов​

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

// Package user provides user management functionality including
// registration, authentication, and profile management.
package user

Для основного пакета приложения документация не обязательна.

Документация функций и типов​

Экспортируемые функции, типы и методы должны иметь комментарии в формате Godoc:

// CreateUser registers a new user with the provided credentials.
// Returns an error if the email is already registered or validation fails.
func CreateUser(email, password string) (*User, error) {
    // ...
}

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

Примеры кода в документации​

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

// ExampleCreateUser demonstrates basic user registration.
func ExampleCreateUser() {
    user, err := CreateUser("test@example.com", "securepass")
    if err != nil {
        log.Fatal(err)
    }
    fmt.Println(user.ID)
    // Output: 123
}

Такие примеры становятся частью генерируемой документации и автоматически проверяются при тестировании.

Проектирование пакетов и интерфейсов​

Принцип единственной ответственности​

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

Пример хорошей структуры:

internal/
├── user/          // Доменная логика пользователей
├── auth/          // Аутентификация и авторизация
├── storage/       // Абстракция хранилища данных
└── delivery/      // HTTP-обработчики

Пакет user не зависит от storage напрямую. Вместо этого он работает с интерфейсом UserRepository, который реализуется в пакете storage.

Минимальные интерфейсы​

Интерфейсы должны содержать минимально необходимое количество методов. Предпочитайте множество маленьких интерфейсов одному большому:

Код ITЗагрузка примера кода…

Маленькие интерфейсы легче реализовать и комбинировать.

Инверсия зависимостей​

Высокоуровневые модули не должны зависеть от низкоуровневых. Оба должны зависеть от абстракций. Абстракции не должны зависеть от деталей. Детали должны зависеть от абстракций.

Пример применения:

Код ITЗагрузка примера кода…

Конкретная реализация размещается в инфраструктурном пакете:

// Реализация в пакете хранилища
package postgres

type UserRepository struct {
    db *sql.DB
}

func (r *UserRepository) FindByID(id string) (*user.User, error) {
    // реализация
}

Связывание происходит на верхнем уровне приложения:

// main.go
repo := postgres.NewUserRepository(db)
svc := user.NewService(repo)

Параллелизм и конкурентность​

Горутины и каналы​

Горутины — легковесные потоки выполнения. Запускайте горутину только когда есть четкое понимание её жизненного цикла и условий завершения.

Всегда предусматривайте механизм завершения горутин:

func processEvents(ctx context.Context, events <-chan Event) {
    for {
        select {
        case <-ctx.Done():
            return // Завершение по сигналу контекста
        case event, ok := <-events:
            if !ok {
                return // Канал закрыт
            }
            handle(event)
        }
    }
}

Контекст для управления жизненным циклом​

Используйте context.Context для передачи сигналов отмены и таймаутов:

func fetchData(ctx context.Context, url string) ([]byte, error) {
    req, err := http.NewRequestWithContext(ctx, "GET", url, nil)
    if err != nil {
        return nil, err
    }
    resp, err := http.DefaultClient.Do(req)
    if err != nil {
        return nil, err
    }
    defer resp.Body.Close()
    return io.ReadAll(resp.Body)
}

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

Синхронизация​

Для защиты общих данных используйте sync.Mutex или sync.RWMutex:

type Counter struct {
    mu    sync.Mutex
    value int
}

func (c *Counter) Increment() {
    c.mu.Lock()
    defer c.mu.Unlock()
    c.value++
}

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

Тестирование​

Структура тестовых файлов​

Тестовые файлы размещаются в той же директории, что и тестируемый код, с суффиксом _test.go:

user/
├── user.go
├── service.go
└── service_test.go

Таблицные тесты​

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

Код ITЗагрузка примера кода…

Моки и заглушки​

Для изолированного тестирования создавайте заглушки зависимостей через интерфейсы:

type mockRepository struct {
    users map[string]*User
}

func (m *mockRepository) FindByID(id string) (*User, error) {
    user, ok := m.users[id]
    if !ok {
        return nil, ErrNotFound
    }
    return user, nil
}

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

Тестирование конкурентности​

Для тестирования конкурентного кода используйте sync.WaitGroup и testing.T.Parallel():

Код ITЗагрузка примера кода…

Производительность и оптимизация​

Аллокации памяти​

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

// Хорошо: предварительное выделение
result := make([]string, 0, len(items))
for _, item := range items {
    result = append(result, item.Name)
}

// Плохо: многократное перевыделение
var result []string
for _, item := range items {
    result = append(result, item.Name)
}

Кэширование​

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

Профилирование​

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

# Профилирование CPU
go test -cpuprofile cpu.prof ./...

# Профилирование памяти
go test -memprofile mem.prof ./...

# Анализ профилей
go tool pprof cpu.prof

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

Инструменты разработки​

Статический анализ​

Регулярно запускайте стандартные инструменты анализа:

# Форматирование
gofmt -w .

# Проверка на ошибки
go vet ./...

# Статический анализ
staticcheck ./...

Linters​

Используйте современные линтеры через golangci-lint:

Код ITЗагрузка примера кода…

Makefile для автоматизации​

Создайте единый интерфейс для повседневных задач:

Код ITЗагрузка примера кода…

Примеры хорошего кода​

Чистая функция обработки данных​

Код ITЗагрузка примера кода…

Структура с методами​

Код ITЗагрузка примера кода…

Обработка ошибок с контекстом​

Код ITЗагрузка примера кода…

Дополнительная литература​

ИсточникЗачем
Дженерики, gRPC, CLI, профилирование, WebSocketУглублённый маршрут раздела
Effective GoОфициальные идиомы
Go Blog — GenericsРазбор constraints
Основа по протоколу

Базовый разбор HTTP и HTTPS находится в отдельной статье — HTTP как основа веб-интеграций.

Содержание