ASP.NET Core Web API 约定使用指南
概述
在开发ASP.NET Core Web API时，我们经常需要为各种HTTP响应添加文档说明。传统方式是使用[ProducesResponseType]属性逐个标注每个Action方法，这种方式在大型项目中会显得冗长且难以维护。ASP.NET Core提供了Web API约定(Conventions)机制，可以集中定义通用的API响应模式，显著提高开发效率。
核心概念
Web API约定是一种将通用API文档规则集中定义并自动应用到多个Action、控制器或整个程序集的机制。它主要解决以下问题：
- 为特定类型的Action定义最常见的返回类型和状态码
- 识别偏离已定义标准的Action
- 减少重复的
[ProducesResponseType]属性标注
默认约定
ASP.NET Core提供了Microsoft.AspNetCore.Mvc.DefaultApiConventions类，包含一组预定义的约定。这些约定适用于遵循标准RESTful模式的API控制器。
例如，一个标准的ValuesController会自动匹配这些默认约定，无需额外标注。
约定应用方式
Web API约定可以通过三种方式应用，按优先级从高到低排列：
1. 方法级应用
使用[ApiConventionMethod]属性将特定约定方法应用到单个Action：
[ApiConventionMethod(typeof(DefaultApiConventions),
nameof(DefaultApiConventions.Put))]
public IActionResult Update(int id, Contact contact)
{
// 实现代码
}
2. 控制器级应用
使用[ApiConventionType]属性将约定应用到整个控制器：
[ApiConventionType(typeof(DefaultApiConventions))]
[ApiController]
[Route("api/[controller]")]
public class ContactsConventionController : ControllerBase
{
// 所有Action都将应用默认约定
}
3. 程序集级应用
在Startup类中应用约定到整个程序集：
[assembly: ApiConventionType(typeof(DefaultApiConventions))]
namespace WebApiConventions
{
public class Startup
{
// 启动配置
}
}
创建自定义约定
当默认约定不能满足需求时，可以创建自定义约定：
1. 定义响应类型
创建一个静态类，定义带有[ProducesResponseType]标注的方法：
public static class MyCustomConventions
{
[ProducesResponseType(StatusCodes.Status200OK)]
[ProducesResponseType(StatusCodes.Status404NotFound)]
public static void GetById(int id)
{
}
}
2. 定义命名匹配规则
使用[ApiConventionNameMatch]和[ApiConventionTypeMatch]控制匹配行为：
[ApiConventionNameMatch(ApiConventionNameMatchBehavior.Prefix)]
public static void Find(
[ApiConventionNameMatch(ApiConventionNameMatchBehavior.Suffix)]
int id)
{
// 匹配所有以"Find"开头的Action方法
// 且包含一个以"id"结尾的参数
}
实际应用建议
-
分层应用：优先在方法级应用最具体的约定，然后在控制器级，最后在程序集级
-
约定组合：虽然约定不能组合，但可以通过继承创建更复杂的约定体系
-
文档生成：约定与Swagger/OpenAPI文档生成器完美配合，确保API文档一致性
-
异常处理：使用
[ProducesDefaultResponseType]标注默认错误响应
常见问题解答
Q：约定会影响实际API行为吗？ A：不会，约定仅影响API文档和元数据生成，不改变实际运行时行为。
Q：如何知道哪些Action不符合约定？ A：ASP.NET Core的API分析器会标记不符合约定的Action，并在编译时生成警告。
Q：可以同时应用多个约定吗？ A：每个Action只能应用一个最具体的约定，不能组合多个约定。
通过合理使用Web API约定，可以显著提高ASP.NET Core Web API项目的开发效率和文档质量，同时保持代码的整洁和一致性。
