Структурные теги

Формат описания

• теги разделяют пробелом;
• имя тега и его значения разделяют двоеточием без пробелов;
• значения тега разделяют запятой и заключают в кавычки;
• имя и значения тега пишут в формате snake_case или camelCase.

type User struct {
    ID        string `json:"id" format:"uuid"`
    Name      string `json:"name"`
    CreatedAt int64  `json:"created_at" format:"unixtime,seconds"`
} 

• json — имя поля JSON-представления объекта (используется JSON-сериализаторами);
• format — дополнительные данные о формате поля (могут использоваться другими библиотеками).

• Сериализация объектов. Тег указывает на имя поля для конкретного сериализатора — json, yaml, xml, protobuf. Как правило, сериализаторы не требуют обязательного указания тегов. Имя поля в результирующем формате данных будет совпадать с именем поля структуры.
  Скопировать кодGO

  // Person содержит информацию о пользователе
  // и описывает сериализацию в JSON и YAML.
  type Person struct {
    ID    int
    Name  string `yaml:"name"`
    Email string `json:"email" yaml:"email"`
  } 
• Описание объекта таблицы для ORM-библиотек. Определённый тег задаёт имя таблицы, а другие теги описывают свойства колонки (например, nullable). Есть пакеты, которые используют структурные теги для работы с базами данных: gorm, bun.
  Скопировать кодGO

  // User демонстрирует пример описания GORM-модели.
  type User struct {
    ID    uuid.UUID `gorm:"type:uuid;default:uuid_generate_v4()"`
    Name  string    `gorm:"size:255"` // указывает размер поля
    Email string    `gorm:"type:varchar (100);unique_index"`
    Phone string    `gorm:"index:phone"` // создаёт индекс для этого поля
    mark  int       `gorm:"-"`           // не участвует в модели
  } 
• Валидации значений полей. Например, в пакете govalidator тег valid описывает тип поля и допустимые значения.
  Скопировать кодGO

  type Example struct {
    Name  string `valid:"-"`
    Email string `valid:"email"`
    URL   string `valid:"url"`
  }
  
  func main() {
    // проверяем на валидность email и URL
    result, err := govalidator.ValidateStruct(Example{
        Email: "johndoe@example.com",
        URL:   "https://www.ya.ru",
    })
    if err != nil {
        log.Fatal(err)
    }
    fmt.Println(result)
  } 

Работа с тегами

• Lookup(key string) (value string, ok bool) — возвращает значение тега по имени и флаг присутствия искомого тега в наборе.
• Get(key string) string — аналогичен Lookup, но не возвращает информацию о наличии тега. Если тег не найден, функция вернёт пустую строку.

obj := MyType{}
// получаем тип переменной — st имеет тип reflect.Type
st := reflect.TypeOf(obj) 
// Type.NumField() — возвращает количество полей
for i:=0; i < st.NumField(); i++ {
    // field содержит информацию о поле с i-м индексом (с 0)
    field := st.Field(i)
 
    // field.Tag имеет тип StructTag и содержит все теги i-го поля
    // выводим имя поля и значение тега `json`
    fmt.Println(field.Name, field.Tag.Get("json"))
} 

package main

import (
    "fmt"
    "reflect"
    "time"
)

type MyType struct {
    User      string    `json:"user,omitempty" example:"Bob"`
    CreatedAt time.Time `json:"created_at"`
}

const (
    targetField = "User" // имя поля, о котором нужно получить информацию
    targetTag   = "json" // тег, значение которого нужно получить
)

func main() {

    obj := MyType{}

    // получаем Go-описание типа
    objType := reflect.TypeOf(obj)

    // ищем поле по имени
    field, ok := objType.FieldByName(targetField)
    if !ok {
        panic(fmt.Errorf("field (%s): not found", targetField))
    }

    // ищем тег по имени
    tagValue, ok := field.Tag.Lookup(targetTag)
    if !ok {
        panic(fmt.Errorf("tag (%s) for field (%s): not found", targetTag, targetField))
    }

    fmt.Printf("Значение тега %s поля %s: %s\n", targetTag, targetField, tagValue)
    fmt.Printf("Теги поля %s: %s\n", targetField, field.Tag)
} 

Значение тега json поля User: user,omitempty
Теги поля User: json:"user,omitempty" example:"Bob" 

Скорость работы

Подводные камни (gotchas)

type MyStruct struct {
    // дубликат тега
    ID int `json:"id" yaml:"id" json:"myid"`
    // разделение запятыми, а не пробелом
    Name string `json:"name", yaml:"name"`
    // лишние пробелы
    Key string `json: "key" yaml :"key"`
    // перепутаны виды кавычек
    Company string "json:`key`"
    // encoding/json игнорирует неэкспортируемые поля
    hidden string `json:"hidden"`
} 

Дополнительные материалы

• go.dev/reflect — документация пакета reflect.
• go.dev/encoding/json — документация пакета json, который использует структурные теги для определения параметров JSON-преобразования.
• GitHub | Gorm — ORM-библиотека, которая использует структурные теги для указания SQL-связей.
• GitHub | Govalidator — пакет для валидации значений полей на основе описания структурных тегов.