构建您的第一个 Web API（使用 ASP.NET Core） 第 1 部分：REST 入门

Source: Dev.to

请提供您希望翻译的正文内容（除代码块和 URL 之外），我将把它翻译成简体中文并保持原有的格式。

什么是 REST？

REST（表述性状态转移）是一种用于设计网络服务的架构模式。它使用标准的 HTTP 动词——与你的浏览器每天使用的相同——来对资源执行操作。

RESTful API 由三件事定义：

1. 基础 URI（例如 https://api.example.com）
2. 上述 HTTP 方法
3. 数据格式——通常是 JSON，有时是 XML

路由把所有内容联系在一起。例如，对 /pizza 的请求可能会路由到 PizzaController，而 /order 则路由到 OrderController。每个资源在代码中都有自己的逻辑位置。

为什么选择 ASP.NET Core？

• 开箱即用的 JSON – ASP.NET Core 会自动将 C# 类序列化为 JSON。
• 内置安全性 – 默认启用 HTTPS，原生支持 JWT 身份验证和基于策略的授权。
• 基于属性的路由 – 使用属性直接在控制器方法上定义路由，使路由逻辑与代码共存。
• 跨 .NET 的代码复用 – 相同的模型和业务逻辑可以在移动端、桌面端或其他 .NET 服务中共享。

前提条件

• 对 C# 有基本了解（初学者水平即可）
• 本地已安装 .NET 8 SDK
• Visual Studio Code
• VS Code 的 C# Dev Kit 扩展
• VS Code 的 REST Client 扩展

要确认你的 .NET 版本，运行：

dotnet --list-sdks

你应该会看到类似 8.0.100 的输出。如果没有，请从官方 Microsoft 网站下载最新的 .NET 8 SDK。

Source: …

创建项目

1. 打开 VS Code → 文件 > 打开文件夹，并创建一个名为 ContosoPizza 的新文件夹。
2. 打开集成终端 (视图 > 终端) 并运行：

dotnet new webapi -controllers -f net8.0

这将脚手架一个带有控制器支持的 ASP.NET Core Web API 项目。生成的结构如下：

├── Controllers/
├── obj/
├── Properties/
├── appsettings.Development.json
├── appsettings.json
├── ContosoPizza.csproj
├── ContosoPizza.http
├── Program.cs
└── WeatherForecast.cs

关键项目

• Controllers/ – 放置 API 端点逻辑的地方
• Program.cs – 应用启动配置和 HTTP 管道
• ContosoPizza.http – 在 VS Code 中测试 API 的便利文件
• ContosoPizza.csproj – 项目元数据和依赖项

VS Code 可能会提示你添加调试资产——点击 是。

运行 API

启动开发服务器：

dotnet run

您将看到类似以下的输出：

Now listening on: https://localhost:7294
Now listening on: http://localhost:5118
Application started. Press Ctrl+C to shut down.

注意 HTTPS 端口（例如 7294）。打开浏览器并访问：

https://localhost:{PORT}/weatherforecast

您应该会收到包含随机天气数据的 JSON 响应，以确认已生成的端点正常工作。

使用 REST 客户端扩展进行测试

项目中包含 ContosoPizza.http，它可与 REST Client 扩展配合使用。打开该文件；其中已经包含对 /weatherforecast 的 GET 请求。

点击 GET 行上方的 Send Request。响应面板将显示类似如下内容：

HTTP/1.1 200 OK
Content-Type: application/json; charset=utf-8
...

[
  {
    "date": "2024-01-18",
    "temperatureC": -2,
    "temperatureF": 29,
    "summary": "Warm"
  },
  ...
]

这种工作流让你无需离开 VS Code 即可测试端点。

使用 HTTP REPL 进行测试

ASP.NET Core 还提供了一个名为 HTTP REPL 的交互式工具。

全局安装它：

dotnet tool install -g Microsoft.dotnet-httprepl

连接到正在运行的 API：

httprepl https://localhost:{PORT}

在 REPL 中，您可以像浏览文件系统一样探索 API：

ls                    # List available endpoints
cd WeatherForecast    # Navigate to an endpoint
get                   # Issue a GET request
exit                  # Quit the REPL

接下来做什么？

当前项目仅包含示例 weather‑forecast 端点。在 第 2 部分 我们将：

• 深入了解 ASP.NET Core 控制器的工作原理
• 逐行解析 WeatherForecastController 代码
• 创建 Pizza 模型和内存数据服务
• 搭建自定义的 PizzaController

完成第 2 部分后，您将能够通过自己的 API 端点获取披萨数据。

---

Tags: dotnet csharp webapi aspnetcore beginners