fmt.Stringer — String() string

1. Навіщо fmt.Stringer і як fmt його використовує

Коли ви тільки починаєте писати програми, може здаватися, що виведення — це просто «показати число і рядок». Але щойно у вас зʼявляються структури (struct) із кількома полями, стандартний вивід швидко перетворюється на кашу: де яке поле, яке значення, чому це виглядає саме так і чому це так незручно читати. Ще гірше — читати логи, де кожна структура друкується «як доведеться», і ви потім сидите, мов археолог над давніми руїнами: «Так… тут було поле Done… мабуть…».

У Go є просте правило: якщо тип важливий для вашої програми, він має вміти коректно представляти себе рядком. Не обовʼязково завжди, але принаймні під час налагодження, логування й користувацького виведення. І тут нас рятує стандартна бібліотека.

Інтерфейс fmt.Stringer і перевірка всередині fmt

Найприємніша частина: вам не потрібно «ламати» fmt, писати власні принтери або винаходити велосипед із квадратними колесами. У пакеті fmt уже є домовленість: якщо значення вміє саме перетворюватися на рядок, то fmt із радістю цим скористається.

Ця домовленість виражена інтерфейсом fmt.Stringer. У межах цієї лекції ми сприймаємо інтерфейс просто як «контракт на один метод» — без занурення в тонкощі інтерфейсних значень і nil-пасток. Якщо у типу є метод із потрібною сигнатурою, отже, тип відповідає цьому контракту.

Ось як виглядає суть Stringer:

type Stringer interface {
    String() string
}

Ідея дуже схожа на те, як fmt працює з помилками: помилка — це значення, у якого є метод Error() string, і fmt друкує її через цей метод. З Stringer діє та сама логіка, тільки для «звичайних» типів.

Щоб краще побачити цю механіку, погляньмо на мінісхему:

flowchart TD
    A["fmt.Println(x)"] --> B{"x реалізує String() string?"}
    B -- так --> C["викликати x.String()"]
    C --> D[надрукувати отриманий рядок]
    B -- ні --> E[застосувати стандартне форматування fmt]
    E --> D

Зауважте: це не магія. Це просто перевірка, чи є у значення метод String().

2. Приклад: робимо Task красивим

Далі розвиватимемо наш навчальний застосунок — маленький менеджер задач. До справжнього CLI ми поки не переходимо, це окрема тема. Але модель даних уже можна зробити приємною: є задача, у неї є заголовок і прапорець виконання.

Почнімо з простої структури й подивімося, як вона друкується «за замовчуванням»:

package main

import "fmt"

type Task struct {
	ID    int
	Title string
	Done  bool
}

func main() {
	t := Task{ID: 1, Title: "Прочитати про Stringer", Done: false}
	fmt.Println(t) // {1 Прочитати про Stringer false}
}

Такий вивід… ну, технічно правильний. Але очима не завжди одразу розумієш, що де. Додаймо String().

Важливо: метод String() має повертати рядок, а не друкувати його сам. Друк — це робота fmt, а ваша робота — дати гарне подання.

package main

import "fmt"

type Task struct {
	ID    int
	Title string
	Done  bool
}

func (t Task) String() string {
	if t.Done {
		return fmt.Sprintf("#%d %q (done)", t.ID, t.Title)
	}
	return fmt.Sprintf("#%d %q (todo)", t.ID, t.Title)
}

func main() {
	t := Task{ID: 1, Title: "Прочитати про Stringer", Done: false}
	fmt.Println(t) // #1 "Прочитати про Stringer" (todo)
}

Зверніть увагу на %q: він друкує рядок у лапках і екранує спецсимволи. Для налагодження це часто корисніше, ніж просто %s, бо ви одразу бачите пробіли, табуляції та інші «невидимі художники».

І ось де починається магія: fmt.Println() викликає не «структурний вивід», а наш t.String().

3. Receiver для String(): T чи *T

Тут якраз стає в пригоді все, що ми вже знаємо з попередніх лекцій, а не лише вправа зі зсувом точки вправо. Ми вже знаємо:

• func (t Task) ... — value receiver, отримуємо копію.
• func (t *Task) ... — pointer receiver, отримуємо адресу.

Але у String() є особливість: він майже завжди не має змінювати обʼєкт. Це метод на кшталт «подивитися на себе в дзеркало й описати, що побачив». Якщо дзеркало ще й змінює обличчя, це вже підозріло.

Тому типове рішення — робити String() на value receiver.

Є й більш прагматична причина: якщо String() оголошено на Task (значенні), то і Task, і *Task зможуть гарно друкуватися. Якщо ж ви зробите String() на *Task, то гарний вивід гарантований лише для вказівника, а значення може друкуватися «як доведеться». Це прямий наслідок набору методів (method set).

Порівняймо на маленькому прикладі:

package main

import "fmt"

type Note struct {
	Text string
}

func (n *Note) String() string {
	return "NOTE: " + n.Text
}

func main() {
	n := Note{Text: "не забути про receiver"}
	fmt.Println(n)  // {не забути про receiver}
	fmt.Println(&n) // NOTE: не забути про receiver
}

Чому так? Тому що Note як значення не зобовʼязане мати метод String() у своєму наборі методів (method set), якщо цей метод оголошено лише для *Note. Натомість *Note бачить повніший набір методів.

Щоб було простіше орієнтуватися, ось компактна таблиця-шпаргалка:

func (t T) String() string

func (t *T) String() string

Ще один нюанс: якщо ви використовуєте pointer receiver для String(), треба памʼятати про можливий nil-вказівник. Сьогодні ми не занурюємося в інтерфейсні тонкощі, але базову обережність варто тримати в голові: якщо метод оголошено на *T, то t всередині може бути nil, і будь-який доступ до полів (t.Title) призведе до паніки.

4. String() для статусів: switch і default

У задачах часто зʼявляються стани: нова, у процесі, зроблена, скасована. У Go популярний підхід — зробити іменований тип на базі int і константи. А щоб не виводити користувачу числа 0, 1, 2, ми пишемо String().

Класичний патерн для такого String() — switch + default, де default повертає щось діагностичне. Це хороша практика: невідоме значення має друкуватися так, щоб ви бачили, що воно невідоме, а не тихо вас обманювало.

Додаймо статус до нашої задачі:

package main

import "fmt"

type Status int

const (
	StatusTodo Status = iota
	StatusDone
)

func (s Status) String() string {
	switch s {
	case StatusTodo:
		return "todo"
	case StatusDone:
		return "done"
	default:
		return fmt.Sprintf("Status(%d)", int(s))
	}
}

Тепер оновімо Task і його String():

package main

import "fmt"

type Status int

const (
	StatusTodo Status = iota
	StatusDone
)

func (s Status) String() string {
	switch s {
	case StatusTodo:
		return "todo"
	case StatusDone:
		return "done"
	default:
		return fmt.Sprintf("Status(%d)", int(s))
	}
}

type Task struct {
	ID     int
	Title  string
	Status Status
}

func (t Task) String() string {
	return fmt.Sprintf("#%d %q [%s]", t.ID, t.Title, t.Status)
}

func main() {
	t1 := Task{ID: 1, Title: "Зрозуміти Stringer", Status: StatusTodo}
	t2 := Task{ID: 2, Title: "Порадіти", Status: StatusDone}

	fmt.Println(t1) // #1 "Зрозуміти Stringer" [todo]
	fmt.Println(t2) // #2 "Порадіти" [done]
}

Зверніть увагу: ми всередині Task.String() форматуємо t.Status через %s. Але %s очікує рядок. Чому це працює? Тому що Status реалізує Stringer, а fmt уміє діставати рядкове подання через String().

5. Stringer і форматування: %v та «сирі» поля

Коли ви додали String(), ви отримали дуже зручний вивід для людини. Але є й зворотний бік: інколи під час налагодження вам хочеться побачити всі поля структури, а String() показує лише «гарну вітрину».

Це не баг, а очікувана поведінка: якщо fmt бачить String(), він вважає, що ви краще знаєте, як друкувати ваш тип.

Погляньмо на приклад:

package main

import "fmt"

type Task struct {
	ID    int
	Title string
	Done  bool
}

func (t Task) String() string {
	if t.Done {
		return "done: " + t.Title
	}
	return "todo: " + t.Title
}

func main() {
	t := Task{ID: 10, Title: "налагодити вивід", Done: false}

	fmt.Println(t)        // todo: налагодити вивід
	fmt.Printf("%v\n", t) // todo: налагодити вивід
	fmt.Printf("%T\n", t) // main.Task
}

Іноді це чудово. Але якщо вам потрібно тимчасово побачити «сирий» обʼєкт, є простий прийом: зробити тимчасовий alias-тип без методів і привести значення до нього. Це виглядає трохи хакерськи, але насправді чесно й прозоро: ви кажете компілятору «вважай це іншим типом, у якого немає String()».

package main

import "fmt"

type Task struct {
	ID    int
	Title string
	Done  bool
}

func (t Task) String() string {
	return fmt.Sprintf("Task#%d %q", t.ID, t.Title)
}

type rawTask Task

func main() {
	t := Task{ID: 10, Title: "подивитися поля", Done: false}

	fmt.Println(t)                  // Task#10 "подивитися поля"
	fmt.Printf("%+v\n", rawTask(t)) // {ID:10 Title:подивитися поля Done:false}
}

Так, це маленька хитрість. Але вона корисна, коли ви не хочете видаляти String() заради одного налагодження.

6. Хороший String(): чистота й захист від рекурсії

З методом String() легко спокуситися на «найрозумніше» й «найуніверсальніше» рішення, а потім випадково побудувати нескінченну рекурсію або перетворити просте виведення на мегакомбайн. У житті String() має бути нудним. І це комплімент.

Перше правило: жодних побічних ефектів. String() не має змінювати поля, писати у файл, збільшувати лічильник, надсилати запит у мережу й заодно лагодити базу даних. Бо fmt може викликати String() неочікувано часто: ви надрукували структуру в логах, вивели її в помилці, налагодили щось іще — і раптом «звичайний println» починає змінювати програму.

Друге правило: не панікувати. Якщо String() панікує, то налагоджувальний вивід перетворюється на міну. Краще повернути щось на кшталт "<invalid>" або акуратно обробити дивні значення.

Третє правило: не викликати форматування самого себе через %v, інакше вийде рекурсія. Ось приклад «як не треба»:

package main

import "fmt"

type Task struct {
	Title string
}

func (t Task) String() string {
	return fmt.Sprintf("%v", t) // погано: fmt знову викличе String()
}

func main() {
	fmt.Println(Task{Title: "boom"})
}

Це закінчиться нескінченною спробою надрукувати t, яка знову викликає String(), яка знову викликає fmt.Sprintf() і так далі — доки не закінчиться стек.

Правильний стиль — явно форматувати поля:

package main

import "fmt"

type Task struct {
	Title string
}

func (t Task) String() string {
	return fmt.Sprintf("Task{title=%q}", t.Title)
}

func main() {
	fmt.Println(Task{Title: "ок"}) // Task{title="ок"}
}

7. Типові помилки

Помилка № 1: оголосити String() на *T, а потім друкувати значення T і дивуватися.
Це виглядає дуже невинно: «ну я ж написав String()». Але набір методів (method set) не пробачає неуважності. Якщо String() висить на *T, то fmt.Println() для x типу T може надрукувати структуру «за замовчуванням», а не ваш гарний текст. Найпростіший вихід — робити String() на value receiver, бо метод не має змінювати обʼєкт і безпечно працює в обох випадках.

Помилка № 2: String() змінює стан обʼєкта.
Іноді хочеться в String() «підправити» дані: обрізати пробіли, заповнити порожнє поле значенням за замовчуванням, підкоригувати статус. Проблема в тому, що друк не має змінювати сенс програми. String() має бути чистою функцією: подивилися — повернули рядок — пішли далі. Якщо вам потрібна нормалізація даних, зробіть окремий метод, наприклад Normalize().

Помилка № 3: рекурсивний виклик друку самого себе через fmt.Sprintf("%v", x).
Це класика, особливо серед новачків: «я ж хочу універсально». Але fmt і Stringer роблять саме те, про що ви попросили, і рекурсія виходить чесна, нескінченна й безжальна. Лікується просто: формуйте поля напряму, без спроб «надрукувати весь обʼєкт ще раз».

Помилка № 4: занадто громіздкий вивід — багато рядків, усі поля, гігантські вкладені структури.
Іноді String() перетворюють на мінідамп памʼяті: «нехай буде все — зате точно зрозуміло». На практиці це вбиває читабельність. Хороший String() зазвичай показує 2–4 ключові поля: ідентифікатор, імʼя, статус. Усе інше — за потреби й окремими діагностичними принтами.

Помилка № 5: забути про default у String() для переліку.
Сьогодні у вас StatusTodo і StatusDone, а завтра десь випадково записалося Status(123) — помилка парсингу, баг логіки, некоректні дані. Якщо String() не вміє відображати невідомі значення, ви отримаєте або порожній рядок, або текст, що вводить в оману. Нормальний default повертає щось на кшталт Status(123), щоб проблема була видна одразу. Такий підхід із діагностичним default — стійка практика для String() на enum-подібних типах.