mirror of
https://github.com/twirl/The-API-Book.git
synced 2025-01-23 17:53:04 +02:00
220 lines
46 KiB
HTML
220 lines
46 KiB
HTML
<!doctype html>
|
|
<html><head>
|
|
<meta charset="utf-8"/>
|
|
<title>API</title>
|
|
<style>
|
|
body {
|
|
width: 80%;
|
|
max-width: 1000px;
|
|
margin: 10px auto;
|
|
font-family: Georgia, serif;
|
|
font-size: 16px;
|
|
}
|
|
</style>
|
|
</head><body>
|
|
<h1>API</h1>
|
|
<h2>Об авторе</h2>
|
|
<h2>Введение</h2>
|
|
<p>Если мы посмотрим на определение из энциклопедии, то узнаем, что программирование — это что-то вроде преобразования формально проставленной задачи в исполняемый код, как правило, путём имплементации какого-то алгоритма на определённом языке программирования. И действительно, курсы обучения соответствующим дисциплинам большей частью и состоят из инструкций, как перевести словесно поставленную задачу в код и запрограммировать тот или иной алгоритм.</p>
|
|
<p>Этот алгоритмический подход — пожалуй, худшее, что могло случиться с программистами. Определять программирование через имплементацию алгоритмов — это как определять работу композитора как написание специальных значков на нотном стане, математика — как написание формул, астронома — как смотрение в телескоп.</p>
|
|
<p>Чем плохи эти определения? Тем, что они описывают лишь формальную сторону процесса, оставляя за кадром главный вопрос: зачем? Зачем программисты пишут код, математики - формулы, композиторы - ноты? Математики увеличивают сумму человеческих знаний, композиторы высекают своей музыкой искры из людских сердец, а вот зачем программисты пишут свои алгоритмы?</p>
|
|
|
|
<p>Почему я придаю этому вопросу столь большое значение? Потому что методы решения задачи и использованные инструменты в первую очередь должны быть адекватны используемой задаче, а всё остальное вторично. Именно цель написания кода должна определять такие первичные вещи, как архитектура приложения, используемый язык разработки и выбор инструментария. Я прочитал немалое количество книг по профессиональной разработке программного обеспечения - и не нашел качественного освещения этого вопроса ни в одной из них. Все они рассказывают, как писать "хороший" код - поддерживаемый, расширяемый, безошибочный; но опускают при этом вопрос о том, насколько написание "хорошего" кода адекватно стоящим перед разработчиками целям. Между тем, мировая практика такова, что ставит под большое сомнение предположение, что хороший код означает качественный или хотя бы поддерживаемый и расширяемый продукт. Легко привести множество примеров удачных продуктов, написанных откровенно плохо и с нарушением всех мыслимых заповедей разработки.</p>
|
|
|
|
<p>Хочу ли я тем самым сказать, будто бы нужно писать плохой код? Нет, что вы - на протяжении всей этой книги я буду призывать вас писать хороший код. Я хочу сказать, что, если мы посмотрим на разработку программных продуктов через призму вопроса "зачем" (они разрабатываются), то поймём, что качество решения задач пользователей само по себе не проистекает из следования советам по написанию хорошего кода - это совершенно отдельное качество продукта, и думать о нём также необходимо отдельно.</p>
|
|
|
|
<h3>Об API и уровнях восприятия</h3>
|
|
|
|
<p>У любопытного читателя может возникнуть вопрос: хорошо, мы поняли интенцию относительно соответствия принципов разработки программного обеспечения её целям. При чем же здесь API? Позвольте объяснить.</p>
|
|
|
|
<p>Программирование как трансляция формальной задачи с человеческого языка на машинный — это первый (скорее даже, нулевой) уровень восприятия процесса разработки. Нет алгоритма, который был бы как остров, сам по себе; каждый алгоритм откуда-то берётся и для чего-то предназначен. Иными словами, существует некоторый контекст, в котором будет работать этот небольшой фрагмент программного кода. В первую очередь таким контекстом является программный продукт целиком, в составе которого имплементируется алгоритм.</p>
|
|
|
|
<p>Чем больше, масштабнее и сложнее программный продукт, тем менее важна собственно алгоритмизация конкретной подзадачи и тем более важна архитектура продукта в целом. Правильно ли произведена декомпозиция? Будет ли этот код понятен другому разработчику через несколько лет? Можно ли потом эффективно расширять и поддерживать этот код?</p>
|
|
|
|
<p>Это следующий уровень восприятия проекта: понимание <em>контекста</em> существования конкретного фрагмента кода. На этом уровне появляется понимание того, что интерфейс должен быть сначала спроектирован, и что с ним надо «переспать», т.е. всесторонне обдумать; что «переключение контекстов» — дорогая операция, и что браться за другую задачу в другом проекте, на самом деле, очень сложно, даже если требуется написать всего 10 строчек кода.</p>
|
|
|
|
<p>Но и этот уровень не последний. Помимо контекста внутри программного продукта существует также и ещё более широкий контекст — внешний, в котором живёт сам продукт. Связи внешнего мира с внутренним миром разработки широки и разнообразны: внешний мир определяет функциональность продукта, внешний мир диктует свои правила. Помимо прямой связи существует и обратная: кто-то во внешнем мире будет пользоваться вашим продуктом и, возможно, вашим программным кодом — т.е. вы сами привносите нечто во внешний контекст, и это «нечто» какое-то время будет там жить.</p>
|
|
|
|
<p>API - это ничто иное, как средство связи контекстов. Например, когда вы реализуете какой-то алгоритм — вы используете API языка программирования. Компилятор языка программирования, в свою очередь, использует API команд процессора. Это API, в случае CISC-процессоров, в свою очередь построено поверх ещё более низкоуровнего API микрокоманд; и так далее. Только представьте себе, какое огромное количество API разных уровней должно отработать — и отработать правильно! — для того, чтобы вы смогли, скажем, увидеть страничку в браузере: тут и весь сетевой стек с его 6-7 уровнями абстракции; и серверное ПО — веб-сервер, генерация страницы, база данных, кэш; и клиентское ПО — браузер — имплементирующее буквально десятки разных API.</p>
|
|
|
|
<p>В современном мире роль API трудно преувеличить, и она продолжает расти. Всё новые и новые устройства — от часов и розеток до кораблей и ветряных турбин — включаются в «игру контекстов» и обзаводятся своим API. При этом, к сожалению, качество этих API всё больше оставляет желать лучшего.</p>
|
|
<p>В отличие от прикладного кода, которым будут пользоваться только ваши коллеги, разработка api подразумевает, что вашими программными интерфейсами будут пользоваться другие разработчики. Именно поэтому в разработке api проблемы, описанные в предыдущем разделе, стоят особенно остро. Хорошее api должно одновременно быть и качественно реализовано, и качественно спроектировано с точки зрения предоставляемых интерфейсов.</p>
|
|
|
|
<p>Цель написания этой книги - посмотреть на разработку программного обеспечения под другим углом, дополнить известные принципы разработки программных продуктов принципами разработки api.</p>
|
|
|
|
<h3>Об относительности критериев качества</h3>
|
|
<p>Несмотря на всё написанное выше, я вовсе не призываю вас подходить к каждой задаче с дополнительными наборами требований. Вовсе даже наоборот: я скорее призываю эти требования сокращать.</p>
|
|
|
|
<p>У каждого инструмента, включая и API, есть своя область применимости, и это важно понимать. Допустим, вы пишете, скажем, скрипт импорта данных из Википедии для того, чтобы залить в базу данных вашего продукта какие-то тестовые данные, и вы собираетесь воспользоваться им один раз. В этом случае, очевидно, совершенно неважно, правильная ли у него архитектура и понятен ли его API. Нет, разумеется, вы можете спроектировать и реализовать этот скрипт «правильно», гибко и универсально, чтобы вы могли им гордиться. Но зачем?</p>
|
|
|
|
<p>Любая красота сложна. Правильная архитектура требует больших затрат времени и сил, часто — неоднократного полного переписывания базовых модулей. Правильное API требует времени и сил ещё больше.</p>
|
|
|
|
<p>Понимать, где ваши усилия полезнее и нужнее — пожалуй, не менее важно, чем их (усилий) приложение.</p>
|
|
|
|
<p>Эти вещи кажутся очевидными на простых примерах; со сложными же проектами, поверьте, то же самое. Достоинства и недостатки любой методологии, как правило, отлично известны, однако редко когда выбор конкретного фреймворка, паттерна или подхода опирается на анализ соответствия их достоинств и недостатков проекту.</p>
|
|
|
|
<p>Есть ещё один момент, который хочется подчеркнуть: инструменты должны соответствовать конкретным обстоятельствам — предметной области, планируемому жизненному циклу продукта и, что немаловажно, компетенциям команды. Во многих случаях неидеальный инструмент, с которым команда привыкла работать, предпочтительнее неидеального, который придётся осваивать по ходу.</p>
|
|
|
|
<h3>API как универсальный паттерн</h3>
|
|
|
|
<p>На фоне сказанного выше этот заголовок должен вызывать некоторые сомнения. Универсального паттерна не существует, разве нет?</p>
|
|
|
|
<p>Тем не менее, API таковым паттерном является. Чтобы пояснить этот парадокс, давайте для начала поймём, что такое API.</p>
|
|
|
|
<p>В первом разделе мы говорили о том, что API — это связь, интерфейс взаимодействия двух программируемых контекстов. Вспомним, что мы живём в мире, очень сильно завязанном на правильное взаимодействие целых иерархий таких контекстов. Что же тогда самое важное, что такое API по смыслу?</p>
|
|
|
|
<p>API — это обязательство. Обязательство поддерживать связь контекстов. Всё остальное вторично.</p>
|
|
|
|
<h3>О структуре этой книги</h3>
|
|
|
|
<p>Книга, которую вы держите в руках, состоит из трех больших разделов, назовем их условно "статическим", "динамическим" и "маркетинговым".</p>
|
|
|
|
<p>В первом разделе мы поговорим о проектировании api на стадии разработки концепции - как грамотно выстроить архитектуру, от крупноблочного планирования до конечных интерфейсов.</p>
|
|
|
|
<p>Второй раздел будет посвящён жизненному циклу api - как интерфейсы эволюционируют со временем и как развивать продукт так, чтобы отвечать потребностям пользователей.</p>
|
|
|
|
<p>Наконец, третий раздел будет касаться больше не-разработческих сторон жизни api - поддержки, маркетинга, достижения контакта с аудиторией.</p>
|
|
|
|
<p>Первые два будут интересны скорее разработчикам, третий - и разработчикам, и менеджерам. При этом я настаиваю, что как раз третий раздел - самый важный для разработчика api. Ввиду того, что api - продукт для разработчиков, перекладывать ответственность за его маркетинг и поддержку на не-разработчиков неправильно: никто кроме вас самих не понимает так хорошо продуктовые свойства вашего api.</p>
|
|
|
|
<h2>Проектирование API</h2>
|
|
|
|
<p>Подход, который мы используем для проектирования, состоит из четырёх шагов:</p>
|
|
|
|
<ul>
|
|
<li>определение области применения;</li>
|
|
<li>разделение уровней абстракции;</li>
|
|
<li>разграничение областей ответственности;</li>
|
|
<li>Описание конечных интерфейсов.</li>
|
|
</ul>
|
|
|
|
<p>Этот алгоритм строит api сверху вниз, от общих требований и сценариев использования до конкретной номенклатуры сущностей; фактически, двигаясь этим путем, вы получите на выходе готовое api - за что мы и ценим этот подход.</p>
|
|
|
|
<p>Поскольку я являюсь убеждённым приверженцем практического подхода, здесь и далее я буду рассматривать проектирование api на конкретных примерах. В качестве такого примера я выбрал гипотетическое api некоей метеорологической службы. На всякий случай, предупрежу заранее, что пример является выдуманным от начала до конца; если бы мне предложили заниматься таким api в реальности - я бы прежде всего потратил время на детальное исследование предметной области, и наверняка пришёл бы совсем к другим решениям в итоге. Но для наших учебных целей такой умозрительный пример вполне допустим, поскольку я ставлю своей целью, прежде всего, объяснение того, как надо думать и не стремлюсь вложить в голову читателя какие-то конкретные решения и рецепты успеха.</p>
|
|
|
|
<h3>Определение области применения</h3>
|
|
|
|
<p>Первый вопрос, на который мы должны ответить, принимая решение о разработке api - "зачем?" Кто и как будет пользоваться нашей программной связью контекстов?</p>
|
|
|
|
<p>Рассмотрим следующий пример. Допустим, мы умеем предсказывать погоду и располагаем возможностью предоставлять данные о погоде в машиночитаемом виде. Стоит ли нам разрабатывать api? Давайте подумаем.</p>
|
|
|
|
<p>Во-первых, необходимо понять, какую такую функциональность мы можем предоставлять потребителям, что они воспользуются api, а не будут разрабатывать сами?</p>
|
|
|
|
<p>По возрастанию сложности самостоятельной реализации такого функционала это будут: получение информации о текущей погоде; получение информации о прогнозе; получение информации о климате какой-то местности; получение информации о "внутреннем устройстве" предметной области - зоны высокого и низкого давления, атмосферные фронты и их движение. </p>
|
|
|
|
<p>Зачем такого рода функциональность может понадобиться? Вот несколько очевидных ответов:</o>
|
|
|
|
<ul><li>конечным пользователям - чтобы понять, нужно ли сегодня брать зонтик и куда можно съездить отдохнуть в ноябре;</li>
|
|
<li>компаниям, бизнес которых зависит от погоды - например, авиаперевозчикам.</li></ul>
|
|
|
|
<p>Для удовлетворения первой группы потребностей потребители будут сами приходить на ресурсы, принадлежащие нашим потенциальным клиентам - популярные локальные веб-сайты (например, на городские порталы за краткосрочным прогнозом погоды или на туристические агрегаторы за информацией о климате) или разного рода приложения для "умных" устройств (телефонов, часов, планшетов, телевизоров и даже домов) или специализированные новостные ресурсы. Вторую группу потребностей будут закрывать компании, производящие программное обеспечение для диспетчерских служб - либо, возможно, проприетарные решения самих транспортных компаний.</p>
|
|
|
|
<p>Допустим мы исследовали и рынок, и собственные технические ресурсы и пришли к выводу, что (а) мы готовы эту функциональность предоставлять, (б) пользователям она необходима и (в) мы способны извлечь для себя какую-то выгоду из предоставления такого api (подробнее обо всем этом я расскажу в третьем разделе). Тем самым мы обозначили пункт "что" - какую функциональность мы физически можем предоставить и зачем.</p>
|
|
|
|
<p>Следующий этап - описание пользовательских сценариев. Ответив на вопросы "что" и "зачем", нужно теперь описать ответ на вопрос "как" - как потребители api будут им пользоваться.</p>
|
|
|
|
<p>Очевидное решение, которое приходит в голову сразу - это выполнить наше api в виде веб-сервиса: разработчик обращается по сформированному определённым образом url и получает погодную информацию. В общем-то, всю имеющуюся у нас информацию можно через такой сервис предоставлять; он будет универсален - такое обращение можно реализовать на любой платформе, и, таким образом, оно покроет все кейсы. Разве нет?</p>
|
|
|
|
<p>Теперь давайте подойдём к вопросу с другой стороны. А как было бы удобно пользоваться нашим api, скажем, веб-мастеру-администратору небольшого локального форума? Скорее всего, ему требуется решение, которое не требует навыков разработки, чтобы было достаточно мышкой нащёлкать параметры информатора о прогнозе погоды. Нет, мы можем, конечно презрительно отмахнуться от таких непрофессионалов; но, тем самым, мы лишим сами себя значительной доли рынка.</p>
|
|
|
|
<p>Аналогично, если мы посмотрим на потребности крупных диспетчерских компаний, то мы, вероятно, выясним, что у них уже есть какое-то автоматизированной рабочее место диспетчера, и идеальным для них решением был бы набор компонентов, которые можно интегрировать в их программный комплекс. Аналогично, у новостных ресурсов также есть какое-то готовое решение для управления контентом, и они предпочтут не заказывать дорогостоящую разработку модуля визуализации погоды, а готовое решение.</p>
|
|
|
|
<p>Иными словами, в начале разработки api перед нами всегда стоит вопрос: насколько приближено оно должно быть к конечному пользователю? Чем более высок уровень вашего api, чем проще оно позволяет реализовать пользовательские сценарии - тем более интересно оно будет разработчикам, но тем дороже оно обойдётся вам самим. Понятно, что невозможно написать модули и компоненты для всех существующих cms и фреймворков, и вам придётся где-то остановиться - исходя из ваших представлений о массовости тех или иных кейсов. Вполне возможно, что в нашей гипотетической ситуации мы в итоге можем прийти к решению делать только http api, так как выясним, что получим от виджетов меньше дохода, чем потратим на разработку, а у каждого из крупных клиентов есть свой отдел разработки и они не доверяют в business-critical задачах разработкам сторонних компаний.</p>
|
|
|
|
<p>Однако, чтобы нам было, о чем говорить в дальнейших разделах, предположим, что мы решили закрывать следующие сценарии:</p>
|
|
|
|
<ul><li>общее http api для клиентов, готовых вести разработку самостоятельно;</li>
|
|
<li>набор виджетов для мобильных и веб-приложений;</li>
|
|
<li>набор компонентов для встраивания в АРМы диспетчерских компаний.</li></ul>
|
|
|
|
<p>Перейдём теперь непосредственно к проектированию api.</p>
|
|
|
|
<h3>Уровни абстракции</h3>
|
|
|
|
<p>"Разделите свой код на уровни абстракции" - пожалуй, самый общий совет для разработчиков программного обеспечения. Что под этим обычно подразумевается?</p>
|
|
|
|
<p>Вспомним, что программный продукт - это средство связи контекстов, средство преобразования терминов и операций одной предметной области в другую. Чем дальше друг от друга эти области отстоят - тем большее число промежуточных контекстов можно ввести. Например, модель OSI, которую часто приводят как эталон разделения уровней абстракции, насчитывает семь промежуточных этапов по дороге от аппаратного обеспечения к протоколам уровня приложений.</p>
|
|
|
|
<p>Если говорить о разделении уровней абстракции именно с точки зрения api, то оно очень желательно по нескольким причинам:</p>
|
|
|
|
<ul><li>Разделение проекта на несколько независимых частей; архитектура каждой из них, таким образом, становится проще, и упрощается интеграция;</li>
|
|
<li>с помощью такого разделения гораздо легче добиваться кроссплатформенности путём отделения платформо-зависимой логики в отдельный уровень (или уровни) абстракции.</li></ul>
|
|
<p>И главное:</p>
|
|
<ul><li>Упрощается задача для ваших клиентов; правильно разделённые уровни абстракции означают, что разработчикам не придется разбираться со всей номенклатурой сущностей вашего api - им достаточно будет работать только с объектами высокого уровня, отвечающими непосредственно за решение их задач.</li></ul>
|
|
|
|
<p>Если мы вернёмся к нашему примеру с погодным api, то увидим, что один уровень абстракции выделился автоматически: http api. Мы можем построить прочие виды api поверх базового http. Можем ли мы выделить ещё какие-то уровни, скажем, внутри самого http api?</p>
|
|
|
|
|
|
<!--
|
|
<h2>О проектировании API</h2>
|
|
<h3>Архитектура против реализации</h3>
|
|
<p>Поскольку API — обязательство, то к качеству его реализации предъявляются, как правило, повышенные требования — во-первых, в силу важности API как инструмента для бизнес-логики потребителей; во-вторых, в силу того, что ошибка в API может привести к гораздо более разрушительным последствиям, чем ошибка в end-user интерфейсе.</p>
|
|
<p></p>
|
|
<p>Попробуем объяснить на конкретном примере. Допустим, мы располагаем огромным и хорошо структурированным сервисом, предоставляющем метаинформацию, скажем, о . (Лично я никогда не делал подобных сервисов, но уже много лет испытываю в них нужду.)</p>
|
|
<p><em>Зачем</em> такому сервису API?</p>
|
|
<p>Чтобы люди могли написать свои новые-кленовые аудиоплееры, использующие ваш сервис? Вряд ли.</p>
|
|
- решать проблемы
|
|
- не делать конкурентов самому себе (если ты не амазон)
|
|
- множество разнородных задач:
|
|
- сделать хорошо конечному пользователю
|
|
- сделать хорошо разработчику
|
|
<h3>О неважности кода</h3>
|
|
- в правильном апи любой код заменяем и он неважен
|
|
<h3>Уровни абстракции</h3>
|
|
< p>Концепция уровней абстракции довольно широко известна. Классическим примером разделения уровней является, скажем, модель OSI, описывающая 7 уровней сетевых взаимодействий.</p>
|
|
<p>К сожалению, в реальных системах выделить уровни абстракции гораздо сложнее, нежели в таких чистых случаях; множество успешных и существующих API и вовсе не оперируют такими терминами. Классический случай — веб-платформа, в которой правильное разделение абстракций фактически никогда не существовало, и лишь Extensible Web Manifesto впервые постулировал необходимость не экстенсивно наращивать номенклатуру методов, а строить иерархию абстракций.</p>
|
|
<p>Связано это, по-видимому, со сложностью подобного разделения в абсолютном большинстве предметных областей. Классический алгоритм «берём все объекты и разбиваем их на слои» в реальном мире работает очень слабо: всегда есть сущности, которые не ложатся в иерархию, будучи либо чересчур глобальными, либо, напротив, чересчур утилитарными.</p>
|
|
<p>Тем не менее, говорить об иерархии абстракций можно и нужно.</p>
|
|
<h4>Иерархия кейсов</h4>
|
|
<p>Самый простой из критериев деления уровней абстракции — это отделение сущностей, работающих в терминах, понятных конечному пользователю, от сущностей, понятных лишь разработчику. Такое дерево объектов можно построить даже для столь неструктурированной платформы, как веб: высший уровень абстракции реализуют те объекты, которые напрямую взаимодействуют с пользователем — скажем, интерфейс HTMLAudioElement. Методы, как play(), pause(), свойство controls — напрямую соответствуют конкретным кейсам использования сущности пользователем. Напротив, базовые сущности низкоуровневого WebAudio API — аудио буферы и потоки данных — для непрограммиста никакого интереса не представляют.</p>
|
|
<p>«Абстрактность» при таком подходе означает иерархию кейсов: есть набор кейсов пользователя (проиграть видео, поставить на паузу, прибавить громкость), которые покрываются сущностями верхнего уровня; однако верхний уровень иерархии, таким образом, сам предъявляет некоторый набор кейсов: обеспечить воспроизведение из некоторого источника, обеспечить микширование данных, обеспечить синхронизацию, встроить плеер в определённое место на странице — которым будет удовлетворять следующий «слой» иерархии — аудиоконтексты в WebAudio API и методы работы с DOM-деревом. Процесс, таким образом, можно повторять итеративно вплоть до «железа».</p>
|
|
<p>Что важно, этот подход работает не только для API, предоставляющих некоторые интерфейсы взаимодействия с конечным пользователем. Даже API доступа к базе данных, таким образом, хорошо разбивается на уровни абстракции, исходя из кейсов использования API.</p>
|
|
<h4>Иерархия знаний</h4>
|
|
<p>Уровни абстракций можно выделять и снизу вверх: самыми низкоуровневыми сущностями объявляются те, которые работают в терминах нижележащей платформы. Интерфейсы, оперирующие байтами, буферами и флагами — самые примитивные. Чем более специфичный, т.е. требующий знаний об устройстве платформы, код требуется написать — тем ниже уровень абстракции. Напротив, объекты, интерфейс которых не содержит никаких знаний о среде исполнения, образуют верхний уровень. В том же примере с аудио в вебе: сущности, работающие напрямую с «сырыми» данными — аудио буферы — низкоуровневые. Сущности, оперирующие буферами — различные операции над звуком — стоят чуть выше: чтобы работать с ними, уже не нужно знать о разрядности или частоте дискретизации. Ещё чуть выше — функциональность группировки операций и аудио контексты; и так далее. На вершине пирамиды — HTMLAudioElement, интерфейс которого не содержит никаких знаний и легко может быть быть применён не к воспроизведению звука в вебе, а, скажем, к API патефона, если кто-то вдруг задумает его сделать.</p>
|
|
<p>Иными словами, тот объект выше, интерфейс которого не поменяется, если вся нижележащая логика полностью изменится вплоть до смены платформы и физических принципов работы.</p>
|
|
<h3>Информационный контекст</h3>
|
|
<p>Как альтернативу традиционному разделению на уровни абстракции можно рассмотреть вашу иерархию сущностей с точки зрения информации, которая через эту иерархию протекает. Любое API, в конечном счёте, предоставляет доступ к некоторой информации.</p>
|
|
<p></p>
|
|
<h3>Code style</h3>
|
|
— "так здесь принято" vs здравый смысл
|
|
<h3>Именование</h3>
|
|
<p>Если говорить и чисто программной составляющей API, то, пожалуй, именно именование важнее всего. Всё остальное, в конечном счёте, можно подправить или переписать, но вот номенклатура сущностей — это лицо вашего API, это фасад, с которым будет работать ваш пользователь.</p>
|
|
<p>Первое и важнейшее правило именования весьма просто: имя сущности должно понятно и однозначно описывать смысл этой сущности. Имя метода должно показывать, какие действия произойдут при вызове этого метода; имя поля — какой объект хранится в этом поле; имя класса — что из себя будет представлять экземпляр этого класса; и так далее.</p>
|
|
— делать именно то, что нужно
|
|
— сайдэффекты
|
|
- build и update
|
|
<h3>Тестирование</h3>
|
|
<p>Тесты обязаны быть в любом API; это, в общем, вытекает из определения API.</p>
|
|
<p>Вместе с тем, </p>
|
|
— покрытие в зависимости от проекта
|
|
<h3>Workflow</h3>
|
|
— эджайл vs здравый смысл
|
|
<h3>Версионирование</h3>
|
|
- зачем?
|
|
- semver
|
|
<h3>Уровни абстракции</h3>
|
|
- как?
|
|
- подход "от железа"
|
|
<h3>Интерфейсы</h3>
|
|
- зачем?
|
|
- 5 плюс минус 2
|
|
- объект в разных разрезах
|
|
<h3>Связность</h3>
|
|
<h4>Code reuse</h4>
|
|
- хороший копипаст
|
|
- плохой копипаст
|
|
<h4>Модульность</h4>
|
|
<h4>События</h4>
|
|
<h4>Паттерны</h4>
|
|
<h2>О видении продукта</h2>
|
|
<h3>Стабильность</h3>
|
|
<h3>Точки расширения</h3>
|
|
<h3>Внешние зависимости</h3>
|
|
<h3>Управление процессом</h3>
|
|
<p>Дело в том, что разработчик API, по определению, обладает относительно полным знанием о том, как API устроено, какие в нём есть крутые фишки и какие сложные задачи оно способно решать.</p>
|
|
<p>В реальности же 90%, если не больше, обращающихся за поддержкой пользователей будут решать совершенно тривиальные задачи и у них в принципе нет никакой мотивации разбираться с внутренним устройством API. Пользователь хочет решить свою задачу с наименьшим напряжением сил, и было бы странным его за это упрекать.</p>
|
|
<p>Люди не читают документацию. Не ищут ответов на свои вопросы на StackOverflow. Не являются гуру разработки. Даже напротив, абсолютное большинство ваших клиентов — начинающие и просто малоквалифицированные специалисты. Даже если вашим API пользуются ребята из соседнего отдела, квалификация которых не уступает вашей, — вряд ли даже у них есть желание глубоко разбираться в вашей архитектуре.</p>
|
|
<p>Поэтому любой поток обращений, как правило, делится на две неравные категории: вопросы от начинающих (часто глупые или тривиальные) и очень редкие запросы от профессионалов. Запросов первого типа абсолютное большинство, и, при том, найти проблему в коде пользователя частенько бывает весьма нетривиальной задачей.</p>
|
|
-->
|
|
</body></html>
|