ASP.NET Core API POST 创建详解｜DTO、AutoMapper 与 EF Core 实战

1. 引言

在现代 Web 开发中，“创建数据”是 API 最基本，也是最常用的操作之一。对于 ASP.NET Core 而言，我们通过 HTTP POST 将客户端传来的 JSON 数据提交到服务器，使用 Entity Framework Core 将其存入数据库。本文将带你从零开始，完整实现一个标准的 POST 接口，包括请求 DTO 设计、AutoMapper 映射、EF Core 的 Add 与 SaveChanges，以及如何优雅地返回 201 Created 响应。

2. 背景与项目结构

假设我们有一个简单的“股票”（Stock）管理 API，项目目录示例：

/Controllers

  StocksController.cs

/Models

  Stock.cs

/DTOs

  CreateStockRequestDto.cs

/Mappings

  StockMapper.cs

/Data

  AppDbContext.cs

Models/Stock.cs：EF Core 实体，包含 Id、Symbol、CompanyName、PurchasePrice、LastDividend、Industry、MarketCap 等属性。
AppDbContext.cs：已注册 DbSet < Stock > 。
引用：已在 Program 中配置好 AddDbContext 与路由、控制器。

3. POST 请求的工作原理

客户端通过 HTTP POST 将 JSON 放入请求 Body。
控制器方法用 [FromBody] 接收绑定到 DTO。
EF Core 的 DbContext.Add(entity) 将实体置为“跟踪”状态，但不立即写入数据库。
调用 SaveChanges() 时，EF Core 才会将变更写入数据库。
最后可通过 CreatedAtAction 返回包含新资源 URL 的 201 Created 响应。

4. 设计请求 DTO（Create Request DTO）

为了避免前端或用户提交不必要或敏感字段，需要单独定义 Create Request DTO：

public class CreateStockRequestDto
{
    public string Symbol        { get; set; }
    public string CompanyName   { get; set; }
    public decimal PurchasePrice{ get; set; }
    public decimal LastDividend { get; set; }
    public string Industry      { get; set; }
    public long   MarketCap     { get; set; }
}

5. 编写 Mapper：从 DTO 到模型

DTO 只负责接收外部数据，写库前需转换成 EF 实体 Stock：

public static class StockMapper
{
    public static Stock FromCreateDto(CreateStockRequestDto dto)
    {
        return new Stock
        {
            Symbol        = dto.Symbol,
            CompanyName   = dto.CompanyName,
            PurchasePrice = dto.PurchasePrice,
            LastDividend  = dto.LastDividend,
            Industry      = dto.Industry,
            MarketCap     = dto.MarketCap
        };
    }
}

6. 在 Controller 中实现 POST Endpoint

在 StocksController.cs 中添加创建方法：

[HttpPost]
public IActionResult CreateStock([FromBody] CreateStockRequestDto dto)
{
    // 1. DTO 转实体
    var stock = StockMapper.FromCreateDto(dto);

    // 2. 添加到 DbContext
    _context.Stocks.Add(stock);

    // 3. 持久化到数据库
    _context.SaveChanges();

    // 4. 返回 201 Created，并包含新资源 URL
    return CreatedAtAction(
        nameof(GetStockById),
        new { id = stock.Id },
        stock
    );
}

6.1 添加模型到 DbContext

_context.Stocks.Add(stock);

6.2 调用 SaveChanges 并返回 CreatedAtAction

_context.SaveChanges();

return CreatedAtAction(
  nameof(GetStockById),
  new { id = stock.Id },
  stock
);

7. 测试与验证

运行 API：dotnet watch run。
Postman/Swagger：
- POST /api/stocks，Body 填入 DTO JSON。
- 期望 201 Created，并在 Location 头看到新资源 URL。

检查数据库：确认 Stocks 表中插入了新记录。

8. 小结与最佳实践

隔离 DTO 与模型：只接收必要字段，避免误写或泄露。
手写 Mapper：流程清晰，易于调试；复杂场景可引入 AutoMapper。
分离跟踪与写库：Add 仅跟踪，SaveChanges() 真正提交。
RESTful 返回：使用 CreatedAtAction 返回 201 Created 和资源 URL。
全面测试：结合 Swagger、Postman、数据库直查，确保每步正确。

通过以上步骤，你已掌握 ASP.NET Core 中标准 POST 创建接口的核心技巧，助你快速、高质量地交付 API。

原文引自YouTube视频：https://www.youtube.com/watch?v=yxQ9CSwc_uk