.NET 8 ASP.NET Core Web API 实战：构建与测试 API Controllers

引言

API Controllers 就像房屋的门，负责人们进出。对于 Web API，当我们通过 URL 访问接口时，就是“走”进了对应的 Controller。理解“列表（List）”与“详情（Detail）”端点是设计 API 的基础。本文将以 StockController 为例，带你从零实现并测试这两种常见端点。

一、创建 Controllers 文件夹与 StockController

在项目根目录下，新建 Controllers 文件夹。
在 Controllers 中添加 StockController.cs，并命名为 StockController，以便后续针对 Stock 模型分离关注点。

namespace MyEfCoreApp.Controllers
{
    public class StockController : ControllerBase
    {
        // 后续补充代码
    }
}

二、添加基类、注解与构造函数注入

继承 ControllerBase 并添加 [ApiController]、[Route("api/[controller]")] 注解：
在 Controller 中通过构造函数注入已配置好的 ApplicationDbContext，并声明为只读字段，避免不必要的可变风险。

[ApiController]
[Route("api/[controller]")]
public class StockController : ControllerBase
{
    private readonly ApplicationDbContext _context;

    public StockController(ApplicationDbContext context)
    {
        _context = context;
    }
    // 列表与详情方法在下一节实现
}

三、实现 List 与 Detail 端点

1. 列表（List）端点

使用 [HttpGet] 定义 GET /api/stock，通过 _context.Stocks.ToListAsync() 获取所有记录。
Deferred Execution：在调用 ToListAsync() 前，查询尚未执行；只有在取列表时才生成 SQL 并发送。

[HttpGet]
public async Task<ActionResult<IEnumerable<Stock>>> GetStocks()
{
    return await _context.Stocks.ToListAsync();
}

2. 详情（Detail）端点

使用 [HttpGet("{id}")] 定义 GET /api/stock/{id}，通过 FindAsync(id) 按主键查询单条记录，并处理未找到的情况。

[HttpGet("{id}")]
public async Task<ActionResult<Stock>> GetStock(int id)
{
    var stock = await _context.Stocks.FindAsync(id);
    if (stock == null)
        return NotFound();
    return stock;
}

四、在 Program.cs 中注册 Controllers

打开 Program.cs，在构建应用之前，添加对 Controllers 的注册与映射：

var builder = WebApplication.CreateBuilder(args);

// 已注册 DbContext（略）…

builder.Services.AddControllers();

var app = builder.Build();

app.MapControllers();

app.Run();

未调用 AddControllers() 与 MapControllers() 会导致 Swagger 无法识别你的端点并出现 HTTPS 重定向错误。

五、添加测试数据 & Swagger 调试

在 SSMS 中插入测试数据
- 打开 SQL Server Management Studio → 选择 Stocks 表 → 右键 “Edit Top 200 Rows” → 手动添加几条示例记录（如 Tesla、VTI 等）。

使用 Swagger 测试 API
- 运行项目后打开 Swagger UI → 先执行 GET /api/stock，确认能拿到所有记录 → 再尝试输入某条记录的 ID 调用 /api/stock/{id}。

小结与下一步

完成了 API Controllers 的基本搭建：
- 创建并注入 StockController
- 实现 List 与 Detail 端点
- 在 Program.cs 注册并映射 Controllers
- 添加测试数据并通过 Swagger 验证接口
后续可扩展：新增 POST/PUT/DELETE 端点、添加 DTO 与 AutoMapper、编写单元测试等，提高 API 的完整性与可维护性。

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