跳到主要内容

4.2 Minimal API 入门

Minimal API 用少量代码定义 HTTP 路由，非常适合入门、微服务、小型接口和教学示例。它不代表“只能写简单项目”，但需要你主动保持结构清晰。

学习目标​

  • 能创建一个最小 ASP.NET Core Web API。
  • 能定义 GET、POST、PUT、DELETE 路由。
  • 能理解路由参数、请求体、服务注入和返回结果。
  • 能识别何时需要把逻辑从路由处理器中抽出来。

应用场景​

  • 快速创建内部工具 API。
  • 为前端原型提供后端接口。
  • 构建小型服务或微服务入口。
  • 在教学和项目实战中演示 HTTP 基础。

核心概念​

概念说明
WebApplicationASP.NET Core 应用入口，负责配置服务和请求管线
MapGet / MapPost把 HTTP 方法和路径映射到处理函数
模型绑定从路由、查询字符串、Header 或 Body 读取参数
Results生成标准 HTTP 响应，例如 200、201、404、400

案例：任务列表 API​

业务要求：前端需要读取任务、创建任务、完成任务。

var builder = WebApplication.CreateBuilder(args);

builder.Services.AddSingleton<TodoStore>();

var app = builder.Build();

app.MapGet("/todos", (TodoStore store) => Results.Ok(store.GetAll()));

app.MapPost("/todos", (CreateTodoRequest request, TodoStore store) =>
{
    if (string.IsNullOrWhiteSpace(request.Title))
    {
        return Results.BadRequest(new {message = "标题不能为空"});
    }

    var todo = store.Create(request.Title, request.Description);
    return Results.Created($"/todos/{todo.Id}", todo);
});

app.MapPut("/todos/{id:int}/complete", (int id, TodoStore store) =>
{
    var completed = store.Complete(id);
    return completed ? Results.NoContent() : Results.NotFound();
});

app.Run();

public sealed record CreateTodoRequest(string Title, string? Description);

public sealed record TodoDto(int Id, string Title, string? Description, bool IsCompleted);

public sealed class TodoStore
{
    private readonly List<TodoDto> todos = [];
    private int nextId = 1;

    public IReadOnlyList<TodoDto> GetAll() => todos;

    public TodoDto Create(string title, string? description)
    {
        var todo = new TodoDto(nextId++, title.Trim(), description, false);
        todos.Add(todo);
        return todo;
    }

    public bool Complete(int id)
    {
        var index = todos.FindIndex(todo => todo.Id == id);
        if (index < 0)
        {
            return false;
        }

        var current = todos[index];
        todos[index] = current with {IsCompleted = true};
        return true;
    }
}

重点难点​

  • 路由处理器应该薄：复杂业务逻辑放到服务类中。
  • AddSingleton 只适合这个内存示例；真实数据库访问通常使用 Scoped 服务。
  • HTTP 状态码要表达语义：创建成功用 201，找不到用 404，校验失败用 400。
  • API 返回 DTO，不要直接暴露复杂实体或 EF Core 跟踪对象。

常见误区​

误区推荐做法
所有逻辑都写在 MapPost 中路由处理输入输出，业务逻辑交给服务
创建成功统一返回 200返回 201，并给出资源地址
内存集合示例直接搬到生产生产环境使用数据库和并发控制

练习​

  • 增加 DELETE /todos/{id}。
  • 增加 GET /todos?completed=true 筛选。
  • 把 TodoStore 替换为接口 ITodoService，再注入实现类。

延伸阅读​

  • ASP.NET Core Minimal API 官方文档。
  • 依赖注入与服务生命周期。
  • Problem Details 统一错误响应。