Как да създадете API, които не са смукали

Други разработчици всъщност трябва да използват API, които проектирате. Така че не позволявайте тези API да смучат. Ако не искате орди разгневени програмисти да се спускат в дома ви посред нощ с факли и вили, трябва да ги проектирате правилно.

Ето някои дизайнерски съвети, които подбрах от колегите през годините. Те се прилагат за всички видове API: библиотеки с отворен код, вътрешни SDK, модули или дори един клас.

Бъдете изрични

Това е може би най-важният съвет. Ако имате метод, наречен getUser и той причинява някакъв страничен ефект, без да е изрично за него, това може да доведе до много проблеми.

Не променяйте споделеното мутационно състояние, без да сте изрично за това. Ако се обадя на getUser, очаквам той просто да върне потребител, а не да увеличава user_id с 1 по пътя. Може да помислите и за използване на неизменни структури от данни.

Кодирайте възможно най-много поведение в името / метода / клас / модул в разумни граници. Не очаквайте потребителите да отидат на гмуркане с източник, за да разкрият скрито поведение, което името не разкрива. Ще си спестите много болка по линията.

Пазете повърхността на вашия API малка

Никой не обича раздутите програми. Колкото по-малко API-та можете да изложите, за да си свършите работата, толкова по-добро е изживяването за всички.

Наистина ли някой иска този нов API, който искате да напишете? Вероятно можете да го отложите, докато всъщност не е проблем, който някой иска да бъде решен.

В някои програмни среди като Android има твърди ограничения за броя на общите методи, които приложенията могат да имат, така че може да е нещо, което трябва да имате предвид, ако се насочите към тези платформи.

Предсказаното изпълнение е отговорно за срамните количества загубени часове за програмиране. Практикувайте YAGNI.

Намалете котела

Работете с възможно най-много подробности за внедряването вътре, за да намалите тежестта за клиентите. Колкото по-малко потребител трябва да направи, толкова по-малък е възможен брой грешки, с които ще трябва да се справите.

Има и въпрос на естетика. Налагането на писане на котел може да съсипе един иначе напълно добър API и да направи потребителския код грозен. Всички харесваме чист код, нали? Улеснявайте потребителите си да поддържат кода кратък и чист код при използване на вашия API.

Намалете зависимостите

Опитайте се да запазите кода си максимално самостоятелен. Колкото повече зависимости имате, толкова повече потенциални проблеми може да причини при потребителския код надолу по веригата.

Ако наистина искате тази приятна функционалност от друг модул, Направете опит да го извлечете и включете само това, от което се нуждаете.

Винаги е фино балансиращо действие между повторна употреба на код и плътно свързване. Ще трябва да осъществите това решение. Ако тази функционалност е малка, може би си струва да я приложите отново.

Върнете смислени състояния на грешки

По цял ден бих могъл да гневя колко нула е безполезна конструкция в много случаи. Това буквално не означава нищо.

„Ей модул, дай ми потребител“

"Не. Тук няма нищо “

Това ми дава нулева информация за това какво се обърка и какво мога да направя, за да подобря ситуацията. Ако вместо това имаме документиран начин да изразим очакваните състояния на грешка в проблемния ни домейн като Error.USER_NOT_CREATED или Error.USER_DELETED, това ми дава много по-полезни данни и ми помага да отстраня грешката в проблема.

Съобщенията за грешки също трябва да следват същите указания. Трябва да влезете, преди да продължите е много по-добре от LOL! Нещо се обърка.

Запазете изключения за наистина изключителни случаи

Ако вашият език няма изключения, радвайте се! Така или иначе типовете и техните групи, които се намират във функционалните езици, са много по-добри при осигуряването на значими състояния на грешки.

Изключенията са силно насилвани в земя на Java. Изключения са за обработка на наистина изключителни случаи. Наистина ли не очаквате, че getUser може да не намери потребител? Не хвърляйте UserNotFoundException. Вместо това върнете правилното състояние на грешка.

Ако има истински отказ обаче, винаги е по-добре да се провалите бързо.

Както казва Джейк Уартън:

"Единственото по-лошо от сриващата програма е тази, която не се срива и продължава в неопределено състояние."

Документирайте всички неща

Документацията е скучна. И като много скучни неща, това е важно. Добрата документация ще ви спести здравия разум. Ще избегнете постоянни въпроси от потребителите на вашия API и само това си струва теглото в злато.

Добрата документация трябва да се състои от:

  1. Преглед на високо ниво на целия модул и как работи
  2. Javadocs, Heredocs, Rdocs или каквото и да е от неговите публични методи и протоколи
  3. Примерен код, показващ как да го използвате

Не всички абстракции изискват едно и също ниво на документация. Един малък клас не се нуждае например от примерен код.

Документацията също трябва да бъде еволюционна. Ако получавате много въпроси, задаващи едно и също нещо, можете да го добавите в документите за бъдещи потребители.

Прекалената документация също е загуба на време, тъй като това е още едно предимство, което трябва да актуализирате. Тя няма стойност, ако никой не я използва.

Фокусираната и адекватна документация обаче винаги е полезна.

Пишете тестове

Тестовете са доказателство за коректност, документация и примерен код, които са събрани в едно цяло. Те осигуряват огромна стойност при рефакторинг и ви позволяват да се движите бързо с увереност при промяна на нещата.

Потребителите, които искат да се задълбочат във вашата реализация, винаги могат да четат тестове, за да разберат повече за намерението и вътрешното поведение на вашия код. Документацията не може да обхване всичко и тук помагат тестовете.

„Защо изобщо да пиша документация, ако имам тестове?“, Може да попитате. С риск от използване на деликатна аналогия. Ако документацията е ръководството за потребителя към вашия API, тогава тестовете са справочник за инструкции за x86 опкод.

Направете го тестируем

Тестването на собствения ви код е едно. Писането на API, които позволяват на тези, които ги използват, за да тестват лесно кода си, е друго. Разработчиците, които се интересуват от тестове, ще бъдат отложени от API, които затрудняват да се подиграват / прекъсват в тестови случаи.

Можете да използвате опции за конфигурация за версии за отстраняване на грешки и продукции, когато е приложимо. Нещата често трябва да се държат малко по-различно в средите на непрекъсната интеграция / непрекъснато внедряване, отколкото при производството. Сметка за това.

Разрешаване на потребителски избор

Не всеки потребител ще иска да консумира вашите API по същия начин. Някои може да го искат синхронно. Други могат да предпочетат асинхронни обратни повиквания, фючърси, обещания или Rx наблюдения.

Дайте възможност на потребителите да избират това, което искат, доколкото е възможно. Колкото повече вашият API може лесно да се интегрира в съществуващата си програмна и системна среда, толкова по-вероятно хората ще го използват.

Не допускайте прекалено голям избор на потребителя

Не давайте на потребителите толкова голям избор, че да стигнат до парализа на анализа. Винаги се стремете да предоставяте разумни настройки по подразбиране. През повечето време вашият API ще бъде използван по определен начин. Накарайте по подразбиране да се държат по този начин.

API трябва да насърчава каноничното поведение. Не позволявайте на потребителите да променят някакво произволно състояние във вашия модул, ако това не е част от договора за API. Ако изложите някакво странно неволно поведение, можете да бъдете сигурни, че то ще бъде използвано един ден, като породи непредвидени последици.

Бъдете уверени. Не губете фокус, като давате твърде много опции. Балансирането на правилното количество мнение с правилния размер на гъвкавост изисква практика и опит. Когато се съмнявате, грешете на страната на по-малко избор.

заключение

Проектирането на API е изкуство. Надяваме се, че описаните тук съвети трябва да ви помогнат да напишете по-добър код. Вероятно съм пропуснал много други неща, но те са ми служили добре. Живей и учи.

Ако това ви е харесало, щракнете върху по-долу. Забелязвам всеки един и съм благодарен за всеки от тях.

За повече размисли относно програмирането, следвайте ме, така че ще получавате известия, когато пиша нови публикации.