mirror of
https://github.com/twirl/The-API-Book.git
synced 2025-01-05 10:20:22 +02:00
563 lines
100 KiB
HTML
563 lines
100 KiB
HTML
<html><head>
|
|
<meta charset="utf-8"/>
|
|
<title>Сергей Константинов. API</title>
|
|
<meta name="author" content="Сергей Константинов"/>
|
|
<link rel="stylesheet" href="https://fonts.googleapis.com/css2?family=PT+Serif&family=PT+Sans&family=Inconsolata"/>
|
|
<style>body {
|
|
font-family: 'PT Serif';
|
|
font-size: 14pt;
|
|
text-align: justify;
|
|
}
|
|
|
|
@media screen {
|
|
body {
|
|
margin: 20px auto;
|
|
max-width: 60%;
|
|
}
|
|
}
|
|
|
|
@media print {
|
|
h1 {
|
|
margin: 3.5in 0 4in 0;
|
|
}
|
|
}
|
|
|
|
.cc-by-nc {
|
|
background: transparent url(https://i.creativecommons.org/l/by-nc/4.0/88x31.png) 0 5px no-repeat;
|
|
padding-left: 92px;
|
|
}
|
|
|
|
code, pre {
|
|
font-family: Inconsolata, sans-serif;
|
|
font-size: 12pt;
|
|
}
|
|
|
|
pre {
|
|
margin: 12pt 0;
|
|
padding: 12pt;
|
|
border-radius: .25em;
|
|
border-top: 1px solid rgba(0,0,0,.45);
|
|
border-left: 1px solid rgba(0,0,0,.45);
|
|
box-shadow: .1em .1em .1em rgba(0,0,0,.45);
|
|
page-break-inside: avoid;
|
|
}
|
|
|
|
.page-break {
|
|
page-break-after: always;
|
|
}
|
|
|
|
a {
|
|
text-decoration: none;
|
|
}
|
|
|
|
h1, h2, h3, h4, h5 {
|
|
text-align: left;
|
|
font-family: 'PT Sans';
|
|
font-weight: bold;
|
|
}
|
|
|
|
h1 {
|
|
font-size: 28pt;
|
|
}
|
|
|
|
h2 {
|
|
font-size: 24pt;
|
|
}
|
|
|
|
h3 {
|
|
font-size: 20pt;
|
|
}
|
|
|
|
h4, h5 {
|
|
font-size: 16pt;
|
|
}
|
|
|
|
@page {
|
|
size: 8.5in 11in;
|
|
margin: 0.5in;
|
|
}
|
|
|
|
:root {
|
|
--main-font: 'PT Serif';
|
|
--alt-font: 'PT Serif';
|
|
--code-font: Inconsolata;
|
|
}</style>
|
|
</head><body>
|
|
<article><h1>Сергей Константинов<br/>API</h1>
|
|
|
|
<p class="cc-by-nc">Это произведение доступно по <a href="http://creativecommons.org/licenses/by-nc/4.0/">лицензии Creative Commons «Attribution-NonCommercial» («Атрибуция — Некоммерческое использование») 4.0 Всемирная</a>.</p>
|
|
<div class="page-break"></div><h2>Введение</h2><h3 id="1">Глава 1. О структуре этой книги</h3>
|
|
<p>Книга, которую вы держите в руках, состоит из введения и трех больших разделов.</p>
|
|
<p>В первом разделе мы поговорим о проектировании API на стадии разработки концепции — как грамотно выстроить архитектуру, от крупноблочного планирования до конечных интерфейсов.</p>
|
|
<p>Второй раздел будет посвящён жизненному циклу API — как интерфейсы эволюционируют со временем и как развивать продукт так, чтобы отвечать потребностям пользователей.</p>
|
|
<p>Наконец, третий раздел будет касаться больше не-разработческих сторон жизни API — поддержки, маркетинга, работы с комьюнити.</p>
|
|
<p>Первые два будут интересны скорее разработчикам, третий — и разработчикам, и менеджерам. При этом мы настаиваем, что как раз третий раздел — самый важный для разработчика API. Ввиду того, что API — продукт для разработчиков, перекладывать ответственность за его развитие и поддержку на не-разработчиков неправильно: никто кроме вас самих не понимает так хорошо продуктовые свойства вашего API.</p>
|
|
<p>На этом переходим к делу.</p><div class="page-break"></div><h3 id="2api">Глава 2. Определение API</h3>
|
|
<p>Прежде чем говорить о разработке API, необходимо для начала договориться о том, что же такое API. Энциклопедия скажет нам, что API — это программный интерфейс приложений. Это точное определение, но бессмысленное. Примерно как определение человека по Платону: «двуногое без перьев» — определение точное, но никоим образом не дающее нам представление о том, чем на самом деле человек примечателен. (Да и не очень-то и точное: Диоген Синопский как-то ощипал петуха и заявил, что это человек Платона; пришлось дополнить определение уточнением «с плоскими ногтями».)</p>
|
|
<p>Что же такое API по смыслу, а не по формальному определению?</p>
|
|
<p>Вероятно, вы сейчас читаете эту книгу посредством браузера. Чтобы браузер смог отобразить эту страничку, должны корректно отработать: разбор URL согласно спецификации; служба DNS; соединение по протоколу TLS; передача данных по протоколу HTTP; разбор HTML-документа; разбор CSS-документа; корректный рендеринг HTML+CSS.</p>
|
|
<p>Но это только верхушка айсберга. Для работы HTTP необходима корректная работа всего сетевого стека, который состоит из 4-5, а то и больше, протоколов разных уровней. Разбор HTML-документа производится согласно сотням различных спецификаций. Рендеринг документа обращается к нижележащему API операционной системы, а также напрямую к API видеокарты. И так далее, и тому подобное — вплоть до того, что наборы команд современных CISC-процессоров имплементируются поверх API микрокоманд.</p>
|
|
<p>Иными словами, десятки, если не сотни, различных API должны отработать корректно для выполнения базовых действий типа просмотра web-страницы; без надёжной работы каждого из них современные информационные технологии попросту не могли бы существовать.</p>
|
|
<p><strong>API — это обязательство</strong>. Формальное обязательство связывать между собой различные программируемые контексты.</p>
|
|
<p>Когда меня просят привести пример хорошего API, я обычно показываю фотографию римского виадука:</p>
|
|
<ul>
|
|
<li>он связывает между собой две области</li>
|
|
<li>обратная совместимость нарушена ноль раз за последние две тысячи лет.</li>
|
|
</ul>
|
|
<p>Отличие римского виадука от хорошего API состоит лишь в том, что API предлагает <em>программный</em> контракт. Для связывания двух областей необходимо написать некоторый <em>код</em>. Цель этой книги — помочь вам разработать API, так же хорошо выполняющий свою задачу, как и римский виадук.</p>
|
|
<p>Виадук также хорошо иллюстрирует другую проблему разработки API: вашими пользователями являются инженеры. Вы не поставляете воду напрямую потребителю: к вашей инженерной мысли подключаются заказчики путём пристройки к ней каких-то своих инженерных конструкций. С одной стороны, вы можете обеспечить водой гораздо больше людей, нежели если бы вы сами подводили трубы к каждому крану. С другой — качество инженерных решений заказчика вы не может контролировать, и проблемы с водой, вызванные некомпетентностью подрядчика, неизбежно будут валить на вас.</p>
|
|
<p>Поэтому проектирование API налагает на вас несколько большую ответственность. <strong>API является как мультипликатором ваших возможностей, так и мультипликатором ваших ошибок</strong>.</p><div class="page-break"></div><h3 id="3api">Глава 3. Критерии качества API</h3>
|
|
<p>Прежде чем излагать рекомендации, нам следует определиться с тем, что мы считаем «хорошим» API, и какую пользу мы получаем от того, что наше API «хорошее».</p>
|
|
<p>Начнём со второго вопроса. Очевидно, «хорошесть» API определяется в первую очередь тем, насколько он помогает разработчикам решать стоящие перед ними задачи. (Можно резонно возразить, что решение задач, стоящих перед разработчиками, не обязательно влечёт за собой выполнение целей, которые мы ставим перед собой, предлагая разработчикам API. Однако манипуляция общественным мнением не входит в область интересов автора этой книги: здесь и далее предполагается, что API существует в первую очередь для того, чтобы разработчики решали с его помощью свои задачи, а не ради каких-то не декларируемых явно целей.)</p>
|
|
<p>Как же дизайн API может помочь разработчику? Очень просто: API должно <em>решать задачи</em>, и делать это максимально удобно и понятно. Путь разработчика от формулирования своей задачи до написания работающего кода должен быть максимально коротким. Это, в том числе, означает, что:</p>
|
|
<ul>
|
|
<li>из структуры вашего API должно быть максимально очевидно, как решить ту или иную задачу; в идеале разработчику должно быть достаточно одного взгляда на документацию, чтобы понять, с помощью каких сущностей следует решать его задачу;</li>
|
|
<li>API должно быть читаемым: в идеале разработчик, просто глядя в номенклатуру методов, сразу пишет правильный код, не углубляясь в детали (особенно — детали реализации!); немаловажно уточнить, что из интерфейсов объектов должно быть понятно не только решение задачи, но и возможные ошибки и исключения;</li>
|
|
<li>API должно быть консистентно: при разработке новой функциональности, т.е. при обращении к каким-то незнакомым сущностям в API, разработчик может действовать по аналогии с уже известными ему концепциями API, и его код будет работать.</li>
|
|
</ul>
|
|
<p>Однако статическое удобство и понятность API — это простая часть. В конце концов, никто не стремится специально сделать API нелогичным и нечитаемым — всегда при разработке мы начинаем с каких-то понятных базовых концепций. При минимальном опыте проектирования сложно сделать ядро API, не удовлетворяющее критериям очевидности, читаемости и консистентности.</p>
|
|
<p>Проблемы начинаются, когда мы начинаем API развивать. Добавление новой функциональности рано или поздно приводит к тому, что некогда простое и понятное API становится наслоением разных концепций, а попытки сохранить обратную совместимость приводят к нелогичным, неочевидным и попросту плохим решениям. Отчасти это связано так же и с тем, что невозможно обладать полным знанием о будущем: ваше понимание о «правильном» API тоже будет меняться со временем, как в объективной части (какие задачи решает API и как лучше это сделать), так и в субъективной — что такое очевидность, читабельность и консистентность для вашего API.</p>
|
|
<p>Принципы, которые я буду излагать ниже, во многом ориентированы именно на то, чтобы API правильно развивалось во времени и не превращалось в нагромождение разнородных неконсистентных интерфейсов. Важно понимать, что такой подход тоже небесплатен: необходимость держать в голове варианты развития событий и закладывать возможность изменений в API означает избыточность интерфейсов и возможно излишнее абстрагирование. И то, и другое, помимо прочего, усложняет и работу программиста, пользующегося вашим API. <strong>Закладывание перспектив «на будущее» имеет смысл, только если это будущее у API есть, иначе это попросту оверинжиниринг</strong>.</p><div class="page-break"></div><h3 id="4">Глава 4. Обратная совместимость</h3>
|
|
<p>Обратная совместимость — это некоторая <em>временна́я</em> характеристика качества вашего API. Именно необходимость поддержания обратной совместимости отличает разработку API от разработки программного обеспечения вообще.</p>
|
|
<p>Разумеется, обратная совместимость не абсолютна. В некоторых предметных областях выпуск новых обратно несовместимых версий API является вполне рутинной процедурой. Тем не менее, каждый раз, когда выпускается новая обратно несовместимая версия API, всем разработчикам приходится инвестировать какое-то ненулевое количество усилий, чтобы адаптировать свой код к новой версии. В этом плане выпуск новых версий API является некоторого рода «налогом» на потребителей — им нужно тратить вполне осязаемые деньги только для того, чтобы их продукт продолжал работать.</p>
|
|
<p>Конечно, крупные компании с прочным положением на рынке могут позволить себе такой налог взымать. Более того, они могут вводить какие-то санкции за отказ от перехода на новые версии API, вплоть до отключения приложений.</p>
|
|
<p>С нашей точки зрения, подобное поведение ничем не может быть оправдано. Избегайте скрытых налогов на своих пользователей. Если вы можете не ломать обратную совместимость — не ломайте её.</p>
|
|
<p>Да, безусловно, поддержка старых версий API — это тоже своего рода налог. Технологии меняются, и, как бы хорошо ни было спроектировано ваше API, всего предусмотреть невозможно. В какой-то момент ценой поддержки старых версий становится невозможность предоставлять новую функциональность и поддерживать новые платформы, и выпустить новую версию всё равно придётся. Однако вы по крайней мере сможете убедить своих потребителей в необходимости перехода.</p>
|
|
<p>Более подробно о жизненном цикле API и политиках выпуска новых версий будет рассказано в разделе II.</p><div class="page-break"></div><h3 id="5">Глава 5. О версионировании</h3>
|
|
<p>Здесь и далее мы будем придерживаться принципов версионирования <a href="https://semver.org/">semver</a>:</p>
|
|
<ol>
|
|
<li>Версия API задаётся тремя цифрами, вида <code>1.2.3</code></li>
|
|
<li>Первая цифра (мажорная версия) увеличивается при обратно несовместимых изменениях в API</li>
|
|
<li>Вторая цифра (минорная версия) увеличивается при добавлении новой функциональности с сохранением обратной совместимости</li>
|
|
<li>Третья цифра (патч) увеличивается при выпуске новых версий, содержащих только исправление ошибок</li>
|
|
</ol>
|
|
<p>Выражения «мажорная версия API» и «версия API, содержащая обратно несовместимые изменения функциональности» тем самым следует считать эквивалентными.</p>
|
|
<p>Более подробно о политиках версионирования будет рассказано в разделе II. В разделе I мы ограничимся лишь указанием версии API в формате <code>v1</code>, <code>v2</code>, etc.</p><div class="page-break"></div><h3 id="6">Глава 6. Условные обозначения и терминология</h3>
|
|
<p>Разработка программного обеспечения характеризуется, помимо прочего, существованием множества различных парадигм разработки, адепты которых зачастую настроены весьма воинственно по отношению к адептам других парадигм. Поэтому при написании этой книги мы намеренно избегаем слов «метод», «объект», «функция» и так далее, используя нейтральный термин «сущность». Под «сущностью» понимается некоторая атомарная единица функциональности — класс, метод, объект, монада, прототип (нужное подчеркнуть).</p>
|
|
<p>Для составных частей сущности, к сожалению, достаточно нейтрального термина нам придумать не удалось, поэтому мы используем слова «поля» и «методы».</p>
|
|
<p>Большинство примеров API в общих разделах будут даны в виде JSON-over-HTTP-эндпойтов. Это некоторая условность, которая помогает описать концепции, как нам кажется, максимально понятно. Вместо <code>GET /v1/orders</code> вполне может быть вызов метода <code>orders.get()</code>, локальный или удалённый; вместо JSON может быть любой другой формат данных. Смысл утверждений от этого не меняется.</p>
|
|
<p>Также в примерах часто применяется следующая конвенция. Запись <code>{ "begin_date" }</code> (т.е. отсутствие значения у поля в JSON-объекте) означает, что в поле находится именно то, что ожидается — т.е. в данном примере какая-то дата начала.</p><div class="page-break"></div><h2>I. Проектирование API</h2><h3 id="7api">Глава 7. Пирамида контекстов API</h3>
|
|
<p>Подход, который мы используем для проектирования, состоит из четырёх шагов:</p>
|
|
<ul>
|
|
<li>определение области применения;</li>
|
|
<li>разделение уровней абстракции;</li>
|
|
<li>разграничение областей ответственности;</li>
|
|
<li>описание конечных интерфейсов.</li>
|
|
</ul>
|
|
<p>Этот алгоритм строит API сверху вниз, от общих требований и сценариев использования до конкретной номенклатуры сущностей; фактически, двигаясь этим путем, вы получите на выходе готовое API — чем этот подход и ценен.</p>
|
|
<p>Может показаться, что наиболее полезные советы приведены в последнем разделе, однако это не так; цена ошибки, допущенной на разных уровнях весьма различна. Если исправить плохое именование довольно просто, то исправить неверное понимание того, зачем вообще нужно API, практически невозможно.</p>
|
|
<p><em>NB</em>. Здесь и далее мы будем рассматривать концепции разработки API на примере некоторого гипотетического API заказа кофе в городских кофейнях. На всякий случай сразу уточним, что пример является синтетическим; в реальной ситуации, если бы такое API пришлось проектировать, оно вероятно было бы совсем не похоже на наш выдуманный пример.</p><div class="page-break"></div><h3 id="8">Глава 8. Определение области применения</h3>
|
|
<p>Ключевой вопрос, который вы должны задать себе четыре раза, выглядит так: какую проблему мы решаем? Задать его следует четыре раза с ударением на каждом из четырёх слов.</p>
|
|
<ol>
|
|
<li><p><em>Какую</em> проблему мы решаем? Можем ли мы чётко описать, в какой ситуации гипотетическим потребителям-разработчикам нужно наше API?</p></li>
|
|
<li><p>Какую <em>проблему</em> мы решаем? А мы правда уверены, что описанная выше ситуация — проблема? Действительно ли кто-то готов платить (в прямом и переносном смысле) за то, что ситуация будет как-то автоматизирована?</p></li>
|
|
<li><p>Какую проблему <em>мы</em> решаем? Действительно ли решение этой проблемы находится в нашей компетенции? Действительно ли мы находимся в той позиции, чтобы решить эту проблему?</p></li>
|
|
<li><p>Какую проблему мы <em>решаем</em>? Правда ли, что решение, которое мы предлагаем, действительно решает проблему? Не создаём ли мы на её месте другую проблему, более сложную?</p></li>
|
|
</ol>
|
|
<p>Итак, предположим, что мы хотим предоставить API автоматического заказа кофе в городских кофейнях. Попробуем применить к ней этот принцип.</p>
|
|
<ol>
|
|
<li><p>Зачем кому-то может потребоваться API для приготовления кофе? В чем неудобство заказа кофе через интерфейс, человек-человек или человек-машина? Зачем нужна возможность заказа машина-машина?</p>
|
|
<ul>
|
|
<li>Возможно, мы хотим решить проблему выбора и знания? Чтобы человек наиболее полно знал о доступных ему здесь и сейчас опциях.</li>
|
|
<li>Возможно, мы оптимизируем время ожидания? Чтобы человеку не пришлось ждать, пока его заказ готовится.</li>
|
|
<li>Возможно, мы хотим минимизировать ошибки? Чтобы человек получил именно то, что хотел заказать, не потеряв информацию при разговорном общении либо при настройке незнакомого интерфейса кофе-машины.</li></ul>
|
|
<p>Вопрос «зачем» — самый важный из тех вопросов, которые вы должны задавать себе. Не только глобально в отношении целей всего проекта, но и локально в отношении каждого кусочка функциональности. <strong>Если вы не можете коротко и понятно ответить на вопрос «зачем эта сущность нужна» — значит, она не нужна</strong>.</p>
|
|
<p>Здесь и далее предположим (в целях придания нашему примеру глубины и некоторой упоротости), что мы оптимизируем все три фактора в порядке убывания важности.</p></li>
|
|
<li><p>Правда ли решаемая проблема существует? Действительно ли мы наблюдаем неравномерную загрузку кофейных автоматов по утрам? Правда ли люди страдают от того, что не могут найти поблизости нужный им латте с ореховым сиропом? Действительно ли людям важны те минуты, которые они теряют, стоя в очередях?</p></li>
|
|
<li><p>Действительно ли мы обладаем достаточным ресурсом, чтобы решить эту проблему? Есть ли у нас доступ к достаточному количеству кофе-машин и клиентов, чтобы обеспечить работоспособность системы?</p></li>
|
|
<li><p>Наконец, правда ли мы решим проблему? Как мы поймём, что оптимизировали перечисленные факторы?</p></li>
|
|
</ol>
|
|
<p>На все эти вопросы, в общем случае, простого ответа нет. В идеале ответы на эти вопросы должны даваться с цифрами в руках. Сколько конкретно времени тратится неоптимально, и какого значения мы рассчитываем добиться, располагая какой плотностью кофе-машин? Заметим также, что в реальной жизни просчитать такого рода цифры можно в основном для проектов, которые пытаются влезть на уже устоявшийся рынок; если вы пытаетесь сделать что-то новое, то, вероятно, вам придётся ориентироваться в основном на свою интуицию.</p>
|
|
<h4 id="api">Почему API?</h4>
|
|
<p>Т.к. наша книга посвящена не просто разработке программного обеспечения, а разработке API, то на все эти вопросы мы должны взглянуть под другим ракурсом: а почему для решения этих задач требуется именно API, а не просто программное обеспечение? В нашем вымышленном примере мы должны спросить себя: зачем нам нужно предоставлять сервис для других разработчиков, чтобы они могли готовить кофе своим клиентам, а не сделать своё приложение для конечного потребителя?</p>
|
|
<p>Иными словами, должна иметься веская причина, по которой два домена разработки ПО должны быть разделены: есть оператор(ы), предоставляющий API; есть оператор(ы), предоставляющий сервисы пользователям. Их интересы в чем-то различны настолько, что объединение этих двух ролей в одном лице нежелательно. Более подробно мы изложим причины и мотивации делать именно API в разделе II.</p>
|
|
<p>Заметим также следующее: вы должны браться делать API тогда и только тогда, когда в ответе на второй вопрос написали «потому что в этом состоит наша экспертиза». Разрабатывая API вы занимаетесь некоторой мета-разработкой: вы разрабатывать ПО для того, чтобы другие могли разрабатывать ПО для решения задачи пользователя. Не обладая экспертизой в обоих этих доменах (API и конечные продукты) написать хорошее API сложно.</p>
|
|
<p>Для нашего умозрительного примера предположим, что в недалеком будущем произошло разделение рынка кофе на две группы игроков: одни предоставляют само железо, кофейные аппараты, а другие имеют доступ к потребителю — примерно как это произошло, например, с рынком авиабилетов, где есть собственно авиакомпании, осуществляющие перевозку, и сервисы планирования путешествий, где люди выбирают варианты перелётов. Мы хотим агрегировать доступ к железу, чтобы владельцы приложений могли встраивать заказ кофе.</p>
|
|
<h4 id="">Что и как</h4>
|
|
<p>Закончив со всеми теоретическими упражнениями, мы должны перейти непосредственно к дизайну и разработке API, имея понимание по двум пунктам:</p>
|
|
<ol>
|
|
<li>Что конкретно мы делаем</li>
|
|
<li>Как мы это делаем</li>
|
|
</ol>
|
|
<p>В случае нашего кофе-примера мы:</p>
|
|
<ol>
|
|
<li>Предоставляем сервисам с большой пользовательской аудиторией API для того, чтобы их потребители могли максимально удобно для себя заказать кофе.</li>
|
|
<li>Для этого мы абстрагируем за нашим HTTP API доступ к «железу» и предоставим методы для выбора вида напитка и места его приготовления и для непосредственно исполнения заказа.</li>
|
|
</ol><div class="page-break"></div><h3 id="9">Глава 9. Разделение уровней абстракции</h3>
|
|
<p>«Разделите свой код на уровни абстракции» - пожалуй, самый общий совет для разработчиков программного обеспечения. Однако будет вовсе не преувеличением сказать, что изоляция уровней абстракции — самая сложная задача, стоящая перед разработчиком API.</p>
|
|
<p>Прежде чем переходить к теории, следует чётко сформулировать, <em>зачем</em> нужны уровни абстракции и каких целей мы хотим достичь их выделением.</p>
|
|
<p>Вспомним, что программный продукт - это средство связи контекстов, средство преобразования терминов и операций одной предметной области в другую. Чем дальше друг от друга эти области отстоят - тем большее число промежуточных передаточных звеньев нам придётся ввести. Вернёмся к нашему примеру с кофейнями. Какие уровни сущностей мы видим?</p>
|
|
<ol>
|
|
<li>Непосредственно состояние кофе-машины и шаги приготовления кофе. Температура, давление, объём воды.</li>
|
|
<li>У кофе есть мета-характеристики: сорт, вкус, вид напитка.</li>
|
|
<li>Мы готовим с помощью нашего API <em>заказ</em> — один или несколько стаканов кофе с определенной стоимостью.</li>
|
|
<li>Наши кофе-машины как-то распределены в пространстве (и времени).</li>
|
|
<li>Кофе-машина принадлежит какой-то сети кофеен, каждая из которых обладает какой-то айдентикой и специальными возможностями.</li>
|
|
</ol>
|
|
<p>Каждый из этих уровней задаёт некоторый срез нашего API, с которым будет работать потребитель. Выделяя иерархию абстракций мы прежде всего стремимся снизить связность различных сущностей нашего API. Это позволит нам добиться нескольких целей:</p>
|
|
<ol>
|
|
<li><p>Упрощение работы разработчика и легкость обучения: в каждый момент времени разработчику достаточно будет оперировать только теми сущностями, которые нужны для решения его задачи; и наоборот, плохо выстроенная изоляция приводит к тому, что разработчику нужно держать в голове множество концепций, не имеющих прямого отношения к решаемой задаче.</p></li>
|
|
<li><p>Возможность поддерживать обратную совместимость; правильно подобранные уровни абстракции позволят нам в дальнейшем добавлять новую функциональность, не меняя интерфейс.</p></li>
|
|
<li><p>Поддержание интероперабельности. Правильно выделенные низкоуровневые абстракции позволят нам адаптировать наше API к другим платформам, не меняя высокоуровневый интерфейс.</p></li>
|
|
</ol>
|
|
<p>Допустим, мы имеем следующий интерфейс:</p>
|
|
<ul>
|
|
<li><code>GET /v1/recipes/lungo</code><br />
|
|
— возвращает рецепт лунго;</li>
|
|
<li><code>POST /v1/coffee-machines/orders?machine_id={id}</code><br />
|
|
<code>{recipe:"lungo"}</code><br />
|
|
— размещает на указанной кофе-машине заказ на приготовление лунго и возвращает идентификатор заказа;</li>
|
|
<li><code>GET /v1/orders?order_id={id}</code><br />
|
|
— возвращает состояние заказа;</li>
|
|
</ul>
|
|
<p>И зададимся вопросом, каким образом разработчик определит, что заказ клиента готов. Допустим, мы сделаем так: добавим в рецепт лунго эталонный объём, а в состояние заказа — количество уже налитого кофе. Тогда разработчику нужно будет проверить совпадение этих двух цифр, чтобы убедиться, что кофе готов.</p>
|
|
<p>Такое решение выглядит интуитивно плохим, и это действительно так: оно нарушает все вышеперечисленные принципы:</p>
|
|
<ol>
|
|
<li><p>Для решения задачи «заказать лунго» разработчику нужно обратиться к сущности «рецепт» и выяснить, что у каждого рецепта есть объём. Далее, нужно принять концепцию, что приготовление кофе заканчивается в тот момент, когда объём сравнялся с эталонным. Нет никакого способа об этой конвенции догадаться: она неочевидна и её нужно найти в документации. При этом никакой пользы для разработчика в этом знании нет.</p></li>
|
|
<li><p>Мы автоматически получаем проблемы, если захотим варьировать размер кофе. Допустим, в какой-то момент мы захотим представить пользователю выбор, сколько конкретно миллилитров лунго он желает. Тогда нам придётся проделать один из следующих трюков:</p>
|
|
<ul>
|
|
<li>или мы фиксируем список допустимых объёмов и заводим фиктивные рецепты типа <code>/recipes/small-lungo</code>, <code>recipes/large-lungo</code>. Почему фиктивные? Потому что рецепт один и тот же, меняется только объём. Нам придётся либо тиражировать одинаковые рецепты, отличающиеся только объёмом, либо вводить какое-то «наследование» рецептов, чтобы можно было указать базовый рецепт и только переопределить объём;</li>
|
|
<li>или мы модифицируем интерфейс, объявляя объём кофе, указанный в рецепте, значением по умолчанию; при размещении заказа мы разрешаем указать объём, отличный от эталонного:<br />
|
|
<code>POST /v1/coffee-machines/orders?machine_id={id}</code><br />
|
|
<code>{recipe:"lungo","volume":"800ml"}</code><br />
|
|
Для таких кофе произвольного объёма нужно будет получать требуемый объём не из <code>GET /v1/recipes</code>, а из <code>GET /v1/orders</code>. Сделав так, мы сразу получаем клубок из связанных проблем:</li>
|
|
<li>разработчик, которому придётся поддержать эту функциональность, имеет высокие шансы сделать ошибку: добавив поддержку произвольного объёма кофе в код, работающий с <code>POST /v1/coffee-machines/orders</code> нужно не забыть переписать код проверки готовности заказа;</li>
|
|
<li>мы получим классическую ситуацию, когда одно и то же поле (объём кофе) значит разные вещи в разных интерфейсах. В <code>GET /v1/recipes</code> поле «объём» теперь значит «объём, который будет запрошен, если не передать его явно в <code>POST /v1/coffee-machines/orders</code>»; переименовать его в «объём по умолчанию» уже не получится, с этой проблемой теперь придётся жить.</li></ul></li>
|
|
<li><p>Вся эта схема полностью неработоспособна, если разные модели кофе-машин производят лунго разного объёма. Для решения задачи «объём лунго зависит от вида машины» нам придётся сделать совсем неприятную вещь: сделать рецепт зависимым от id машины. Тем самым мы начнём активно смешивать уровни абстракции: одной частью нашего API (рецептов) станет невозможно пользоваться без другой части (информации о кофе-машинах). Что немаловажно, от разработчиков потребуется изменить логику своего приложения: если раньше они могли предлагать сначала выбрать объём, а потом кофе-машину, то теперь им придётся полностью изменить этот шаг.</p></li>
|
|
</ol>
|
|
<p>Хорошо, допустим, мы поняли, как сделать плохо. Но как же тогда сделать <em>хорошо</em>? Разделение уровней абстракции должно происходить вдоль трёх направлений:</p>
|
|
<ol>
|
|
<li><p>От сценариев использования к их внутренней реализации: высокоуровневые сущности и номенклатура их методов должны напрямую отражать сценарии использования API; низкоуровневый - отражать декомпозицию сценариев на составные части.</p></li>
|
|
<li><p>От терминов предметной области пользователя к терминам предметной области исходных данных — в нашем случае от высокоуровневых понятий «рецепт», «заказ», «бренд», «кофейня» к низкоуровневым «температура напитка» и «координаты кофе-машины»</p></li>
|
|
<li><p>Наконец, от структур данных, в которых удобно оперировать пользователю к структурам данных, максимально приближенных к «сырым» - в нашем случае от «лунго» и «сети кофеен "Ромашка"» - к сырым байтовый данным, описывающим состояние кофе-машины марки «Доброе утро» в процессе приготовления напитка.</p></li>
|
|
</ol>
|
|
<p>Чем дальше находятся друг от друга программные контексты, которые соединяет наше API - тем более глубокая иерархия сущностей должна получиться у нас в итоге.</p>
|
|
<p>В нашем примере с определением готовности кофе мы явно пришли к тому, что нам требуется промежуточный уровень абстракции:</p>
|
|
<ul>
|
|
<li>с одной стороны, «заказ» не должен содержать информацию о датчиках и сенсорах кофе-машины;</li>
|
|
<li>с другой стороны, кофе-машина не должна хранить информацию о свойствах заказа (да и вероятно её API такой возможности и не предоставляет).</li>
|
|
</ul>
|
|
<p>Наивный подход в такой ситуации — искусственно ввести некий промежуточный уровень абстракции, «передаточное звено», который переформулирует задачи одного уровня абстракции в другой. Например, введём сущность <code>task</code> вида:</p>
|
|
<pre><code>{
|
|
…
|
|
"volume_requested": "800ml",
|
|
"volume_prepared": "200ml",
|
|
"readiness_policy": "check_volume",
|
|
"ready": false,
|
|
"operation_state": {
|
|
"status": "executing",
|
|
"operations": [
|
|
// описание операций, запущенных на
|
|
// физической кофе-машине
|
|
]
|
|
}
|
|
…
|
|
}
|
|
</code></pre>
|
|
<p>Я называю этот подход «наивным» не потому, что он неправильный; напротив, это вполне логичное решение «по умолчанию», если вы на данном этапе ещё не знаете или не понимаете, как будет выглядеть ваше API. Проблема его в том, что он умозрительный: он не добавляет понимания того, как устроена предметная область.</p>
|
|
<p>Хороший разработчик в нашем примере должен спросить: хорошо, а какие вообще говоря существуют варианты? Как можно определять готовность напитка? Если вдруг окажется, что сравнение объёмов — единственный способ определения готовности во всех без исключения кофе-машинах, то почти все рассуждения выше — неверны: можно совершенно спокойно включать в интерфейсы определение готовности кофе по объёму, т.к. никакого другого и не существует. Прежде, чем что-то абстрагировать — надо представлять, <em>что</em> мы, собственно, абстрагируем.</p>
|
|
<p>Для нашего примера допустим, что мы сели изучать спецификации API кофе-машин и выяснили, что существует принципиально два класса устройств:</p>
|
|
<ul>
|
|
<li>кофе-машины с предустановленными программами, которые умеют готовить заранее прошитые N видов напитков, и мы можем управлять только какими-то параметрами напитка (скажем, объёмом напитка, вкусом сиропа и видом молока); у таких машин отсутствует доступ к внутренним функциям и датчикам, но зато машина умеет через API сама отдавать статус приготовления напитка;</li>
|
|
<li>кофе-машины с предустановленными функциями типа «смолоть такой-то объём кофе», «пролить N миллилитров воды», «взбить молочную пену» и т.д.: у таких машин отсутствует понятие «программа приготовления», но есть доступ к микрокомандам и датчикам.</li>
|
|
</ul>
|
|
<p>Предположим, для большей конкретности, что эти два класса устройств поставляются вот с таким физическим API:</p>
|
|
<ul>
|
|
<li><p>Машины с предустановленными программами:</p>
|
|
<pre><code>GET /programs
|
|
// Возвращает список предустановленных программ
|
|
{
|
|
// идентификатор программы
|
|
"program": "01",
|
|
// вид кофе
|
|
"type": "lungo"
|
|
}
|
|
</code></pre>
|
|
<pre><code>POST /execute
|
|
{
|
|
"program": 1,
|
|
"volume": "200ml"
|
|
}
|
|
// Запускает указанную программу на исполнение
|
|
// и возвращает статус исполнения
|
|
{
|
|
// Уникальный идентификатор задания
|
|
"execution_id": "01-01",
|
|
// Идентификатор исполняемой программы
|
|
"program": 1,
|
|
// Запрошенный объём напитка
|
|
"volume": "200ml",
|
|
// Ожидаемое время приготовления
|
|
"preparation_time": "20s",
|
|
// Готовность
|
|
"ready": false
|
|
}
|
|
</code></pre>
|
|
<pre><code>POST /cancel
|
|
// Отменяет текущую программу
|
|
</code></pre>
|
|
<pre><code>GET /execution/{execution_id}/status
|
|
// Возвращает статус исполнения
|
|
// Формат аналогичен формату ответа `POST /execute`
|
|
</code></pre>
|
|
<p><em>NB</em>. На всякий случай отметим, что данное API нарушает множество описанных нами принципов проектирования, начиная с отсутствия версионирования; оно приведено в таком виде по двум причинам: (1) чтобы мы могли показать, как спроектировать API более удачно; (2) скорее всего, в реальной жизни вы получите именно такое API от производителей кофе-машин, и это ещё довольно вменяемый вариант.</p></li>
|
|
<li><p>Машины с предустановленными функциями:</p>
|
|
<pre><code>GET /functions
|
|
// Возвращает список доступных функций
|
|
{
|
|
"functions": [
|
|
{
|
|
// Тип операции
|
|
// * set_cup — поставить стакан
|
|
// * grind_coffee — смолоть кофе
|
|
// * shed_water — пролить воду
|
|
// * discard_cup — утилизировать стакан
|
|
"type": "set_cup",
|
|
// Допустимые аргументы для каждой операции
|
|
// Для простоты ограничимся одним аргументом:
|
|
// * volume — объём стакана, кофе или воды
|
|
"arguments": ["volume"]
|
|
},
|
|
…
|
|
]
|
|
}
|
|
</code></pre>
|
|
<pre><code>POST /functions
|
|
{
|
|
"type": "set_cup",
|
|
"arguments": [{ "name": "volume", "value": "300ml" }]
|
|
}
|
|
// Запускает на исполнение функцию
|
|
// с передачей указанных значений аргументов
|
|
</code></pre>
|
|
<pre><code>GET /sensors
|
|
// Возвращает статусы датчиков
|
|
{
|
|
"sensors": [
|
|
{
|
|
// Допустимые значения
|
|
// * cup_volume — объём установленного стакана
|
|
// * ground_coffee_volume — объём смолотого кофе
|
|
// * cup_filled_volume — объём напитка в стакане
|
|
"type": "cup_volume",
|
|
"value": "200ml"
|
|
},
|
|
…
|
|
]
|
|
}
|
|
</code></pre>
|
|
<p><em>NB</em>. Пример нарочно сделан умозрительным для моделирования ситуации, описанной в начале главы: для определения готовности напитка нужно сличить объём налитого с эталоном.</p></li>
|
|
</ul>
|
|
<p>Теперь картина становится более явной: нам нужно абстрагировать работу с кофе-машиной так, чтобы наш «уровень исполнения» в API предоставлял общие функции (такие, как определение готовности напитка) в унифицированном виде. Важно отметить, что с точки зрения разделения абстракций два этих вида кофе-машин сами находятся на разных уровнях: первые предоставляют API более высокого уровня, нежели вторые; следовательно, и «ветка» нашего API, работающая со вторым видом машин, будет более «развесистой».</p>
|
|
<p>Следующий шаг, необходимый для отделения уровней абстракции — необходимо понять, какую функциональность нам, собственно, необходимо абстрагировать. Для этого нам необходимо обратиться к задачам, которые решает разработчик на уровне работы с заказами, и понять, какие проблемы у него возникнут в случае отсутствия нашего слоя абстракции.</p>
|
|
<ol>
|
|
<li>Очевидно, что разработчику хочется создавать заказ унифицированным образом — перечислить высокоуровневые параметры заказа (вид напитка, объём и специальные требования, такие как вид сиропа или молока) — и не думать о том, как на конкретной машине исполнить этот заказ.</li>
|
|
<li>Разработчику надо понимать состояние исполнения — готов ли заказ или нет; если не готов — когда ожидать готовность (и надо ли её ожидать вообще в случае ошибки исполнения).</li>
|
|
<li>Разработчику нужно уметь соотносить заказ с его положением в пространстве и времени — чтобы показать потребителю, когда и как нужно заказ забрать.</li>
|
|
<li>Наконец, разработчику нужно выполнять атомарные операции — прежде всего, отменять заказ.</li>
|
|
</ol>
|
|
<p>Таким образом, наш промежуточный уровень абстракции должен:</p>
|
|
<ul>
|
|
<li>скрывать параметры создания задания на приготовление напитка — их вычисление должно производиться в нашем коде;</li>
|
|
<li>обобщать состояние исполнения в единый набор статусов, не зависящий от физического уровня приготовления напитка;</li>
|
|
<li>связывать параметры заказа (его уникальный идентификатор) с конкретным процессом приготовления напитка;</li>
|
|
<li>предоставлять атомарный интерфейс логических операций, скрывая за фасадом различия в физической имплементации этих операций.</li>
|
|
</ul>
|
|
<p>Первая из проблем, которую мы видим на данном этапе — это отсутствие на физическом уровне машин второго типа самого понятия «заказ» или «напиток»: машина выполняет какой-то набор операций</p>
|
|
<p>Выделение уровней абстракции — прежде всего <em>логическая</em> процедура: как мы объясняем себе и разработчику, из чего состоит наш API. Мы могли бы просто ограничиться выделением секции <code>task</code> в ответе <code>GET /orders/{id}</code> — или вовсе сказать, что <code>task</code> — это просто четверка полей (<code>ready</code>, <code>volume_requested</code>, <code>volume_prepared</code>, <code>readiness_policy</code>) и есть. <strong>Абстрагируемая дистанция между сущностями существует объективно</strong>, каким бы образом мы ни написали конкретные интерфейсы. Наша задача состоит только лишь в том, чтобы эта дистанция была разделена на уровни <em>явно</em>. Чем неявнее разведены уровни абстракции (или хуже того, перемешаны) уровни абстракции, тем сложнее будет разобраться в вашем API и тем хуже будет написан использующий его код.</p>
|
|
<p>NB: важно заметить, что с дальнейшей проработкой уровень исполнения, скорее всего, сам должен будет разделиться на два и более уровня, т.к. «задача» по сути — просто сущность-зонтик, связывающая в рамках заказа несколько высокоуровневых сущностей. Идея определения параметров кофе-машины на этапе создания заказов не очень удобна, да и до манипуляции командами кофе-машины и состоянием сенсоров всё ещё далеко с точки зрения абстрагирования. Но мы пока оставим в таком виде, для удобства дальнейшего изложения.</p>
|
|
<h4 id="">Изоляция уровней абстракции</h4>
|
|
<p>Важное свойство правильно подобранных уровней абстракции, и отсюда требование к их проектированию — это требование изоляции: <strong>взамодействие возможно только между сущностями соседних уровней абстракции</strong>. Если при проектировании выясняется, что для выполнения того или иного действия требуется «перепрыгнуть» уровень абстракции, это явный признак того, что в проекте допущены ошибки.</p>
|
|
<p>Возвращаясь к нашему примеру с готовностью кофе: проблемы с определением готовности кофе исходя из объёма возникают именно потому, что мы не можем ожидать от пользователя, создающего заказ, знания о необходимости проверки объёма налитого реальной кофе-машиной объёма кофе. Мы вводим дополнительный уровень абстракции именно для того, чтобы на нём переформулировать, что такое «заказ готов».</p>
|
|
<p>Важным следствием этого принципа является то, что информацию о готовности заказа нам придётся «прорастить» через все уровни абстракции:</p>
|
|
<ol>
|
|
<li>На физическом уровне мы будем оперировать состоянием кофе-машины, её сенсоров; с точки зрения физических сенсоров нет никакой «готовности заказа», есть только состояние выполнения команд;</li>
|
|
<li>На уровне исполнения статус готовности означает, что состояние сенсоров приведено к эталонному (в случае политики "check_volume" — что налит именно тот объём кофе, который был запрошен);</li>
|
|
<li>На пользовательском уровне статус готовности заказа означает, что все ассоциированные задачи выполнены.</li>
|
|
</ol>
|
|
<p>На каждом уровне абстракции понятие «готовность» переформулируется в терминах нижележащей предметной области, и так вплоть до физического уровня.</p>
|
|
<p>Аналогично нам придётся поступить и с действиями, доступными на том или ином уровне. Если, допустим, в нашем API появится метод отмены заказа <code>cancel</code>, то его придётся точно так же «спустить» по всем уровням абстракции.</p>
|
|
<ul>
|
|
<li><code>POST /orders/{id}/cancel</code> работает с высокоуровневыми данными о заказе:<ul>
|
|
<li>проверяет авторизацию, т.е. имеет ли право этот пользователь отменять этот заказ;</li>
|
|
<li>решает денежные вопросы — нужно ли делать рефанд;</li>
|
|
<li>находит все незавершённые задачи и отменяет их;</li></ul></li>
|
|
<li><code>POST /tasks/{id}/cancel</code> работает с исполнением заказа:<ul>
|
|
<li>определяет, возможно ли физически отменить исполнение, есть ли такая функция у кофе-машины;</li>
|
|
<li>генерирует последовательность действий отмены (возможно, не только непосредственно для самой машины — вполне вероятно, необходимо будет поставить задание сотруднику кофейни утилизировать невостребованный напиток);</li></ul></li>
|
|
<li><code>POST /coffee-machines/{id}/operations</code> выполняет операции на кофе-машине, сгенерированные на предыдущем шаге.</li>
|
|
</ul>
|
|
<p>Обратите также внимание, что содержание операции «отменить заказ» изменяется на каждом из уровней. На пользовательском уровне заказ отменён, когда решены все важные для пользователя вопросы. То, что отменённый заказ какое-то время продолжает исполняться (например, ждёт утилизации) — пользователю неважно. На уровне исполнения же нужно связать оба контекста:</p>
|
|
<ul>
|
|
<li><code>GET /tasks/{id}/status</code><br />
|
|
<code>{"status":"canceled","operation_state":{"status":"canceling","operations":[…]}</code><br />
|
|
— с т.з. высокоуровневого кода задача завершена (<code>canceled</code>), но с точки зрения низкоуровневого кода список исполняемых операций непуст, т.е. задача продолжает работать.</li>
|
|
</ul>
|
|
<p><strong>NB</strong>: так как <code>task</code> связывает два разных уровня абстракции, то и статусов у неё два: внешний <code>canceled</code> и внутренний <code>canceling</code>. Мы могли бы опустить второй статус и предложить ориентироваться на содержание <code>operations</code>, но это (а) неявно, (б) предполагает необходимость разбираться в более низкоуровневом интерфейсе <code>operation_state</code>, что, быть может, разработчику вовсе и не нужно.</p>
|
|
<p>Может показаться, что соблюдение правила изоляции уровней абстракции является избыточным и заставляет усложнять интерфейс. И это в действительности так: важно понимать, что никакая гибкость, логичность, читабельность и расширяемость не бывает бесплатной. Можно построить API так, чтобы оно выполняло свою функцию с минимальными накладными расходами, по сути — дать интерфейс к микроконтроллерам кофе-машины. Однако пользоваться им будет крайне неудобно, и расширяемость такого API будет нулевой.</p><div class="page-break"></div><h3 id="10">Глава 10. Разграничение областей ответственности</h3>
|
|
<p>Исходя из описанного в предыдущей главе, мы понимаем, что иерархия абстракций в нашем гипотетическом проекте должна выглядеть примерно так:</p>
|
|
<ul>
|
|
<li>пользовательский уровень (те сущности, с которыми непосредственно взаимодействует пользователь и сформулированы в понятных для него терминах; например, заказы и виды кофе);</li>
|
|
<li>исполнительный уровень (те сущности, которые отвечают за переформулирование заказа в машинные термины);</li>
|
|
<li>физический уровень (непосредственно сами датчики машины).</li>
|
|
</ul>
|
|
<p>Теперь нам необходимо определить ответственность каждой сущности: в чём смысл её существования в рамках нашего API, какие действия можно выполнять с самой сущностью, а какие — делегировать другим объектам. Фактически, нам нужно применить «зачем-принцип» к каждой отдельной сущности нашего API.</p>
|
|
<p>Для этого нам нужно пройти по нашему API и сформулировать в терминах предметной области, что представляет из себя каждый объект. Напомню, что из концепции уровней абстракции следует, что каждый уровень иерархии — это некоторая собственная промежуточная предметная область, ступенька, по которой мы переходим от описания задачи в терминах одного связываемого контекста («заказанный пользователем лунго») к описанию в терминах второго («задание кофе-машине на выполнение указанной программы»).</p>
|
|
<p>В нашем умозрительном примере получится примерно так:</p>
|
|
<ol>
|
|
<li>Заказ <code>order</code> — описывает некоторую логическую единицу взаимодействия с пользователем. Заказ можно:<ul>
|
|
<li>создавать</li>
|
|
<li>проверять статус</li>
|
|
<li>получать или отменять</li></ul></li>
|
|
<li>Рецепт <code>recipe</code> — описывает «идеальную модель» вида кофе, его потребительские свойства. Рецепт в данном контексте для нас неизменяемая сущность, которую можно только просмотреть и выбрать;</li>
|
|
<li>Задание <code>task</code> — описывает некоторые задачи, на которые декомпозируются заказ;</li>
|
|
<li>Кофе-машина <code>cofee-machine</code> — модель объекта реального мира. Мы можем:<ul>
|
|
<li>получать статусы датчиков</li>
|
|
<li>отправлять команды и проверять их исполнение</li></ul></li>
|
|
</ol>
|
|
<p>Если внимательно посмотреть на каждый объект, то мы увидим, что, в итоге, каждый объект оказался в смысле своей ответственности составным. Например, <code>coffee-machine</code> будет частично оперировать реальными командами кофе-машины <em>и</em> представлять их состояние в каком-то машиночитаемом виде.</p>
|
|
<h4 id="">Декомпозиция интерфейсов</h4>
|
|
<p>На этапе разделения уровней абстракции мы упомянули, что одна из целей такого разделения — добиться возможности безболезненно сменить нижележащие уровни абстракции при добавлении новых технологий или изменении нижележащих протоколов. Декомпозиция интерфейсов — основной инструмент, позволяющий добиться такой гибкости.</p>
|
|
<p>На этом этапе нам предстоит отделить частное от общего: понять, какие свойства сущностей фиксированы в нашей модели, а какие будут зависеть от реализации. В нашем кофе-примере таким сильно зависящим от имплементации объектом, очевидно, будут сами кофе-машины. Попробуем ещё немного развить наше API: каким образом нам нужно описать модели кофе-машин для того, чтобы предоставить интерфейсы для работы с задачами заказа?</p>
|
|
<h4 id="-1">Интерфейсы как универсальный паттерн</h4>
|
|
<p>Как мы убедились в предыдущей главе, выделение интерфейсов крайне важно с точки зрения удобства написания кода. Однако, интерфейсы играют и другую важную роль в проектировании: они позволяют уложить в голове архитектуру API целиком.</p>
|
|
<p>Любой сколько-нибудь крупный API рано или поздно обрастает разнообразной номенклатурой сущностей, их свойст и методов, как в силу того, что в одном объекте «сходятся» несколько предметных областей, так и в силу появления со временем разнообразной вспомогательной и дополнительной функциональности. Особенно сложной номенклатура объектов и их методов становится в случае появления альтернативных реализаций одного и того же интерфейса.</p>
|
|
<p>Человеческие возможности небезграничны: невозможно держать в голове всю номенклатуру объектов. Это осложняет и проектирование API, и рефакторинг, и просто решение возникающих задач по реализации той или иной бизнес-логики.</p>
|
|
<p>Держать же в голове схему взаимодействия интерфейсов гораздо проще - как в силу исключения из рассмотрения разнообразных вспомогательных и специфических методов, так и в силу того, что интерфейсы позволяют отделить существенное (в чем смысл конкретной сущности) от несущественного (деталей реализации).</p>
|
|
<p>Поскольку задача выделения интерфейсов есть задача удобного манипулирования сущностями в голове разработчика, мы рекомендуем при проектировании интерфейсов руководствоваться, прежде всего, здравым смыслом: интерфейсы должны быть ровно настолько сложны, насколько это удобно для человеческого восприятия (а лучше даже чуть проще). В простейших случаях это просто означает, что интерфейс должен содержать семь плюс-минуса два свойства/метода. Более сложные интерфейсы должны декомпозироваться в несколько простых.</p>
|
|
<p>Это правило существенно важно не только при проектировании api - не забывайте, что ваши пользователи неизбежно столкнутся с той же проблемой - понять примерную архитектуру вашего api, запомнить, что с чем связано в вашей системе. Правильно выделенные интерфейсы помогут и здесь, причём сразу в двух смыслах - как непосредственно работающему с вашим кодом программисту, так и документатору, которому будет гораздо проще описать структуру вашего api, опираясь на дерево интерфейсов.</p>
|
|
<p>С другой стороны надо вновь напомнить, что бесплатно ничего не бывает, и выделение интерфейсов - самая «небесплатная» часть процесса разработки API, поскольку в чистом виде приносится в жертву удобство разработки ради построения «правильной» архитектуры: разумеется, код писать куда проще, когда имеешь доступ ко всем объектам API со всей их богатой номенклатурой методов, нежели когда из каждого объекта доступны только пара непосредственно примыкающих интерфейсов, притом с максимально общими методами.</p>
|
|
<p>Помимо прочего, это означает, что интерфейсы необходимо выделять там, где это актуально решаемой задаче - прежде всего, в точках будущего роста и там, где возможны альтернативные реализации. Чем проще API, тем меньше нужда в интерфейсах, и наоборот: сложное API требует интерфейсов практически всюду просто для того, чтобы ограничить разрастание излишне сильной связанности и при этом не сойти с ума.</p>
|
|
<p>В пределе в сложном api должна сложиться ситуация, при которой все объекты взаимодействуют друг с другом только как интерфейсы — нет ни одной публичной сигнатуры, принимающей конкретный объект, а не его интерфейс. Разумеется, достичь такого уровня абстракции практически невозможно - почти в любой системе есть глобальные объекты, разнообразные технические сущности (имплементации стандартных структур данных, например); наконец, невозможно «спрятать» за интерфейсы системные объекты или сущности физического уровня.</p>
|
|
<h4 id="-2">Информационные контексты</h4>
|
|
<p>При выделении интерфейсов и вообще при проектировании api бывает полезно взглянуть на иерархию абстракций с другой точки зрения, а именно: каким образом информация «протекает» через нашу иерархию.</p>
|
|
<p>Вспомним, что одним из критериев отделения уровней абстракции является переход от структур данных одной предметной области к структурам данных другой. В рамках нашего примера через иерархию наших объектов происходит трансляция данных реального мира — «железные» кофе-машины, которые готовят реально существующие напитки — в виртуальные интерфейсы «заказов».</p>
|
|
<p>Если обратиться к правилу «неперепрыгивания» через уровни абстракции, то с точки зрения потоков данных оно формулируется так:</p>
|
|
<ul>
|
|
<li>каждый объект в иерархии абстракций должен оперировать данными согласно своему уровню иерархии;</li>
|
|
<li>преобразованием данных имеют право заниматься только те объекты, в чьи непосредственные обязанности это входит.</li>
|
|
</ul>
|
|
<p>Дерево информационных контекстов (какой объект обладает какой информацией, и кто является транслятором из одного контекста в другой), по сути, представляет собой «срез» нашего дерева иерархии интерфейсов; выделение такого среза позволяет проще и удобнее удерживать в голове всю архитектуру проекта.</p>
|
|
<p>// TODO
|
|
// Хелперы, бойлерплейт</p><div class="page-break"></div><h3 id="11">Глава 11. Описание конечных интерфейсов</h3>
|
|
<p>Определив все сущности, их ответственность и отношения друг с другом, мы переходим непосредственно к разработке API: нам осталось прописать номенклатуру всех объектов, полей, методов и функций в деталях. В этой главе мы дадим сугубо практические советы, как сделать API удобным и понятным.</p>
|
|
<p>Важное уточнение под номером ноль:</p>
|
|
<h4 id="0">0. Правила — это всего лишь обобщения</h4>
|
|
<p>Правила не действуют безусловно и не означают, что можно не думать головой. У каждого правила есть какая-то рациональная причина его существования. Если в вашей ситуации нет причин следовать правилу — значит, следовать ему не надо.</p>
|
|
<p>Например, требование консистентности номенклатуры существует затем, чтобы разработчик тратил меньше времени на чтение документации; если вам <em>необходимо</em>, чтобы разработчик обязательно прочитал документацию по какому-то методу, вполне разумно сделать его сигнатуру нарочито неконсистентно.</p>
|
|
<p>Это соображение применимо ко всем принципам ниже. Если из-за следования правилам у вас получается неудобное, громоздкое, неочевидное API — это повод пересмотреть правила (или API).</p>
|
|
<p>Важно понимать, что вы вольны вводить свои собственные конвенции. Например, в некоторых фреймворках сознательно отказываются от парных методов <code>set_entity</code> / <code>get_entity</code> в пользу одного метода <code>entity</code> с опциональным параметром. Важно только проявить последовательность в её применении — если такая конвенция вводится, то абсолютно все методы API должны иметь подобную полиморфную сигнатуру, или по крайней мере должен существовать принцип именования, отличающий такие комбинированные методы от обычных вызовов.</p>
|
|
<h4 id="1">1. Явное лучше неявного</h4>
|
|
<p>Из названия любой сущности должно быть очевидно, что она делает и к каким сайд-эффектам может привести её использование.</p>
|
|
<ul>
|
|
<li><p>плохо: </p>
|
|
<pre><code>GET /orders/cancellation
|
|
// отменяет заказ
|
|
</code></pre>
|
|
<p>Неочевидно, что достаточно просто обращения к сущности <code>cancellation</code> (что это?), тем более немодифицирующим методом <code>GET</code>, чтобы отменить заказ; </p>
|
|
<p>Хорошо: </p>
|
|
<pre><code>POST /orders/cancel
|
|
отменяет заказ
|
|
</code></pre>
|
|
<ul>
|
|
<li>плохо:</li></ul>
|
|
<pre><code>GET /orders/statistics
|
|
// Возвращает агрегированную статистику заказов за всё время
|
|
</code></pre>
|
|
<p>Даже если операция немодифицирующая, но вычислительно дорогая — следует об этом явно индицировать, особенно если вычислительные ресурсы тарифицируются для пользователя; тем более не стоит подбирать значения по умолчанию так, чтобы вызов операции без параметров максимально расходовал ресурсы.</p>
|
|
<p>Хорошо:</p>
|
|
<pre><code>POST /orders/statistics/aggregate
|
|
{ "start_date", "end_date" }
|
|
// Возвращает агрегированную статистику заказов за указанный период
|
|
</code></pre></li>
|
|
</ul>
|
|
<p><strong>Стремитесь к тому, чтобы из сигнатуры функции было абсолютно ясно, что она делает, что принимает на вход и что возвращает</strong>. Вообще, при прочтении кода, работающего с вашим API, должно быть сразу понятно, что, собственно, он делает — без подглядывания в документацию.</p>
|
|
<p>Два важных следствия:</p>
|
|
<p><strong>1.1.</strong> Если операция модифицирующая, это должно быть очевидно из сигнатуры. В частности, не может быть модифицирующих операций за <code>GET</code>.</p>
|
|
<p><strong>1.2.</strong> Если операция асинхронная, это должно быть очевидно из сигнатуры, <strong>либо</strong> должна существовать конвенция именования, позволяющая отличаться синхронные операции от асинхронных.</p>
|
|
<h4 id="2">2. Сущности должны именоваться конкретно</h4>
|
|
<p>Избегайте слов-«амёб» без определённой семантики, таких как get, apply, make. Сущности должны именоваться конкретно:</p>
|
|
<ul>
|
|
<li>плохо: <code>user.get()</code> — неочевидно, что конкретно будет возвращено;<br />
|
|
хорошо: <code>user.get_id()</code>;</li>
|
|
</ul>
|
|
<h4 id="3">3. Не экономьте буквы</h4>
|
|
<p>В XXI веке давно уже нет нужды называть переменные покороче.</p>
|
|
<ul>
|
|
<li>плохо: <code>order.time()</code> — неясно, о каком времени идёт речь: время создания заказа, время готовности заказа, время ожидания заказа?…<br />
|
|
хорошо: <code>order.get_estimated_delivery_time()</code></li>
|
|
<li>плохо:
|
|
<code>
|
|
strpbrk (str1, str2)
|
|
// возвращает положение первого вхождения в строку str2
|
|
// любого символа из строки str2
|
|
</code>
|
|
Возможно, автору этого API казалось, что аббревиатура <code>pbrk</code> что-то значит для читателя, но он явно ошибся. К тому же, невозможно сходу понять, какая из строк <code>str1</code>, <code>str2</code> является набором символов для поиска.
|
|
Хорошо: <code>str_search_for_characters(lookup_character_set, str)</code><br />
|
|
Однако необходимость существования такого метода вообще вызывает сомнения, достаточно было бы иметь удобную функцию поиска подстроки с нужными параметрами. Аналогично сокращение <code>string</code> до <code>str</code> выглядит совершенно бессмысленным, но, увы, является устоявшимся для большого количества предметных областей.</li>
|
|
</ul>
|
|
<h4 id="4">4. Тип поля должен быть ясен из его названия</h4>
|
|
<p>Если поле называется <code>recipe</code> — мы ожидаем, что его значением является сущность типа <code>Recipe</code>. Если поле называется <code>recipe_id</code> — мы ожидаем, что его значением является идентификатор, который я могу найти в составе сущности <code>Recipe</code>.</p>
|
|
<p>Сущности-массивы должны именоваться во множественном числе или собирательными выражениями — <code>objects</code>, <code>children</code>; если это невозможно (термин неисчисляемый), следует добавить префикс или постфикс, не оставляющий сомнений:</p>
|
|
<ul>
|
|
<li>плохо: <code>GET /news</code> — неясно, будет ли получена какая-то конкретная новость или массив новостей;
|
|
хорошо: <code>GET /news-list</code>.</li>
|
|
</ul>
|
|
<p>Аналогично, если ожидается булево значение, то из названия это должно быть очевидно, т.е. именование должно описывать некоторое качественное состояние, например, <code>is_ready</code>, <code>open_now</code>:</p>
|
|
<ul>
|
|
<li>плохо: <code>"task.status": true</code> — неочевидно, что статус бинарен, плюс такое API будет нерасширяемым;<br />
|
|
хорошо: <code>"task.is_finished": true</code></li>
|
|
</ul>
|
|
<p>Отдельно следует оговорить, что на разных платформах эти правила следует дополнить по-своему с учетом специфики first-class citizen-типов. Например, объекты типа <code>Date</code>, если таковые имеются, разумно индицировать с помощью, например, постфикса <code>_at</code> (<code>created_at</code>, <code>occurred_at</code>, etc) или <code>_date</code>.</p>
|
|
<p>Если наименование сущности само по себе является каким-либо термином, способным смутить разработчика, лучше добавить лишний префикс или постфикс, чтобы избежать непонимания.</p>
|
|
<ul>
|
|
<li>Плохо:
|
|
<code>
|
|
GET /coffee-machines/functions
|
|
// Возвращает список встроенных функций кофе-машины
|
|
</code>
|
|
Слово "functions" многозначное; может означать и встроенные функции, и написанный код, и состояние (функционирует-не функционирует).<br />
|
|
Хорошо: <code>GET /coffee-machines/builtin-functions-list</code></li>
|
|
</ul>
|
|
<h4 id="5">5. Подобные сущности должны называться подобно и вести себя подобным образом</h4>
|
|
<ul>
|
|
<li><p>плохо: <code>begin_transition</code> / <code>stop_transition</code><br />
|
|
— <code>begin</code> и <code>stop</code> — непарные термины; разработчик будет вынужден рыться в документации;<br />
|
|
хорошо: <code>begin_transition</code> / <code>end_transition</code> либо <code>start_transition</code> / <code>stop_transition</code>;</p></li>
|
|
<li><p>плохо: </p>
|
|
<pre><code>strpos(haystack, needle)
|
|
// Находит первую позицию позицию строки `needle`
|
|
// внутри строки `haystack`
|
|
</code></pre>
|
|
<pre><code>str_replace(needle, replace, haystack)
|
|
// Находит и заменяет все вхождения строки `needle`
|
|
// внутри строки `haystack` на строку `replace`
|
|
</code></pre>
|
|
<p>Здесь нарушены сразу несколько правил:</p>
|
|
<ul>
|
|
<li>написание неконсистентно в части знака подчеркивания;</li>
|
|
<li>близкие по смыслу методы имеют разный порядок аргументов <code>needle</code>/<code>haystack</code>; </li>
|
|
<li>первый из методов находит только первое вхождение строки <code>needle</code>, а другой — все вхождения, и об этом поведении никак нельзя узнать из сигнатуры функций.</li></ul>
|
|
<p>Упражнение «как сделать эти интерфейсы хорошо» предоставим читателю.</p></li>
|
|
</ul>
|
|
<h4 id="6">6. Использованные стандарты указывайте явно</h4>
|
|
<p>К сожалению, человечество не в состоянии договориться о таких простейших вещах, как «начинать ли неделю с понедельника или с воскресенья», что уж говорить о каких-то более сложных стандартах.</p>
|
|
<p>Поэтому <em>всегда</em> указывайте, по какому конкретно стандарту вы отдаёте те или иные величины. Исключения возможны только там, где вы на 100% уверены, что в мире существует только один стандарт для этой сущности, и всё население земного шара о нём в курсе.</p>
|
|
<ul>
|
|
<li>Плохо: <code>"date":"11/12/2020"</code> — стандартов записи дат существует огромное количество, плюс из этой записи невозможно даже понять, что здесь число, а что месяц;<br />
|
|
хорошо: <code>"iso_date":"2020-11-12"</code>.</li>
|
|
<li>Плохо: <code>"duration":5000</code> — пять тысяч чего?<br />
|
|
Хорошо:<br />
|
|
<code>"duration_ms":5000</code><br />
|
|
либо<br />
|
|
<code>"duration":"5000ms"</code><br />
|
|
либо<br />
|
|
<code>"duration":{"unit":"ms","value":5000}</code></li>
|
|
</ul>
|
|
<p>Отдельное следствие из этого правила — денежные величины <em>всегда</em> должны сопровождаться указанием кода валюты.</p>
|
|
<p>Также следует отметить, что в некоторых областях ситуация со стандартами настолько плоха, что как ни сделай — кто-то останется недовольным. Классический пример такого рода — порядок геокоординат ("широта-долгота" против "долгота-широта"). Здесь, увы, вам остаётся только смириться и проявлять выдержку при нападках на ваше API.</p>
|
|
<p>// TODO: блокнот душевного спокойствия</p>
|
|
<h4 id="7">7. Сохраняйте точность дробных чисел</h4>
|
|
<p>Там, где это позволено протоколом, дробные числа с фиксированной запятой — такие, как денежные суммы, например — должны передаваться в виде специально предназначенных для этого объектов, например, Decimal или аналогичных.</p>
|
|
<p>Если в протоколе нет Decimal-типов (в частности, в JSON нет чисел с фиксированной запятой), следует либо привести к целому, либо использовать строковый тип.</p><div class="page-break"></div></article>
|
|
</body></html> |