ASP.NET Core Web API 数据校验实战：路由约束与 DataAnnotations

引言：为什么需要数据校验？

在互联网上填写表单时，用户经常输入虚假或格式错误的数据。为保证 API 接收的数据符合预期，数据校验（Data Validation） 是必不可少的步骤。

本文将演示两种常见校验方式：路由约束（简单类型校验）与 DataAnnotations（复杂类型校验）。

一、路由约束（URL Constraints）——简单类型校验

1. 原理
   路由约束可以在路由模板中指定参数类型，例如 {id:int}，如果传入非整数会直接返回 404。

2. 实现步骤
   在 Controller 的路由属性中添加类型约束：

   [HttpGet("{id:int}")]
   public async Task < ActionResult < Comment > > GetCommentAsync(int id)
   {
      // ...
   }

   同理，DELETE、PUT 等带 ID 的路由也可加上 :int。

3. 验证
   使用 Swagger 或直接在浏览器地址栏输入非数字，如 GET /api/comment/abc，将返回 404。

二、DTO 中的 DataAnnotations——复杂类型校验

1. 为何用 DTO
   将校验属性放在专用 DTO 上，避免在实体模型中混入校验逻辑，保持关注点分离。

2. 添加校验特性
   在 DTO 属性上使用 [Required]、[MinLength]、[MaxLength]、[Range] 等特性。例如对 CreateCommentRequest：

   public class CreateCommentRequest
   {
      [Required]
      [MinLength(5, ErrorMessage = "Title must be at least 5 characters.")]
      [MaxLength(280, ErrorMessage = "Title cannot exceed 280 characters.")]
      public string Title { get; set; }
   
      [Required]
      [MinLength(5, ErrorMessage = "Content must be at least 5 characters.")]
      [MaxLength(280, ErrorMessage = "Content cannot exceed 280 characters.")]
      public string Content { get; set; }
   }

3. 对其他 DTO 重复同样操作

   • UpdateCommentRequest
   • CreateStockRequest（Symbol、CompanyName、PurchasePrice、Dividend、Industry、MarketCap）
   • UpdateStockRequest
     在各自 DTO 中添加相应的特性与参数范围。[截图时间节点：6:02]

三、在 Controller 中启用 ModelState 校验

1. 检查 ModelState
   在每个接收 DTO 的端点顶部添加：

   if (!ModelState.IsValid)
      return BadRequest(ModelState);

   这样一来，框架会根据 DTO 上的 DataAnnotations 自动校验，并在失败时返回 400 错误及详细信息。

2. 示例：CreateCommentAsync

   [HttpPost]
   public async Task < ActionResult < Comment > > CreateCommentAsync(CreateCommentRequest dto)
   {
      if (!ModelState.IsValid)
          return BadRequest(ModelState);
   
      // 创建逻辑...
   }

四、测试与验证

1. 路由约束测试

   • GET /api/comment/string → 404。

2. DTO 校验测试

   • 使用 Swagger 向 POST /api/comment 提交短于 5 字符的 Title 或超长 Content → 返回 400 与错误信息。
   • 向 POST /api/stock 提交缺失必填字段或超出范围的数值 → 返回 400。

小结

• 路由约束：在路由模板中对简单类型参数进行初步校验。
• DataAnnotations：在 DTO 上声明详细校验规则，结合 ModelState 进行复杂校验。
• ModelState：统一捕获并返回校验错误，无需手动逐个验证。

通过以上方法，可有效提升 API 的健壮性与安全性。下一步可探索全局过滤器（Action Filter）、自定义校验属性等更高级的校验机制。

原文引自YouTube视频：https://www.youtube.com/watch?v=1i_WE4aGVLU