Если мы посмотрим на определение из энциклопедии, то узнаем, что программирование — это что-то вроде преобразования формально проставленной задачи в исполняемый код, как правило, путём имплементации какого-то алгоритма на определённом языке программирования. И действительно, курсы обучения соответствующим дисциплинам большей частью и состоят из инструкций, как перевести словесно поставленную задачу в код и запрограммировать тот или иной алгоритм.
Этот алгоритмический подход — пожалуй, худшее, что могло случиться с программистами. Определять программирование через имплементацию алгоритмов — это как определять работу композитора как написание специальных значков на нотном стане, математика — как написание формул, астронома — как смотрение в телескоп.
Разумеется, написание кода — неотъемлемая часть процесса программирования. Но позвольте мне высказаться резко: это наименее важная и наиболее простая часть работы программиста. К сожалению, реальность такова, что множество людей, так или иначе связанных с программированием — включая самих программистов и их непосредственное руководство, — этого не понимают. Результат — огромное количество откровенно плохих, неудобных, небезопасных и дырявых как решето приложений, которые окружают человека в XXI веке.
Программирование как трансляция формальной задачи с человеческого языка на машинный — это лишь первый (скорее даже, нулевой) уровень восприятия процесса разработки. Нет алгоритма, который был бы как остров, сам по себе; каждый алгоритм откуда-то берётся и для чего-то предназначен. Иными словами, существует некоторый контекст, в котором будет работать этот небольшой фрагмент программного кода. В первую очередь таким контекстом является программный продукт целиком, в составе которого имплементируется алгоритм.
Чем больше, масштабнее и сложнее программный продукт, тем менее важна собственно алгоритмизация конкретной подзадачи и тем более важна архитектура продукта в целом. Правильно ли произведена декомпозиция? Будет ли этот код понятен другому разработчику через несколько лет? Можно ли потом эффективно расширять и поддерживать этот код?
Это следующий уровень восприятия проекта: понимание контекста существования конкретного фрагмента кода. На этом уровне появляется понимание того, что интерфейс должен быть сначала спроектирован, и что с ним надо «переспать», т.е. всесторонне обдумать; что «переключение контекстов» — дорогая операция, и что браться за другую задачу в другом проекте, на самом деле, очень сложно, даже если требуется написать всего 10 строчек кода.
Но и этот уровень не последний. Помимо контекст продукта существует также и ещё более широкий контекст — внешний, в котором живёт сам продукт. Связи внешнего мира с внутренним миром разработки широки и разнообразны: внешний мир определяет функциональность продукта, внешний мир диктует свои правила. Помимо прямой связи существует и обратная: кто-то во внешнем мире будет пользоваться вашим продуктом и, возможно, вашим программным кодом — т.е. вы сами привносите нечто во внешний контекст, и это «нечто» какое-то время будет там жить.
Существуют ли иные, более масштабные уровни восприятия — наверняка хочет поинтересоваться пытливый читатель. Мне, во всяком случае, о них неизвестно; если что, я напишу о них в следующем, исправленном и дополненном, издании.
Свою задачу как автора этой книги я вижу в том, чтобы помочь вам мыслить на более высоких уровнях понимания. «При чём же здесь тогда API?» — наверняка удивится пытливый читатель.
При том, что API это ничто иное, как средство связи контекстов. Например, когда вы реализуете какой-то алгоритм — вы используете API языка программирования. Компилятор языка программирования, в свою очередь, использует API команд процессора. Это API, в случае CISC-процессоров, в свою очередь построено поверх ещё более низкоуровнего API микрокоманд; и так далее. Только представьте себе, какое огромное количество API разных уровней должно отработать — и отработать правильно! — для того, чтобы вы смогли, скажем, увидеть страничку в браузере: тут и весь сетевой стек с его 6-7 уровнями абстракции; и серверное ПО — веб-сервер, генерация страницы, база данных, кэш; и клиентское ПО — браузер — имплементирующее буквально десятки разных API.
В современном мире роль API трудно преувеличить, и она продолжает расти. Всё новые и новые устройства — от часов и розеток до кораблей и ветряных турбин — включаются в «игру контекстов» и обзаводятся своим API. При этом, к сожалению, качество этих API всё больше оставляет желать лучшего.
Именно эти соображения и побудили меня написать эту книгу. Разработка хорошего API требует, во-первых, определённого системного мышления; а, во-вторых, понимания того, что API — это не просто какой-то командный код, но и большая ответственность. Я надеюсь, что с помощью этой книги окружающие меня API станут чуть лучше.
Несмотря на всё написанное выше, я вовсе не призываю вас подходить к каждой задаче глобально; чрезмерное переусложнение ничуть не лучше чрезмерного упрощения.
У каждого инструмента, включая и API, есть своя область применимости, и это важно понимать. Допустим, вы пишете, скажем, скрипт импорта данных из Википедии для того, чтобы залить в базу данных вашего продукта какие-то тестовые данные, и вы собираетесь воспользоваться им один раз. В этом случае, очевидно, совершенно неважно, правильная ли у него архитектура и понятен ли его API. Нет, разумеется, вы можете спроектировать и реализовать этот скрипт «правильно», гибко и универсально, чтобы вы могли им гордиться. Но зачем?
Любая красота сложна. Правильная архитектура требует больших затрат времени и сил, часто — неоднократного полного переписывания базовых модулей. Правильное API требует времени и сил ещё больше.
Понимать, где ваши усилия полезнее и нужнее — пожалуй, не менее важно, чем их (усилий) приложение.
Этот принцип, в общем и целом, относится не только к архитектуре и красоте кода, но и ко многим другим вещам. Применение любого паттерна, любого принципа разработки имеет свою стоимость — и, к сожалению, мало кто всерьёз берётся анализировать эту стоимость до начала разработки.
Например, бессмысленно примернять MVC-подход к вашему скрипту. Нет, конечно, можно, но зачем? Накладные расходы на описание моделей и представлений, будут разменены на что?
Бессмысленно пытаться внедрять и agile или waterfall практики. Зачем и для чего нужны переоценки и анализы требований для скрипта, который один раз отработает и будет забыт?
Более того, применение даже таких базовых принципов, как, скажем, ООП для этой задачи вовсе не выглядит обоснованным.
Эти вещи кажутся очевидными на простых примерах; со сложными же проектами, поверьте, то же самое. Достоинства и недостатки любой методологии, как правило, отлично известны, однако редко когда выбор конкретного фреймворка, паттерна или подхода опирается на анализ соответствия их достоинств и недостатков проекту.
Есть ещё один момент, который хочется подчеркнуть: инструменты должны соответствовать конкретным обстоятельствам — предметной области, планируемому жизненному циклу продукта и, что немаловажно, компетенциям команды. Во многих случаях неидеальный инструмент, с которым команда привыкла работать, предпочтительнее неидеального, который придётся осваивать по ходу.
На фоне сказанного выше этот заголовок должен вызывать некоторые сомнения. Универсального паттерна не существует, разве нет?
Тем не менее, API таковым паттерном является. Чтобы пояснить этот парадокс, давайте для начала поймём, что такое API.
В первом разделе мы говорили о том, что API — это связь, интерфейс взаимодействия двух программируемых контекстов. Вспомним, что мы живём в мире, очень сильно завязанном на правильное взаимодействие целых иерархий таких контекстов. Что же тогда самое важное, что такое API по смыслу?
API — это обязательство. Обязательство поддерживать связь контекстов. Всё остальное вторично.
Поэтому любой сложный проект требует как минимум внутреннего API. Невозможно разработать что-то сложнее скрипта импорта данных, исполняемого один раз, без предоставления некоторых обязательств.
Надо понимать, что ничего бесплатного не существует. Написание продукта как API требует существенно больших затрат, и, разумеется, для многих проектов эти затраты никогда не окупятся. С другой стороны, и преуменьшать ценность API не стоит: поддержание взятых на себя обязательств — гигантское конкурентное преимущество в современном мире.
Решение «API-зации» того или иного функционала — также всецело вопрос баланса; это всегда размен времени и сил сейчас на стабильный и поддерживаемый код в будущем.
При этом, надо сразу оговорить, что наличие API вовсе не гарантирует отсутствие ошибок в коде (или хотя бы меньшее их количество); код, написанный как API, при прочих равных будет скорее содержать больше ошибок вследствие избыточности интерфейсов. Основная цель написания API — добиться стабильной, поддерживаемой и расширяемой архитектуры, которая способна покрыть все потребности пользователя.
Итак, API — это механизм связывания программируемых контекстов и обязательство поддерживать эту связь. Из чего же состоит это связывание и эта поддержка?
Понятно, что API имеет некоторую программную составляющую, иначе зачем бы оно было кому-то нужно. Но, исходя из вышесказанного, очевидно, что сам программный интерфейс — это далеко не всё.
Прежде всего, API обязано обладать некоторой гарантированной стабильностью. Это — ключевое свойство, без него API лишено смысла.
Во-вторых, API должно быть понятно пользователям. Это касается как архитектуры интерфейсов, т.е. номенклатуры программных сущностей, так и публичной документации. API без документации не существует так же, как и без программного кода.
В-третьих, помимо документации, должна осуществляться поддержка пользователей: решение их проблем и обратная связь. Идеальных API не существует, всегда есть какой-то поток вопросов и проблем.
И то, и другое, и третье кажется, на первый взгляд, понятным. Однако, когда теория сталкивается с практикой, часто оказывается, что разработчики API уделяют непростительно мало внимания этим проблемам.
Если попытаться одной фразой описать основной принцип проектирования API, то можно ограничиться отним словом «зачем» и вопросительным знаком.
Попробуем объяснить на конкретном примере. Допустим, мы располагаем огромным и хорошо структурированным сервисом, предоставляющем метаинформацию, скажем, о . (Лично я никогда не делал подобных сервисов, но уже много лет испытываю в них нужду.)
Зачем такому сервису API?
Чтобы люди могли написать свои новые-кленовые аудиоплееры, использующие ваш сервис? Вряд ли.
- решать проблемы - не делать конкурентов самому себе (если ты не амазон) - множество разнородных задач: - сделать хорошо конечному пользователю - сделать хорошо разработчикуКонцепция уровней абстракции довольно широко известна. Классическим примером разделения уровней является, скажем, модель OSI, описывающая 7 уровней сетевых взаимодействий.
К сожалению, в реальных системах выделить уровни абстракции гораздо сложнее, нежели в таких чистых случаях; множество успешных и существующих API и вовсе не оперируют такими терминами. Классический случай — веб-платформа, в которой правильное разделение абстракций фактически никогда не существовало, и лишь Extensible Web Manifesto впервые постулировал необходимость не экстенсивно наращивать номенклатуру методов, а строить иерархию абстракций.
Связано это, по-видимому, со сложностью подобного разделения в абсолютном большинстве предметных областей. Классический алгоритм «берём все объекты и разбиваем их на слои» в реальном мире работает очень слабо: всегда есть сущности, которые не ложатся в иерархию, будучи либо чересчур глобальными, либо, напротив, чересчур утилитарными.
Тем не менее, говорить об иерархии абстракций можно и нужно.
Самый простой из критериев деления уровней абстракции — это отделение сущностей, работающих в терминах, понятных конечному пользователю, от сущностей, понятных лишь разработчику. Такое дерево объектов можно построить даже для столь неструктурированной платформы, как веб: высший уровень абстракции реализуют те объекты, которые напрямую взаимодействуют с пользователем — скажем, интерфейс HTMLAudioElement. Методы, как play(), pause(), свойство controls — напрямую соответствуют конкретным кейсам использования сущности пользователем. Напротив, базовые сущности низкоуровневого WebAudio API — аудио буферы и потоки данных — для непрограммиста никакого интереса не представляют.
«Абстрактность» при таком подходе означает иерархию кейсов: есть набор кейсов пользователя (проиграть видео, поставить на паузу, прибавить громкость), которые покрываются сущностями верхнего уровня; однако верхний уровень иерархии, таким образом, сам предъявляет некоторый набор кейсов: обеспечить воспроизведение из некоторого источника, обеспечить микширование данных, обеспечить синхронизацию, встроить плеер в определённое место на странице — которым будет удовлетворять следующий «слой» иерархии — аудиоконтексты в WebAudio API и методы работы с DOM-деревом. Процесс, таким образом, можно повторять итеративно вплоть до «железа».
Что важно, этот подход работает не только для API, предоставляющих некоторые интерфейсы взаимодействия с конечным пользователем. Даже API доступа к базе данных, таким образом, хорошо разбивается на уровни абстракции, исходя из кейсов использования API.
Уровни абстракций можно выделять и снизу вверх: самыми низкоуровневыми сущностями объявляются те, которые работают в терминах нижележащей платформы. Интерфейсы, оперирующие байтами, буферами и флагами — самые примитивные. Чем более специфичный, т.е. требующий знаний об устройстве платформы, код требуется написать — тем ниже уровень абстракции. Напротив, объекты, интерфейс которых не содержит никаких знаний о среде исполнения, образуют верхний уровень. В том же примере с аудио в вебе: сущности, работающие напрямую с «сырыми» данными — аудио буферы — низкоуровневые. Сущности, оперирующие буферами — различные операции над звуком — стоят чуть выше: чтобы работать с ними, уже не нужно знать о разрядности или частоте дискретизации. Ещё чуть выше — функциональность группировки операций и аудио контексты; и так далее. На вершине пирамиды — HTMLAudioElement, интерфейс которого не содержит никаких знаний и легко может быть быть применён не к воспроизведению звука в вебе, а, скажем, к API патефона, если кто-то вдруг задумает его сделать.
Иными словами, тот объект выше, интерфейс которого не поменяется, если вся нижележащая логика полностью изменится вплоть до смены платформы и физических принципов работы.
Если говорить и чисто программной составляющей API, то, пожалуй, именно именование важнее всего. Всё остальное, в конечном счёте, можно подправить или переписать, но вот номенклатура сущностей — это лицо вашего API, это фасад, с которым будет работать ваш пользователь.
Удивительно, но заставить разработчиков называть сущности правильно — гораздо более сложная задача, чем кажется.
— делать именно то, что нужно — сайдэффекты - build и updateТесты обязаны быть в любом API; это, в общем, вытекает из определения API.
Вместе с тем,
— покрытие в зависимости от проектаДело в том, что разработчик API, по определению, обладает относительно полным знанием о том, как API устроено, какие в нём есть крутые фишки и какие сложные задачи оно способно решать.
В реальности же 90%, если не больше, обращающихся за поддержкой пользователей будут решать совершенно тривиальные задачи и у них в принципе нет никакой мотивации разбираться с внутренним устройством API. Пользователь хочет решить свою задачу с наименьшим напряжением сил, и было бы странным его за это упрекать.
Люди не читают документацию. Не ищут ответов на свои вопросы на StackOverflow. Не являются гуру разработки. Даже напротив, абсолютное большинство ваших клиентов — начинающие и просто малоквалифицированные специалисты. Даже если вашим API пользуются ребята из соседнего отдела, квалификация которых не уступает вашей, — вряд ли даже у них есть желание глубоко разбираться в вашей архитектуре.
Поэтому любой поток обращений, как правило, делится на две неравные категории: вопросы от начинающих (часто глупые или тривиальные) и очень редкие запросы от профессионалов. Запросов первого типа абсолютное большинство, и, при том, найти проблему в коде пользователя частенько бывает весьма нетривиальной задачей.