BizTalk: Соглашения об именах в примерах

Вначале можно ознакомиться со статьей BizTalk: BizTalk Solution Naming Conventions.

В небольших  приложениях мы особенно не беспокоимся об именах. Когда же количество объектов приложения начинает расти, мы вынуждены начать думать об именах. Опытного разработчика, работавшего с большими проектами, можно распознать по тщательно и досконально продуманным именам в коде. Это верно на 200% . Программист может со скоростью мысли писать изощренный код , но, если он не думает об именах, он никогда не делал большие проекты.

Когда девелопер начинает работать в новой команде, он/она проводит вначале много часов, читая документацию, и «Соглашения об именах» (Naming conventions) обычно — важная часть этой документации. Потом он/она начинает разработку и опять часть времени уходит на ознакомление со существующим кодом, чтобы вникнуть в действующие стандарты кодирования. И опять, Соглашения об именах — важная часть этого процесса.

Документированные Соглашения об именах важны, но реальный код не менее важен. Документация может устареть, код всегда актуален. И код более нагляден.

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

Описание примера

Этот BizTalk код состоит из многих BizTalk приложений (applications). Каждое из приложений состоит в свою очередь из 1-10 Visual Studio проектов (projects). Эти приложения были разработаны в течении многих лет разными группами разработчиков. Приложения интегрируют несколько систем. Некоторые системы имеют только один интерфейс, некоторые — несколько интерфейсов. В большинстве случаев интерфейс одной системы интегрирован с интерфейсом другой системы. Иногда несколько систем интегрированны с одним интерфейсом системы.

Для этого примера было выбрано одно приложение (solution) . Еще раз акцентирую, это приложение из реальной жизни. Почему это приложение, GLG.Samples.Name.Shared.Schemas, было создано в данной ситуации? 

Как известно, интерфейсы в BizTalk определяются с помощью протокола и одной или нескольких XML cхем (schemas). Во многих случаях эти схемы диктуются самими интегрируемыми системами, а не разработчиками приложений. Обычно разработчик использует Adapter Wizard, чтобы сгенирировать/импортировать эти схемы. Эти схемы определяются и при необходимости меняются не разработчиками BizTalk приложения, а создателями и хозяевами интегрируемых систем. В дальнейшем такие схемы я буду называть внешними (external schemas).

Одна из интересных характеристик внешних схем то, что они могут использоваться несколькими BizTalk приложениями. Я однажды уже писал, что схемы, используемы в портах, должны быть уникальными (receive locations should be unique), они не могут содержаться одновременено в нескольких установленных библиотеках (deployed assemblies). Это означает, что если нам надо использовать одну и ту же схему в нескольких проектах, мы должны установить одну общую (shared) библиотеку один раз, не больше, и ссылаться на нее из всех этих проектов. 

Данное ограничение заставляет обращать особое внимние на организацию и тщательную проработку общих библиотек.

Обычно используется следующий дизайн: Все внешние схемы размещены в отдельном приложении Visual Studio. В данном примере схемы сгруппированы по системам. Внутри каждой системы схемы сгруппированы по имени интерфейса. Группировка схем и лежит в основе Соглашения об именай.

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

Викторина🙂 по деталям реализации:

  1. Нормально ли, когда имена скомпонованы из четырех и даже более частей, наподобие GLD.Samples.Names.Shared.Schemas?
  2. Необходим ли GLD.Samples префикс для имен BizTalk приложений?
  3. Почему мы используем суффикс _Ops в именах проектов SystemA, SystemB, и SystemC?

(Попытайтесь ответить на эти вопросы самостоятельно. Я дам мои ответы в конце статьи.)

В данном примере рассмотрены два варианта Соглашений об именах. Я назвал их Длинные имена и Короткие имена.

Длинные имена

Картинка из Solution Explorer (все картинки взяты из BizTalk Server 2013):

Solution.Long

Это картинка папок:

Folders.Long

Короткие имена

Это картинка из Solution Explorer:

Solution

Это картинка папок:

Folders

Сравнение соглашений

Соглашение Короткие Имена выглядит изящнее. Здесь нет общих префиксов (GLD.Samples.Names.Shared.Schemas) внутри имен проектов и файловых папок. Если вы сражаетесь с хорошо известным ограничением Visual Studio TFS на общий размер имен файлов, это соглашение будет предпочтительным вариантом.

Я предпочитаю Длинные Имена (Полные имена). В этом случае имена проектов абсолютно такие же как .NET namespace у этих проектов и такие же, как имена билиотек (assembly). Полные имена проектов лучше в ситуациях, когда имена проектов могут быть включены одновременно в несколько Visual Studio приложений (solutions) или когда приложения часто перемещаются между приложениями. Срабатывает закон KISS (keep it simple stupid). В данном случае соглашение Длинные имена позволяет обходиться одним соглашением для многих объектов. Закон KISS неимоверно важен в больших проектах. Простота обходится дорого, сложность рождается бесплатно. За простоту приходится сражаться. В данном случае наблюдается некий пародокс, простота достигается не короткими именами, а длинными.

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

Имена BizTalk приложений (Applications)

Это картинка Административной Консоли (BizTalk Administration Console):

BizTalkAdminConsole

Вы видите Visual Studio приложение (solution) GLD.Samples.Names.Shared.Schemas установлено (deployed) как  Names.Shared.Schemas приложение (application). Префикс GLD.Samples удален, так как все устновленные VS приложения используют этот префикс. Если все артифкты используют одну и ту же часть имени, эта часть совершенно однозначно может быть удалена. Не должна быть удалена, а может быть удлалена. Возникает вопрос, почему эта часть не удалена из имени приложения/проекта (solution/project)? Причина в том, что проекты и assemblies практически всегда именуются одинаково. Но assemblies работают в одном глобальном пространстве имен вместе с system, Microsoft и другими assemblies, в едином пространстве имен .NET run-time. В этом глобальном пространстве имен префикс GLD.Samples помогает нам находить наши assembles. Получается, что глобальное пространство имен assemblies вынуждает нас использовать этот префикс, что, в свою очередь, вынуждает нас использовать этот префикс для имен проектов. Это и есть обещанный ответ на второй вопрос. Smile

В результате я использовал соглашение с Короткими именами для имен BizTalk приложений. 

Насколько сложной может быть иерархия имен?

Для примера возьму имя GLD.Samples.Names.Shared.Schemas.Sap.AV_CREDIT_STATUS_MODIFY. Не слишком ли оно сложное и длинное?

Конечно оно длинное. Но сложное ли оно? Все части этого имени однозначно отражают иерархию объектов, и все части имени здесь нужны. Попробуйте выбросить какую-нибудь часть, чтобы уменьшить длину имени, и получите одни неприятности. Почему? Потому что придется создавать дополнительное соглашение об именах. Дополнительное соглашение стоит куда как больше, чем длина имени на весах суммарной сложности.

Иерархические соглашения об именах — короли в BizTalk разработке. Эти соглашения отражают группировку объектов. Иерархические соглашения работают хуже в тех областях, где объектов мало и они логически не связаны. Здесь лучше работают соглашения, основанные на ключевых словах (keys or tags).

Обычно мы видим такую картину:

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

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

Надеюсь, я ответил на первый вопрос.

Теперь ответ на третий вопрос. Сразу уточню, что этот вопрос относится только к BizTalk проектам.
Почему был использован суффикс _Ops для проектов SystemA, SystemB и SystemC?

 Например, почему было использовано имя GLD.Samples.Names.Shared.Schemas.SystemA.CreditCheck_Ops, а не имя GLD.Samples.Names.Shared.Schemas.SystemA.CreditCheck ?

Проблема с этим именем в том, что проект содержит схему с именем CreditCheck. Что плохого в этом, почему мы не не можем использовать одинаковое слово для части имени проекта и для схемы?

XML схема (XML schema) сериализуется в .NET класс и имя схемы сериализуется в имя класса. В результате мы имеем класс с полным именем (full qualified name) GLD.Samples.Names.Shared.Schemas.SystemA.CreditCheck.ChreditCheck. И когда мы компилируем проект мы получаем ошибку:

Error.SymbolXIsAlreadyDefined

Описание (description) ошибки могло бы быть чуть понятнее, что-нибудь типа: “symbol ‘GLD.Samples.Names.Shared.Schemas.SystemA.CreditCheck’ is already defined; the first definition is in assembly…”.

По какой-то причине .NET builder разбирает имена иногда слева направо, а иногда справа налево, что и приводит к подобным ошибкам.

Это деталь реализации, но мы вынуждены из-за нее изменить наше соглашение об именах. Имя схемы мы не можем изменить (это внешняя схема), а вот имя проекта мы изменить можем. Добавили _Ops (operations) и это разрешило конфликт одинаковых имен.

Выводы

Не существует единственно правильного Соглашения об именах для всех случаев жизни. Будьте практичны и не создавайте слишком сложных соглашений. Цель разработки — не создание соглашений об именах. Соглашения только облегчают разработку, но не заменяют ее.

Из моего опыта: идеальных Соглашений об именах не бывает, всегда надо исходить из разумных компромисов.

Оставьте комментарий

Filed under BizTalk, BizTalk course, Integration Architecture

Добавить комментарий

Заполните поля или щелкните по значку, чтобы оставить свой комментарий:

Логотип WordPress.com

Для комментария используется ваша учётная запись WordPress.com. Выход / Изменить )

Фотография Twitter

Для комментария используется ваша учётная запись Twitter. Выход / Изменить )

Фотография Facebook

Для комментария используется ваша учётная запись Facebook. Выход / Изменить )

Google+ photo

Для комментария используется ваша учётная запись Google+. Выход / Изменить )

Connecting to %s