Спецификация микросервиса
Спецификация микросервиса — технический документ, относящийся к документации разработки систем, имеющих микросервисную архитектуру. Содержит описание одного микросервиса. Используется в качестве технического задания на программное обеспечение микросервиса и руководства программиста для разработчиков смежных микросервисов.
Предмет
Один из микросервисов в составе системы, имеющей микросервисную архитектуру.
Целевая аудитория
- разработчики микросервиса, описанного в спецификации;
- разработчики компонентов системы, использующих микросервис.
Типовая структура
В каждом коллективе разработчиков спецификации микросервисов составляют по-своему. Используемые технологии и подходы к организации работу не могут не влиять на типовую структуру этого документа. Здесь мы приводим обобщенные типовые структуры спецификации микросервиса. Не стоит воспринимать их как стандарт де-факто или настоятельную рекомендацию. Следует относиться к ним критически и брать из них только то, что поможет участникам конкретного проекта разрабатывать микросервисы и обмениваться важными сведениями на этот счет.
Спецификация микросервиса-сервера
Типовая структура спецификации микросервиса, выполняющего запросы от других компонентов системы, включает в себя перечисленные ниже разделы.
- Наименование.
- Назначение.
- Положение в системе.
- Состав.
- Интеграция.
- Основные понятия.
- Структуры и базы данных.
- Методы.
- Клиентские библиотеки.
В разделе «Наименование» указывают полное наименование и имя микросервиса.
В разделе «Назначение» кратко описывают характер задач, решаемых микросервисом. Если микросервис предназначен для обработки данных об экземплярах каких-то сущностей из предметной области, следует указать эту сущность.
В разделе «Положение в системе» приводят следующие сведения:
- названием подсистемы или другой части системы, в состав которой входит микросервис;
- тип микросервиса;
- слой микросервиса.
В разделе «Состав» приводят список основных компонентов микросервиса. Целесообразно включить в него только те компоненты, которые будут фигурировать в дальнейшем изложении. Например, если автор не собирается дальше упоминать об интерпретаторе языка Python, нет смысла включать его в перечисление, даже если он входит в состав микросервиса как системы.
В разделе «Интеграция» перечисляют:
- другие микросервисы, которыми пользуется микросервис;
- базы данных и очереди сообщений, с которыми работает микросервис;
- внешние системы, с которыми взаимодействует микросервис.
Если в состав микросервиса входят собственные базы данных, то не стоит упоминать о ней здесь. Эти базы данных лучше описать подробно в посвященном ей разделе.
В разделе «Основные понятия» приводят определения терминов, используемых в документе, при необходимости раскрывают их содержание и взаимосвязи между явлениями, на которые эти термины указывают. Изложение материала должно быть логичным и последовательным, как принято писать в теоретические разделы документов. Если в проекте уже существует документ, снабженный теоретическим разделом, информативным для читателя конкретной спецификации, допустимо полностью или частично заменить обсуждаемый раздел спецификации ссылкой на него. Главное, чтобы адресуемый документ был заведомо доступен читателю.
В разделе «Структуры и базы данных» приводят следующие сведения:
- перечень собственных баз данных микросервиса (если они есть);
- описание логической структуры каждой базы данных;
- перечень используемых объектов передачи данных;
- описание структуры представления каждого объекта передачи данных.
См. Описание структуры данных.
Если в проекте уже существует документ, описывающий унифицированные на уровне всего проекта форматы представления объектов того или иного типа, допустимо сослаться на него. Например, если в проекте есть полтора десятка микросервисов, работающих с представлением сущности автомобиль в формате JSON, и это представление унифицировано на уровне проекта, то нет смысла повторять его описание в каждой спецификации.
В разделе «Методы» приводят следующие сведения:
- перечень методов микросервиса;
- описание каждого метода микросервиса.
Метод микросервиса описывают по следующему плану.
- Наименование метода (заголовок подраздела).
- Назначение метода.
- Метод HTTP и URL энд-пойнта.
- Описание входных данных.
- Описание выходных данных.
- Описание алгоритма выполнения задачи.
В описании входных данных следует привести (при их наличии у метода):
В описании выходных данных следует привести:
- перечень кодов состояния HTTP в зависимости от возможных результатов;
- описание структурированных выходных данных (при их наличии у метода).
Алгоритм выполнения задачи должен быть описан настолько подробно, чтобы программисту, который будет заниматься реализацией микросервиса, не приходилось домысливать, что имел в виду автор спецификации. В частности, необходимо точно указывать следующие детали:
- имена используемых полей, элементов и атрибутов объектов передачи данных;
- имена используемых баз данных, их таблиц и полей;
- критерии выбора данных из базы данных.
В разделе «Клиентские библиотеки» приводят следующие сведения:
- перечень клиентских библиотек, входящих в состав микросервиса;
- описание каждой клиентской библиотеки.
План описания клиентской библиотеки определяется способом ее реализации и набором абстракций, которые она предлагает использовать. Универсальная рекомендация состоит в том, чтобы описание библиотеки не превращалось в «паззл» из описаний отдельных объектов или функций. У программиста, который будет руководствоваться этим писанием, следует сформировать связное представление о полном осмысленном цикле работы с микросервисом от инициализации всех необходимых объектов до освобождения занимаемых ресурсов (разумеется, если эти аспекты имеют смысл для конкретного микросервиса и его клиентских библиотек). См. Руководство программиста по библиотеке или фреймворку.
Спецификация микросервиса-демона
Спецификация демона отличается от спецификации сервера тем, что место раздела «Методы» в ней занимает раздел «Задачи». Задачу демона описывают по следующему плану.
- Наименование задачи (заголовок подраздела).
- Назначение задачи.
- Расписание или условия выполнения задачи.
- Описание входных данных.
- Описание выходных данных.
- Описание алгоритма выполнения задачи.