ASP.NET Core Web API 开发指南
概述
ASP.NET Core 提供了强大的功能来构建 Web API，支持通过控制器或最小 API 两种方式创建。本文将重点介绍基于控制器的 Web API 开发方法，这是构建 RESTful 服务的传统且功能完备的方式。
控制器基础
ControllerBase 类
Web API 控制器应继承自 ControllerBase 类，而不是用于 MVC 视图的 Controller 类。ControllerBase 提供了丰富的属性和方法来处理 HTTP 请求：
public class ProductsController : ControllerBase
{
// 控制器方法
}
ControllerBase 包含许多有用的方法，例如：
Ok()- 返回 200 状态码CreatedAtAction()- 返回 201 状态码BadRequest()- 返回 400 状态码NotFound()- 返回 404 状态码
常用属性
ASP.NET Core 提供了多种属性来配置控制器和行为：
[ApiController]
[Route("api/[controller]")]
public class ProductsController : ControllerBase
{
[HttpGet("{id}")]
public ActionResult<Product> GetById(int id)
{
// ...
}
}
常用属性包括：
[Route]- 指定控制器或操作的 URL 模式[HttpGet],[HttpPost]等 - 指定支持的 HTTP 方法[Produces]- 指定返回的数据类型[Consumes]- 指定接受的数据类型
ApiController 特性
[ApiController] 特性为控制器启用了多个 API 专用行为：
1. 属性路由要求
使用 [ApiController] 的控制器必须使用属性路由，不能使用传统路由。
2. 自动 HTTP 400 响应
当模型验证失败时，自动返回 HTTP 400 响应，无需手动检查 ModelState.IsValid。
3. 绑定源推断
自动推断参数绑定源：
- 复杂类型参数默认从请求体绑定 (
[FromBody]) - 简单类型参数默认从查询字符串绑定 (
[FromQuery]) - 与路由模板匹配的参数从路由数据绑定 (
[FromRoute])
4. 多部分/表单数据推断
对于 IFormFile 和 IFormFileCollection 类型参数，自动推断 multipart/form-data 内容类型。
5. 错误状态码的问题详情
对于 400 及以上状态码，自动转换为 ProblemDetails 响应，符合 RFC 7807 规范。
参数绑定
ASP.NET Core 提供了多种绑定源属性：
| 属性 | 绑定源 |
|---|---|
[FromBody] |
请求体 |
[FromForm] |
表单数据 |
[FromHeader] |
请求头 |
[FromQuery] |
查询字符串 |
[FromRoute] |
路由数据 |
[FromServices] |
依赖注入服务 |
示例：
public IActionResult Get(
[FromQuery] int page,
[FromRoute] int id,
[FromServices] IProductRepository repository)
{
// ...
}
高级配置
自定义自动 400 响应
可以通过配置 InvalidModelStateResponseFactory 来自定义自动 400 响应：
builder.Services.Configure<ApiBehaviorOptions>(options =>
{
options.InvalidModelStateResponseFactory = context =>
{
var logger = context.HttpContext.RequestServices
.GetRequiredService<ILogger<Program>>();
// 记录验证错误
logger.LogWarning("模型验证失败: {Errors}", context.ModelState);
return new BadRequestObjectResult(context.ModelState);
};
});
禁用特定 ApiController 行为
可以禁用任何默认行为：
builder.Services.Configure<ApiBehaviorOptions>(options =>
{
options.SuppressModelStateInvalidFilter = true; // 禁用自动400响应
options.SuppressInferBindingSourcesForParameters = true; // 禁用绑定源推断
options.SuppressMapClientErrors = true; // 禁用ProblemDetails
});
最佳实践
- 保持控制器精简：将业务逻辑放在服务层
- 使用适当的HTTP状态码：准确反映操作结果
- 实现一致的错误处理：使用ProblemDetails提供标准错误响应
- 考虑API版本控制：从项目开始就规划版本策略
- 实现适当的缓存策略：使用ETag或Cache-Control头部
总结
ASP.NET Core 提供了强大而灵活的工具来构建 Web API。通过合理使用控制器、ApiController 特性和各种配置选项，开发者可以创建高效、可维护且符合标准的 RESTful 服务。理解这些核心概念是构建高质量 API 的基础。
