Value Object в Go: как защитить доменную модель

Практический способ перенести правила и инварианты в типы Go
10 мин чтения
Ты пишешь сервис доставки на Go. Мобильное приложение курьера присылает координаты, HTTP-хендлер передаёт их в сервис назначения заказов, оттуда они попадают в сущность Courier и через репозиторий в базу. На всём пути координаты остаются парой float64 с именами lat и lon. Пока в проекте два сценария, такой код выглядит достаточным.
Ниже на примере Value Object Geolocation разберём, во что обходится эта простота, как собрать объект-значение на Go шаг за шагом, где его чаще всего ломают и с какими паттернами DDD он работает вместе.

Что происходит с моделью без Value Object

Через полгода правило «широта от −90 до 90, долгота от −180 до 180» записано в трёх местах: в хендлере, в конструкторе курьера и в методе, который меняет его позицию. Новый сценарий добавляют без проверки, потому что о ней забыли. Одну копию правила исправляют, две другие остаются старыми. Владимир Хориков описывает тот же эффект на примере e-mail и имени клиента: знание о предметной области расходится по нескольким местам, и у правила больше нет единственного источника.
Вторая проблема скрыта в сигнатурах. Метод Move(lat, lon float64) принимает два числа одного типа. Если вызывающий код перепутает порядок аргументов, компилятор это пропустит, и ошибку ты увидишь уже в данных.
Третья проблема в доверии. Ни одна функция не знает, проверил ли кто-то координаты до неё. Поэтому каждый слой либо повторяет проверку, либо рассчитывает на соседний слой.
Одержимость примитивами (primitive obsession) означает, что понятия предметной области описаны встроенными типами вроде string, int и float64, а правила для них разбросаны по коду.

Паттерн Value Object и какие проблемы он решает

Value Object, или объект-значение, описывает понятие предметной области без собственной идентичности. Его определяют только значения атрибутов, поэтому два объекта с одинаковыми атрибутами взаимозаменяемы.
Сравни с сущностью. Курьер остаётся тем же курьером после смены имени, потому что его отличает идентификатор. Две точки с одинаковыми широтой и долготой обозначают одно и то же место, и тебе неважно, какой из экземпляров лежит в поле. Хориков предлагает простой тест: мысленно замени понятие целым числом. Тебя не интересует, та же ли это пятёрка, что в соседнем методе. Если понятие ведёт себя так же, перед тобой объект-значение.
Из определения следуют два свойства. Объект-значение неизменяем: чтобы получить другие координаты, ты создаёшь новый экземпляр. Свои инварианты он проверяет при создании, поэтому некорректный экземпляр в программе не появляется.
Так решаются все три проблемы. Правило о диапазонах ты пишешь один раз, в конструкторе. Сигнатуры принимают Geolocation вместо двух чисел. Код за пределами конструктора больше не перепроверяет данные. Хориков советует выделять объект-значение всегда, когда понятию нужно больше одного примитива, если приложение не одноразовое. Геолокации нужны два числа, так что случай однозначный.

Пошаговый пример: Value Object Geolocation на Go

Шаг 1. Тип с неэкспортируемыми полями

Объяви структуру со строчными полями. Код вне пакета model не сможет записать в них значения, поэтому корректную точку можно получить только через конструктор.
package model

type Geolocation struct {
	latitude  float64
	longitude float64
	valid     bool
}
Поле valid отличает значение из конструктора от нулевого значения структуры. Зачем оно нужно, разберём в разделе об ошибках.

Шаг 2. Конструктор с проверкой инвариантов

Конструктор проверяет диапазоны и при нарушении возвращает пустое значение и ошибку. Так же устроен NewLocation в учебном микросервисе доставки, где точка лежит на сетке 10 × 10.
package model

import (
	"errors"
	"fmt"
)

const (
	minLatitude  = -90.0
	maxLatitude  = 90.0
	minLongitude = -180.0
	maxLongitude = 180.0
)

var ErrInvalidGeolocation = errors.New("invalid geolocation")

func NewGeolocation(latitude, longitude float64) (Geolocation, error) {
	// Условие записано через отрицание, чтобы отсечь и NaN:
	// любое сравнение с NaN возвращает false.
	if !(latitude >= minLatitude && latitude <= maxLatitude) {
		return Geolocation{}, fmt.Errorf("%w: latitude %v must be between %v and %v",
			ErrInvalidGeolocation, latitude, minLatitude, maxLatitude)
	}
	if !(longitude >= minLongitude && longitude <= maxLongitude) {
		return Geolocation{}, fmt.Errorf("%w: longitude %v must be between %v and %v",
			ErrInvalidGeolocation, longitude, minLongitude, maxLongitude)
	}

	return Geolocation{latitude: latitude, longitude: longitude, valid: true}, nil
}

func MustGeolocation(latitude, longitude float64) Geolocation {
	g, err := NewGeolocation(latitude, longitude)
	if err != nil {
		panic(err)
	}
	return g
}
MustGeolocation подходит для тестов и заранее известных значений. Координаты из запроса передавай в NewGeolocation и обрабатывай ошибку, иначе некорректный ввод закончится panic.

Шаг 3. Методы чтения и сравнение

func (g Geolocation) Latitude() float64 {
	return g.latitude
}

func (g Geolocation) Longitude() float64 {
	return g.longitude
}

func (g Geolocation) IsValid() bool {
	return g.valid
}

func (g Geolocation) Equal(other Geolocation) bool {
	return g == other
}
У всех методов получатель передаётся по значению. Метод работает с копией и не может изменить исходный объект. Оператор == здесь допустим: по спецификации Go структура сравнима, если сравнимы все её поля, а float64 и bool сравнимы. Для двух точек с одинаковыми координатами Equal вернёт true, это и есть структурное равенство.

Шаг 4. Использование в сущности

package courier

import (
	"github.com/google/uuid"

	"delivery/internal/core/domain/model"
)

type Courier struct {
	id       uuid.UUID
	name     string
	location model.Geolocation
}

func (c *Courier) Move(location model.Geolocation) {
	c.location = location
}
Курьер меняет позицию, заменяя значение целиком. Метод Move больше не принимает два числа, которые легко перепутать, и не проверяет диапазоны: экземпляр Geolocation из конструктора уже корректен. Агрегат Courier в том же микросервисе устроен так же, только хранит Location.

Article's Title

Book design is the art of incorporating the content, style, format, design, and sequence of the various components of a book into a coherent whole. In the words of Jan Tschichold, "Methods and rules that cannot be improved upon have been developed over centuries. To produce perfect books, these rules must be revived and applied." The front matter, or preliminaries, is the first section of a book and typically has the fewest pages.
package model

import (
	"testing"

	"github.com/stretchr/testify/assert"
)

func Test_Geolocation_ShouldReturnError_WhenLatitudeOutOfRange(t *testing.T) {
	_, err := NewGeolocation(91, 37.61)

	assert.ErrorIs(t, err, ErrInvalidGeolocation)
}

func Test_Geolocation_ShouldBeEqual_WhenCoordinatesAreSame(t *testing.T) {
	a := MustGeolocation(55.75, 37.61)
	b := MustGeolocation(55.75, 37.61)

	assert.True(t, a.Equal(b))
}

Article's Title

Book design is the art of incorporating the content, style, format, design, and sequence of the various components of a book into a coherent whole. In the words of Jan Tschichold, "Methods and rules that cannot be improved upon have been developed over centuries. To produce perfect books, these rules must be revived and applied." The front matter, or preliminaries, is the first section of a book and typically has the fewest pages.

Плюсы Value Object

  • Правило о допустимых координатах записано один раз. Чтобы его изменить, ты правишь только конструктор.
  • Компилятор проверяет типы. Функция с параметром Geolocation не примет произвольное число, а перепутать широту и долготу можно лишь в одном месте, при вызове NewGeolocation.
  • Повторные проверки не нужны. Экземпляр из конструктора корректен, и доменный код может на это полагаться.
  • Неизменяемое значение безопасно передавать между горутинами и кешировать без защитного копирования. Сравнимую структуру можно использовать как ключ map.
  • Код модели использует термины предметной области. Поле location model.Geolocation объясняет себя лучше, чем пара lat, lon float64.
  • Тестам объекта-значения не нужна инфраструктура.

Частые ошибки при реализации Value Object в Go

Создание через литерал

Go разрешает написать model.Geolocation{} или var g model.Geolocation даже при неэкспортируемых полях. Получится точка 0, 0. Она попадает в допустимые диапазоны, хотя конструктор её не создавал, и по координатам её нельзя отличить от настоящей. Для этого и нужно поле valid: у нулевого значения оно равно false, и IsValid() позволяет отсечь такой объект на границе. В учебном примере Color используют тот же приём и дополнительно советуют настроить линтер, который запрещает создавать объект через литерал.

Изменяемое значение

Метод вроде func (g *Geolocation) SetLatitude(v float64) меняет координаты в обход конструктора и его проверок. Если сущности хранят указатель *Geolocation, правка через одну ссылку неожиданно проявится во всех остальных. Хориков считает: если объект-значение нельзя сделать неизменяемым, это не объект-значение.

Несравнимые поля

Если добавить в структуру срез или map, выражение g == other перестанет компилироваться. Сравнение таких значений через интерфейс скомпилируется, но вызовет panic во время выполнения. Для составных данных пиши Equal вручную.

Отдельная таблица для значения

У объекта-значения нет собственного идентификатора, поэтому его поля встраивают в таблицу владельца. В микросервисе доставки LocationDTO встроен в CourierDTO тегом gorm:"embedded;embeddedPrefix:location_", и координаты лежат в колонках таблицы couriers. Отдельная таблица с ID даёт значению идентичность и позволяет ему существовать без сущности.

Value Object для каждого примитива

Хориков предлагает перед созданием объекта-значения оценивать четыре признака: число и сложность инвариантов, число примитивов, сложность проекта и объём дублирования. Положительное число с единственным правилом в типичном корпоративном приложении на C# или Java он, скорее всего, оставил бы обычным decimal.

Какие ещё паттерны есть в DDD

Domain-Driven Design (DDD) предлагает строить код вокруг модели предметной области. Термин появился в книге Эрика Эванса «Domain-Driven Design». Единой модели на всю систему в DDD нет: систему делят на ограниченные контексты (bounded contexts), и у каждого своя модель. Это стратегическая часть подхода. Внутри контекста модель собирают из тактических паттернов, и Value Object лишь один из них:
  • Сущность (Entity) обладает идентичностью, которая сохраняется во времени, и содержит поведение вместе с данными.
  • Агрегат (Aggregate) задаёт границу согласованности вокруг одной или нескольких сущностей с единственным корнем. В микросервисе доставки корнем агрегата служит Courier: он хранит назначенные заказы и не даёт превысить свою вместимость.
  • Доменное событие (Domain Event) фиксирует значимое для бизнеса изменение, например «доставка отменена». Агрегаты публикуют события после изменения состояния и через них координируют работу друг с другом.
  • Доменный сервис содержит правила, которые затрагивают несколько сущностей или агрегатов и не принадлежат ни одному из них.
  • Сервис приложения оркестрирует сценарий: вызывает доменные сервисы и репозитории, управляет транзакцией и не содержит бизнес-логики.
  • Репозиторий, фабрика и модуль отвечают за сохранение агрегатов, их создание и организацию кода.
По этим паттернам определяют и границы сервисов. В руководстве Microsoft по тактическому DDD советуют проектировать микросервис не меньше агрегата и не больше ограниченного контекста. Там же предлагают выбирать объект-значение по умолчанию и превращать понятие в сущность, только когда нужно отслеживать его идентичность во времени. Хориков советует переносить в объекты-значения большую часть бизнес-логики, а сущности делать обёртками над ними.
Начни с одного понятия, которое сейчас передаётся парой примитивов и проверяется в нескольких местах. Когда в коде появится свой Geolocation, следующий вопрос будет о том, кто владеет этим значением и где проходит граница согласованности. На него отвечают сущности и агрегаты.
Подробнее эта тема разбирается на курсе
"DDD и Clean Architecture"