Создание API на ASP.NET с MongoDB: от проекта до деплоя
Быстрые ссылки
Создание проекта
Подключение к базе данных
Создание CRUD-сервиса
Настройка API-контроллера
О чём эта статья
Это практическое руководство по созданию простого REST API на ASP.NET Core с использованием MongoDB. Мы пройдём через создание проекта в Visual Studio, определение модели данных, конфигурацию подключений, реализацию сервиса уровня данных (CRUD), создание контроллера, базовое тестирование и выпуск в продакшен. Также включены рекомендации по безопасности, тестированию, наблюдаемости, бэкапу и миграции.
Кому полезно: разработчикам .NET, инженерам DevOps, тестировщикам и архитектам, которые хотят быстро поднять API на ASP.NET с документной базой данных.
Important: примеры ориентированы на локальную разработку. Для продакшена добавьте шифрование секретов, мониторинг и безопасную конфигурацию.
1. Создание проекта
Для удобства используем Visual Studio: она поставляется с готовыми шаблонами и интеграцией .NET. Создайте новое приложение — шаблон “ASP.NET Core Web Application” и выберите профиль API.
Дайте проекту имя и выберите режим “API” — нам не нужен фронтенд на Razor Pages.
Запустив проект (кнопка запуска с профилем IIS Express), вы увидите стартовую страницу с заглушкой (например, демонстрационные данные о погоде). Это стандартный скелет, на котором мы будем строить сервис.
Краткое определение: ASP.NET Core — кроссплатформенный фреймворк для создания веб-API и веб-приложений на C# и .NET.
2. Подключение к базе данных
Хорошая практика — разделять логику обработки HTTP-запросов (контроллеры) и доступ к данным (сервис/репозиторий). Мы создадим сервис данных, который инкапсулирует доступ к MongoDB, и контроллер, который будет вызывать сервис.
- Установите пакет драйвера MongoDB для .NET: в NuGet Manager найдите и установите пакет MongoDB.Driver.
Почему MongoDB? Документные БД естественно соответствуют коллекциям объектов (List
- Создайте папку Models в корне проекта. В ней определим схему сущности User и класс настроек подключения.
Пример модели User (файл User.cs):
using MongoDB.Bson;
using MongoDB.Bson.Serialization.Attributes;
using System;
namespace ExampleService.Models
{
public class User
{
[BsonId]
[BsonRepresentation(BsonType.ObjectId)]
public string Id { get; set; }
[BsonElement("Name")]
public string Name { get; set; }
public string Email { get; set; }
// дополнительные поля по необходимости
}
}Пояснение: атрибуты [BsonId] и [BsonRepresentation(BsonType.ObjectId)] позволяют использовать строковый Id в коде, тогда как MongoDB хранит его как ObjectId.
- Класс настроек подключения (DatabaseSettings.cs):
namespace ExampleService.Models
{
public class ExampleDatabaseSettings : IExampleDatabaseSettings
{
public string ExampleCollectionName { get; set; }
public string ConnectionString { get; set; }
public string DatabaseName { get; set; }
}
public interface IExampleDatabaseSettings
{
string ExampleCollectionName { get; set; }
string ConnectionString { get; set; }
string DatabaseName { get; set; }
}
}- Добавьте настройки в appsettings.json:
"ExampleDatabaseSettings": {
"ExampleCollectionName": "Users",
"ConnectionString": "mongodb://localhost:27017",
"DatabaseName": "Example"
}Создайте базу данных Example и коллекцию Users в MongoDB (локально или удалённо).
- Зарегистрируйте настройки в Startup.cs (или Program.cs для .NET 6+). В методе ConfigureServices добавьте привязку конфигурации и регистрацию через DI:
public void ConfigureServices(IServiceCollection services)
{
services.Configure(
Configuration.GetSection(nameof(ExampleDatabaseSettings)));
services.AddSingleton(sp =>
sp.GetRequiredService>().Value);
services.AddControllers();
} Если у вас .NET 6/7 с минимальным хостом, подобная конфигурация выполняется в Program.cs через builder.Services.Configure<…>().
Notes: убедитесь, что у вас подключён namespace ExampleService.Models в Startup/Program.
3. Написание CRUD-сервиса для работы с базой
Сервис инкапсулирует IMongoCollection
Пример сервиса (ExampleService.cs):
using ExampleService.Models;
using MongoDB.Driver;
using System.Collections.Generic;
using System.Linq;
namespace ExampleService.Services
{
public class ExampleService
{
private readonly IMongoCollection _users;
public ExampleService(IExampleDatabaseSettings settings)
{
var client = new MongoClient(settings.ConnectionString);
var database = client.GetDatabase(settings.DatabaseName);
_users = database.GetCollection(settings.ExampleCollectionName);
}
public List Get() =>
_users.Find(user => true).ToList();
public User Get(string id) =>
_users.Find(user => user.Id == id).FirstOrDefault();
public User Create(User user)
{
_users.InsertOne(user);
return user;
}
public void Update(string id, User userIn) =>
_users.ReplaceOne(user => user.Id == id, userIn);
public void Remove(User userIn) =>
_users.DeleteOne(user => user.Id == userIn.Id);
public void Remove(string id) =>
_users.DeleteOne(user => user.Id == id);
}
} Пояснения:
- IMongoCollection
— потокобезопасный объект коллекции; можно выполнять LINQ-совместимые запросы. - Методы простые для наглядности; в реальном проекте добавьте валидацию и обработку ошибок.
- Зарегистрируйте сервис в DI в Startup/Program:
services.AddSingleton(); 4. Настройка API-контроллера
Visual Studio упрощает создание контроллера: правой кнопкой по папке Controllers -> Add -> Controller.
Пример контроллера (ExampleController.cs):
using ExampleService.Models;
using ExampleService.Services;
using Microsoft.AspNetCore.Mvc;
using System.Collections.Generic;
[Route("api/[controller]")]
[ApiController]
public class ExampleController : ControllerBase
{
private readonly ExampleService _exampleService;
public ExampleController(ExampleService exampleService)
{
_exampleService = exampleService;
}
[HttpGet]
public ActionResult> Get()
{
return _exampleService.Get();
}
[HttpGet("{id}", Name = "GetUser")]
public ActionResult Get(string id)
{
var user = _exampleService.Get(id);
if (user == null)
{
return NotFound();
}
return user;
}
[HttpPost]
public ActionResult Create(User userIn)
{
_exampleService.Create(userIn);
return CreatedAtRoute("GetUser", new { id = userIn.Id.ToString() }, userIn);
}
[HttpPut("{id}")]
public IActionResult Update(string id, User userIn)
{
var existing = _exampleService.Get(id);
if (existing == null)
{
return NotFound();
}
_exampleService.Update(id, userIn);
return NoContent();
}
[HttpDelete("{id}")]
public IActionResult Delete(string id)
{
var user = _exampleService.Get(id);
if (user == null)
{
return NotFound();
}
_exampleService.Remove(id);
return NoContent();
}
} Пояснение: ActionResult
5. Локальное тестирование и отладка
- Запустите проект через IIS Express или Kestrel.
- Проверьте маршруты через Postman, curl или встроенный Swagger (если подключили Swashbuckle).
- По умолчанию корневая точка может быть стартовой заглушкой — измените Debug Launch URL в Project > Properties > Debug.
Примеры запросов:
- GET /api/example — получить всех пользователей
- GET /api/example/{id} — получить пользователя по id
- POST /api/example — создать пользователя (тело JSON)
- PUT /api/example/{id} — обновить
- DELETE /api/example/{id} — удалить
6. Деплой и сборка в продакшен
Для публикации используйте Build > Publish. Можно выбрать File System, Docker или облако. В опциях укажите:
- Self-contained или framework-dependent build
- Однофайловую публикацию (single file) при необходимости
- Целевую Runtime Identifier (например, linux-x64) если ориентируетесь на Linux-сервер
Если публикуете на Linux и используете .csproj, добавьте:
linux-x64 Для контейнеризации используйте Dockerfile с базовым образом mcr.microsoft.com/dotnet/aspnet или sdk для сборки. CI/CD: добавьте шаги сборки, тестов, security-scan и деплоя.
7. Безопасность и аутентификация
Это руководство демонстрационное, поэтому API не защищён. В реальном приложении нужно:
- Включить HTTPS и принудительный редирект на TLS
- Настроить аутентификацию (JWT для API). В ASP.NET есть встроенная поддержка JWT через Microsoft.AspNetCore.Authentication.JwtBearer
- Ограничивать права доступа ролями или политиками (Authorization)
- Ограничивать CORS только доверенными доменами
- Хранить строки подключения и секреты в безопасном хранилище (Azure Key Vault, AWS Secrets Manager, HashiCorp Vault или в User Secrets для разработки)
- Логировать попытки доступа и применять rate limiting
Пример добавления JWT (вкратце):
- Добавьте пакет Microsoft.AspNetCore.Authentication.JwtBearer
- В ConfigureServices добавьте JWT-схему и параметры валидации ключа/issuer/audience
- Пометьте защищённые контроллеры [Authorize]
Security hardening: шифрование полей чувствительных данных на уровне приложения, включение мониторинга инцидентов, аудит доступа к данным.
8. Наблюдаемость, логирование и бэкап
- Логирование: используйте Serilog или Microsoft.Extensions.Logging с выводом в файл, ElasticSearch или облачные сервисы.
- Метрики: Prometheus + Grafana или Application Insights.
- Бэкап MongoDB: регулярные дампы mongodump или облачные механизмы бэкапа.
- Репликация: используйте replica set для высокой доступности.
9. Производительность и масштабирование
- Добавляйте индексы в MongoDB по полям, используемым в фильтрах/сортировках.
- Пагинация вместо получения всех документов.
- Пакетные операции BulkWrite для массовых вставок/обновлений.
- Кеширование часто запрашиваемых данных (Redis).
10. Тестирование и приемка
Минимальный набор тестов:
- Unit-тесты для логики сервиса (мок IMongoCollection / MongoDB Driver адаптер)
- Интеграционные тесты с тестовой базой (контейнер MongoDB или in-memory тестовая БД)
- Контрактные тесты для API (проверка ответов и схемы JSON)
Примеры тест-кейсов:
- Создать пользователя — ожидать 201 и корректный Location
- Получить несуществующий id — ожидать 404
- Обновить пользователя — ожидать 204 и корректные изменения
- Удалить пользователя — ожидать 204 и невозможность получить ресурс потом
Критерии приёмки:
- Все основные CRUD-эндпойнты возвращают ожидаемые коды и данные
- Логирование запросов присутствует
- Секьюрность: хотя бы базовая проверка JWT и HTTPS
11. Поддержка и миграция данных
- Документные БД не имеют схемы в строгом виде — контролируйте изменения модели через миграционные скрипты приложения или миграции на уровне данных.
- Для миграции полей: пишите скрипты трансформации, запускайте их под контролем (например, в отдельном миграционном сервисе).
- Версионирование API: добавляйте версию в маршрут (/api/v1/…), чтобы не ломать клиентов при рефакторинге.
12. Альтернативные подходы
- Реляционная БД + EF Core: если требуются транзакции и строгая схема — используйте SQL Server/PostgreSQL с EF Core.
- DDD / Repository + Unit of Work: для сложных предметных областей применяйте слои абстракции.
- Использование MongoDB BsonClassMap или подобных инструментов для маппинга сложных типов.
13. Когда этот подход не подходит
Counterexamples:
- Нужны сложные JOIN-операции и строгая целостность ссылок — лучше реляционная БД.
- Требуется ACID-транзакция на уровне множества коллекций (хотя MongoDB поддерживает многоадресные транзакции в некоторых сценариях, это не всегда удобно).
- Высокие требования к аналитике и OLAP-запросам — рассмотреть отдельный аналитический хранилище.
14. Рекомендации по локализации и соответствию GDPR
Если приложение хранит персональные данные (имена, email, IP и т.д.), учтите:
- Минимизируйте собираемые данные и храните их не дольше, чем нужно.
- Обеспечьте возможность удаления или анонимизации данных по запросу пользователя.
- Шифруйте персональные данные в состоянии покоя и при передаче.
- Документируйте основания обработки данных и уведомляйте пользователей.
Privacy notes: используйте механизмы удаления и лога изменений для аудита. Храните резервные копии в зашифрованном виде.
15. Чек-листы и роли
Разработчик:
- Создать модель и настройки
- Реализовать сервис CRUD
- Написать unit-тесты
- Настроить логирование
DevOps:
- Настроить CI/CD сборку и тесты
- Обеспечить безопасное хранение секретов
- Настроить бэкап MongoDB и мониторинг
QA:
- Провести API-тесты (позитивные и негативные)
- Проверить сценарии авторизации
- Проверить устойчивость при отказах БД
16. Шаблоны и сниппеты
appsettings.json (фрагмент):
{
"ExampleDatabaseSettings": {
"ExampleCollectionName": "Users",
"ConnectionString": "mongodb://localhost:27017",
"DatabaseName": "Example"
}
}Dockerfile (пример для ASP.NET Core):
FROM mcr.microsoft.com/dotnet/aspnet:6.0 AS base
WORKDIR /app
EXPOSE 80
FROM mcr.microsoft.com/dotnet/sdk:6.0 AS build
WORKDIR /src
COPY ["MyProject.csproj", "./"]
RUN dotnet restore "MyProject.csproj"
COPY . ./
RUN dotnet publish "MyProject.csproj" -c Release -o /app/publish
FROM base AS final
WORKDIR /app
COPY --from=build /app/publish ./
ENTRYPOINT ["dotnet", "MyProject.dll"]CI-пайплайн (коротко):
- Checkout
- Restore и сборка
- Unit-тесты
- Static analysis / security scan
- Publish артефактов
- Deploy в staging, run smoke tests
- Promote to production
17. Примеры ошибок и пути их решения
- Не удаётся подключиться к MongoDB — проверьте ConnectionString, доступность порта и firewall.
- NullReference в сервисе — проверьте регистрацию сервиса в DI.
- ID не конвертируется — убедитесь, что используете [BsonRepresentation(BsonType.ObjectId)].
18. Рекомендации по дальнейшему расширению
- Добавьте DTO и AutoMapper для отделения внешней представления данных от внутренней модели.
- Внедрите пагинацию и фильтрацию для GET-методов.
- Добавьте rate limiting и защиту от DDoS.
19. Полезная справка и термины
1-line glossary:
- API — интерфейс для взаимодействия через HTTP.
- DI — внедрение зависимостей, механизм конфигурации сервисов в ASP.NET.
- DTO — объект передачи данных.
- Bson — формат BSON, используемый MongoDB для хранения документов.
Fact box:
- MongoDB обычно хранит идентификатор документа как ObjectId, но в C# можно представлять его строкой с помощью BsonRepresentation.
- IMongoCollection безопасен для многопоточных операций.
Краткое резюме
- Создайте проект API в Visual Studio.
- Подключите MongoDB драйвер и определите модель и настройки.
- Реализуйте сервис CRUD и зарегистрируйте его в DI.
- Создайте контроллеры и протестируйте локально.
- Добавьте безопасность, логирование и мониторинг перед деплоем.
Если нужны примеры для .NET 6 minimal APIs, Docker Compose с MongoDB или шаблоны CI для GitHub Actions — скажите, и я подготовлю их отдельно.
Похожие материалы
RDP: полный гид по настройке и безопасности
Android как клавиатура и трекпад для Windows
Советы и приёмы для работы с PDF
Calibration в Lightroom Classic: как и когда использовать
Отключить Siri Suggestions на iPhone
