Валидация UML модели API

в 5:18, , рубрики: .net, architecture, UML, Visual Studio, метки: , , ,

В компании существует множество сервисов, которые объединены в общий Service Layer. Написаны они на разных технологиях и платформах, но все эти сервисы изначально должны проектироваться архитекторами, которые предварительно придумывают API, а затем проверяют соответствие их проекта и реализованной архитектуры.

Очевидно, что качество (понятность, единообразие, предсказуемость поведения и т.п.) зависит от опыта архитектора. Чем опытнее человек, тем больше у него обязанностей. Определив на бумаге (wiki) набор формальных правил для API, можно избавить проект (и самого архитектора) от части проблем, неточностей и неконсистентности.

Если API спроектирован в Visual Studio с помощью UML Сlass diagram, то можно добавить написанные на бумаге правила к валидации архитектуры в UML проекте.

Формулировка правил человеческим языком

Что первое приходит в голову при фразе «правила проектирования API»? Лично мне – не создавать классы всемогуторы (God Object), в которых сотни методов.
Правило 1: не более N метод на класс. N выбрать под себя.
Второе: мне вспоминается Win API, где сотни параметров, большинство из которых в примерах, да и в коде null/0.
Правило 2: не более M параметров у метода. M выбрать под себя.
Очепятки и копипаст
Правило 3: явно запрещаем повторение имен operations и attributes в рамках класса.
Правило 4: не менее 2 символов на имя параметра, и не более 30. Причина — меньше 2 не понятно что за параметр (У Google конечно есть q= в поиске, но это слабый аргумент), больше 30 – это уже перебор (мое субъективное мнение).
Правило 5: каждый метод API должен возвращать значение, т.е. никаких void быть не должно. Коды возврата, состояние, созданный объект — как угодно, но «выстрелил и забыл» всё-таки не наш метод.
Правило 6: в классе с моделью API не должно быть никаких private/protected методов. Мы ведь не реализацией еще занимаемся, а архитектурой! Нам не надо так глубоко залезать, иначе за деревьями можно не увидеть леса. Детализировать можно бесконечно, но цель не в этом.

Правила для REST:
Правило 7: в имени метода должно быть имя глагола get/post/delete/put. (Можно спорить, говорить, что роутинг можно настроить или что это не важно. Однако, это вариант, который можно использовать.)
Правило 8: не использовать в именах методов запрещенный список глаголов. Иначе из REST у нас получится remote procedure call over http.
Пример: предположим, что создан метод StartExecutionProcess. По названию заметно, что оно в концепцию REST как-то не очень укладывается.
В общем, такие правила можно придумывать бесконечно, можно обсуждать, спорить, бить в лицевую часть морды и так далее, поэтому остановимся на уже написанном списке. Переходим к реализации.

Visual Studio SDK

Чтобы писать расширения для uml нужно 2 компонента:

Информация для ознакомления

Информацию по нижеперечисленным ссылкам лучше прочесть, т.к. это описание объектов, из которых мы будем получать данные:

Опциональные ссылки:

План реализации

Шаги по реализации:

  • Создаем проект расширения
  • Создаем проект с кодом валидации
  • Создаем проект, на котором будем тестировать валидацию

Начнем с конца.

Создадим простой проект с набором явных нарушений.

Валидация UML модели API

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

Создаем проект расширения для Visual Studio

Валидация UML модели API

Прочесть можно либо в прошлой статье, либо по ссылке msdn.microsoft.com/en-us/library/ee329482.aspx в разделе Defining a Validation Extension
Должно получиться:

Разбираем код валидации:

Начнем с сигнатуры метода и его описания:

Валидация UML модели API

Export-атрибут фактически определяет, что этот метод будет использоваться для валидации. Visual Studio по нему понимает, что параметры для метода, нужно получить из DI контейнера MEF.
ValidationMethod — это атрибут, который говорит, что этот метод используется для валидации и также дает информацию на какие действия он будет активирован потом (перечисляя Enum).

Тело метода:

Валидация UML модели API

Код написания простых правил тривиален. Получили список методов и проверили, что методов больше чем MaxMethodParametersInMethod (который равен 5).

Проверка, что в методе API нет каких-либо методов логики, которые не видны.

Валидация UML модели API

Я думаю, что код объяснять излишне.

Что должно получится на выходе:

Вариант 1

Валидация UML модели API

Вариант 2 (Чуть сложнее)

Валидация UML модели API

Все наши проверки отработали, и мы их видим: Warning, Errors. Правила писать конечно надо под конкретный проект, но уж сейчас Архитектор-Аналитик который будет писать совсем уж ерунду получит по рукам автоматически при попытке сохранить модель.

Текстовый формат модели

Кроме валидации модели, нам так же захотелось получить текстовый формат модели.
Для этого пришлось в лоб обойти все классы модели, интерфейсы, методы и вывести в текстовый файл.

Это был самый простой способ.

Валидация UML модели API

Выбираем все компоненты

Валидация UML модели API

и далее идем по всем методам интерфейса распечатывая их входные параметры и выходное значение.
Единственной особенностью кода является необходимость проверить, какие из параметров находятся в одной коллекции объектов — parameters.

И на выходе текстовый вывод

Валидация UML модели API

Автор: SychevIgor

Источник

Поделиться

* - обязательные к заполнению поля