Делимся опытом и навыками самостоятельного написания SDK
Всем привет, я Fish Skin.
Недавно из-за рабочих потребностей я сам написал несколько общих SDK для проектов. В процессе написания я прочитал и сослался на SDK, написанный многими другими шишками в компании, а также обобщил некоторый опыт и навыки разработки SDK, и делюсь с вами~
Перед этим я должен объяснить вам, что такое SDK.
Что такое SDK?
SDK (Software Development Kit) — этоКомплект для разработки программного обеспечения, представляет собой набор инструментов, которые помогают нам разрабатывать программное обеспечение. Помимо кода, он обычно сопровождается документацией, примерами и т. д.
Требуется общий SDKвводитьиспользуется в проекте. Например, JDK, с которым впервые столкнулись друзья, изучавшие Java, был набором инструментов для разработки программного обеспечения Java, при использовании которого необходимо было написать что-то вродеimport java.util.*синтаксис для импорта. Кроме того, большинство SDK необходимо импортировать вручную или с помощью инструментов управления проектами, загрузив их файлы по указанному пути.
Каковы преимущества использования SDK?
Например, предположим, что в компании есть много систем, которым необходимо реализовать функцию загрузки файлов. Друзья, которые читали мою статью раньше, должны знать, что отличную функцию загрузки файлов реализовать непросто, и нужно учитывать множество моментов, таких как фрагментация, возобновление точки останова, повторная загрузка, хранение файлов, управление файлами и т. д.
Дизайн загрузки файлов:Tickets.WeChat.QQ.com/Yes/3Q XE4ms OB…
Очевидно, что нам не нужно разрабатывать загрузку файлов для каждой системы, нам нужна только команда, которая выйдет и напишет наборуниверсальныйЗагрузите файл в SDK, а затем позвольте системе, которой необходимо выполнить ту же функцию, ссылаться на него, чтобыЗначительно снижает нагрузку и повышает эффективность разработки.
Немного бывшего рукотворного автомобиля, смысл наслаждаться будущими поколениями~
Написание SDK акаделать колеса, хорошее колесо может не только помочь команде сэкономить время и усилия, но и уменьшить различия некоторых проектов в одной и той же функции. Не говоря уже об одной и той же функции, написанная Сяо Ваном будет работать 1 секунду, а написанная Сяо Ли — 1 час!
И если предположить, что каждая система развивает одну и ту же функцию, то естьзаново изобретать колесо, в большинстве случаев не является мудрым ходом.
Поняв, что такое SDK, давайте посмотрим, как написать отличный SDK~
Сводка по опыту написания SDK вручную
Хороший SDK должен быть простым в использовании, понятным, легко расширяемым, эффективным и стабильным.
Простота использования
В наши дни так много готовых колес! Как сделать так, чтобы ваши колеса выделялись? Тогда мы должны сначала улучшить удобство использования SDK.
Когда я выбираю технологию, я предпочитаю простой в использовании SDK, предпочтительно несколько строк кода, который можно легко использовать, вместо того, чтобы читать длинный документ и писать десятки строк кода, чтобы он вступил в силу.
Точно так же, как и руководство по продукту, слишком сложное может напрямую убедить людей бросить курить.
Мы можем улучшить удобство использования следующим образом:
Единый вызов
Инкапсулируйте сложные функции, предоставьте унифицированную запись вызова для внешнего мира, постарайтесь скрыть некоторые детали реализации и уменьшите процесс вызова пользователя и затраты на понимание параметров.
В качестве примера, вот две функции обработки даты. Пользователям не нужно заботиться о том, как они это реализуют, им просто нужно знать, как это использовать, какие параметры передавать и какие возвращаемые значения получать.
// 第 1 种：需要 new 对象
DateUtils dateUtils = new DateUtils();
dateUtils.setDate('2021-08-31');
Date date = dateUtils.parse();
// 第 2 种：直接调用
Date date = DateUtils.parse('2021-08-13');
Как вы думаете, какой из них проще в использовании?
Централизованная конфигурация
Для настройки сложных параметров пользователям не нужно везде прописывать параметры, а нужно единое управление через конфигурационный файл.
Стандартный фреймворк разработки Java SpringBoot является типичным примером.Если пользователь хочет изменить порт, с которого запускается встроенный сервер, или изменить адрес подключения к базе данных, ему не нужно писать код, а достаточно изменить файл конфигурации:
# 服务器配置
server:
port: 8081
# 数据库配置
db:
ip: 10.0.0.1
Кроме того, это упрощает поддержку проектов и реализацию нескольких сред.
хорошо названный
Называя функции SDK, старайтесь, чтобы они соответствовали привычкам пользователя.
Например, функцию с функцией синтаксического анализа можно назвать «parseXXX», функцию для определения того, является ли она пустой, можно назвать «xx.isEmpty» и так далее. Лучше всего сообщить пользователям, что делает ваша функция, не заглядывая в документацию, только через имя функции и параметры.
Поэтому, если вы хотите написать хороший SDK, вы должны сначала использовать и ссылаться на чужие SDK.После того, как вы привыкнете к этому, вы обнаружите, что у всех одинаковое имя.
Но также обратите внимание на один момент, по возможности старайтесь не делать имя класса (название функции) в вашем SDK точно таким же, как у других, иначе это может вызвать путаницу у пользователей: так много функций с одинаковым именем, что один я должен использовать? Какой SDK вы разработали?
понятность
Иногда пользователям может быть недостаточно простого использования вашего SDK, но они хотят прочитать исходный код вашего SDK для дальнейшего понимания, чтобы они могли использовать его с уверенностью.
Поэтому, помимо простоты использования, вы также должны сделать свой SDK простым для понимания, и вы не сможете его потерять.
Это во многом связано с привычками кодирования.Пишете ли вы SDK или делаете проект, вы должны сделать следующее:
четкая структура
Организуйте код по функциям или категориям и поместите его в указанный каталог. Общие практики включают в себя субподряд, наслоение и т. д., чтобы люди могли с первого взгляда узнать роль файлов в каждом каталоге.
Например, в следующей классической структуре проекта Java каталог сервисов предназначен для написания бизнес-логики, константы — для хранения констант, утилиты — для хранения классов инструментов и т. д., и все они очень понятны:
Единый стиль
Цель единого стиля проста: создать впечатление, что проект написан одним и тем же человеком.
Например, используйте 4 пробела для отступа кода, используйте верблюжий регистр для именования и т. д. Особенно для кода с похожими функциями обязательно следите за тем, чтобы имена и использование были согласованными! Например, функция парсинга текста, не называйте ее пока «parseXXX», а некоторое время «jiexiXXX», она доставит пользователям массу удовольствия~
Но на самом деле в командной разработке это сделать сложно. Следовательно, необходимо иметь набор общих спецификаций кода, и все должны соблюдать спецификации, чтобы проект можно было лучше понять и упростить поддержку.
писать заметки
Лучше дать каждому классу и функции в SDKначалоДобавлены комментарии, так что когда пользователи используют SDK, им даже не нужно читать документацию, но они могут узнать, что он делает и как его использовать, непосредственно из комментариев к коду.
Когда вы открываете функцию в Java SDK или известном SDK в Интернете, вы обычно можете увидеть следующие комментарии, включая описание функции, значение параметров, значение возвращаемого значения и т. д.:
Документация
В дополнение к комментариям напишите документ-описание (руководство пользователя), в том числе о том, как представить SDK, какие у него есть функции, как его использовать и т. д., и даже добавить некоторые ключевые детали реализации и список общих проблем.
Это также сильно влияет на выбор пользователя. Лично я вообще не выбираю SDK без документации, если что-то пойдет не так, к кому обращаться?
Масштабируемость
Основная трудность при написании SDK заключается не только в рассмотрении наиболее распространенных сценариев использования, но и в удовлетворении потребностей небольшого числа пользовательских настроек.
Поэтому масштабируемость SDK очень важна, но как ее улучшить?
Легкие зависимости
С одной стороны, мы можем минимизировать зависимость самого SDK от других библиотек классов.
Например, если вы хотите сделать очень легкий и небольшой класс инструментов, который может занимать всего несколько десятков КБ, то нет необходимости вводить библиотеку зависимостей размером в сотни КБ, выигрыш перевешивает потерю! Никто не счастлив использовать его!
Облегченные зависимости могут не только уменьшить размер SDK, но, что более важно, снизить вероятность конфликтов зависимостей. Я сам много раз сталкивался с такой конфузной ситуацией: после введения класса инструмента не может запуститься весь проект!
пользовательская реализация
Чтобы повысить универсальность и гибкость SDK, при разработке SDK, в дополнение к реализации по умолчанию, рекомендуется предоставить общий интерфейс или абстрактный класс, чтобы пользователи могли наследовать и писать свои собственные методы реализации.
Например, предположим, что мы хотим написать класс для разбора даты.Правило разбора по умолчанию состоит в том, чтобы разбивать строки в соответствии с тире:
// 按照 '-' 切分
date = DateUtils.parse('2021-01-18')
Если он может только это, то SDK очень жесткий. Потому что пользователи могут захотеть выполнить синтаксический анализ с помощью двоеточий или других правил.
Как этого достичь?
Мы можем позволить пользователям самим передавать разделенный символ:
// 按照 '-' 切分
parseRule = ':'
date = DateUtils.parse('2021-01-18', parseRule)
Вы также можете позволить пользователю контролировать, как выполняется синтаксический анализ:
// 自定义解析器
interface MyParser extends Parser {
// 需要用户自己实现
void doParse();
}
// 指定解析器
date = DateUtils.parse('2021-01-18', MyParser.class);
Эти два метода являются общими при разработке SDK, помимо того, что пользователи могут сами писать или указывать файлы конфигурации, они также могут повысить гибкость.
Эффективный и стабильный
На самом деле разработка SDK, особенно на большой фабрике, — очень сложная работа, и я верю, что друзья, которые занимались этим, почувствуют то же самое.
Потому что по мере того, как все больше и больше пользователей используют ваш SDK, могут обнаруживаться различные необъяснимые проблемы, а поскольку зависимость относительно низкого уровня, влияние SDK на пользователя не поддается учету. Поэтому, если вы не хотите работать сверхурочно, чтобы часто исправлять ошибки, вы должны обеспечить стабильность своего SDK.
Нам необходимо обратить внимание на следующие моменты:
1. Тест
Чтобы гарантировать, что каждая функция нормальна, мы можем написатьмодульный тест(UT), чтобы максимально охватить функции и код SDK.
Особенно после каждого изменения кода и перед выпуском новой версии тест должен быть полностью выполнен снова, и не быть слепо уверенным.
Кроме того, черезиспытание давлениемДля оценки эффективности выполнения SDK, например не более 3 одновременных исполнений в секунду, каждое выполнение занимает 500 миллисекунд и т. д. Рекомендуется добавить эту информацию в документацию, чтобы дать пользователям определенные ожидания. Конечно, вы также можете попытаться оптимизировать производительность SDK с помощью стресс-тестирования.
2. Совместимость
Сведите к минимуму изменения важных функций и интерфейсов, особенно имен функций, входных параметров и возвращаемых значений!
Например, в SDK 0.1 определение функции выглядит следующим образом:
boolean isValid(String str)
Результат внезапно изменился на:
String checkValid(StringBuilder str)
Это приведет пользователей в замешательство при обновлении: почему они сообщают о множестве функций, которые не могут быть найдены?
Следовательно, для относительно больших изменений можно написать новую функцию, а старую функцию пометить аналогичным образом.@DeprecatedПримечание, указывающее на устаревшее, помогает пользователям использовать более новый.
Кроме того, вы также можетеномер версииПоднимите шумиху по этому поводу, изменяйте номер младшей версии только для небольших изменений, например, с 0.0.1 на 0.0.2, и меняйте номер основной версии только для серьезных изменений, например, с 1.0 на 2.0. Это может дать пользователям ожидание: это большое изменение и могут быть несовместимости.
3. Выявляйте исключения
Сообщите пользователям об исключениях, которые могут быть вызваны в коде SDK, и позвольте им обрабатывать их соответствующим образом, чтобы предотвратить непредвиденные ошибки.
Кроме того, SDK должен разумно печатать журналы, особенно журналы исключений, и сообщать вызывающему абоненту, что пошло не так, когда возникает проблема, чтобы облегчить устранение неполадок.
Выше рассказано об этой проблеме.Студентам, которые изучают программирование, рекомендуется написать SDK самостоятельно и оптимизировать его в соответствии с кратким изложением этой статьи.Это действительно полезно для улучшения их навыков программирования!
Недавно я собрал 140 своих оригинальных статей по программированию и технических статей Добро пожаловать, читайте и развивайтесь вместе! ⛽️
Направляя путь:t.1yb.co/ARnD
Я рыбья кожа, пожалуйста, спроситекак, это будет для меня самой большой мотивацией продолжать творить, спасибо 🙏