Сначала разработайте отличные контракты

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

Серия Содержание

Часть 0: Стандартные уровни абстракции и определение платформы
Часть 1: Типы и процесс обобщения
Часть 2: Архитектура вашей платформы
Часть 3. Сначала разработайте отличные контракты
Часть 4. Внедрение и тестирование контрактов
Часть 5. Первые шаги непрерывной интеграции
Часть 6. Развитие платформы< br /> Часть 7: Ужасные подробности документации
Часть 8: Распространение платформы

Введение

Мы продолжаем нашу рубрику «Создание платформы». Мы говорили о «Процессе обобщения» и «Архитектуре вашей платформы». Теперь пришло время применить некоторые из них на практике.

В части 3 мы поговорим о контрактах и ​​их важности при создании платформы.

Код Контракты — это формальные или неформальные соглашения между двумя объектами в программной системе или внешними субъектами.

Эти контракты могут быть любыми: от схем проектирования API, условий абстрактного класса, общих соглашений о производительности или чего-либо еще. Слово «контракт» является очень общим термином. Мы опишем принципы разработки этих контрактов и какие из них следует отдать предпочтение.

Общие типы контрактов на платформе

Как упоминалось ранее, договор – это любое соглашение между двумя субъектами. Иногда соглашение бывает односторонним (когда разработчик/проектировщик определяет соглашение единолично) или двусторонним (когда требования устанавливаются от заказчика и подписываются). И то, и другое произойдет в каждом проекте или платформе. Давайте обсудим различные типы контрактов и их важность.

Требования заинтересованных сторон

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

Этот тип контракта является неявным по своей природе. Никакого реального дизайна не выдвинуто, хотя может быть дискуссия об эффективности требования. Как правило, мы не можем выйти из этого «контракта». Для любого проекта это самое главное. Они также являются основой платформы, а затем и дизайном остальных контрактов. Думайте о требованиях как о самом нижнем контракте.

Пользовательский интерфейс

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

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

Схема веб-API

Не все пользователи будут взаимодействовать исключительно из пользовательского интерфейса. Вместо этого они могут взаимодействовать со службой или конечной точкой, обычно сервер-сервер. Иногда может случиться так, что пользовательский интерфейс вызывает конечную веб-точку. В любом случае схема действует как цифровой механизм для передачи данных между двумя взаимосвязанными (общими) интерфейсами.

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

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

Одним из преимуществ заключения этого контракта на ранней стадии, до начала разработки, является то, что, когда API-интерфейсы используются командой внешнего интерфейса, вы можете заставить группы внешнего и внутреннего интерфейса работать одновременно. Поскольку оба знают контракт, вам не обязательно ждать завершения работы серверной части, чтобы начать разработку.

Библиотека/SDK

Если предоставление платформы предназначено для группы разработчиков, большая часть контрактов будет касаться вызовов функций и некоторых абстракций. Мы, как разработчики, используем эти типы библиотек каждый день. Это могут быть фреймворки Vue.js или библиотеки типа System.Net.Http. Авторы нацелены на очень большую аудиторию и, следовательно, должны обеспечить обратную совместимость, чтобы обеспечить наименьшее влияние при внесении изменений.

Библиотеки и SDK следует рассматривать как стабильный контракт, которым следует надлежащим образом управлять.

Однако библиотеки для внутреннего использования могут не требовать такого же уровня стабильности, если аудитория ограничена.

Хранилище данных

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

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

Триггерные услуги

Вам когда-нибудь приходилось создавать фоновую задачу, которая запускается каждый день в час ночи? Или приходилось отправлять электронные письма после запуска определенного процесса? Это то, что мы называем триггерным сервисом. Мы создаем «контракт» с бизнесом или системой, который гарантирует, что что-то произойдет в ответ на какое-то событие.

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

Разработка процесса

Как мы взаимодействуем с другими командами? Что мы собираемся передать отделу Х, когда будем готовы заняться Y? Хорошо продуманный процесс также можно считать контрактом. Обычно это будет между людьми (хотя службы и другие системы также применимы). Мы хотим убедиться, что дизайн наших систем на нашей платформе, включая коммуникацию, продуман и эффективен для всех групп. И что самое сложное в контрактах на проектирование процессов? Бай-ин.

Контракт между группами может быть таким простым, как следующее:

  1. Разработчики создают плагин как дополнение к функции.
  2. Разработчики соглашаются предоставить инструкции по установке функций.
  3. Разработчики соглашаются выпускать примечания к выпуску плагина.
  4. Разработчики передают плагин и документацию инженерам по доставке.
  5. Инженеры по доставке соглашаются размещать плагин и документацию на торговой площадке платформы.

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

Приоритизация разработки контракта

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

Теперь возникает вопрос: «Какие контракты мы разрабатываем?».

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

Но в большинстве систем мы не можем быть парализованы дизайном и никогда не создадим приложение. Таким образом, мы действительно должны расставить приоритеты в разработке контрактов. Как же тогда мы выбираем, какие контракты разрабатывать? Какие из них наиболее важны?

Заказчик и Платформа

Давайте на мгновение отвлечемся от разговора и поговорим о потребностях клиентов и потребностях платформы.

Нам нужно помнить о цели нашей платформы…

Платформа НЕ создана для клиента! Речь идет о более эффективной доставке Системы Заказчику.

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

Если вы предоставляете платформу самообслуживания для внешнего клиента, он будет использовать ее для более эффективного выполнения своих требований. Отличным примером платформы самообслуживания является webflow.com. Это позволяет любому создать сайт электронной коммерции с хранилищем данных, даже не зная разработки программного обеспечения. Webflow — это платформа для всех целей и задач.

Стабильность и разветвление

Итак, как мы узнаем, какие контракты наиболее важны для начала? На самом деле это довольно простой ответ,

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

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

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

Возврат инвестиций (ROI)

Если мы заключаем большое количество внешних контрактов, нам следует расставить приоритеты в зависимости от рентабельности инвестиций (или ROI). Мы можем определить нашу рентабельность инвестиций как

Общая стоимость создания клиентских функций без указанного контракта минус общая стоимость создания клиентских функций с указанным контрактом.

Это, наверное, не самое лучшее определение. И это немного абстрактно (и его трудно измерить). Но давайте использовать пример, чтобы проиллюстрировать,

Допустим, нам приходится выполнять переводы клиентов каждый раз, когда мы доставляем онлайн-продукт. Мы используем простой файл JSON с парами ключ-значение key: "<translation text>". Каждый файл на своем языке. Предположим, что каждый ключ довольно несовместим от приложения к приложению, которое использует эти ключи. При добавлении нового ключа он добавляется в каждый файл вручную. Предполагая, что мы не забыли добавить эти ключи соответствующим образом, в итоге у разработчика уходит примерно 2 недели на то, чтобы обеспечить правильность перевода на экране (с ручным тестированием).

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

Что, если бы мы сделали следующее,

Все разработчики во всех приложениях согласны со стандартным форматом ключа. Но вместо того, чтобы добавлять ключи вручную, разработчик-исполнитель создает инструмент CLI, который сканирует все файлы кода на наличие ключей. Затем эти ключи преобразуются в стандартизированный компьютерный формат. Затем этот формат можно использовать для экспорта в соответствующий формат Excel/CSV, который можно передать группе переводчиков. После завершения команда может вернуть файл Excel/CSV для объединения с оригиналом. На этом этапе разработчик может потратить пару часов на координацию между группами, но ручной ввод их в файл JSON или поиск соответствующих ключей исчезает.

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

Разработка контрактов

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

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

Примечание. Я расскажу только о типах контрактов пользовательского интерфейса, API, библиотек и хранилища данных.

Общие рекомендации

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

1. Сотрудничество

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

Рекомендуемые инструменты: Microsoft Teams, Slack, доски.

2. Потоки работы/данных/процессов

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

Я сам неравнодушен к Microsoft Visio (в основном потому, что знаю его лучше всех). Однако я знаю, что это может быть ограничением. В прошлом я также использовал программное обеспечение для построения диаграмм, такое как Lucidchart, и обнаружил, что оно работает хорошо (если не лучше в некоторых сценариях). И если ни то, ни другое не работает, вы всегда можете создать окончательную документацию после ручной обработки (белой доски) в чем-то вроде PlantUML.

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

Рекомендуемые инструменты:Microsoft Visio, Lucidchart, PlantUML

3. Сеансы дизайна

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

Даже если вы проводите сеанс дизайна самостоятельно, записывайте его. Резиновый уклонся от сеанса и говорите вслух. Вы обнаружите, что даже произносите это вслух много Ага! моменты выскочат.

Образец повестки дня совещания по дизайну

  1. (Начало) Обобщить проблему или требование
  2. Нарисуйте поток(и) для решения проблемы и обсудите все известные варианты использования (разрешите другим предлагать другие варианты использования)
  3. Обсуждение решений высокого уровня (технология, архитектура и т. д.)
  4. Набросайте низкоуровневые решения (дизайн API, абстрактные классы и т. д.)
  5. Обсудите план и повторите 4–6, пока решение не будет согласовано.
  6. (Конец) Обобщить решения дизайна

Имейте вопросы и мысли, прежде чем начинать дизайнерское решение. Обязательно отстаивайте свою позицию. Вы будете и должны получить отпор. Тем не менее, будьте в состоянии уступить, если появится лучший дизайн.

Рекомендуемые инструменты: Microsoft Teams, OBS

Пользовательский интерфейс (UI)

При «контрактном» дизайне пользовательского интерфейса целью НЕ является высокая точность воспроизведения. Вместо этого речь идет о намерении. Предполагая, что у нас уже есть некоторые рабочие процессы, мы должны использовать инструмент, который можно использовать для простого просмотра дизайна в стиле раскадровки.

Для разработчика я обычно предпочитаю Balsamiq. Однако я также использовал Adobe XD для быстрого прототипирования. Еще один инструмент, который я видел, — Figma, хотя я не думаю, что он так приспособлен для разработчиков, как опыт UI/UX.

Целью любого дизайна здесь является понимание основных механизмов, которые вам понадобятся. Я бы разбил это на несколько этапов:

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

Этап 1 касается только дизайна. Опять же, это может быть в Adobe XD или Balsamiq и не предназначено для высококачественного дизайна. Он просто предназначен для понимания того, что потребуется пользовательскому интерфейсу.

На этапе 2 мы начинаем разрабатывать контракты, которые нам небезразличны. Мы составим конструкцию. Здесь мы определяем компоненты, которые можно повторно использовать во всем проекте или, что еще лучше, во многих приложениях.

Этап 3 посвящен документированию компонентов. Лучше всего это можно описать с помощью простых рекомендаций по документации. В большинстве случаев отформатированного файла уценки должно быть достаточно.

Ниже приведены некоторые рекомендации по проектированию компонентов:

  1. Что такое входные данные? Требуется ли определенный формат, чтобы сделать эту работу взаимозаменяемой?
  2. Что будет отображать компонент по сравнению с тем, что ему придется поддерживать в фоновом режиме?
  3. Является ли компонент интерактивным? Каких событий вы ожидаете, чтобы он заработал в полную силу?
  4. Как будет меняться компонент в разных вариантах использования? Можно ли количественно оценить изменения? Просто разница в стиле? Или у них разные визуальные макеты? Как насчет включения или отключения различных аспектов компонента? Ответ на этот вопрос напрямую повлияет на параметры компонента.

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

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

# Component: Internationalization (i18n) Label
## Status
Proposed
## Description
A simple label that will automatically translate text based on a key and language offering. The element will be an `inline-block` that utilizing the `span` HTML element. An implicit class of `i18n` will be on all elements.
### Input
| Attribute | Type | Description |
| --------- | ---- | ----------- |
| data-key | string | The i18n key to be used |
| lang | string | i18n standardized language value |
| default | string | The default value to show while the strings are loading |
### Events
N/A (Non-Interactive)
### Functionality
A service is required to perform the replacement of these keys appropriately. The component itself should not perform the replacement but rather it acts as a holder of the keys.
### Usage
`vue.js` Example
<i18n data-key="page1.title" :lang="options.language" default="The title of the page" />
**NPM Package**: `internal\general-components\vue`
**TypeScript Interface**: `VueI18n`

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

Я рекомендую, чтобы эти документы жили либо:

  1. В согласованном централизованном глобальном месте с соответствующими средствами контроля доступа
  2. С самой библиотекой кода, централизованной в репозитории.

Схема веб-API

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

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

  1. Минимальный размер запроса/ответа. Какие минимальные поля требуются в вашей системе для работы основных функций?
  2. Дополнительные требования к данным: какие поля необходимы клиентам? Это могут быть идентификаторы, которые они могут потребовать вернуть.
  3. Планирование на будущее. Ожидаем ли мы, что этот API сильно изменится? Какие общие изменения мы можем предвидеть?
  4. Тестирование дизайна. Всегда проверяйте дизайн на соответствие вариантам использования, чтобы обеспечить совместимость.
  5. Дизайн документа: задокументируйте дизайн для использования клиентами и разработчиками.

Рекомендую на каждом этапе действительно выписывать образцы запросов/ответов. Это могут быть просто образцы запросов. Когда вы начнете добавлять в дизайн, вы придете к выводу о том, что вам следует использовать.

В рамках контракта, вот некоторые соображения,

  • Должны ли мы верифицировать API? Это позволит нам легче изменять его, не затрагивая клиентов. Это самый безопасный способ обеспечить обратную совместимость изменений. (т.е. /api/v1/products )
  • Как мы будем обрабатывать аутентификацию/авторизацию? Обрабатывается ли аутентификация отдельно от запроса (т. е. конечная точка входа) или мы используем встроенную аутентификацию (базовая аутентификация).
  • Нужны ли нам разбиение по страницам и сортировка? Это функция, которая должна стабильно работать в API. Эти сквозные типы проблем должны быть изменчивыми.
  • Будете ли вы поддерживать несколько типов контента? Поддерживаете ли вы только application/json? Или вы будете поддерживать application/xml или какие-то другие настраиваемые типы контента?
  • Как вы будете использовать коды ответов HTTP? Означает ли код 404, что ресурс не найден? Или вы всегда будете возвращать Bad Request? Хотя они стандартизированы, иногда бывают случаи, когда вы можете стандартизировать определенные режимы.
  • Как об ошибках или проблемах будет сообщаться вызывающему абоненту? Какой будет формат сообщения об ошибке помимо основного кода ответа? Будет ли он включен в модель первичного реагирования? Или вы будете использовать общую модель, такую ​​как Детали проблемы?
  • Что произойдет с дополнительными свойствами? Вы сразу отклоните их? Будет ли возвращен ответ Bad Request, если будут обнаружены дополнительные поля? Будут ли они когда-нибудь использованы?

Можно задать еще много вопросов, но это одни из самых важных.

Наконец, давайте упомянем документацию. В качестве документации я предпочитаю спецификацию OpenAPI. Это может быть довольно сложно сделать напрямую, поэтому вы можете сначала создать макет в своей системе, а затем экспортировать (Swagger).

После того, как вы закончите файл JSON, вы можете использовать его непосредственно в своем программном обеспечении или использовать такой инструмент, как Redocly, для преобразования в соответствующий язык разметки для Wiki. Вы можете разместить это внутри или найти облачного провайдера, который разместит его для вас.

Думаю, стоит отметить, что для таких технологий, как SOAP, GraphQL и gRPC, все документируется по-разному. Хотя для этого есть решения, мы не будем их здесь рассматривать.

Библиотека/SDK

При разработке библиотеки или SDK для внешнего использования эти контракты должны быть разработаны так же, как и веб-API:

  1. Минимальный размер запроса/ответа. Какие минимальные поля требуются в вашей системе для работы основных функций?
  2. Дополнительные требования к данным: какие поля необходимы клиентам? Это могут быть идентификаторы, которые они могут потребовать вернуть.
  3. Планирование на будущее. Ожидаем ли мы, что этот API сильно изменится? Какие общие изменения мы можем предвидеть?
  4. Тестирование дизайна. Всегда проверяйте дизайн на соответствие вариантам использования, чтобы обеспечить совместимость.
  5. Дизайн документа: задокументируйте дизайн для использования клиентами и разработчиками.

Разница в реализации. Например, вы можете предоставить фабрики, абстрактные классы (интерфейсы), шаблоны проектов или генераторы кода. Несмотря на это, предпосылка одна и та же, дизайн для общего случая в первую очередь.

Ниже приведены некоторые рекомендации по созданию библиотеки или SDK для ваших клиентов.

  • Используйте абстрактные классы. Не заставляйте пользователей напрямую подключаться к конкретным классам. Это значительно ограничит вашу способность развиваться.
  • Сохраняйте контракты небольшими: не создавайте абстрактные классы Бога. Сохраняйте их как можно меньше, сохраняя при этом функциональность.
  • Используйте методы расширения (C#). При использовании .NET используйте методы расширения для расширения функциональности абстрактных классов и интерфейсов, а не помещайте их в интерфейс.
  • Предоставление фабричных классов или методов. Используйте фабрики, чтобы ваши клиенты могли быстро создавать классы, вместо того, чтобы позволять им создавать классы напрямую.
  • Предоставить компоновщики. Предоставьте пользователю несколько компоновщиков, которые облегчат задачу реализации сложной настройки функций.
  • Http-клиенты: при предоставлении библиотеки для подключения к удаленной службе следуйте рекомендациям по выбору языка вместо того, чтобы пытаться сопоставить буквальные форматы объекта запроса/ответа. Возможно, в будущем их придется изменить. Вам нужен логический контракт.
  • Максимальная инкапсуляция: старайтесь защитить все, пока у вас не останется выбора. Это означает частные занятия, пока вам не понадобится предоставить их клиенту. Чем больше вы защищаете, тем больше шансов, что пользователи не будут использовать библиотеку неправильно.
  • Отдельно разделять: разделяйте сборки и пакеты соответствующим образом. Не скидывайте все в один большой пакет. Если вы пытаетесь обеспечить удобство, вы можете создать отдельный пакет, который импортирует отдельные пакеты по мере необходимости.
  • Последовательность. Будьте последовательны в подходах и названиях. Что бы вы ни решили, не отклоняйтесь, особенно для внешних клиентов.

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

Используйте свои собственные библиотеки! Вы быстро обнаружите, что не так с библиотекой, когда разочаруетесь в ней.

Цель библиотек — обеспечить удобство, позволяя клиентам использовать контракты таким же образом.

Когда вы будете готовы документировать свои проекты, документируйте их как разработчик. Каким бы вы хотели его видеть? Используйте примеры документации, которые вам нравятся. Вот некоторые из них, которые я ценю:

Документация бывает всех форм и размеров. В конечном счете, упростите задачу с помощью примеров и четких правил. Это контракт!

Хранилище данных

Хранение данных немного отличается от других. Хотя этот процесс может работать одинаково,

  1. Минимальный размер запроса/ответа. Какие минимальные поля требуются в вашей системе для работы основных функций?
  2. Дополнительные требования к данным: какие поля необходимы клиентам? Это могут быть идентификаторы, которые они могут потребовать вернуть.
  3. Планирование на будущее. Ожидаем ли мы, что этот API сильно изменится? Какие общие изменения мы можем предвидеть?
  4. Тестирование дизайна. Всегда проверяйте дизайн на соответствие вариантам использования, чтобы обеспечить совместимость.
  5. Дизайн документа: задокументируйте дизайн для использования клиентами и разработчиками.

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

  • Используем ли мы технологии SQL, Graph или NoSQL?
  • Будет ли база данных использоваться для отчетности вместе с транзакциями?
  • Сколько клиентов будет использовать эту базу данных?
  • Есть ли проблемы параллелизма?
  • Как осуществляется контроль изменений и аудит записей?
  • Мы выполняем мягкое удаление или полное удаление?
  • Какие таблицы или контейнеры пострадают больше всего?
  • Что мы делаем с данными больших объектов? Должен ли он быть разделен по соображениям производительности?
  • Будет ли SQL встроен или в хранимых процедурах (где они доступны)?
  • Будут ли данные разделены? Сколько серверов будет использоваться?
  • Как схема влияет на зеркальное отображение, репликацию или группы доступности?
  • Будем ли мы удалять данные через какой-то период времени?

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

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

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

  • SQL Server — используйте проект базы данных с комментариями
  • База данных графов — Visio/Lucidchart: обобщенная графическая диаграмма, описывающая отношения
  • Документ NoSQL — Markdown: ожидаемая схема хранения JSON
  • NoSQL Key-Value — Markdown: ключевые шаблоны и ожидаемые данные

Тем не менее, эти конструкции важны. Я бы даже порекомендовал, чтобы вместо простого описания структуры еще важнее было описать запросы.

Предоставьте примеры запросов со всей документацией по хранению данных.

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

Заключение и подпись

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

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

Я надеюсь, что эта статья помогла предоставить более подробную информацию о контрактах и ​​их важности. Всегда заключайте контракты заранее. Не ждите, иначе вам придется переделывать много кода. И не экономьте на документации. Нет, это не самый приятный аспект работы разработчика, это самый важный аспект не только во время проектирования, но и в процессе поддержки.

Спасибо за чтение! До скорого!

Бонус! Проектирование для нескольких вариантов

Я подозреваю, что некоторые люди будут упоминать идею требований и Agile. Как мы можем составить контракт, не зная всех деталей? Agile — это быстрое реагирование на изменения. Зачем иметь дело с контрактами рано?

Хороший вопрос.

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

Итак, я спрашиваю вас: вы можете справиться со всеми сценариями? Почему бы не принять во внимание каждый? Я не предлагаю создавать все функции сразу, но, по крайней мере, убедитесь, что ваши контракты могут работать с различными сценариями. Это сделает вашу платформу более гибкой для изменений в будущем, сократив ваши расходы в будущем.