Jak navrhnout API, která nejsou sát

Ostatní vývojáři musí skutečně používat API, která navrhujete. Nedovolte, aby tato API sála. Pokud nechcete, aby hordy rozzlobených programátorů sestupovaly ve vašem domě uprostřed noci pochodněmi a vidlemi, musíte je navrhnout správně.

Zde je několik návrhových tipů, které jsem během let získal od kolegů. Platí pro všechny druhy rozhraní API: knihovny s otevřeným zdrojovým kódem, interní sady SDK, moduly nebo dokonce jednu třídu.

Buďte explicitní

To je možná nejdůležitější tip. Pokud máte metodu nazvanou getUser a způsobuje to některé vedlejší účinky, aniž by se na to výslovně vztahovalo, může to vést k mnoha problémům.

Neupravujte sdílený mutabilní stav, aniž byste o tom byli výslovně. Pokud zavolám getUser, očekávám, že to pouze vrátí uživatele, nikoli zvýší user_id o 1 podél cesty. Můžete také zvážit použití neměnných datových struktur.

Zakódujte co nejvíce chování v názvu metody / třídy / modulu v rozumných mezích. Neočekávejte, že uživatelé půjdou na potápění se zdrojem, aby odhalili skryté chování, které jeho jméno neodhalí. Ušetřete si spoustu bolesti v řadě.

Udržujte malou plochu rozhraní API

Nikdo nemá rád nafouklé programy. Čím méně rozhraní API můžete vystavit, aby byla práce dokončena, tím lepší bude zážitek pro každého.

Opravdu někdo požaduje nové API, které chcete napsat? Pravděpodobně to můžete odložit, dokud to není vlastně problém, který někdo chce vyřešit.

V některých programovacích prostředích, jako je Android, existuje přísný limit počtu metod, které aplikace mohou mít, takže pokud na tyto platformy cílíte, může to být něco, co musíte mít na paměti.

Předvídavá implementace je zodpovědná za hanebné množství zbytečných programovacích hodin. Cvičte YAGNI.

Omezte desku kotle

Interně zpracovejte co nejvíce podrobností o implementaci, aby se snížilo zatížení klientů. Čím méně musí zákazník udělat, tím menší je možný počet chyb, s nimiž se budete muset vypořádat.

Je tu také otázka estetiky. To, že budete muset psát kotl, může zničit jinak dokonale dobré API a způsobit, že kód spotřebitele bude ošklivý. Všichni máme rádi čistý kód, že? Usnadněte svým zákazníkům, aby při používání rozhraní API udržovali napjatý a čistý kód.

Snižte závislosti

Pokuste se udržet kód co nejucelenější. Čím více závislostí máte, tím více potenciálních problémů může způsobit v následném spotřebitelském kódu.

Pokud opravdu chcete tuto pěknou funkci z jiného modulu, pokuste se ji extrahovat a zahrňte pouze to, co potřebujete.

Vždy je to jemné vyvážení mezi opakovaným použitím kódu a pevným spojením. Budete muset zavolat ten rozsudek. Pokud je tato funkce malá, může být užitečné ji znovu implementovat.

Vraťte smysluplné chybové stavy

Celý den jsem mohl chtít o tom, jak null je v mnoha případech zbytečný konstrukt. Doslova to neznamená nic.

"Ahoj modul, dej mi uživatele"

"Ani náhodou. Tady místo toho není nic “

To mi dává nulové informace o tom, co se pokazilo a co mohu udělat pro zlepšení situace. Pokud místo toho máme zdokumentovaný způsob, jak vyjádřit očekávané chybové stavy v naší problémové doméně, například Error.USER_NOT_CREATED nebo Error.USER_DELETED, což mi poskytne mnohem více údajů, které lze použít, a pomůže mi tento problém vyladit.

Chybové zprávy by se měly řídit stejnými pokyny. Před pokračováním se musíte přihlásit, než je LOL! Něco se pokazilo.

S výjimkou výjimek pro skutečně výjimečné případy

Pokud váš jazyk nemá výjimky, radujte se! Oba typy a jejich kohorty nalezené ve funkčních jazycích jsou mnohem lepší v poskytování smysluplných chybových stavů.

Výjimky bývají v zemi Java silně zneužívány. Výjimkou je řešení skutečně výjimečných případů. Opravdu neočekáváte, že uživatel getUser nemusí najít uživatele? Nevyhazujte UserNotFoundException. Místo toho vraťte správný chybový stav.

Pokud však dojde k opravdovému selhání, je vždy lepší rychle selhat.

Jak říká Jake Wharton:

"Jediné, co je horší než havarující program, je ten, který nezkracuje a pokračuje v neurčitém stavu."

Zdokumentujte všechny věci

Dokumentace je nudná. A stejně jako mnoho nudných věcí, je to nezbytné. Dobrá dokumentace vám zachrání zdravý rozum. Vyhnete se neustálým otázkám spotřebitelů vašeho API, a to samo o sobě stojí za to, že má váhu ve zlatě.

Dobrá dokumentace by měla obsahovat:

  1. Vysoký přehled o celém modulu a jeho fungování
  2. Javadocs, Heredocs, Rdocs nebo cokoli z jeho veřejných metod a protokolů
  3. Ukázkový kód ukazující, jak jej používat

Ne všechna abstrakce vyžadují stejnou úroveň dokumentace. Malá třída například nepotřebuje ukázkový kód.

Dokumentace musí být také evoluční. Máte-li mnoho otázek, které kladou totéž, můžete je přidat do dokumentů pro budoucí spotřebitele.

Příliš mnoho dokumentace je také ztráta času, protože je to další aktivum, které musíte udržovat v aktuálním stavu. Pokud to nikdo nepoužívá, nemá žádnou hodnotu.

Cílená a přiměřená dokumentace je však vždy užitečná.

Napište testy

Testy jsou důkazem správnosti, dokumentace a ukázkového kódu, které jsou shrnuty do jednoho. Poskytují nesmírnou hodnotu při refaktoringu a umožňují vám rychle se pohybovat s jistotou, když měníte věci.

Spotřebitelé, kteří se chtějí hlouběji věnovat vaší implementaci, si mohou vždy přečíst testy, aby pochopili více o záměru a vnitřním chování vašeho kódu. Dokumentace nemůže zachytit všechno, a to je místo, kde testy pomáhají.

"Proč tedy vůbec psát dokumentaci, když mám testy?" V případě rizika, že budete používat jemnou analogii, je-li dokumentace uživatelská příručka k vašemu rozhraní API, pak jsou testy odkazem na instrukce opx x86.

Nechte to být testovatelné

Testování vlastního kódu je jedna věc. Psaní API, která umožňují těm, kteří je používají, snadno otestovat svůj kód, je další. Vývojáři, kteří se zajímají o testy, budou odkládáni pomocí API, která jim v testovacích případech ztěžují jejich zesměšňování.

V případě potřeby můžete použít možnosti konfigurace pro ladicí a produkční verze. Věci se často musí chovat v prostředí kontinuální integrace / kontinuálního nasazení trochu jinak než ve výrobě. Účet za to.

Povolit uživateli výběr

Ne každý spotřebitel bude chtít vaše API konzumovat stejným způsobem. Někteří to mohou chtít synchronní. Jiní mohou preferovat asynchronní zpětná volání, futures, přísliby nebo pozorovatelné Rx.

Umožněte spotřebitelům vybrat si co nejvíce chtějí. Čím více se vaše API může snadno integrovat do svého stávajícího programovacího a systémového prostředí, tím je pravděpodobnější, že jej budou lidé používat.

Nedovolte příliš mnoho uživatelského výběru

Nedávají spotřebitelům tolik možností, aby skončili s paralýzou analýzy. Vždy se snažte poskytnout rozumné výchozí hodnoty. Ve většině případů bude vaše API používáno určitým způsobem. Nechte výchozí hodnoty chovat se tak.

API by měla podporovat kanonické chování. Nedovolte zákazníkům, aby ve vašem modulu upravili nějaký náhodný stav, pokud to není součástí smlouvy API. Pokud odhalíte nějaké podivné neúmyslné chování, můžete si být jisti, že bude použito jeden den, což způsobí nepředvídané následky.

Buďte komentovaní. Neztrácejte pozornost tím, že poskytujete příliš mnoho možností. Vyvážení správného množství názorů proti správnému množství flexibility vyžaduje praxi a zkušenosti. V případě pochybností se mýlejte na straně menšího výběru.

Závěr

Navrhování API je umění. Doufejme, že zde uvedené tipy by vám měly pomoci napsat lepší kód. Pravděpodobně jsem vynechal mnoho dalších věcí, ale ty mi dobře posloužily. Žij a uč se.

Pokud se vám to líbilo, klikněte níže na . Všiml jsem si každého a jsem vděčný za každého z nich.

Chcete-li získat více informací o programování, sledujte mě, abyste byli upozorněni, když píšu nové příspěvky.