RESTful API(Representational State Transfer)是一种设计风格,用于在客户端和服务器之间传递数据。ASP.NET Core 提供了一个简洁而强大的框架来构建 RESTful API,能够快速开发和部署高性能的 Web API 应用。
1. 创建 ASP.NET Core 项目
首先,确保你已经安装了最新版本的 .NET SDK。打开终端或命令行工具,使用以下命令创建新的 ASP.NET Core Web API 项目:
dotnet new webapi -n MyRestfulApi
cd MyRestfulApi
该命令会创建一个名为 MyRestfulApi 的项目,其中包含基本的 Web API 模板结构。
2. 配置 Startup.cs
在 ASP.NET Core 中,Startup.cs 是应用的核心配置文件,负责配置请求管道和服务。
在 Startup.cs 中,你会看到 ConfigureServices 方法和 Configure 方法。ConfigureServices 用于注册应用的服务,例如依赖注入、数据库上下文等;Configure 用于设置中间件,例如路由、认证等。
public class Startup
{
// 该方法用于注册应用服务,包括控制器、Swagger等
public void ConfigureServices(IServiceCollection services)
{
// 注册控制器服务,支持基于MVC的Web API开发
services.AddControllers();
// 注册Swagger生成器,用于生成API文档
services.AddSwaggerGen();
}
// 该方法配置HTTP请求管道中的中间件
public void Configure(IApplicationBuilder app, IWebHostEnvironment env)
{
// 如果是开发环境,启用开发者异常页面,方便调试
if (env.IsDevelopment())
{
app.UseDeveloperExceptionPage();
}
// 启用Swagger中间件来生成Swagger文档
app.UseSwagger();
// 启用SwaggerUI,为Swagger文档提供UI界面,方便测试API
app.UseSwaggerUI(c =>
{
c.SwaggerEndpoint("/swagger/v1/swagger.json", "My API V1");
});
// 启用路由中间件,支持终端路由映射
app.UseRouting();
// 启用终端中间件,将控制器映射到路由
app.UseEndpoints(endpoints =>
{
endpoints.MapControllers();
});
}
}
在上面的代码中,我们通过 services.AddControllers() 方法添加了控制器支持。这是创建 RESTful API 的基础。
3. 创建控制器
接下来,我们创建一个简单的控制器来处理 HTTP 请求。在 Controllers 文件夹下添加一个新的控制器文件 ProductsController.cs。
[ApiController] // 指定该类是API控制器,自动启用模型验证和错误处理
[Route("api/[controller]")] // 为控制器定义路由,支持基于控制器名的URL
public class ProductsController : ControllerBase
{
// 模拟的产品数据列表
private static readonly List<Product> Products = new List<Product>
{
new Product { Id = 1, Name = "Product1", Price = 10.0M },
new Product { Id = 2, Name = "Product2", Price = 20.0M }
};
// 获取所有产品
[HttpGet] // 处理GET请求,返回产品列表
public IEnumerable<Product> GetAll()
{
return Products; // 返回产品数据
}
// 根据ID获取产品
[HttpGet("{id}")] // 处理GET请求,接受URL中的ID参数
public ActionResult<Product> GetById(int id)
{
// 查找指定ID的产品
var product = Products.FirstOrDefault(p => p.Id == id);
// 如果未找到产品,返回404 Not Found
if (product == null)
{
return NotFound();
}
// 返回找到的产品数据
return product;
}
// 创建新产品
[HttpPost] // 处理POST请求,接受请求体中的产品数据
public ActionResult<Product> Create(Product product)
{
// 生成新产品的ID
product.Id = Products.Max(p => p.Id) + 1;
// 将新产品添加到产品列表中
Products.Add(product);
// 返回201 Created状态码,并在响应中包含新创建的产品
return CreatedAtAction(nameof(GetById), new { id = product.Id }, product);
}
// 更新产品信息
[HttpPut("{id}")] // 处理PUT请求,接受URL中的ID参数和请求体中的更新数据
public IActionResult Update(int id, Product updatedProduct)
{
// 查找指定ID的产品
var product = Products.FirstOrDefault(p => p.Id == id);
// 如果未找到产品,返回404 Not Found
if (product == null)
{
return NotFound();
}
// 更新产品的名称和价格
product.Name = updatedProduct.Name;
product.Price = updatedProduct.Price;
// 返回204 No Content状态码,表示更新成功但不返回数据
return NoContent();
}
// 删除指定ID的产品
[HttpDelete("{id}")] // 处理DELETE请求,接受URL中的ID参数
public IActionResult Delete(int id)
{
// 查找指定ID的产品
var product = Products.FirstOrDefault(p => p.Id == id);
// 如果未找到产品,返回404 Not Found
if (product == null)
{
return NotFound();
}
// 从产品列表中移除该产品
Products.Remove(product);
// 返回204 No Content状态码,表示删除成功
return NoContent();
}
}
4. 定义模型
我们需要定义 Product 模型来表示 API 中使用的产品对象。在 Models 文件夹下添加一个新的类 Product.cs。
// 定义产品模型类,用于表示API中传输的产品数据
public class Product
{
public int Id { get; set; } // 产品的唯一标识符
public string Name { get; set; } // 产品名称
public decimal Price { get; set; } // 产品价格
}
5. 测试 API
启动应用后,你可以通过 Postman 或浏览器来测试 API:
- GET /api/products: 返回所有产品
- GET /api/products/{id}: 根据 ID 返回产品
- POST /api/products: 创建新产品
- PUT /api/products/{id}: 更新产品信息
- DELETE /api/products/{id}: 删除指定产品
6. 使用 Swagger 进行 API 文档生成
为了简化 API 文档的生成和测试,ASP.NET Core 提供了对 Swagger 的内置支持。你可以通过安装 Swashbuckle.AspNetCore NuGet 包来轻松集成 Swagger。
安装依赖项:
dotnet add package Swashbuckle.AspNetCore
在 Startup.cs 中注册 Swagger 服务:
public class Startup
{
// 配置服务注册的方法
public void ConfigureServices(IServiceCollection services)
{
// 注册控制器服务,支持基于MVC的Web API开发
services.AddControllers();
// 注册Swagger生成器服务,用于生成API文档
services.AddSwaggerGen();
}
// 配置HTTP请求管道的方法
public void Configure(IApplicationBuilder app, IWebHostEnvironment env)
{
// 如果当前环境是开发环境,启用开发者异常页面以方便调试
if (env.IsDevelopment())
{
app.UseDeveloperExceptionPage();
}
// 启用Swagger中间件,用于生成API的Swagger文档
app.UseSwagger();
// 启用Swagger UI中间件,提供用户界面来查看和测试API的文档
app.UseSwaggerUI(c =>
{
// 配置Swagger端点,指定Swagger JSON的URL路径和API版本标题
c.SwaggerEndpoint("/swagger/v1/swagger.json", "My API V1");
});
// 启用路由中间件,解析传入的HTTP请求并将其路由到适当的终端点
app.UseRouting();
// 配置终端点映射,将控制器动作映射到路由
app.UseEndpoints(endpoints =>
{
// 映射控制器终端点,使控制器能够处理请求
endpoints.MapControllers();
});
}
}
运行应用后,访问 http://localhost:{port}/swagger 就可以看到自动生成的 API 文档并进行测试了。
7. 小结
通过本文的介绍,你已经学会了如何使用 ASP.NET Core 创建一个简单的 RESTful API。从创建控制器到使用 Swagger 生成文档,ASP.NET Core 提供了全面而简洁的工具,使得构建 RESTful 服务变得更加高效和便捷。