API pubblica ed entry point

Una libreria dovrebbe esporre solo ciò che i consumer devono utilizzare. L'API pubblica è l'insieme curato degli export; tutto il resto rimane interno. Nelle librerie Angular questa superficie è definita da public-api.ts.

public-api.ts riesporta i simboli a cui si desidera dare accesso ai consumer. Se qualcosa non viene esportato qui, è di fatto privato, anche se esiste nel codice sorgente.

Mantenere privati gli helper consente di rifattorizzarli liberamente senza interrompere i consumer. Un'API pubblica ridotta e intenzionale è più facile da documentare, versionare e mantenere rispetto all'esportazione indiscriminata di tutto.

L'API pubblica include non solo i componenti, ma anche le interfacce, i tipi e i token di injection di cui i consumer hanno bisogno per utilizzarli correttamente.

Le librerie di grandi dimensioni si suddividono in entry point secondari, così i consumer importano solo ciò di cui hanno bisogno, migliorando il tree-shaking. Ad esempio, ui-kit/testing separato da ui-kit.

Un entry point secondario è una sottocartella con il proprio ng-package.json e public-api.ts. ng-packagr lo individua automaticamente e lo compila come percorso di import separato.

Il ng-package.json della libreria associa entryFile a public-api.ts, indicando al build quale file costituisce la superficie pubblica principale.

Consideri l'API pubblica come un contratto: rimuovere o rinominare un export è una breaking change. Aggiunga liberamente nuovi export, ma li contrassegni come deprecati prima di rimuoverli, così i consumer avranno il tempo di migrare.

Poiché solo public-api.ts costituisce il contratto, i consumer non dovrebbero mai effettuare import profondi di percorsi interni come ui-kit/lib/button/internal. L'esportazione tramite il barrel mantiene un'unica superficie di import stabile.

Se un metodo della sua API restituisce un tipo proveniente da un altro pacchetto, riesporti quel tipo, così i consumer non avranno bisogno di una dipendenza aggiuntiva solo per poterlo indicare. In questo modo la superficie pubblica rimane autosufficiente.

Aggiunga commenti JSDoc ai simboli esportati. Poiché ai consumer sono visibili solo gli elementi della public API, documentarli fornisce IntelliSense e indicazioni chiare sul loro utilizzo.

Che cosa definisce ciò che i consumer possono importare?

L'API pubblica viene curata in public-api.ts, che riesporta componenti, tipi e token; tutto il resto rimane privato e può essere rifattorizzato. Utilizzi entry point secondari per le librerie di grandi dimensioni, punti ng-package.json al file di entry, eviti gli import profondi e consideri la superficie come un contratto stabile e documentato.