创建 RESTful API

Overview

在本教程中，您可以学习；了解如何创建带有端点的 RESTful API ，这些端点跨MongoDB Atlas 群集中的集合执行基本的创建、读取、更新和删除(增删改查 ) 操作。

先决条件

在开始本教程之前，请执行以下操作：

设置MongoDB Atlas帐户，并部署和配置 M0 或更高级别的集群。要查看说明，请参阅MongoDB入门指南。
在计算机上安装.NET 6.0 或更高版本。要安装.NET，请访问Microsoft .NET下载页面。

注意

语言兼容性

本教程使用.NET Core 8.0，但您可以使用.NET 6.0 之后的任何版本。

设置您的项目

在终端中运行以下命令，创建使用 Web应用程序模板的新.NET Core项目：

dotnet new webapi -o MongoExamplecd MongoExample

要将.NET/ C#驱动程序作为依赖项添加到项目中，运行以下命令：

dotnet add package MongoDB.Driver

前面的命令为.NET Core 创建一个名为 MongoExample 的新 Web应用程序项目，并安装最新的.NET/ C#驱动程序。模板项目包括一些样板文件，您可以修改这些文件以实现RESTful API。

设计文档模型和数据库服务

在本部分中，您可以创建和配置MongoDB服务，并为 RESTful API定义数据模型。

创建 MongoDB 服务

创建 MongoDBSettings 类

MongoDB服务负责建立连接并直接处理MongoDB中的文档。在您的项目中，创建一个名为 Models 的文件夹。在 Models 文件夹中，创建一个名为 MongoDBSettings.cs 的新文件。在此文件中，添加以下代码：

namespace MongoExample.Models;
public class MongoDBSettings {
    public string ConnectionURI { get; set; } = null!;    public string DatabaseName { get; set; } = null!;    public string CollectionName { get; set; } = null!;
}

前面的代码定义了一个名为 MongoDBSettings 的类，其中包含有关连接、数据库名称和集合名称的信息。

更新 appsettings.json文件

您可以在项目的 appsettings.json文件的 MongoDBSettings 类中定义的类字段中找到存储的数据。打开此文件并添加以下配置：

{   "Logging": {      "LogLevel": {      "Default": "Information",      "Microsoft.AspNetCore": "Warning"      }   },   "AllowedHosts": "*",   "MongoDB": {      "ConnectionURI": "<Atlas connection string>",      "DatabaseName": "sample_mflix",      "CollectionName": "playlist"      }}

本教程使用 sample_mflix数据库和 playlist集合。将 <Atlas connection string> 占位符替换为MongoDB Atlas连接字符串。有关如何查找连接字符串的更多信息，请参阅Atlas文档中的连接到集群教程。

创建服务

在您的项目中，创建一个名为 Services 的文件夹。在 Services 文件夹中，创建名为 MongoDBService.cs 的新文件并添加以下代码：

using MongoExample.Models;using Microsoft.Extensions.Options;using MongoDB.Driver;using MongoDB.Bson;
namespace MongoExample.Services;
public class MongoDBService {
    private readonly IMongoCollection<Playlist> _playlistCollection;
    public MongoDBService(IOptions<MongoDBSettings> mongoDBSettings) {        MongoClient client = new MongoClient(mongoDBSettings.Value.ConnectionURI);        IMongoDatabase database = client.GetDatabase(mongoDBSettings.Value.DatabaseName);        _playlistCollection = database.GetCollection<Playlist>(mongoDBSettings.Value.CollectionName);    }
    public async Task<List<Playlist>> GetAsync() { }    public async Task CreateAsync(Playlist playlist) { }    public async Task AddToPlaylistAsync(string id, string movieId) {}    public async Task DeleteAsync(string id) { }
}

前面的代码定义了一个名为 MongoDBService 的类，其中包含空异步函数。在本教程中，您将在创建端点时向这些函数添加代码。您在 appsettings.json文件中配置的设置将设立变量。

将服务连接到应用程序

打开 Program.cs文件并将以下代码添加到文件顶部：

using MongoExample.Models;using MongoExample.Services;
var builder = WebApplication.CreateBuilder(args);
builder.Services.Configure<MongoDBSettings>(builder.Configuration.GetSection("MongoDB"));builder.Services.AddSingleton<MongoDBService>();

在前面的代码中，GetSection() 函数从 appsettings.json文件的 MongoDB字段中提取设置。

提示

如果模板代码已具有 builder 变量，请勿添加两次。

创建文档模型

现在服务已设立，您可以为集合创建数据模型。

在 Models 文件夹中，创建名为 Playlist.cs 的新文件并添加以下代码：

using MongoDB.Bson;using MongoDB.Bson.Serialization.Attributes;using System.Text.Json.Serialization;
namespace MongoExample.Models;
public class Playlist {
    [BsonId]    [BsonRepresentation(BsonType.ObjectId)]    public string? Id { get; set; }
    public string username { get; set; } = null!;
    [BsonElement("items")]    [JsonPropertyName("items")]    public List<string> movieIds { get; set; } = null!;
}

在前面的代码中，Id字段被序列化为 _id字段中的 ObjectId。该字段在应用程序中表示为字符串。

movieIds字段被序列化为 items。发送或接收JSON值时，该字段也命名为 items 而不是 movieIds。

如果计划让本地类字段直接匹配文档字段，则无需定义自定义映射。示例，前面代码中的 username字段没有自定义映射。它在C#、 JSON和MongoDB中称为 be username。

完成此步骤后，您的集合就拥有了MongoDB服务和文档模型，可以与.NET Core 一起使用。

构建增删改查端点

要为此应用程序创建增删改查端点，必须更新项目中的两个不同文件。在本节中，您可以学习；了解如何在控制器中定义端点并在服务中更新相应的工作。

注意

数据验证

在此示例项目中，没有针对HTTP请求的数据验证。

构建终结点以与 MongoDB 交互

创建控制器

在您的项目中，创建一个名为 Controllers 的文件夹。在 Controllers 文件夹中，创建名为 PlaylistController.cs 的新文件并添加以下代码：

using System;using Microsoft.AspNetCore.Mvc;using MongoExample.Services;using MongoExample.Models;
namespace MongoExample.Controllers; 
[Controller][Route("api/[controller]")]public class PlaylistController: Controller {        private readonly MongoDBService _mongoDBService;
    public PlaylistController(MongoDBService mongoDBService) {        _mongoDBService = mongoDBService;    }
    [HttpGet]    public async Task<List<Playlist>> Get() {}
    [HttpPost]    public async Task<IActionResult> Post([FromBody] Playlist playlist) {}
    [HttpPut("{id}")]    public async Task<IActionResult> AddToPlaylist(string id, [FromBody] string movieId) {}
    [HttpDelete("{id}")]    public async Task<IActionResult> Delete(string id) {}
}

PlaylistController 类包含一个构造函数方法，用于获取对单例服务类的访问权限。然后，该控制器有一系列端点。

通过 POST 端点添加数据

GoServices/MongoDBService.cs 并更新CreateAsync 函数以使用以下代码：

public async Task CreateAsync(Playlist playlist) {   await _playlistCollection.InsertOneAsync(playlist);  return;}

前面的代码在服务的构造函数方法中设置了 _playlistCollection。此操作可让您的应用程序使用 InsertOneAsync 方法，该方法接受并插入传递的 Playlist 变量。

要完成 POST 端点的创建，GoControllers/PlaylistController.cs文件并更新Post 方法以使用以下代码：

[HttpPost]public async Task<IActionResult> Post([FromBody] Playlist playlist) {  await _mongoDBService.CreateAsync(playlist);  return CreatedAtAction(nameof(Get), new { id = playlist.Id }, playlist);}

执行 POST 端点时，应用程序会从 request 获取.NET Core 解析的 Playlist对象，并将其传递给服务中的 CreateAsync 函数。插入后，代码会返回有关交互的信息。

通过 GET 端点读取数据

GoServices/MongoDBService.cs 并更新GetAsync 函数以使用以下代码：

public async Task<List<Playlist>> GetAsync() {   return await _playlistCollection.Find(new BsonDocument()).ToListAsync();}

上述代码中的 Find 操作会返回集合中存在的所有文档。

要完成 GET 端点的创建，GoControllers/PlaylistController.cs文件并更新Get 方法以使用以下代码：

[HttpGet]public async Task<List<Playlist>> Get() {  return await _mongoDBService.GetAsync();}

使用 PUT 端点更新数据

GoServices/MongoDBService.cs 并更新AddToPlaylistAsync 函数以使用以下代码：

public async Task AddToPlaylistAsync(string id, string movieId) {  FilterDefinition<Playlist> filter = Builders<Playlist>.Filter.Eq("Id", id);  UpdateDefinition<Playlist> update = Builders<Playlist>.Update.AddToSet<string>("movieIds", movieId);  await _playlistCollection.UpdateOneAsync(filter, update);  return;}

前面的代码设置了一个匹配过滤，以确定哪个或哪些文档接收更新，在本例中，即向播放列表添加一个项目。该代码基于唯一的 Id字段进行匹配。然后，代码定义更新条件，这是一个 AddtoSet 操作，仅当大量中尚不存在项目时才将其添加到大量中。

即使匹配过滤返回多个匹配项，UpdateOneAsync 方法也仅对文档进行更新。

要完成 PUT 端点的创建，GoControllers/PlaylistController.cs文件并更新AddToPlaylist 函数以使用以下代码：

[HttpPut("{id}")]public async Task<IActionResult> AddToPlaylist(string id, [FromBody] string movieId) {      await _mongoDBService.AddToPlaylistAsync(id, movieId);  return NoContent();}

使用 DELETE 端点删除数据

GoServices/MongoDBService.cs 并更新DeleteAsync 函数以使用以下代码：

public async Task DeleteAsync(string id) {  FilterDefinition<Playlist> filter = Builders<Playlist>.Filter.Eq("Id", id);  await _playlistCollection.DeleteOneAsync(filter);  return;}

前面的代码根据过滤条件删除单个文档，该筛选条件与 Id字段的唯一值匹配。

要完成 DELETE 端点的创建，GoControllers/PlaylistController.cs文件并更新Delete 函数以使用以下代码：

[HttpDelete("{id}")]public async Task<IActionResult> Delete(string id) {  await _mongoDBService.DeleteAsync(id);  return NoContent();}

在此步骤之后，您就拥有了 RESTful API的设立增删改查端点。

测试您的API端点

创建端点后，可以使用.NET Core应用程序模板包含的 Swagger用户界面对其进行测试。为此，GoProgram.cs文件并从模板项目中删除与 WeatherForecast 类相关的所有代码。更新文件以包含以下代码：

// Adds services to the container to configure Swagger/OpenAPIbuilder.Services.AddEndpointsApiExplorer();builder.Services.AddSwaggerGen();
var app = builder.Build();
// Configures the HTTP request pipelineif (app.Environment.IsDevelopment()){    app.UseSwagger();    app.UseSwaggerUI();}
app.UseHttpsRedirection();
// Maps the endpoints for the APIapp.MapGet("/api/playlists", async (MongoDBService mongoDBService) =>{    var playlists = await mongoDBService.GetAsync();    return playlists;}).WithName("GetPlaylists").WithOpenApi();
app.MapPost("/api/playlists", async (MongoDBService mongoDBService, Playlist newPlaylist) =>{    await mongoDBService.CreateAsync(newPlaylist);    return Results.Created($"/playlists/{newPlaylist.Id}", newPlaylist);}).WithName("CreatePlaylist").WithOpenApi();
app.MapPut("/api/playlists/{id}", async (MongoDBService mongoDBService, string id, string movieId) =>{    await mongoDBService.AddToPlaylistAsync(id, movieId);    return Results.NoContent();}).WithName("AddMovieToPlaylist").WithOpenApi();
app.MapDelete("/playlists/{id}", async (MongoDBService mongoDBService, string id) =>{    await mongoDBService.DeleteAsync(id);    return Results.NoContent();}).WithName("DeletePlaylist").WithOpenApi();
app.Run();

您可以将项目模板中的任何重复代码替换为前面的代码。

执行以下命令运行应用程序：

dotnet run

应用程序启动后，打开浏览器并Go已配置的本地主机URL以访问权限Swagger用户界面，示例http://localhost:5000/swagger。下图显示了 Swagger用户界面的显示方式：

RESTful API的 Swagger用户界面。

您可以通过单击每个端点上的 Try it out 按钮来测试应用程序。要开始，Go/api/playlists POST 端点以向数据库添加一些数据。添加以下示例数据：

{   "username": "testuser",   "items": [      "1234",      "5678"   ]}

运行此请求以将数据插入数据库。然后，您可以GoGET 端点，查看刚刚插入的数据。您还可以测试 PUT 和 DELETE 端点以更新和删除数据。

后续步骤

要学习；了解有关本教程中讨论的操作的更多信息，请参阅以下指南：