2、第一个Web应用：创建项目、项目结构解析、Program.cs与Startup.cs的秘密、运行你的第一个API

好，咱们正式开始动手了。

这一章，我会带你从零创建一个ASP.NET Core项目。别怕，真的就几步。我当年第一次接触时，也被各种文件搞晕过。但等你走完这一遍，会发现——其实就那么回事。

2.1 创建项目：两种方式，随你挑

创建项目有两种主流方式。我个人习惯用命令行，因为快。但如果你喜欢点鼠标，用Visual Studio也行。

方式一：命令行（推荐）

打开终端，敲下面这行命令：

dotnet new webapi -n MyFirstApi

解释一下：

  • dotnet new 是创建项目的命令
  • webapi 是模板名称，表示创建Web API项目
  • -n MyFirstApi 指定项目名称

命令执行完，你会看到一个 MyFirstApi 文件夹。进去看看：

cd MyFirstApi
code .

如果你装了VS Code，这会直接打开项目。嗯，就这么简单。

方式二：Visual Studio

如果你用VS，步骤是：

  1. 文件 → 新建 → 项目
  2. 选择“ASP.NET Core Web API”模板
  3. 填项目名、选位置，点创建

效果一样。我个人觉得命令行更干脆，但看你自己习惯。

小提示： 我第一次用VS创建项目时，被那一堆复选框搞懵了。什么“启用OpenAPI”、“配置HTTPS”……别慌，默认勾选就行。后面咱们慢慢调。

2.2 项目结构解析：这些文件都是干嘛的？

项目创建好了，你会看到一堆文件。别慌，咱们一个一个看。

文件/文件夹 作用
Controllers/ 存放API控制器，你的接口逻辑主要写在这里
Program.cs 应用程序的入口，启动配置的核心
appsettings.json 配置文件，比如数据库连接字符串、日志级别等
Properties/launchSettings.json 启动配置，比如端口号、环境变量
MyFirstApi.csproj 项目文件，记录依赖包、目标框架等信息

你想想看，一个Web应用要跑起来，至少需要三样东西：

  • 入口（Program.cs）
  • 配置（appsettings.json）
  • 业务逻辑（Controllers里的代码）

ASP.NET Core把这几个职责分得很清楚。我在项目中遇到过不少新手，把所有代码都塞进Program.cs，结果项目一复杂就乱成一锅粥。别学他们。

2.3 Program.cs与Startup.cs的秘密

这里有个历史故事。在.NET 6之前，项目里有两个核心文件：Program.cs 和 Startup.cs。从.NET 6开始，微软把它们合并了。说白了，就是简化了启动流程。

咱们打开 Program.cs，看看里面到底写了啥：

var builder = WebApplication.CreateBuilder(args);

// 注册服务
builder.Services.AddControllers();
builder.Services.AddEndpointsApiExplorer();
builder.Services.AddSwaggerGen();

var app = builder.Build();

// 配置中间件管道
if (app.Environment.IsDevelopment())
{
    app.UseSwagger();
    app.UseSwaggerUI();
}

app.UseHttpsRedirection();
app.UseAuthorization();
app.MapControllers();

app.Run();

这段代码，我拆成三部分给你讲：

第一部分：创建Builder并注册服务

builder.Services.AddControllers() 这行，说白了就是告诉系统：“我要用控制器模式”。你想想看，如果不注册，系统根本不知道你有控制器。

我刚开始学的时候，总忘记加这行。结果一运行，接口404。排查了半天，原来是没注册服务。嗯，这种坑踩过一次就记住了。

第二部分：构建应用并配置中间件

app.UseSwagger() 这些，就是所谓的“中间件”。你可以把中间件想象成流水线上的工人。每个工人负责一道工序：

  • Swagger中间件：生成API文档
  • HTTPS重定向中间件：把HTTP请求转到HTTPS
  • 授权中间件：检查用户有没有权限

中间件的顺序很重要。我曾经在生产环境遇到过一个问题：把授权中间件放到了Swagger后面，结果Swagger页面能访问，但实际接口全被拦截了。顺序搞反了。

第三部分：启动应用

app.Run() 这行，就是让应用开始监听请求。没有这行，程序跑完就退出了。

核心要点： Program.cs 就是应用的“总指挥”。它决定了：用什么服务、走什么中间件、怎么启动。理解了这个文件，你就理解了ASP.NET Core的骨架。

2.4 运行你的第一个API

好了，理论讲完了。咱们来点实际的。

在终端里运行：

dotnet run

你会看到类似这样的输出：

Now listening on: https://localhost:5001
Now listening on: http://localhost:5000

打开浏览器，访问 https://localhost:5001/swagger。你会看到一个漂亮的API文档页面。这就是Swagger UI。

在页面上，你会看到一个 GET /WeatherForecast 的接口。点一下“Try it out”，再点“Execute”。

你会看到返回的JSON数据：

[
  {
    "date": "2024-01-15",
    "temperatureC": 25,
    "temperatureF": 77,
    "summary": "Hot"
  },
  {
    "date": "2024-01-16",
    "temperatureC": 18,
    "temperatureF": 64,
    "summary": "Mild"
  }
]

恭喜你！你的第一个API跑起来了。

注意： 如果你遇到“无法建立SSL连接”的错误，别慌。这是因为开发证书没安装。运行 dotnet dev-certs https --trust 即可解决。我当年被这个坑了整整一下午。

这个 WeatherForecast 控制器是模板自带的。它演示了：

  • 如何定义GET接口
  • 如何返回JSON数据
  • 如何使用Swagger测试接口

说白了，这就是一个“Hello World”的升级版。但别小看它，麻雀虽小五脏俱全。

2.5 本章小结

咱们这一章，做了三件事：

  1. 创建了一个ASP.NET Core Web API项目
  2. 搞清楚了项目里每个文件是干嘛的
  3. 理解了Program.cs的核心逻辑
  4. 成功运行了第一个API

下一章，咱们会深入控制器，看看怎么自己写接口。到时候，你就可以摆脱那个示例的WeatherForecast，写真正属于你自己的API了。

记住：别怕犯错。我写代码十几年，照样天天踩坑。关键是踩完坑要明白为什么。好了，去动手试试吧。

← 上一章 📖 返回目录 下一章 →