0Pricing
Angular Academy · Урок

Публичный API и точки входа

Проектируйте чистый публичный интерфейс библиотеки

«Публичный API и точки входа» — бесплатный урок Angular Academy на CoddyKit. Это урок 2 из 4. Ты можешь прочитать весь урок бесплатно ниже — а потом практиковать его прямо в браузере с встроенным редактором кода и ИИ-репетитором 24/7. Это часть пути обучения Angular Academy, и твой прогресс синхронизируется между веб-версией и приложением CoddyKit. Курс Angular Academy содержит 4 уроков всего.

Общедоступная поверхность API

Библиотека должна предоставлять только то, что предназначено для использования потребителями. Общедоступный API — это отобранный набор экспортов; всё остальное остаётся внутренним. В библиотеках Angular эта поверхность определяется файлом public-api.ts.

public-api.ts как сводный файл

public-api.ts повторно экспортирует символы, к которым вы хотите предоставить доступ потребителям. Если что-либо не экспортируется из этого файла, оно фактически является закрытым, даже если существует в исходном коде.

// projects/ui-kit/src/public-api.ts
export * from './lib/button/button.component';
export * from './lib/theme.service';
// internal helpers are intentionally NOT exported

Зачем скрывать внутренние элементы

Если вспомогательные средства остаются закрытыми, вы можете свободно изменять их внутреннее устройство, не нарушая работу потребителей. Небольшой продуманный общедоступный API проще документировать, версионировать и поддерживать, чем экспортировать всё подряд.

Экспорт типов и токенов

Общедоступный API включает не только компоненты, но и интерфейсы, типы и токены внедрения, необходимые потребителям для правильного использования этих компонентов.

export { ButtonComponent } from './lib/button/button.component';
export type { ButtonVariant } from './lib/button/button.types';
export { THEME_CONFIG } from './lib/theme.tokens';

Дополнительные точки входа

Большие библиотеки разделяются на дополнительные точки входа, чтобы потребители импортировали только нужное им содержимое (для более эффективного удаления неиспользуемого кода). Например, ui-kit/testing отдельно от ui-kit.

import { ButtonComponent } from 'ui-kit';
import { provideUiKitTesting } from 'ui-kit/testing';

Создание дополнительной точки входа

Дополнительная точка входа — это вложенная папка со своими ng-package.json и public-api.ts. ng-packagr автоматически обнаруживает её и собирает как отдельный путь импорта.

projects/ui-kit/
  testing/
    ng-package.json   # marks a secondary entry point
    src/public-api.ts

Сопоставление основной точки входа

Файл ng-package.json библиотеки указывает в entryFile файл public-api.ts, сообщая сборке, какой файл является основной общедоступной поверхностью.

// projects/ui-kit/ng-package.json
{
  "lib": { "entryFile": "src/public-api.ts" }
}

Проектирование с учётом стабильности

Рассматривайте общедоступный API как контракт: удаление или переименование экспорта является нарушающим совместимость изменением. Новые экспорты можно добавлять свободно, но перед удалением помечайте их как устаревшие, чтобы у потребителей было время на переход.

Избегайте глубоких импортов

Поскольку контрактом является только public-api.ts, потребители не должны напрямую импортировать внутренние пути, такие как ui-kit/lib/button/internal. Экспорт через сводный файл обеспечивает единую стабильную поверхность импорта.

Повторный экспорт сторонних типов

Если метод API возвращает тип из другого пакета, повторно экспортируйте этот тип, чтобы потребителям не требовалась отдельная зависимость лишь для его указания. Так общедоступная поверхность остаётся самодостаточной.

Документирование поверхности

Добавляйте комментарии JSDoc к экспортируемым символам. Поскольку потребителям видны только элементы общедоступного API, их документирование предоставляет пользователям IntelliSense и понятные рекомендации по использованию.

Быстрая проверка

Что определяет, что могут импортировать потребители?

Итоги

Общедоступный API формируется в public-api.ts, который повторно экспортирует компоненты, типы и токены; всё остальное остаётся закрытым и доступным для изменения. Используйте дополнительные точки входа для больших библиотек, указывайте файл входа в ng-package.json, избегайте глубоких импортов и относитесь к общедоступной поверхности как к стабильному документированному контракту.

Часто задаваемые вопросы

Урок «Публичный API и точки входа» бесплатный?

Да — полный текст урока «Публичный API и точки входа» бесплатно доступен здесь в веб-версии. Чтобы практиковать его интерактивно (встроенный редактор кода и ИИ-репетитор 24/7) и разблокировать остальной курс Angular Academy, подпишись на CoddyKit PRO. Курс Angular Academy содержит 4 уроков всего.

Чему я научусь в уроке «Публичный API и точки входа»?

Проектируйте чистый публичный интерфейс библиотеки Ты практикуешь Angular Academy с помощью реального кода, который запускаешь прямо в браузере, и ИИ-репетитор 24/7 отвечает на твои вопросы во время урока.

Нужен ли мне опыт, чтобы начать Angular Academy?

Предыдущий опыт не требуется. Angular Academy на CoddyKit структурирован для всех уровней — от новичков до продвинутых, поэтому ты можешь начать отсюда или с самого начала и учиться в своем темпе. Это урок 2 из 4.

Сколько времени занимает урок «Публичный API и точки входа»?

Большинство уроков CoddyKit занимают около 5–10 минут. Каждый из них компактный и интерактивный, поэтому ты постоянно делаешь прогресс и продолжаешь с того же места в веб-версии и приложении.

Можно ли писать и запускать код в этом уроке Angular Academy?

Да. Каждый урок Angular Academy включает встроенный редактор кода, поэтому ты пишешь и запускаешь реальный код прямо в браузере и получаешь моментальную обратную связь от AI — локальная установка не требуется.

Все уроки этого курса

  1. Создание библиотеки с помощью ng generate
  2. Публичный API и точки входа
  3. Сборка с помощью ng-packagr
  4. Публикация в npm
← Назад к Angular Academy