asp net core статусные коды
Типы возвращаемых значений действий контроллера в веб-API ASP.NET Core
Автор: Скотт Адди (Scott Addie)
ASP.NET Core предоставляет следующие параметры для типов возвращаемых значений действий контроллера веб-API:
В этом документе объясняется, когда лучше использовать каждый тип возвращаемого значения.
Определенный тип
Простейшее действие возвращает элементарный или сложный тип данных (например, string или пользовательский тип объекта). Рассмотрим следующее действие, которое возвращает коллекцию пользовательских объектов Product :
Если не известны условия, которые необходимо соблюдать при выполнении действия, конкретного типа будет достаточно. Предыдущее действие не принимает параметры, поэтому проверка ограничений параметров не требуется.
Возврат IEnumerable или иасинценумерабле
В ASP.NET Core 2.2 и более ранних версиях получение интерфейса IEnumerable из действия приводит к тому, что сериализатор выполняет синхронную итерацию операции сбора. В результате вызовы блокируются, что может стать причиной перегрузки пула потоков. Представьте, что Entity Framework (EF) Core используется веб-API для доступа к данным. Во время сериализации выполняется синхронное перечисление для типа возвращаемого значения следующего действия:
Чтобы не допустить синхронного перечисления и блокировки операций ожидания для базы данных в ASP.NET Core 2.2 и более ранних версий, вызовите ToListAsync :
В ASP.NET Core 3.0 и более поздних версиях получение IAsyncEnumerable из действия:
ASP.NET Core 3.0 и более поздних версий помещает результаты следующего действия в буфер перед предоставлением его сериализатору:
Рассмотрим следующее действие, которое возвращает записи о продуктах со сниженной ценой как IEnumerable
для предшествующего действия является:
Начиная с версии ASP.NET Core 3.0, оба предшествующих действия не являются блокирующими.
Тип IActionResult
Так как в этом типе действий существует несколько возвращаемых типов и путей, необходимо свободно использовать [ProducesResponseType] атрибут. Этот атрибут создает описательные сведения об ответе для страниц справки по веб-API, создаваемых с помощью таких инструментов, как Swagger. [ProducesResponseType] указывает известные типы и коды состояния HTTP, возвращаемые действием.
Синхронное действие
Рассмотрим следующее синхронное действие, в котором возможны два типа возвращаемых значений:
В предшествующем действии:
Асинхронное действие
Рассмотрим следующее асинхронное действие, в котором возможны два типа возвращаемых значений:
В предшествующем действии:
если [ApiController] применяется атрибут в ASP.NET Core 2,1 или более поздней версии, ошибки проверки модели приводят к коду состояния 400. Дополнительные сведения см. в разделе Автоматические отклики HTTP 400.
ActionResult VS IActionResult
В следующем разделе сравниваются ActionResult с IActionResult
Тип ActionResult
ASP.NET Core включает тип возвращаемого значения ActionResult для действий контроллера веб-API. Он позволяет возвращать тип, производный от ActionResult или определенный тип. ActionResult имеет следующие преимущества по сравнению с типом IActionResult:
Большинство действий имеют тип возвращаемого значения. При выполнении действия могут возникнуть непредвиденные условия, и в этом случае определенный тип не возвращается. Например, входной параметр действия может не пройти проверку модели. В этом случае обычно возвращается подходящий тип ActionResult вместо конкретного типа.
Синхронное действие
Рассмотрим синхронное действие, в котором возможны два типа возвращаемых значений:
В предшествующем действии:
Асинхронное действие
Рассмотрим асинхронное действие, в котором возможны два типа возвращаемых значений:
Обработка ошибок в ASP.NET Core
Авторы: Кирк Ларкин (Kirk Larkin), Том Дикстра (Tom Dykstra) и Стив Смит (Steve Smith)
В этой статье рассматриваются основные методы обработки ошибок в веб-приложениях ASP.NET Core. Для веб-API см. раздел Обработка ошибок в веб-API ASP.NET Core.
Просмотреть или скачать образец кода. См. раздел Загрузка примера. Вкладка «Сеть» в средствах разработчика F12 в браузере полезна при тестировании примера приложения.
Страница со сведениями об исключении для разработчика
Страница исключений для разработчика содержит подробные сведения о необработанных исключениях запросов. Шаблоны ASP.NET Core создают следующий код:
Выделенный выше код включает страницу исключений для разработчика при выполнении приложения в среде разработки.
Шаблоны помещают метод UseDeveloperExceptionPage в начало конвейера ПО промежуточного слоя, чтобы он мог перехватывать необработанные исключения, вызываемые в последующем ПО промежуточного слоя.
Приведенный выше код включает страницу исключений для разработчика только при выполнении приложения в среде разработки. Подробные сведения об исключениях не должны быть общедоступными при выполнении приложения в рабочей среде. Дополнительные сведения о настройке среды см. в статье Использование нескольких сред в ASP.NET Core.
Страница исключений для разработчика содержит следующие сведения об исключении и запросе:
Страница обработчика исключений
Чтобы настроить пользовательскую страницу обработки ошибок для рабочей среды, вызовите UseExceptionHandler. Это ПО промежуточного слоя для обработки исключений выполняет следующие действия:
Если альтернативный конвейер создает собственное исключение, ПО промежуточного слоя обработки исключений повторно создаст исходное исключение.
В следующем примере с помощью UseExceptionHandler добавляется ПО промежуточного слоя для обработки исключений в средах, не предназначенных для разработки:
Для избирательного управления исключениями в зависимости от исходного метода HTTP:
Чтобы разрешить пользователям, не прошедшим проверку подлинности, просматривать страницу пользовательской обработки ошибок, убедитесь, что она поддерживает анонимный доступ.
Доступ к исключению
Используйте интерфейс IExceptionHandlerPathFeature, чтобы получить доступ к исключению и к пути исходного запроса в обработчике ошибок. Следующий код добавляет ExceptionMessage в файл Pages/Error.cshtml.cs по умолчанию, создаваемый шаблонами ASP.NET Core:
Не передавайте клиентам конфиденциальную информацию об ошибках. Сохранение ошибок создает риски для безопасности.
Чтобы протестировать исключение в примере приложения, выполните указанные ниже действия.
Лямбда-функция для обработчика исключений
Альтернативой пользовательской странице обработчика исключений является предоставление лямбда-функции для UseExceptionHandler. Использование лямбда-функции позволяет получить доступ к ошибке до возврата ответа.
В следующем коде для обработки исключений используется лямбда-выражение:
Не передавайте клиентам конфиденциальную информацию об ошибках из IExceptionHandlerFeature или IExceptionHandlerPathFeature. Сохранение ошибок создает риски для безопасности.
Чтобы протестировать лямбда-выражение для обработки исключений в примере приложения, выполните указанные ниже действия.
UseStatusCodePages
Вызовите UseStatusCodePages до ПО промежуточного слоя для обработки запросов. Например, вызовите UseStatusCodePages до ПО промежуточного слоя для статических файлов и конечных точек.
UseStatusCodePages обычно не применяется в рабочей среде, так как возвращает сообщение, бесполезное для пользователей.
Чтобы протестировать UseStatusCodePages в примере приложения, выполните указанные ниже действия.
ПО промежуточного слоя страниц кода состояния не перехватывает исключения. Чтобы предоставить настраиваемую страницу обработки ошибок, используйтестраницу обработчика исключений.
UseStatusCodePages со строкой формата
Чтобы настроить тип содержимого и указать текст ответа, используйте перегрузку UseStatusCodePages, которая принимает тип содержимого и строку формата.
В предыдущем коде <0>является заполнителем для кода ошибки.
UseStatusCodePages со строкой формата обычно не применяется в рабочей среде, так как возвращает сообщение, бесполезное для пользователей.
UseStatusCodePages с лямбда-выражением
Чтобы указать пользовательский код для обработки ошибок и отображения ответа, используйте перегрузку UseStatusCodePages, которая принимает лямбда-выражение.
UseStatusCodePages с лямбда-выражением обычно не применяется в рабочей среде, так как возвращает сообщение, бесполезное для пользователей.
UseStatusCodePagesWithRedirects
Шаблон URL-адреса может содержать заполнитель <0>для кода состояния, как показано в предыдущем коде. Если шаблон URL-адреса начинается с символа
заменяется PathBase приложения. При указании конечной точки в приложении создайте представление MVC или страницу Razor для конечной точки. Пример Razor Pages доступен в примере приложения в файле Pages/MyStatusCode.cshtml.
Этот метод обычно используется, если приложение:
UseStatusCodePagesWithReExecute
Этот метод обычно используется, если приложение:
Конечная точка, которая обрабатывает ошибку, может получать исходный URL-адрес, вызвавший ошибку, как показано в следующем примере:
Отключение страниц с кодами состояния
Чтобы отключить страницы кодов состояния для метода контроллера или действия MVC, используйте атрибут [SkipStatusCodePages].
Чтобы отключить страницы кодов состояния для конкретных запросов в методе обработчика Razor Pages или в контроллере MVC, используйте IStatusCodePagesFeature.
Код обработки исключений
Код на страницах обработки исключений также может создавать исключения. Рабочие страницы ошибок необходимо тщательно тестировать, чтобы они не создавали собственных исключений.
Заголовки ответов
После отправки заголовков для ответа происходит следующее:
Обработка исключений на сервере
Обработка исключений при запуске
Исключения, возникающие во время запуска приложения, могут обрабатываться только на уровне размещения. Узел можно настроить для перехвата ошибок при загрузке и записи подробных сведений об ошибках.
На уровне размещения может отображаться страница со сведениями о перехваченной ошибке при загрузке, только если ошибка произошла после привязки адреса и порта узла. При сбое привязки происходит следующее:
При работе в службах IIS (или Службе приложений Azure) либо IIS Expressмодуль ASP.NET Core возвращает ошибку 502.5 Process Failure (ошибка процесса), если процесс невозможно запустить. Для получения дополнительной информации см. Устранение неполадок ASP.NET Core в Службе приложений Azure и IIS.
Страница ошибок базы данных
Фильтр исключений для страницы разработчика базы данных AddDatabaseDeveloperPageExceptionFilter перехватывает исключения, относящиеся к базе данных, которые могут быть устранены с помощью миграций Entity Framework Core. При возникновении этих исключений формируется HTML-ответ с подробными сведениями о возможных действиях для устранения проблемы. Эта страница включается только в среде разработки. Следующий код был создан шаблонами страниц Razor в ASP.NET Core при указании отдельных учетных записей пользователей:
Фильтры исключений
В приложениях MVC фильтры исключений можно настраивать как глобально, так и для отдельных контроллеров или действий. В приложениях Razor Pages они могут быть настроены глобально или для модели страницы. Эти фильтры обрабатывают все необработанные исключения, которые возникают во время выполнения действия контроллера или другого фильтра. Для получения дополнительной информации см. Фильтры в ASP.NET Core.
Ошибки состояния модели
Сведения о том, как обрабатывать ошибки состояния модели, см. в статьях о привязке модели и проверке модели.
Дополнительные ресурсы
Авторы: Том Дикстра (Tom Dykstra) и Стив Смит (Steve Smith)
В этой статье рассматриваются основные методы обработки ошибок в веб-приложениях ASP.NET Core. Для веб-API см. раздел Обработка ошибок в веб-API ASP.NET Core.
Страница со сведениями об исключении для разработчика
Страница исключений для разработчика содержит подробные сведения об исключениях запросов. Шаблоны ASP.NET Core создают следующий код:
Приведенный выше код включает страницу исключений для разработчика при выполнении приложения в среде разработки.
Шаблоны помещают метод UseDeveloperExceptionPage перед всем ПО промежуточного слоя, чтобы исключения перехватывались в этом ПО.
Приведенный выше код включает страницу исключений для разработчика только при выполнении приложения в среде разработки. Подробные сведения об исключениях не должны быть общедоступными при выполнении приложения в рабочей среде. Дополнительные сведения о настройке среды см. в статье Использование нескольких сред в ASP.NET Core.
Страница исключений для разработчика содержит следующие сведения об исключении и запросе:
Страница обработчика исключений
Чтобы настроить пользовательскую страницу обработки ошибок для рабочей среды, используйте ПО промежуточного слоя для обработки исключений. ПО промежуточного слоя выполняет такие функции:
В следующем примере с помощью UseExceptionHandler добавляется ПО промежуточного слоя для обработки исключений в средах, не предназначенных для разработки.
Доступ к исключению
Используйте интерфейс IExceptionHandlerPathFeature, чтобы получить доступ к исключению и к пути исходного запроса в контроллере или на странице обработчика ошибок:
Не передавайте клиентам конфиденциальную информацию об ошибках. Сохранение ошибок создает риски для безопасности.
Чтобы активировать предыдущую страницу обработки исключений, задайте рабочую среду и принудительно вызовите исключение.
Лямбда-функция для обработчика исключений
Альтернативой пользовательской странице обработчика исключений является предоставление лямбда-функции для UseExceptionHandler. Использование лямбда-функции позволяет получить доступ к ошибке до возврата ответа.
Ниже приведен пример использования лямбда-функции для обработки исключений:
Не передавайте клиентам конфиденциальную информацию об ошибках из IExceptionHandlerFeature или IExceptionHandlerPathFeature. Сохранение ошибок создает риски для безопасности.
UseStatusCodePages
По умолчанию приложение ASP.NET Core не предоставляет страницы для кодов состояния HTTP, таких как код 404 Not Found (не найдено). Приложение возвращает код состояния без текста ответа. Чтобы указать коды состояния, используйте ПО промежуточного слоя страниц с кодами состояния.
Это ПО промежуточного слоя доступно в пакете Microsoft.AspNetCore.Diagnostics.
Вызовите UseStatusCodePages до ПО промежуточного слоя для обработки запросов (например ПО промежуточного слоя для статических файлов и ПО промежуточного слоя MVC).
UseStatusCodePages со строкой формата
Чтобы настроить тип содержимого и указать текст ответа, используйте перегрузку UseStatusCodePages, которая принимает тип содержимого и строку формата.
UseStatusCodePages с лямбда-выражением
Чтобы указать пользовательский код для обработки ошибок и отображения ответа, используйте перегрузку UseStatusCodePages, которая принимает лямбда-выражение.
UseStatusCodePagesWithRedirects
Шаблон URL-адреса может содержать заполнитель <0>для кода состояния, как показано в примере. Если шаблон URL-адреса начинается с символа
заменяется PathBase приложения. Если вы указываете на конечную точку в приложении, создайте представление MVC или страницу Razor для конечной точки. Пример Razor Pages доступен в примере приложения в файле Pages/StatusCode.cshtml.
Этот метод обычно используется, если приложение:
UseStatusCodePagesWithReExecute
Этот метод обычно используется, если приложение:
Конечная точка, которая обрабатывает ошибку, может получать исходный URL-адрес, вызвавший ошибку, как показано в следующем примере:
Отключение страниц с кодами состояния
Чтобы отключить страницы кодов состояния для конкретных запросов в методе обработчика Razor Pages или в контроллере MVC, используйте IStatusCodePagesFeature.
Код обработки исключений
Код на страницах обработки исключений может создавать исключения. Часто желательно, чтобы страницы ошибок в рабочей среде содержали только статическое содержимое.
Заголовки ответов
После отправки заголовков для ответа происходит следующее:
Обработка исключений на сервере
Помимо логики обработки исключений в приложении, реализация HTTP-сервера может выполнять ряд операций по обработке исключений. Если сервер перехватывает исключение перед отправкой заголовков ответа, он отсылает ответ 500 Internal Server Error (внутренняя ошибка сервера) без текста ответа. Если сервер перехватывает исключение после отправки заголовков ответа, он закрывает соединение. Запросы, не обработанные приложением, обрабатываются сервером. Все исключения, возникшие при обработке запроса серверов, обрабатываются с помощью механизма обработки исключений на сервере. Пользовательские страницы ошибок приложений, ПО промежуточного слоя для обработки исключений и фильтры не влияют на этот процесс.
Обработка исключений при запуске
Исключения, возникающие во время запуска приложения, могут обрабатываться только на уровне размещения. Узел можно настроить для перехвата ошибок при загрузке и записи подробных сведений об ошибках.
На уровне размещения может отображаться страница со сведениями о перехваченной ошибке при загрузке, только если ошибка произошла после привязки адреса и порта узла. При сбое привязки происходит следующее:
При работе в службах IIS (или Службе приложений Azure) либо IIS Expressмодуль ASP.NET Core возвращает ошибку 502.5 Process Failure (ошибка процесса), если процесс невозможно запустить. Для получения дополнительной информации см. Устранение неполадок ASP.NET Core в Службе приложений Azure и IIS.
Страница ошибок базы данных
Фильтры исключений
В приложениях MVC фильтры исключений можно настраивать как глобально, так и для отдельных контроллеров или действий. В приложениях Razor Pages они могут быть настроены глобально или для модели страницы. Эти фильтры обрабатывают все необработанные исключения, которые возникают во время выполнения действия контроллера или другого фильтра. Для получения дополнительной информации см. Фильтры в ASP.NET Core.
Фильтры исключений полезны при перехвате исключений, которые возникают в действиях MVC. Но эти фильтры не так гибки, как ПО промежуточного слоя для обработки исключений. Мы рекомендуем использовать ПО промежуточного слоя. Используйте фильтры, только если ошибки нужно обрабатывать по-разному в зависимости от выбранного действия MVC.
Ошибки состояния модели
Сведения о том, как обрабатывать ошибки состояния модели, см. в статьях о привязке модели и проверке модели.
WEB API
Введение в Web API
Web API представляет способ построения приложения ASP.NET, который специально заточен для работы в стиле REST (Representation State Transfer или «передача состояния представления»). REST-архитектура предполагает применение следующих методов или типов запросов HTTP для взаимодействия с сервером:
Создадим проект Web API. Для этого при создании проекта ASP.NET Core среди шаблонов выберем API :
Проект, который создается в Visual Studio, будет во многом напоминать проект для MVC за тем исключением, что в нем не будет представлений:
Кроме того, здесь есть модель WeatherForecast и типовой контроллер WeatherForecastController, который использует данную модель для обработки запросов:
Так, в данном случае метод Get() эмулирует прогноз погоды. В реальности в этом контроллере нет большого смысла, тем не менее мы можем запустить проект на выполнение и увидеть в браузере возвращаемые методом данные:
Из других особенностей проекта Web API следует отметить содержимое класса Startup:
Прежде всего, поскольку в данном случае не используются представления, то подключение в методе ConfigureServices() сервисов MVC, необходимых для работы контроллеров Web API производится с помощью метода services.AddControllers()
В итоге, как можно увидеть, большого смысла от данного типа проекта нет, равным образом мы могли бы взять пустой проект и добавить все необходимое сами.
Asp net core статусные коды
Начиная с версии ASP.NET Core 2.1 были добавлены новые возможности для работы с приложением по протоколу HTTPS. Рассмотрим их.
Отладка по https
Создадим новый проект ASP.NET Core по шаблону Empty.
При установке отметки после создания проекта он уже сконфигурирован на запуск через HTTPS. В частности, если мы зайдем в Visual Studio в свойства проекта на вкладку Debug, то мы увидим, что на этой вкладке установлено поле Enable SSL :
В процессе работы с проектом мы можем свободно включать или отключать это поле в зависимости от того, нужна ли нам отладка по Https.
Соответственно после запуска такого проекта он будет запускаться по протоколу HTTPS:
UseHttpsRedirection
Метод UseHttpsRedirection() объекта IApplicationBuilder добавляет для проекта переадресацию на тот же ресурс только по протоколу https (если приложение имеет поддержку SSL). В частности, изменим в классе Startup метод Configure следующим образом:
С помощью метода AddHttpsRedirection() мы можем настроить параметры переадресации. Например, изменим в классе Startup метод ConfigureServices следующим образом:
HttpsPort : устанавливает порт. Данная опция необходима, если порт отличается от стандартного 443. В данном случае это порт 44344. При запуске в Visual Studio через HTTPS данная опция не учитывается, поскольку порт устанавливает сама Visual Studio.
HTTP Strict Transport Security Protocol (HSTS)
Заголовок имеет три параметра:
max-age : задает максимальное действие заголовка (обязательный параметр)
includeSubDomains : если этот параметр установлен, то действие применяется ко всем поддоменам
preload : если этот параметр установлен, то будет использоваться специальный preload-список доменов, обращение к которым безопасно.
В ASP.NET Core 2.1+ С помощью метода UseHsts() объекта IApplicationBuilder мы можем отправить браузеру заголовок Strict-Transport-Security. Так, изменим метод Configure в классе Startup следующим образом:
Стоит отметить, что метод UseHsts вызывается, если только приложение уже развернуто для полноценного использования, потому что в процессе разработки использование данного метода может создавать неудобства, так как заголовки кэшируются.
Дополнительно, с помощью метода AddHsts в методе ConfigureServices мы можем настроить параметры заголовка Strict-Transport-Security. Так, изменим, к примеру, метод ConfigureServices в классе Startup следующим образом:
Preload : устанавливает параметр preload
MaxAge : устанавливает параметр max-age
IncludeSubDomains : устанавливает параметр includeSubDomains
ExcludedHosts : добавляет список доменов, которые надо исключить из действия заголовка
Тестируем веб-API ASP.NET Core
Привет, Хабровчане! Для будущих учащихся на курсе «C# ASP.NET Core разработчик» публикуем перевод полезной статьи.
При проектировании и разработке широкого спектра API с использованием ASP.NET Core 2.1 Web API важно понимать, что это только первый этап в создании продуктивного и стабильного решения. Наличие стабильной среды для вашего решения также очень важно. Ключ к отличному решению заключается не только в правильном построении API, но и в его тщательном тестировании, чтобы исключить возможность негативного опыта у пользователей во время использования вашего API.
Эта статья является продолжением моей предыдущей статьи для InfoQ под названием «Продвинутая архитектура веб-API ASP.NET Core». Не беспокойтесь, вам не нужно вникать в предыдущую статью, чтобы разобраться с тестированием в этой, но она может помочь вам лучше понять, как я спроектировал обсуждаемое здесь решение. На протяжении последних нескольких лет я много времени размышлял о тестировании, создавая API для клиентов. Знание архитектуры веб-API ASP.NET Core 2.1 может помочь и вам расширить ваше понимание.
Солюшн и весь код из примеров в этой статье можно найти в моем GitHub репозитории.
Букварь веб-API ASP.NET Core
Что такое модульное тестирование?
Для некоторых людей тестирование программного обеспечения может быть в новинку, но ничего сложного в нем нет. Начнем с модульного тестирования (или юнит-тестирования). Формальное определение из Википедии — это «процесс в программировании, позволяющий проверить на корректность отдельные модули исходного кода программы, наборы из одного или более программных модулей вместе с соответствующими управляющими данными, процедурами использования и обработки.» Я предпочитаю использовать более доступное определение: модульное тестирование используется для того, чтобы убедиться, что после добавления нового функционала или исправления багов код в вашем приложении работает должным образом. Мы тестируем небольшой фрагмент кода, чтобы убедиться, что он соответствуем нашим ожиданиям. Давайте посмотрим на образец модульного теста:
Хороший модульный тест состоит из трех частей. Первая — это Arrange часть, которая используется для подготовки любых ресурсов, которые могут понадобиться вашему тесту. В приведенном выше примере мне не требуется никакая подготовительная настройка, поэтому часть Arrange пуста (но я все еще оставляю комментарий к ней). Следующая часть, называемая Act, — это часть, в которой выполняется тестируемое действие. В этом примере я вызываю репозиторий данных для сущности типа Album, чтобы получить весь набор альбомов из источника данных, который использует репозиторий. В последней части теста мы убеждаемся или утверждаем (Assert) что результат выполненного действия был правильным. В этом тесте я проверяю, что получил только один альбом из репозитория данных.
Рисунок 1: Создание нового Unit Test проекта в Visual Studio 2017
Теперь давайте перейдем к модульному тестированию вашего веб-API ASP.NET Core.
Как следует тестировать веб-API?
Я большой сторонник использования модульного тестирования для поддержания стабильности и надежности API для ваших пользователей. Но я подхожу с умом к тому, как я использую свои модульные тесты и что тестирую. Моя философия заключается в том, что вы должны реализовать модульное тестирование своего проекта ровно настолько, насколько это необходимо. Что я имею в виду? Я могу получить много гневных комментариев за эту точку зрения, но меня не слишком заботит 100%-ное покрытие тестами. Считаю ли я, что нам нужны тесты, которые охватывают важные части API и изолируют каждую область независимо, чтобы гарантировать, что контракт каждого сегмента кода соблюден? Конечно! Это именно то, как я делаю и что хочу обсудить.
Поскольку наш демо проект Chinook.API очень легковесный, и для него можно провести интеграционное тестирование (об этом чуть позже), я обнаружил, что больше всего концентрируюсь на модульных тестах в моих Domain и Data проектах. Я не буду вдаваться в подробности о том, как вам следует проводите модульное тестирование (поскольку эта тема выходит за рамки этой статьи). Я хочу, чтобы вы протестировали как можно больше ваших Domain и Data проектов, используя данные, которые не зависят от вашей производственной базы данных. Это следующая тема, которую мы рассмотрим, под названием «Моки данных и объектов».
Зачем использовать моки данных/объектов в ваших модульных тестах?
Мы рассмотрели, что и зачем нам нужно для модульного тестирования. Важно также понимать, как правильно выполнить модульное тестирование кода веб-API ASP.NET Core. Данные являются ключом к тестированию вашего API. Вам необходимо иметь предсказуемый набор данных, который вы можете протестировать. Вот почему я бы не рекомендовал использовать производственные данные или любые данные, которые могут изменяться со временем без вашего ведома. Нам нужен стабильный набор данных, чтобы убедиться, что все модульные тесты выполняются и подтверждают выполнение контракта между сегментом кода и тестом. В качестве примера, когда я тестирую проект Chinook.Domain для получения альбома (Album) с ID 42, я хочу быть уверен, что он существует и имеет ожидаемые от него детали, такие как имя альбома, и он связан с исполнителем (Artist). Я также хочу быть уверенным, что когда я получаю набор альбомов из источника данных, я получаю ожидаемую форму и размер, которые соответствуют написанному мной модульному тесту.
Многие коллеги используют термин «моки» (mocks или заглушки) для обозначения этого типа данных. Есть много способов сгенерировать моки данных для модульных тестов, и я надеюсь, что вы создадите как можно более «реальный» набор данных. Чем лучше ваши данные, которые вы создадите для своих тестов, тем лучше будет ваш тест. Я бы посоветовал вам в первую очередь убедиться, что ваши данные свободны от проблем с приватностью и не содержат личных или конфиденциальных данных вашей компании или вашего клиента.
Чтобы удовлетворить нашу потребность в чистых, стабильных данных, я создаю уникальные проекты, которые инкапсулируют моки данных для моих Unit Test проектов. В целях наглядности назовем мой проект с моками Chinook.MockData (как вы можете видеть в исходном демонстрационном коде). Мой MockData проект почти идентичен моему обычному проекту Chinook.Data. Он имеет одинаковое количество репозиториев данных, и каждый из них реализует одни и те же интерфейсы. Я хочу, чтобы MockData проект хранился в контейнере внедрения зависимостей (Dependency Injection — DI), чтобы проект Chinook.Domain мог использовать его так же, как проект Chinook.Data, подключенный к источнику производственных данных. Вот за что я люблю внедрение зависимостей. Это позволяет мне переключать Data проекты в конфигурации без каких-либо изменений в коде.
Интеграционное тестирование: а это еще что за вид тестирования веб-API?
После того, как мы выполнили и проверили модульные тесты для нашего веб-API ASP.NET Core, мы рассмотрим другой тип тестирования. Я использую модульное тестирование, чтобы проверить и подтвердить ожидания в отношении внутренних компонентов решения. Когда мы удовлетворены качеством внутренних тестов, мы можем перейти к тестированию API из внешнего интерфейса, что и называется интеграционным тестированием.
Интеграционные тесты следует писать и выполнять после завершения работы над всеми компонентами, чтобы ваше API могло быть использовано с правильным HTTP-ответом для проверки. Я смотрю на модульные тесты как на тестирование независимых и изолированных сегментов кода, в то время как интеграционные тесты используются для тестирования всей логики каждого API на моем HTTP эндпоинте. Это тестирование будет исследовать весь рабочий процесс API от контроллеров API проектов до супервизоров Domain проектов и, наконец, репозиториев Data проектов (и весь путь обратно до ответа).
Создание проекта для интеграционного тестирования
Рисунок 2: Добавление пакета NuGet Microsoft.AspNetCore.TestHost
Теперь мы можем перейти к созданию нашего первого интеграционного теста для внешней проверки нашего API.
Создание вашего первого интеграционного теста
Чтобы начать внешнее тестирование всех API в нашем солюшене, я собираюсь создать новую папку под названием API, в которой будут храниться наши тесты. Я также создам новый тестовый класс для каждого из типов сущностей (Entity) в нашем домене API. Наш первый интеграционный тест будет покрывать тип сущности «Album».
Создайте в папке API новый класс с именем AlbumAPITest.cs. Теперь мы добавим в наш файл следующие пространства имен.
Рисунок 3: Интеграционный тест с использованием директив
Рисунок 4: Наш первый интеграционный тест для получения всех альбомов
Помимо кода конструктора, на рисунке 4 также показан код для нашего первого интеграционного теста. Метод AlbumGetAllTestAsync проверит, работает ли вызов из API для получения всех альбомов. Как и в предыдущем разделе, где мы обсуждали модульное тестирование, логика нашего интеграционного тестирования также использует паттерн Arrange/Act/Assert. Сначала мы создаем объект HttpRequestMessage с HTTP-командой, предоставляемой в виде переменной из аннотации InlineData, и сегментом URI, который представляет вызов для запроса всех альбомов («/api/Album/»). Затем мы попросим _client HttpClient отправить HTTP-запрос, и, наконец, мы проверим, соответствует ли HTTP-ответ нашим ожиданиям, которые в данном случае — 200 OK. На рисунке 4 я показал два способа проверить наш вызов API. Вы можете использовать любой из них, но я предпочитаю второй способ, поскольку он позволяет мне использовать тот же шаблон для проверки ответов для определенных кодов HTTP-ответов.
Мы также можем создавать интеграционные тесты, которые должны проверять определенные ключи сущностей из нашего API. Для этого типа тестов нам нужно добавить дополнительное значение в аннотацию InlineData, которая будет передаваться через параметры метода AlbumGetTestAsync. Наш новый тест следует той же логике и использует те же ресурсы, что и предыдущий, но мы еще должны передать ключ сущности в сегменте URI для объекта HttpRequestMessage. Код вы можете увидеть на рисунке 5.
Рисунок 5: Второй интеграционный тест для сущности Album
Рисунок 6: Выполнение интеграционных тестов в Visual Studio 2017