- PVSM.RU - https://www.pvsm.ru -
В компании существует множество сервисов, которые объединены в общий 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 как-то не очень укладывается.
В общем, такие правила можно придумывать бесконечно, можно обсуждать, спорить, бить в лицевую часть морды и так далее, поэтому остановимся на уже написанном списке. Переходим к реализации.
Чтобы писать расширения для uml нужно 2 компонента:
Информацию по нижеперечисленным ссылкам лучше прочесть, т.к. это описание объектов, из которых мы будем получать данные:
Опциональные ссылки:
Шаги по реализации:
Начнем с конца.
Класс с повторяющимися именами атрибутов, класс с большим количеством методов. Класс с методом, у которого слишком много параметров, методы-классы с пробелами в именах.
Прочесть можно либо в прошлой статье [10], либо по ссылке msdn.microsoft.com/en-us/library/ee329482.aspx [6] в разделе Defining a Validation Extension
Должно получиться:
Export-атрибут фактически определяет, что этот метод будет использоваться для валидации. Visual Studio по нему понимает, что параметры для метода, нужно получить из DI контейнера MEF.
ValidationMethod — это атрибут, который говорит, что этот метод используется для валидации и также дает информацию на какие действия он будет активирован потом (перечисляя Enum).
Код написания простых правил тривиален. Получили список методов и проверили, что методов больше чем MaxMethodParametersInMethod (который равен 5).
Я думаю, что код объяснять излишне.
Все наши проверки отработали, и мы их видим: Warning, Errors. Правила писать конечно надо под конкретный проект, но уж сейчас Архитектор-Аналитик который будет писать совсем уж ерунду получит по рукам автоматически при попытке сохранить модель.
Кроме валидации модели, нам так же захотелось получить текстовый формат модели.
Для этого пришлось в лоб обойти все классы модели, интерфейсы, методы и вывести в текстовый файл.
и далее идем по всем методам интерфейса распечатывая их входные параметры и выходное значение.
Единственной особенностью кода является необходимость проверить, какие из параметров находятся в одной коллекции объектов — parameters.
Автор: SychevIgor
Источник [11]
Сайт-источник PVSM.RU: https://www.pvsm.ru
Путь до страницы источника: https://www.pvsm.ru/net/54991
Ссылки в тексте:
[1] Microsoft Visual Studio 2012 SDK : http://www.microsoft.com/en-us/download/details.aspx?id=30668
[2] Microsoft Visual Studio 2012 Visualization & Modeling SDK: https://www.microsoft.com/en-us/download/details.aspx?id=30680
[3] Properties of Types in UML Class Diagrams: http://msdn.microsoft.com/en-us/library/dd323860.aspx
[4] Properties of Attributes in UML Class Diagrams : http://msdn.microsoft.com/en-us/library/dd323861.aspx
[5] Properties of Operations in UML Class Diagrams : http://msdn.microsoft.com/en-us/library/dd323859.aspx
[6] How to: Define Validation Constraints for UML Models: http://msdn.microsoft.com/en-us/library/ee329482.aspx
[7] msdn.microsoft.com/en-us/library/dd409436.aspx: http://msdn.microsoft.com/en-us/library/dd409436.aspx
[8] msdn.microsoft.com/en-us/library/dd409437.aspx: http://msdn.microsoft.com/en-us/library/dd409437.aspx
[9] msdn.microsoft.com/en-us/library/dd409416.aspx: http://msdn.microsoft.com/en-us/library/dd409416.aspx
[10] прошлой статье: http://habrahabr.ru/post/211949/
[11] Источник: http://habrahabr.ru/post/212551/
Нажмите здесь для печати.