range в Go: перебор коллекций, копирование значений и ошибки

• 11 мин чтения

for range в Go перебирает элементы массива, слайса или map, декодирует строку по рунам и получает значения из канала. Переменная цикла получает копию значения. Поэтому присваивание полю user.Active внутри for _, user := range users не меняет структуру в слайсе.

Для изменения структуры в слайсе обращайтесь к ней по индексу: users[i].Active = true. Ниже показано, когда нужны индекс, копия значения или указатель. Примеры с адресами и замыканиями учитывают новые правила переменных цикла, действующие с Go 1.22.

Что возвращает range

Начнём с обхода слайса:

package main

import "fmt"

func main() {
	names := []string{"Анна", "Борис"}
	for i, name := range names {
		fmt.Println(i, name)
	}
	// 0 Анна
	// 1 Борис
}

Первое значение зависит от типа справа от range. Для слайса это индекс, для map ключ, а для канала сразу полученный элемент.

ВыражениеПервое значениеВторое значение
Массив [N]T, указатель *[N]T, слайс []TИндекс intЭлемент T
Строка stringИндекс первого байта руны, intРуна rune
Карта map[K]VКлюч KЗначение V
Канал chan T или <-chan TПолученный элемент TНет
Целое число n, начиная с Go 1.22Числа от 0 до n-1Нет
Итератор в виде функции, начиная с Go 1.23Зависит от сигнатурыЗависит от сигнатуры

Если нужен только индекс слайса, пишите for i := range items. Для значений используйте for _, value := range items. Запись for value := range items тоже допустима, но переменная с именем value получит индекс.

Когда значения вообще не нужны, допустимо for range items. Например, так можно выполнить действие по одному разу на каждый элемент. Для канала эта форма получает и отбрасывает значения до его закрытия.

Дальше короткие блоки без package main являются фрагментами внутри main. Для вывода нужен импорт fmt. Полные программы приведены отдельно.

Почему изменение value не меняет элемент слайса

Пусть нужно активировать пользователей:

type User struct {
	Name   string
	Active bool
}

users := []User{{Name: "Анна"}, {Name: "Борис"}}
for _, user := range users {
	user.Active = true
}
fmt.Println(users[0].Active) // false

В user находится копия структуры. Присваивание меняет эту копию, а элемент users[0] остаётся прежним. Для изменения оригинала обращайтесь по индексу:

// Продолжение предыдущего примера.
for i := range users {
	users[i].Active = true
}
fmt.Println(users[0].Active) // true

Если методу нужен указатель, его можно вызвать у users[i]: компилятор сможет взять адрес элемента. Вызов такого же метода у user изменит локальную копию. Подробнее это разобрано в статье о методах и копировании структур.

Копирование не делает вложенные данные независимыми

Если элемент сам является слайсом, копируется значение слайса, которое сохраняет доступ к базовому массиву:

rows := [][]int{{1, 2}, {3, 4}}
for _, row := range rows {
	row[0] = 99
}
fmt.Println(rows) // [[99 2] [99 4]]

Копия row обращается к тем же числам, что и соответствующий элемент rows. Но присваивание row = nil меняет только локальную переменную. Чтобы заменить вложенный слайс, нужно rows[i] = nil.

Так же ведёт себя слайс указателей []*User: переменная цикла получает копию указателя. Через user.Active = true можно изменить структуру, на которую он указывает. Если указатель равен nil, такое обращение вызовет панику.

Что происходит при append внутри range

Добавленные через append элементы слайса не попадут в текущий обход range. До начала цикла вычисляется выражение справа от range. Для слайса сохраняются исходная длина и доступ к базовому массиву. Сами элементы слайса не копируются целиком.

items := make([]int, 2, 4)
items[0], items[1] = 1, 2

for i, value := range items {
	fmt.Println(i, value)
	if i == 0 {
		items[1] = 20
		items = append(items, 3)
	}
}
// 0 1
// 1 20
fmt.Println(items) // [1 20 3]

Цикл делает две итерации, хотя len(items) в теле выросла до трёх. Изменение второго элемента видно, потому что базовый массив остался общим.

Если ёмкости не хватит, append создаст новый базовый массив. Переменная items начнёт ссылаться на него, а текущий обход продолжит читать старый. Поэтому результат последующих изменений зависит от того, какой массив они затрагивают. Не стройте обработку очереди на предположении, что range посетит добавленные элементы.

Если нужно обрабатывать и новые элементы, условие обычного цикла может проверять текущую длину: for i := 0; i < len(items); i++. Предусмотрите условие завершения: если каждый шаг добавляет новую работу, такой цикл может не закончиться.

Сокращать слайс внутри range тоже нужно осторожно. Индексы продолжают доходить до исходной границы. Обращение items[i] после уменьшения длины может вызвать панику. Для удаления по условию удобнее отдельный проход с записью оставшихся элементов, как в статье об удалении из слайса.

Массив: обход копии и чтение оригинала

У массива поведение отличается от слайса:

a := [3]int{1, 2, 3}
for i, value := range a {
	if i == 0 {
		a[1] = 20
	}
	fmt.Println(value)
}
// 1
// 2
// 3
fmt.Println(a) // [1 20 3]

В форме с индексом и значением range a перебирает копию массива. Изменение a[1] не влияет на будущий value из этой копии.

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

a := [3]int{1, 2, 3}
for i := range a {
	if i == 0 {
		a[1] = 20
	}
	fmt.Println(a[i])
}
// 1
// 20
// 3

Другой вариант: for i, value := range &a. Выражение содержит указатель на массив, поэтому значения читаются из исходного массива.

Здесь есть исключение из правила вычисления выражения перед циклом. Когда переменных итерации не больше одной, а len выражения является константой, само выражение range не вычисляется. Например, обход for i := range a для массива a только выдаёт индексы. Он не читает элементы и не требует копии массива ради этих индексов. Разница между массивом и слайсом подробнее показана в статье о массивах.

Адрес переменной цикла и изменения в Go 1.22

В семантике Go 1.22 и новее переменные, объявленные через := в заголовке цикла, создаются заново на каждой итерации. Однако копия элемента не становится самим элементом:

package main

import "fmt"

type User struct {
	Name string
}

func main() {
	users := []User{{Name: "Анна"}, {Name: "Борис"}}
	var copies []*User
	for _, user := range users {
		copies = append(copies, &user)
	}

	fmt.Println(copies[0] == copies[1]) // false
	copies[0].Name = "Копия"
	fmt.Println(users[0].Name) // Анна

	var originals []*User
	for i := range users {
		originals = append(originals, &users[i])
	}
	originals[0].Name = "Изменено"
	fmt.Println(users[0].Name) // Изменено
}

&user указывает на переменную с копией структуры. &users[i] указывает на элемент базового массива. Выбирайте адрес по задаче: сохранить отдельное значение или получить доступ к исходному элементу.

Если после сохранения адресов слайс вырастет с выделением нового массива, указатели останутся действительными. Но они продолжат указывать на элементы прежнего массива и больше не будут адресами элементов нового users.

Присваивание через = сохраняет общую переменную

Изменение Go 1.22 относится к объявлению переменных в цикле. Заранее объявленная переменная при = используется повторно:

values := []int{10, 20, 30}
var value int
var pointers []*int
for _, value = range values {
	pointers = append(pointers, &value)
}
fmt.Println(*pointers[0], *pointers[1], *pointers[2]) // 30 30 30
fmt.Println(pointers[0] == pointers[1])             // true

Все указатели ссылаются на одну переменную value. В старой семантике, до Go 1.22, это происходило и с переменной, объявленной через :=.

Для обычного пакета в модуле версию языка задаёт директива go в go.mod. Нового компилятора самого по себе недостаточно, чтобы пакет с go 1.21 получил новые правила переменных цикла. Версию для отдельного файла могут также повысить ограничения сборки //go:build. Переход описан в разборе команды Go.

Что изменилось для замыканий

Тот же принцип относится к отложенным вызовам замыканий:

values := []int{10, 20, 30}
var printLater []func()
for _, value := range values {
	printLater = append(printLater, func() {
		fmt.Println(value)
	})
}
for _, print := range printLater {
	print()
}
// В семантике Go 1.22+: 10, 20, 30 на отдельных строках.
// В старой семантике: 30, 30, 30.

Здесь горутин нет, поэтому результат не зависит от планировщика. С = вместо := все функции и в новой семантике прочитают общую переменную.

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

Map: порядок, изменение значений и удаление

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

Если последовательность попадает в тест, лог или отчёт, отсортируйте ключи перед обходом. В Go 1.23 и новее это можно сделать так:

package main

import (
	"fmt"
	"maps"
	"slices"
)

func main() {
	ports := map[string]int{"http": 80, "https": 443}
	for _, name := range slices.Sorted(maps.Keys(ports)) {
		fmt.Println(name, ports[name])
	}
	// http 80
	// https 443
}

maps.Keys возвращает итератор ключей, а slices.Sorted собирает их в отсортированный слайс. Подробности операций с map есть в отдельном разборе.

Значение из map тоже копируется. Чтобы сохранить изменение структуры, запишите её обратно:

type Counter struct {
	Total int
}

counts := map[string]Counter{"go": {Total: 1}}
for key, counter := range counts {
	counter.Total++
	counts[key] = counter
}
fmt.Println(counts["go"].Total) // 2

Элемент map нельзя адресовать как элемент слайса: выражение &counts[key] недопустимо. Если map хранит указатели, через них можно менять связанные объекты, но нужно проверять nil и учитывать совместный доступ.

В пределах одного последовательного обхода удалять записи разрешено:

counts := map[string]int{"go": 2, "sql": 0}
for key, count := range counts {
	if count == 0 {
		delete(counts, key)
	}
}
fmt.Println(len(counts)) // 1

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

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

Строки: индекс в байтах, значение в рунах

Для строки второе значение имеет тип rune. Индекс указывает на первый байт этой руны в UTF-8:

s := "Goя!"
for i, r := range s {
	fmt.Printf("%d %c\n", i, r)
}
// 0 G
// 1 o
// 2 я
// 4 !
fmt.Println(len(s)) // 5

Буква я занимает два байта. Поэтому следующий индекс равен 4, а len(s) возвращает 5. Использовать индекс из range как порядковый номер символа нельзя. Для такого номера заведите отдельный счётчик.

При некорректном UTF-8 цикл выдаёт U+FFFD и сдвигается на один байт. Одна руна при этом не обязательно соответствует одному видимому символу: например, буква и комбинируемый акцент могут быть разными рунами.

Если нужны байты, используйте обычный цикл по i < len(s) и читайте s[i]. Для изменения текста создайте новую строку; исходная строка неизменяема.

Каналы: range заканчивается после закрытия

При обходе канала переменная получает само значение, а не индекс:

package main

import "fmt"

func main() {
	ch := make(chan int, 2)
	ch <- 10
	ch <- 20
	close(ch)

	for value := range ch {
		fmt.Println(value)
	}
	// 10
	// 20
}

После закрытия цикл сначала забирает оставшиеся значения из буфера, затем завершается. Если канал открыт и значений нет, очередное получение блокируется. Для nil-канала оно блокируется навсегда. В отличие от канала, nil-слайс и nil-map дают ноль итераций.

Закрывайте канал на стороне, которая знает, что отправок больше не будет. Обычно это отправитель. Если отправителей несколько, закрытие нужно согласовать с завершением каждого из них.

Выход через break прекращает чтение, но не закрывает канал и не останавливает отправителя. Он может заблокироваться на следующей отправке. Если потребитель может уйти раньше, предусмотрите отмену и проверку этой отмены при отправке. Чтобы прервать ожидание получения через context.Context, вместо прямого range обычно используют цикл с select по каналу данных и ctx.Done().

range по числу и итератору

Начиная с Go 1.22, цикл можно повторить заданное число раз без отдельного условия:

for i := range 3 {
	fmt.Println(i)
}
// 0
// 1
// 2

Для нуля и отрицательного целого числа итераций нет. По целочисленной переменной n цикл выдаёт значения её типа. В примере с нетипизированной константой 3 переменная i имеет тип int. Эта форма не задаёт произвольный шаг или нижнюю границу; для них используйте обычный for. Изменение вошло в Go 1.22.

В Go 1.23 добавили обход функций со специальной сигнатурой. Такой итератор вызывает переданную функцию yield, чтобы отдать следующее значение телу цикла:

package main

import "fmt"

func numbers(yield func(int) bool) {
	for i := 1; i <= 3; i++ {
		if !yield(i) {
			return
		}
	}
}

func main() {
	for value := range numbers {
		fmt.Println(value)
		if value == 2 {
			break
		}
	}
	// 1
	// 2
}

При break функция yield возвращает false. Итератор обязан прекратить вызовы yield; в примере он сразу возвращается. Если продолжить вызывать yield после false, программа вызовет панику.

У допустимых итераторов три формы сигнатуры: func(func() bool), func(func(V) bool) и func(func(K, V) bool). Они выдают ноль, одно или два значения соответственно. Типы iter.Seq[V] и iter.Seq2[K, V] именуют последние две формы.

FAQ: частые ошибки с range

Как обойти слайс в обратном порядке?
Используйте обычный цикл: for i := len(items) - 1; i >= 0; i--. Переменная i здесь имеет тип int, поэтому после нуля станет отрицательной и цикл закончится. Для пустого слайса начальное значение равно -1, тело не выполнится. Сам range по слайсу всегда выдаёт индексы по возрастанию.
Почему break внутри switch не завершает range?
break без метки завершает ближайший for, switch или select. Если он находится внутри switch, завершится именно switch. Для выхода из внешнего цикла добавьте перед for метку, например Loop:, и используйте break Loop. return завершает всю текущую функцию.
Нужно ли писать value := value перед запуском горутины?
При семантике Go 1.22 и новее и объявлении for _, value := range values у каждой итерации своя переменная. Дополнительное объявление ради захвата не требуется. При старой семантике или присваивании через = общая переменная сохраняется. Явная передача значения параметром горутины позволяет получить отдельный параметр при любых из этих правил. Если значение содержит указатель или слайс, связанные данные всё равно могут быть общими.

Итог

Для чтения элементов подходит for _, value := range items. Чтобы изменить структуру в слайсе или сохранить адрес исходного элемента, используйте индекс: items[i] и &items[i]. Изменение переменной value остаётся изменением копии.

При неожиданном результате проверьте тип выражения справа от range. Массив и слайс по-разному реагируют на изменения исходных элементов. Map не гарантирует порядок, строка выдаёт байтовые индексы, а канал ждёт закрытия. Для адресов и замыканий дополнительно проверьте версию языка и выбор между := и =.

Полные правила собраны в разделе спецификации о for range.


Об авторе: Александр Бруяко — руководитель разработки с опытом в backend, инфраструктуре и управлении командами.


Теги: