Web API

Ему нужны TokenValidationParameters: ключ подписи, допустимый issuer и допустимая audience. Их привязывают при старте из builder.Configuration, а не зашивают в код — ключ является секретом, поэтому приходит из переменной окружения, читаемой после appsettings.json и потому побеждающей.

Аутентификация устанавливает, кто вызывающий, и даёт ClaimsPrincipal; авторизация решает, вправе ли этот principal дойти до эндпоинта. Политика — это именованный набор требований: claims, роли или своё требование с обработчиком, поэтому [Authorize] называет намерение вроде CanRefund вместо жёсткой привязки к имени группы.

UseAuthentication работает после UseRouting и до UseAuthorization. Обработчик читает bearer-токен из заголовка Authorization, проверяет его подпись настроенным ключом, а также issuer, audience и срок годности; при успехе он кладёт ClaimsPrincipal в HttpContext.User. Доступ он не решает — это делает UseAuthorization.

Он включает API-соглашения: автоматический ответ 400 с телом ProblemDetails, когда ModelState невалиден, вывод источника привязки (сложные типы берутся из тела, простые — из route values, затем из query string), и обязательный attribute routing на контроллере.

Конкретный тип возвращают, когда действие всегда отдаёт одну форму — она сериализуется и уходит с кодом 200. IActionResult возвращают, когда действие само выбирает статус-код, например NotFound() или BadRequest(). ActionResult<T> даёт и то и другое, сохраняя тип полезной нагрузки видимым для описания API.

Minimal APIs отображают делегат прямо на маршрут: нет класса контроллера, нет конвейера action-фильтров, ответ строится через TypedResults. Контроллеры дают соглашения, которые тянут большой API: action-фильтры, валидацию ModelState через [ApiController], свои model binders. И те и другие работают на одном routing, контейнере и конвейере middleware.

Явный атрибут побеждает — [FromRoute], [FromQuery], [FromHeader], [FromBody], [FromServices]. Без него [ApiController] выводит источник сам: сложный тип берётся из тела, простой — из route values, а затем из query string. Из тела может прийти не более одного параметра, потому что тело читается один раз.

Версионируйте контракт, а не базу. Выберите один явный селектор: сегмент URL заметнее всего, заголовок сохраняет URL неизменными. Заморозьте обработчики v1 и дайте v2 развиваться, отображая обе версии на одну доменную модель. На неподдерживаемую версию отвечайте 400 и перечисляйте поддерживаемые. Объявляйте устаревание заголовком Sunset и считайте вызовы по версиям, чтобы удаление опиралось на данные, а не на надежду.

Два уровня: кэш в памяти инстанса перед общим распределённым кэшем, оба читаются cache-aside поверх запроса с AsNoTracking. На обновление инвалидируйте ключ в обоих уровнях и держите время жизни коротким, чтобы пропущенная инвалидация самоисцелялась за секунды. Кэшируйте и промахи, ненадолго, чтобы несуществующие идентификаторы не доходили до базы. Сливайте параллельные перестройки ключа, чтобы истечение стоило одного запроса, а не десятков.

Поставляйте оба варианта за одной абстракцией. Разрешайте tenant один раз на запрос из claim токена в scoped-контекст tenant, который scoped DbContext берёт, чтобы выбрать строку подключения. Tenant-ы в общей базе получают глобальный фильтр по дискриминатору плюс идентификатор tenant на каждой записи: дёшево подключать и мигрировать, но пропущенный фильтр утечёт данные. Корпоративный tenant получает свою базу — изоляция по построению ценой миграции многих.

Ограничивайте в конвейере до всякой работы: лимитер стоит выше авторизации, а health-эндпоинт из него исключён. Относите запрос к subject токена, если он аутентифицирован, иначе к адресу, и выбирайте политику по тарифу вызывающего. Сглаживайте стык скользящим окном или token bucket, чтобы короткий всплеск проходил, а средняя скорость держалась. Счётчики держите в хранилище, общем для всех инстансов, и отклоняйте кодом 429 с Retry-After.