1.1. Разработка доменной модели¶

1.1.1. Язык доменной модели¶

В терминологии системы TDG язык описания является языком доменной модели, при этом домен — синоним понятия предметная область.

Язык доменной модели состоит из двух элементов:

• описания структуры объектов;

• описания связей между объектами.

В качестве такого языка используется Avro Schema. Он не сложный и достаточно распространен в сообществе и разрабатываемых им сторонних приложениях.

В стандарте Avro Schema есть два «контейнера», содержащих описания типов: протокол и схема. Оба — JSON-файлы с расширением .avsc.

Приложение использует схему в качестве формата и понимает ее в виде массива типов:

[
    {"name": "TypeA", "type": "record", ...},
    {"name": "TypeB", "type": "record", ...}
]

Каждый тип соответствует стандарту Avro Schema, за исключением расширений для системы TDG. Расширения обратно совместимы, а модель, описанная с их помощью, должна успешно преобразовываться стандартными парсерами (синтаксическими анализаторами).

1.1.2. Объекты модели: агрегат, сущность, значение¶

В дополнение к типичной для UML (Unified Model Language) терминологии «агрегация и композиция», в TDG есть три дополнительных понятия:

• Агрегат (Aggregate) — самостоятельный объект, имеющий идентичность;

• Сущность (Entity) — несамостоятельный объект, имеющий идентичность;

• Значение (Value Object) — несамостоятельный объект, не имеющий идентичности.

  Примечание

  Значение здесь — отдельная единица моделирования (значение-объект), а не атрибут класса объекта.

Эти понятия — часть словаря Domain Driven Design. Они описывают классы объектов с точки зрения идентичности и принадлежности.

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

Примером класса, объекты которого имеют идентичность, является класс клиент (бизнеса). Изменение имени клиента или его адреса не делает его другим клиентом — это тот же человек. С другой стороны, его адрес не имеет собственной идентичности, потому что смена улицы и дома сделает его другим адресом.

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

Примером сущности, которая не может существовать отдельно, является паспорт. Паспорта выдаются только существующим людям, и, даже если они были выданы «мертвым душам», полное удаление информации о «душах» потребует удаления информации об их паспортах.

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

Является ли объект агрегатом, сущностью или значением, важно не только для контроля жизненного цикла, но и для указания границ транзакционности и возможности ссылаться на объекты.

В пределах одного агрегата все его подчиненные сущности и значения можно обновить транзакционно и атомарно. Любая логика, работающая на уровне агрегата, может на это рассчитывать. Между агрегатами таких гарантий нет, то есть логика, обновляющая несколько агрегатов, является всегда согласованной в конечном счете (eventually consistent).

Также объекты могут ссылаться либо на объекты-сущности внутри своего агрегата-родителя, либо на другие агрегаты. Ссылки на сущности других агрегатов запрещены, так как сущности являются деталью реализации агрегата, и их данные всегда запрашиваются через объект агрегата.

1.1.3. Пример описания на языке доменной модели¶

Предположим, в системе требуется хранить информацию о клиентах (Client), их паспортах (Passport), адресах (Address), договорах (Contract), счетах (Account) и операциях (Operation) по ним.

Рассмотрим следующую диаграмму объектов в качестве примера:

В примере:

• Агрегатами являются Client, Contract, Account и Operation. Информацию о каждом из них следует хранить вне зависимости от наличия других объектов, чтобы построить финансовую отчетность для любого временного среза;

• Сущностью — Passport. Информацию о паспортах хранить отдельно от клиентов не нужно, паспорта не существуют сами по себе. У каждого клиента может быть несколько паспортов и их состояние может меняться, например, может истечь срок действия. Поэтому каждый паспорт — отдельная сущность, зависимая от агрегата клиента;

• Значением — Address, так как он не обладает идентичностью. Система автоматически версионирует объекты, поэтому создавать массив для новых адресов не нужно, достаточно одного объекта-значения.

Из схемы также видны отношения:

• Между Client и Address, а также множеством экземпляров Passport есть отношение владения;

• Объекты Client, Contract, Account и Operation существуют отдельно. Cвязи между ними — ссылочного типа.

  Одному и тому же агрегату разрешено находиться в отношениях агрегации с другими объектами.

Опишем данную структуру на языке доменной модели:

[
    {
        "name": "Passport",
        "type": "record",
        "logicalType": "Entity",
        "fields": [
            {"name": "id", "type": "long"},
            {"name": "passport_series", "type": "string"},
            {"name": "passport_number", "type": "string"},
            {"name": "expired_flag", "type": "boolean"}
        ],
        "indexes": [
            "id",
            {
                "name": "passport",
                "parts": ["passport_series", "passport_number"]
            }
        ]
    },
    {
        "name": "Address",
        "type": "record",
        "logicalType": "ValueObject",
        "fields": [
            {"name": "country", "type": "string"},
            {"name": "city", "type": "string"},
            {"name": "street", "type": "string"},
            {"name": "building", "type": "int"}
        ]
    },
    {
        "name": "Client",
        "type": "record",
        "logicalType": "Aggregate",
        "doc": "Клиент",
        "fields": [
            {"name": "id", "type": "long"},
            {"name": "first_name", "type": "string"},
            {"name": "last_name", "type": "string"},
            {"name": "passports", "type": {"type": "array", "items": "Passport"}},
            {"name": "address", "type": "Address"}
        ],
        "indexes": ["id"],
        "relations": [
            {"name": "contracts", "to": "Contract", "count": "many",
             "from_fields": "id", "to_fields": "client_id"}
        ]
    },
    {
        "name": "Contract",
        "type": "record",
        "logicalType": "Aggregate",
        "doc": "Договор",
        "fields": [
            {"name": "id", "type": "long"},
            {"name": "client_id", "type": "long"},
            {"name": "header", "type": "string"},
            {"name": "body", "type": "string"},
            {"name": "date", "type": {"type": "string", "logicalType": "Date"}}
        ],
        "indexes": [
            "id",
            "client_id"
        ],
        "relations": [
            {"name": "accounts", "to": "Account", "count": "many",
             "from_fields": "id", "to_fields": "contract_id"}
        ]
    },
    {
        "name": "Account",
        "type": "record",
        "logicalType": "Aggregate",
        "doc": "Счет",
        "fields": [
            {"name": "id", "type": "long"},
            {"name": "contract_id", "type": "long"},
            {"name": "date", "type": {"type": "string", "logicalType": "Date"}}
        ],
        "indexes": [
            "id",
            "contract_id"
        ],
        "relations": [
            {"name": "operations", "to": "Operation", "count": "many",
             "from_fields": "id", "to_fields": "account_id"}
        ]
    },
    {
        "name": "Operation",
        "type": "record",
        "logicalType": "Aggregate",
        "doc": "Операция",
        "fields": [
            {"name": "id", "type": "long"},
            {"name": "account_id", "type": "long"},
            {"name": "amount", "type": "double"},
            {"name": "type", "type": "string"},
            {"name": "timestamp", "type": {"type": "string", "logicalType": "DateTime"}}
        ],
        "indexes": [
            "id",
            "account_id"
        ]
    }
]

{"name": "amount", "type": ["null","double"]}

При описании мы использовали расширения для TDG. Следующий раздел подробно описывает каждое расширение.

1.1.4. Расширения доменной модели для TDG¶

Расширения дополняют спецификацию Avro Schema и позволяют воспользоваться функциональностью приложения.

TDG понимает следующие расширения:

{ "type": "string", "logicalType": "Date"}

 {
     "name": "Client",
     "type": "record",
     "logicalType": "Aggregate",
     "fields": [...]
 }

{
   "name": "Client",
   "type": "record",
   "logicalType": "Aggregate",
   "fields": [
       {"name": "id", "type": "long"},
       {"name": "first_name", "type": "string"},
       {"name": "last_name", "type": "string"},
       {"name": "passports", "type": {"type": "array", "items": "Passport"}},
       {"name": "address", "type": "Address"}
   ],
   "indexes": ["id"],
   // Здесь должно быть поле "relations", формат которого описан ниже.
},
{
   "name": "Contract",
   "type": "record",
   "logicalType": "Aggregate",
   "doc": "Договор",
   "fields": [
       {"name": "id", "type": "long"},
       {"name": "client_id", "type": "long"},
       {"name": "header", "type": "string"},
       {"name": "body", "type": "string"},
       {"name": "date", "type": {"type": "string", "logicalType": "Date"}}
   ],
   "indexes": [
       "id",
       "client_id"
   ],
}

"relations": [
    {
        // Все параметры обязательные.
        "name": "<имя_отношения>",
        "to": "<класс_объекта>",
        "count": <"one"|"many">, // один к одному или один к многим
        "from_fields": <спецификация_первичного_ключа>,
        "to_fields": <спецификация_внешнего_ключа>
    },
    ...
]

"index_name" | "field_name" | ["field_name", "field_name", "field_name", ...]

[
    {
      "name": "Client",
      "type": "record",
      "logicalType": "Aggregate",
      "fields": [
          {"name": "id", "type": "long"},
          ...
      ],
      "indexes": ["id"],
      "relations": [
          {"name": "contracts", "to": "Contract", "count": "many",
           "from_fields": "id", "to_fields": "client_id"}
      ]
    },
    {
      "name": "Contract",
      "type": "record",
      "logicalType": "Aggregate",
      "fields": [
          {"name": "id", "type": "long"},
          {"name": "client_id", "type": "long"},
          ...
      ],
      "indexes": [
          "id",
          "client_id"
      ],
      "relations": [
          {"name": "client", "to": "Client", "count": "one",
           "from_fields": "client_id", "to_fields": "id"}
      ]
    },
]

[<index1>, <index2>, <index3>, ...]

{
    "name": "Passport",
    "type": "record",
    "logicalType": "Entity",
    "fields": [
        {"name": "id", "type": "long"},
        {"name": "passport_series", "type": "string"},
        {"name": "passport_number", "type": "string"},
        {"name": "expired_flag", "type": "boolean"}
    ],
    "indexes": [
        "id",
        {
            "name": "passport",
            "parts": ["passport_series", "passport_number"]
        }
    ]
}

[
    {
        "name": "Header",
        "type": "record",
        "doc": "Заголовок операции",
        "logicalType": "ValueObject",
        "fields": [
            {"name": "id", "type": "long"},
            {"name": "header_body", "type": "string"}
        ]
    },
    {
        "name": "Operation",
        "type": "record",
        "logicalType": "Aggregate",
        "doc": "Операция",
        "fields": [
            {"name": "id", "type": "long"},
            {"name": "header", "type": "Header"},
            {"name": "account_id", "type": "long"},
            {"name": "amount", "type": "double"},
            {"name": "type", "type": "string"},
            {"name": "timestamp", "type": {"type": "string", "logicalType": "DateTime"}}
        ],
        "indexes": [
            "id",
            "account_id",
            {"name": "header_id", "parts": ["header.id"]}
        ]
    }
]

"affinity": <index_name>[, "affinity": index_name, ...]

{
  "name": "Operation",
  "type": "record",
  "logicalType": "Aggregate",
  "doc": "Операция",
  "fields": [
      {"name": "id", "type": "long"},
      {"name": "account_id", "type": "long"},
      {"name": "amount", "type": "double"},
      {"name": "type", "type": "string"},
      {"name": "timestamp", "type": {"type": "string", "logicalType": "DateTime"}}
  ],
  "indexes": [
      {"name":"pkey", "parts": ["id", "account_id"]},
      "account_id",
  ],
  "affinity": "account_id"
}

1.1.5. Работа с датой и временем¶

Внутри TDG для представления даты/времени используется строковый формат ISO 8601. Этот формат позволяет делать поля даты/времени индексируемыми, и при этом имеющими правильный порядок сравнения.

Все даты, поступающие в приложение, должны быть приведены к UTC.

Допустимые форматы записи:

• дата: YYYY-MM-DDZ;

• время: HH:MM:SSZ;

• дата/время с миллисекундами: YYYY-MM-DDTHH:MM:SS.sssZ;

• дата/время с микросекундами: YYYY-MM-DDTHH:MM:SS.ssssssZ;

• дата/время с наносекундами: YYYY-MM-DDTHH:MM:SS.sssssssssZ.

Например: 2018-03-24T10:20:48Z.

Чтобы объявить поле типа Date, Time или DateTime, используйте механизм логических типов (logicalType) Avro Schema. Базовый же тип для этих полей — всегда строковый. Пример объявления поля даты/времени:

{"name": "timestamp", "type": {"type": "string", "logicalType": "DateTime"}}