
如果你想快速用 .NET 写一个 Web API，**Minimal API** 是 ASP.NET Core 官方主推的轻量方式。
它特别适合：

- 小型 API
- 快速原型
- 微服务
- 低样板代码项目

这篇教程尽量保持和微软官方入门思路一致：
**创建项目 → 编写接口 → 运行测试 → 加一点常用能力。**

---

## 一、什么是 Minimal API？

传统 ASP.NET Core Web API 一般会有：

- Controller
- Action
- `[ApiController]`
- `[Route]`

而 Minimal API 直接把路由和处理逻辑写在 `Program.cs` 里，例如：

```csharp
var app = WebApplication.Create(args);

app.MapGet("/", () => "Hello World!");

app.Run();
```

这就是最小化 API 的核心思路：

> **用最少代码定义 HTTP 接口。**

---

## 二、创建项目

先用命令行创建一个 Web 项目：

```bash
dotnet new web -o MinimalApiDemo
cd MinimalApiDemo
```

这个模板就是最适合 Minimal API 的官方模板。

运行项目：

```bash
dotnet run
```

默认会看到类似输出：

```bash
Now listening on: http://localhost:5xxx
Now listening on: https://localhost:7xxx
```

---

## 三、默认项目结构

创建后，最关键的文件就是 `Program.cs`。

一个最基础的项目通常长这样：

```csharp
var builder = WebApplication.CreateBuilder(args);
var app = builder.Build();

app.MapGet("/", () => "Hello World!");

app.Run();
```

这几行代码分别代表：

- `CreateBuilder(args)`：创建应用构建器
- `Build()`：构建应用
- `MapGet(...)`：定义 GET 接口
- `Run()`：启动 Web 服务

---

## 四、编写第一个接口

把 `Program.cs` 改成下面这样：

```csharp
var builder = WebApplication.CreateBuilder(args);
var app = builder.Build();

// GET /
app.MapGet("/", () => "Hello World!");

// GET /hello
app.MapGet("/hello", () => "Hello Minimal API!");

app.Run();
```

运行后访问：

- `/`
- `/hello`

你就能看到返回内容。

---

## 五、接收路由参数

Minimal API 可以直接从路由里拿参数。

```csharp
var builder = WebApplication.CreateBuilder(args);
var app = builder.Build();

// 访问 /users/1
app.MapGet("/users/{id}", (int id) =>
{
    return $"User Id: {id}";
});

app.Run();
```

例如访问：

```bash
GET /users/123
```

返回：

```text
User Id: 123
```

这里的 `(int id)` 会自动绑定路由参数。

---

## 六、接收查询字符串参数

例如：

```csharp
var builder = WebApplication.CreateBuilder(args);
var app = builder.Build();

// 访问 /search?keyword=dotnet
app.MapGet("/search", (string keyword) =>
{
    return $"You searched: {keyword}";
});

app.Run();
```

请求：

```bash
GET /search?keyword=dotnet
```

返回：

```text
You searched: dotnet
```

---

## 七、接收对象参数

先定义一个模型：

```csharp
public record Todo(int Id, string Title, bool IsDone);
```

然后在 `Program.cs` 里写 POST 接口：

```csharp
var builder = WebApplication.CreateBuilder(args);
var app = builder.Build();

app.MapPost("/todos", (Todo todo) =>
{
    return Results.Ok(todo);
});

app.Run();

public record Todo(int Id, string Title, bool IsDone);
```

发送请求：

```http
POST /todos
Content-Type: application/json

{
  "id": 1,
  "title": "Learn Minimal API",
  "isDone": false
}
```

返回的就是你提交的对象。

---

## 八、返回不同类型结果

官网教程里也很强调：
Minimal API 不只是返回字符串，也可以返回标准 HTTP 结果。

```csharp
var builder = WebApplication.CreateBuilder(args);
var app = builder.Build();

app.MapGet("/ok", () => Results.Ok(new { message = "success" }));

app.MapGet("/notfound", () => Results.NotFound());

app.MapGet("/badrequest", () => Results.BadRequest(new { error = "invalid request" }));

app.Run();
```

常见结果有：

- `Results.Ok()`
- `Results.NotFound()`
- `Results.BadRequest()`
- `Results.Created()`
- `Results.NoContent()`

这样更适合真实 API 项目。

---

## 九、做一个最简单的 Todo API

下面给一个可以直接运行的最小示例，风格和官方教程很接近。

```csharp
var builder = WebApplication.CreateBuilder(args);
var app = builder.Build();

// 内存数据
var todos = new List<Todo>
{
    new Todo(1, "Learn C#", false),
    new Todo(2, "Learn Minimal API", true)
};

// 获取全部
app.MapGet("/todos", () => todos);

// 根据 Id 获取
app.MapGet("/todos/{id}", (int id) =>
{
    var todo = todos.FirstOrDefault(t => t.Id == id);
    return todo is not null ? Results.Ok(todo) : Results.NotFound();
});

// 新增
app.MapPost("/todos", (Todo todo) =>
{
    todos.Add(todo);
    return Results.Created($"/todos/{todo.Id}", todo);
});

app.Run();

public record Todo(int Id, string Title, bool IsDone);
```

这个例子包含了：

- `GET /todos`
- `GET /todos/{id}`
- `POST /todos`

已经是一个最基础的 REST 风格 API 了。

---

## 十、启用 Swagger

如果你想像官网示例那样方便调试接口，可以加 Swagger。

### 1. 注册服务

```csharp
var builder = WebApplication.CreateBuilder(args);

builder.Services.AddEndpointsApiExplorer();
builder.Services.AddSwaggerGen();

var app = builder.Build();

if (app.Environment.IsDevelopment())
{
    app.UseSwagger();
    app.UseSwaggerUI();
}

app.MapGet("/", () => "Hello World!");

app.Run();
```

### 2. 运行后访问

```bash
/swagger
```

你就能看到接口文档页面。

---

## 十一、完整入门版示例

下面是一个更完整、可直接运行的 Minimal API 入门项目。

```csharp
var builder = WebApplication.CreateBuilder(args);

// Swagger
builder.Services.AddEndpointsApiExplorer();
builder.Services.AddSwaggerGen();

var app = builder.Build();

// 开发环境启用 Swagger
if (app.Environment.IsDevelopment())
{
    app.UseSwagger();
    app.UseSwaggerUI();
}

var todos = new List<Todo>
{
    new Todo(1, "Learn .NET", false),
    new Todo(2, "Build Minimal API", true)
};

// 根路由
app.MapGet("/", () => "Hello Minimal API!");

// 获取全部 Todo
app.MapGet("/todos", () => Results.Ok(todos));

// 根据 Id 获取 Todo
app.MapGet("/todos/{id}", (int id) =>
{
    var todo = todos.FirstOrDefault(x => x.Id == id);
    return todo is not null ? Results.Ok(todo) : Results.NotFound();
});

// 新增 Todo
app.MapPost("/todos", (Todo todo) =>
{
    todos.Add(todo);
    return Results.Created($"/todos/{todo.Id}", todo);
});

// 删除 Todo
app.MapDelete("/todos/{id}", (int id) =>
{
    var todo = todos.FirstOrDefault(x => x.Id == id);
    if (todo is null)
    {
        return Results.NotFound();
    }

    todos.Remove(todo);
    return Results.NoContent();
});

app.Run();

public record Todo(int Id, string Title, bool IsDone);
```

---

## 十二、怎么运行这个项目？

### 1. 创建项目

```bash
dotnet new web -o MinimalApiDemo
cd MinimalApiDemo
```

### 2. 替换 `Program.cs`
把上面的完整示例复制进去。

### 3. 安装 Swagger（如果项目里没有）

```bash
dotnet add package Swashbuckle.AspNetCore
```

### 4. 运行

```bash
dotnet run
```

### 5. 打开 Swagger

浏览器访问：

```bash
https://localhost:xxxx/swagger
```

---

## 十三、和 Controller 有什么区别？

Minimal API 和传统 Controller 都能写 Web API。

### Minimal API 更适合
- 小型服务
- 快速开发
- 简单接口
- 微服务

### Controller 更适合
- 大型复杂业务
- 需要更清晰分层
- 团队长期维护
- 习惯 MVC 风格

入门阶段，你可以先从 Minimal API 开始，因为它更容易理解 ASP.NET Core 请求处理流程。

---

## 十四、总结

如果你按官方思路入门 Minimal API，最重要的是先掌握这几件事：

- 用 `dotnet new web` 创建项目
- 用 `MapGet` / `MapPost` 定义接口
- 用参数绑定接收路由、查询、Body 数据
- 用 `Results` 返回标准 HTTP 响应
- 用 Swagger 测试接口

可以把 Minimal API 理解成：

> **更轻量、更直接的 ASP.NET Core Web API 写法。**



如果你想快速用 .NET 写一个 Web API，Minimal API 是 ASP.NET Core 官方主推的轻量方式。它特别适合：

ASP.NET Core Minimal API 入门教程

后端

开发工具

编程语言

学习ASP.NET Core Minimal API开发，掌握轻量级WebAPI快速构建技巧。本文详细介绍从项目创建、路由定义到参数绑定的完整流程，包含GET/POST接口实现、Swagger集成和Todo API实战示例。Minimal API通过最简代码实现HTTP接口，特别适合微服务和小型项目开发，是.NET开发者必备的现代API开发技能。

路由

文章

问答

视频

教程

学习中心

腾讯云实验室

直播

竞赛

腾讯云代码分析专区

腾讯iOA零信任安全管理系统专区

腾讯云架构师技术同盟交流圈

腾讯云数据库专区

腾讯云智能顾问专区

腾讯云原生专区

腾讯混元专区

腾讯云TCE专区

腾讯云Lighthouse专区

腾讯云HAI专区

腾讯云Edgeone专区

腾讯云存储专区

腾讯云智能专区

腾讯轻联专区 

腾讯云开发专区

TAPD专区

腾讯轻量云游戏服专区

EdgeOne AI 安全实战专区

腾讯云最具价值专家

腾讯云架构师技术同盟

腾讯云创作之星

腾讯云开发者先锋

腾讯云代码助手

云原生构建

TAPD 敏捷项目管理

Cloud Studio

SDK中心

API中心

命令行工具

涵盖代码开发、场景应用、自动测试全流程，助你从零构建专属AI助手

一站式MCP教程库，解锁AI应用新玩法

聚焦“写作效率、视觉美观与运行性能”三方面进行全面升级，为您提供更高效、稳定的创作环境

社区富文本&Markdown编辑器全新改版上线，欢迎大家体验!

诚挚邀请您参与本次调研，分享您的真实使用感受与建议。您的反馈至关重要，感谢您的支持与参与！

社区新版编辑器体验调研

学习ASP.NET Core Minimal API开发，掌握轻量级WebAPI快速构建技巧。本文详细介绍从项目创建、路由定义到参数绑定的完整流程，包含GET/POST接口实现、Swagger集成和Todo API实战示例。Minimal API通过最简代码实现HTTP接口，特别适合微服务和小型项目开发，是.NET开发...

ASP.NET Core Minimal API 入门教程-腾讯云开发者社区-腾讯云

ASP.NET Core Minimal API 入门教程

ASP.NET Core Minimal API 入门教程

社区

活动

圈层

关于

腾讯云开发者

热门产品

热门推荐

更多推荐