Как и где в 'Чистой архитектуре' (Clean Architecture) описываются и реализуются API?

Ответ

В 'Чистой архитектуре' API описывается и реализуется в слое Адаптеров Интерфейсов (Interface Adapters). Это внешний слой, который преобразует данные из формата, удобного для внешнего мира (например, HTTP JSON), в формат, удобный для ядра вашего приложения (Use Cases), и обратно.

Где это находится в проекте:

Обычно это директории internal/delivery, internal/controller или internal/interfaces.

/my-project
├── cmd/app/main.go      // Точка входа
└── internal/
    ├── domain/          // Сущности и основная бизнес-логика
    ├── usecase/         // Сценарии использования (прикладная бизнес-логика)
    └── delivery/        // Слой адаптеров (API)
        ├── http/        // Адаптеры для HTTP
        │   ├── handler.go // Обработчики HTTP-запросов (хендлеры)
        │   └── router.go  // Регистрация роутов
        └── grpc/        // Адаптеры для gRPC
            └── service.go // Реализация gRPC-сервисов

В каком виде описывается API:

HTTP-хендлеры: Функции, которые принимают http.Request, вызывают соответствующий usecase и возвращают http.Response.
gRPC-сервисы: Реализации сервисов, сгенерированных из .proto файлов.
Спецификации OpenAPI/Swagger: Файлы в формате YAML или JSON, которые формально описывают эндпоинты, запросы и ответы. Часто размещаются рядом с HTTP-хендлерами.

Ключевой принцип: Этот слой не должен содержать бизнес-логики. Его единственная задача — адаптация данных и вызов следующего слоя (Use Cases). Это защищает бизнес-логику от изменений в способе доставки (например, при переходе с REST на gRPC).