- Версия(и) Minecraft
- 0.0+
Содержание:
0. Введение
Прежде всего, скажу пару слов. Не так давно, передо мной встала задача спроектировать библиотеку абстрактного кода, а также апи для неё. Причём оно должно было бы удовлетворять многим требованиям, которым в совокупности не удовлетворяло ни одно апи, найденное мной на просторах интернета. Изучив многие ресурсы, я пришёл к выводу, что придётся работать в слепую и что намного хуже, с нуля, ибо полноценных руководств я не нашёл. Возможно, плохо искал.
Недавно моя работа принесла первые плоды, и, хотя успех всё ещё не очевиден, думаю, я смог осуществить задуманное. Итак, я хотел бы поделиться своим опытом. Возможно, для кого-то это окажется полезным. Руководство планирую публиковать по частям, по мере появления свободного времени. Любая обратная связь категорически приветствуется, и я надеюсь, все вместе, мы сможем создать первый качественный паттерн проектирования программного модуля и API на просторах рунета.
В планах:
- Теоретическая постановка задачи
- Постановка проблем
- Поиск решений поставленных проблем
- Подготовка рабочего пространства
- Примеры проектирования
- Процесс разработки
- Примеры интеграции
- Примеры использования
- Оптимизация
- Защита
- Публикация на различных платформах
1.1 Словарь
Библиотека (англ. library) — это набор готовых функций, классов и объектов для решения каких-либо задач.
API (Application programming interface) — это некоторая функциональность, которую предоставляет программа, для обеспечения безопасного и удобного взаимодействия между ней и разработчиком, её использующим. API может быть частью программы, библиотеки, модуля, может быть рассчитано на программиста, и на обычного пользователя, может содержать визуальные элементы. Если простыми словами, API — это набор точек входа в систему, своего рода приборная панель, с набором кнопок и рычажков, для управления этой системой.
API (Application programming interface) — это некоторая функциональность, которую предоставляет программа, для обеспечения безопасного и удобного взаимодействия между ней и разработчиком, её использующим. API может быть частью программы, библиотеки, модуля, может быть рассчитано на программиста, и на обычного пользователя, может содержать визуальные элементы. Если простыми словами, API — это набор точек входа в систему, своего рода приборная панель, с набором кнопок и рычажков, для управления этой системой.
1.2 Понятие библиотеки. Почему она связана с API?
API может быть реализовано с использованием разной архитектуры кода, но важно понимать, что любое API имеет под собой твёрдый фундамент, называемый библиотекой. Это происходит явно или неявно. Например, если API строго привязано к программе, программа сама по себе является библиотекой, но неявной. Однако, после некоторых экспериментов, я пришёл к выводу, что API – это не просто функциональность, расширяющая программу. Если мы хотим добиться наибольшей гибкости, API не стоит делать «дочерней» системой. Основная программа должна сама по себе расширять API. Иначе говоря, всю систему можно представить в виде следующей диаграммы:
В пользу такого подхода говорит следующее:
- Если мы реализуем основную программу на основе API, мы уже в процессе разработки, можем гарантировать наибольшую функциональность API, ведь в нём будет всё, что нужно для функционирования всей системы (основной программы).
- Параллельно с этим мы можем контролировать гибкость системы, и что очень важно, можем добавить возможность отключать/включать компоненты основной программы с помощью дочерних программ.
- Аналогично, основная программа сможет контролировать дочерние программы.
- Можно легко спроектировать приоритет для дочерних программ, повысить приоритет основной, а также понизить приоритет основной программы, если это необходимо.
- При изменении основной программы, дочерние программы не обязаны «поломаться», ведь подобное изменение не обязательно изменит основную библиотеку и API которое с ней связано
- Первый и основной недостаток состоит в том, что такой подход хорошо применим только если система разрабатывается с нуля. Если мы имеем дело с уже готовой программой, применить данный подход сложно, и возможно лишь в том случае, если мы имеем полный доступ к программе, иначе говоря, если являемся её владельцем. К тому же, изменять что-то готовое в 100 раз сложнее, чем создавать новое.
- Иногда излишняя абстракция вредит. Если программа небольшая, и API предназначено для «корпоративного» использования, нет смысла добиваться огромной гибкости и функциональности, затраты на производство такого продукта будут просто несоизмеримы с полученным результатом.
- Если дочерних программ немного, то, опять же, затраты несоизмеримы с резульатом.
В любом случае, мы рассмотрим оба подхода, и «основная программа + библиотека -> API» и «библиотека -> API -> основная программа».
1.3 Виды библиотек
Итак, для начала, что следует знать о самой библиотеке.
Информации по этому поводу я не нашёл, поэтому набравшись смелости, рискну самостоятельно подразделить библиотеки на несколько глобальных видов:
- Утилитарная – представляет из себя набор полезных функций/инструментов, для упрощения работы с рутинными задачами, в том числе с многократно повторяющимися.
- Системная – представляет собой своего рода рабочую систему. Сама по себе она ничего не делает, однако обладает способностью хранить и обрабатывать некоторый набор данных.
- Смешанная – комбинация двух предыдущих видов.
1.4 Виды API
Само же API можно подразделить на два вида:
Интегрированное – встроено в саму библиотеку или программу, поставляется вместе с ней.
- Компактный размер исходного кода.
- Не требует больших усилий в проектировании.
- Вместе с самим API разработчик имеет доступ к реализации, может более тщательно анализировать ситуацию.
- Количество документации можно ограничить, поскольку разработчик может получить основной набор информации, исследуя реализацию.
- Доступ к реализации – обоюдоострое оружие, ведь если разработчик ненадёжен, то проект может стать достоянием общественности.
- Поскольку API поставляется вместе с библиотекой, общий размер подключённой к среде библиотеки может оказаться довольно большим.
- Если программа большая и многослойная – легко запутаться, и гораздо сложнее обнаружить точки входа предоставляемые API.
- При изменении реализации, API может также серьёзно измениться, что поломает дочерние программы
Модульное – разделено на несколько модулей (обычно 2), основной модуль встроен в библиотеку, берёт на себя основную нагрузку по обработке и хранению данных. Дополнительные модули – панель управления, иначе говоря, набор точек входа в библиотеку. Поставляется отдельно. Чаще всего используется подход: модуль API + модуль CORE. При этом API никогда не обращается к модулю CORE, чтобы избежать ошибок компиляции при разделении. Сам же модуль CORE таких ограничений не имеет.
- У разработчика нет доступа к реализации, следовательно, даже если он окажется «нечист на руку» и опубликует исходный код – злоумышленники не получат ничего, кроме «панели управления». Панель управления без «двигателя» даст злоумышленнику разве что общее представление о возможной функциональности программы.
- Поскольку API разделено на модули, размер модуля, подключённого к среде разработки, может оказаться довольно небольшим.
- «Панель управления» не перемешана с реализацией, запутаться крайне сложно, всё будет на виду.
- При изменении реализации библиотеки, само API не обязано пострадать, иначе говоря, разработчик имеет доступ к тем же «рычажкам» и «кнопкам», просто работать они станут иначе. Это обеспечивает хорошую обратную совместимость.
- Требует хорошего документирования, иначе сторонний разработчик просто не сможет понять, что делает тот, или иной «рычажок».
- Количество исходного кода в совокупности может вырасти в 1.5 или даже в 2 раза, поскольку практически любой элемент будет иметь два экземпляра, один интерфейсный, другой внутренний
- Требует гораздо больших усилий в проектировании, чем интегрированное API
- Возникает довольно много проблем, связанных с взаимодействием модулей. Нужно добиться обособленности, при этом обеспечить корректное взаимодействие и передачу данных.
Как мы видим, у каждого вида есть свои достоинства и недостатки. Выбор зависит от требований к разработке продукта.
1.5 Примеры
Приведём примеры:
- Apache Commons:
- Библиотека: утилитарная
- API: интегрированное
- Forge API:
- Библиотека: смешанная
- API: интегрированное
- Spigot
- Библиотека: смешанная
- API: модульное
- Instrumentation API:
- Библиотека: системная
- API: модульное
- ASM:
- Библиотека: утилитарная
- API: интегрированное
1.6 Диаграммы структур проектирования
Проектирование этих двух видов API можно представить в виде диаграмм.
Например, такой вариант интегрированного API:
Ввиду всего вышесказанного, можно сделать вывод, что архитектура кода будет напрямую зависеть от наших требований. Для разработки своего API я выбрал подход «Библиотека -> API -> основная программа» Библиотека получилась смешанная, а API модульным. Постановкой требований и проблем мы и займёмся в следующем разделе.
