Publiczne API i punkty wejścia
Projektować przejrzysty interfejs biblioteki
Publiczne API i punkty wejścia to bezpłatna lekcja Angular Academy na CoddyKit. To lekcja 2 z 4. Możesz przeczytać całą lekcję poniżej za darmo — a potem ćwiczyć ją interaktywnie w przeglądarce z wbudowanym edytorem kodu i tutorem AI dostępnym 24/7. To część ścieżki edukacyjnej Angular Academy, a Twój postęp synchronizuje się między webem a aplikacją CoddyKit. Kurs Angular Academy zawiera 4 lekcji w sumie.
Publiczna powierzchnia API
Biblioteka powinna udostępniać tylko to, z czego mają korzystać odbiorcy. Publiczne API to starannie wybrany zestaw eksportów; cała reszta pozostaje wewnętrzna. W bibliotekach Angulara tę powierzchnię definiuje plik public-api.ts.
public-api.ts jako plik zbiorczy
Plik public-api.ts ponownie eksportuje symbole, do których odbiorcy mają mieć dostęp. Jeśli coś nie jest tutaj eksportowane, jest w praktyce prywatne, nawet jeśli istnieje w kodzie źródłowym.
// projects/ui-kit/src/public-api.ts
export * from './lib/button/button.component';
export * from './lib/theme.service';
// internal helpers are intentionally NOT exportedDlaczego ukrywać elementy wewnętrzne
Utrzymywanie pomocniczych elementów jako prywatnych pozwala swobodnie je refaktoryzować bez łamania kodu odbiorców. Małe, świadomie zaprojektowane publiczne API łatwiej dokumentować, wersjonować i utrzymywać niż API eksportujące wszystko.
Eksportowanie typów i tokenów
Publiczne API obejmuje nie tylko komponenty, lecz także interfejsy, typy i tokeny wstrzykiwania potrzebne odbiorcom do poprawnego korzystania z tych komponentów.
export { ButtonComponent } from './lib/button/button.component';
export type { ButtonVariant } from './lib/button/button.types';
export { THEME_CONFIG } from './lib/theme.tokens';Dodatkowe punkty wejścia
Duże biblioteki dzielą się na dodatkowe punkty wejścia, aby odbiorcy importowali tylko to, czego potrzebują (co usprawnia tree-shaking). Na przykład ui-kit/testing jest oddzielone od ui-kit.
import { ButtonComponent } from 'ui-kit';
import { provideUiKitTesting } from 'ui-kit/testing';Tworzenie dodatkowego punktu wejścia
Dodatkowy punkt wejścia to podfolder zawierający własne pliki ng-package.json i public-api.ts. ng-packagr wykrywa go automatycznie i buduje jako oddzielną ścieżkę importu.
projects/ui-kit/
testing/
ng-package.json # marks a secondary entry point
src/public-api.tsMapowanie głównego punktu wejścia
Plik ng-package.json biblioteki wskazuje w polu entryFile plik public-api.ts, informując proces budowania, który plik stanowi główną publiczną powierzchnię biblioteki.
// projects/ui-kit/ng-package.json
{
"lib": { "entryFile": "src/public-api.ts" }
}Projektowanie z myślą o stabilności
Traktuj publiczne API jak kontrakt: usunięcie lub zmiana nazwy eksportu to zmiana łamiąca zgodność. Nowe eksporty można dodawać swobodnie, ale przed ich usunięciem należy je oznaczyć jako przestarzałe, aby odbiorcy mieli czas na migrację.
Unikanie głębokich importów
Ponieważ kontraktem jest wyłącznie public-api.ts, odbiorcy nigdy nie powinni importować bezpośrednio wewnętrznych ścieżek, takich jak ui-kit/lib/button/internal. Eksportowanie przez plik zbiorczy zapewnia jedną stabilną powierzchnię importu.
Ponowne eksportowanie typów firm trzecich
Jeśli metoda API zwraca typ z innego pakietu, wyeksportuj ten typ ponownie, aby odbiorcy nie potrzebowali osobnej zależności tylko po to, by móc się do niego odwołać. Dzięki temu publiczna powierzchnia jest samowystarczalna.
Dokumentowanie publicznej powierzchni
Dodawaj komentarze JSDoc do eksportowanych symboli. Ponieważ odbiorcy widzą tylko elementy public-api, ich dokumentowanie zapewnia użytkownikom funkcję IntelliSense i jasne wskazówki dotyczące użycia.
Szybkie sprawdzenie
Co definiuje to, co odbiorcy mogą importować?
Podsumowanie
Publiczne API jest uporządkowane w pliku public-api.ts, który ponownie eksportuje komponenty, typy i tokeny; cała reszta pozostaje prywatna i może być swobodnie refaktoryzowana. W dużych bibliotekach stosuj dodatkowe punkty wejścia, wskaż plik wejściowy w ng-package.json, unikaj głębokich importów i traktuj publiczną powierzchnię jako stabilny, udokumentowany kontrakt.
Często zadawane pytania
Czy lekcja „Publiczne API i punkty wejścia” jest bezpłatna?
Tak — pełny tekst „Publiczne API i punkty wejścia” jest dostępny za darmo tutaj w sieci. Aby ćwiczyć ją interaktywnie (wbudowany edytor kodu i tutor AI dostępny 24/7) i odblokować resztę kursu Angular Academy, przejdź na CoddyKit PRO. Kurs Angular Academy zawiera 4 lekcji w sumie.
Co nauczysz się w „Publiczne API i punkty wejścia”?
Projektować przejrzysty interfejs biblioteki Ćwiczysz Angular Academy z praktycznym kodem, który uruchamiasz bezpośrednio w przeglądarce, a tutor AI dostępny 24/7 odpowiada na Twoje pytania podczas pracy nad lekcją.
Czy potrzebuję doświadczenia, aby zacząć Angular Academy?
Nie wymagamy żadnego doświadczenia. Angular Academy w CoddyKit jest strukturyzowany dla początkujących i zaawansowanych użytkowników, więc możesz zacząć tutaj lub od początku i uczyć się w swoim tempie. To lekcja 2 z 4.
Ile czasu zajmuje lekcja „Publiczne API i punkty wejścia”?
Większość lekcji CoddyKit trwa około 5–10 minut. Każda lekcja to mały, interaktywny krok, dzięki czemu robisz systematyczne postępy i zawsze wracasz dokładnie do tego samego miejsca — na webie i w aplikacji.
Czy mogę pisać i uruchamiać kod w tej lekcji Angular Academy?
Tak. Każda lekcja Angular Academy zawiera wbudowany edytor kodu, więc piszesz i uruchamiasz prawdziwy kod bezpośrednio w przeglądarce i od razu otrzymujesz sprzężenie zwrotne od AI — bez konfiguracji na komputerze.
Wszystkie lekcje w tym kursie
- Tworzenie biblioteki za pomocą ng generate
- Publiczne API i punkty wejścia
- Budowanie za pomocą ng-packagr
- Publikowanie w npm