В компании существует множество сервисов, которые объединены в общий 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 компонента:
- Microsoft Visual Studio * SDK. Microsoft Visual Studio 2012 SDK
- Microsoft Visual Studio * Visualization & Modeling SDK. Microsoft Visual Studio 2012 Visualization & Modeling SDK
Информация для ознакомления
Информацию по нижеперечисленным ссылкам лучше прочесть, т.к. это описание объектов, из которых мы будем получать данные:
- Properties of Types in UML Class Diagrams информация о типах
- Properties of Attributes in UML Class Diagrams информация о полях
- Properties of Operations in UML Class Diagrams информация о методах
- How to: Define Validation Constraints for UML Models как мы будем писать расширение.
Опциональные ссылки:
- Developing Models for Software Design msdn.microsoft.com/en-us/library/dd409436.aspx
- UML Class Diagrams: Reference msdn.microsoft.com/en-us/library/dd409437.aspx
- UML Class Diagrams: Guidelines msdn.microsoft.com/en-us/library/dd409416.aspx
План реализации
Шаги по реализации:
- Создаем проект расширения
- Создаем проект с кодом валидации
- Создаем проект, на котором будем тестировать валидацию
Начнем с конца.
Класс с повторяющимися именами атрибутов, класс с большим количеством методов. Класс с методом, у которого слишком много параметров, методы-классы с пробелами в именах.
Прочесть можно либо в прошлой статье, либо по ссылке msdn.microsoft.com/en-us/library/ee329482.aspx в разделе Defining a Validation Extension
Должно получиться:
Разбираем код валидации:
Export-атрибут фактически определяет, что этот метод будет использоваться для валидации. Visual Studio по нему понимает, что параметры для метода, нужно получить из DI контейнера MEF.
ValidationMethod — это атрибут, который говорит, что этот метод используется для валидации и также дает информацию на какие действия он будет активирован потом (перечисляя Enum).
Код написания простых правил тривиален. Получили список методов и проверили, что методов больше чем MaxMethodParametersInMethod (который равен 5).
Я думаю, что код объяснять излишне.
Что должно получится на выходе:
Все наши проверки отработали, и мы их видим: Warning, Errors. Правила писать конечно надо под конкретный проект, но уж сейчас Архитектор-Аналитик который будет писать совсем уж ерунду получит по рукам автоматически при попытке сохранить модель.
Текстовый формат модели
Кроме валидации модели, нам так же захотелось получить текстовый формат модели.
Для этого пришлось в лоб обойти все классы модели, интерфейсы, методы и вывести в текстовый файл.
и далее идем по всем методам интерфейса распечатывая их входные параметры и выходное значение.
Единственной особенностью кода является необходимость проверить, какие из параметров находятся в одной коллекции объектов — parameters.
Автор: SychevIgor
