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 请求的工作原理

1. 客户端通过 HTTP POST 将 JSON 放入请求 Body。
2. 控制器方法用 [FromBody] 接收绑定到 DTO。
3. EF Core 的 DbContext.Add(entity) 将实体置为“跟踪”状态，但不立即写入数据库。
4. 调用 SaveChanges() 时，EF Core 才会将变更写入数据库。
5. 最后可通过 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. 测试与验证

1. 运行 API：dotnet watch run。

2. Postman/Swagger：

   • POST /api/stocks，Body 填入 DTO JSON。
   • 期望 201 Created，并在 Location 头看到新资源 URL。

3. 检查数据库：确认 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