C# Academy · 课时

数据注解验证

Q: 「数据注解验证」这节课中我会学到什么？

使用特性验证模型。 你通过在浏览器中直接运行的动手代码来练习 C# Academy，全天候 AI 导师会在你学习这节课的过程中回答你的问题。

使用特性验证模型。

数据注解验证 是 CoddyKit 上的免费 C# Academy 课时。这是第 1 节课，共 4 节。你可以在下方免费阅读本课时的完整内容 — 然后在浏览器中使用内置代码编辑器和全天候 AI 导师进行实践。这是 C# Academy 学习路径的一部分，你的进度在网页和 CoddyKit 应用中同步。 C# Academy 课程共包含 4 节课。

什么是数据注解验证

数据注解是添加到模型属性上的特性，用于直接在 C# 类中声明验证规则。ASP.NET Core 会在模型绑定期间读取这些特性，并自动验证传入的请求。

它们位于 System.ComponentModel.DataAnnotations 命名空间中。

using System.ComponentModel.DataAnnotations;

public class RegisterRequest
{
    [Required]
    public string Username { get; set; }
}

[必填] 特性

[Required] 可确保属性不为 null（默认情况下也不能为空字符串）。如果客户端未提供该字段，模型验证会在操作方法运行前失败。

您可以使用 ErrorMessage 自定义消息。

public class RegisterRequest
{
    [Required(ErrorMessage = "Username is required.")]
    public string Username { get; set; }

    [Required]
    public string Password { get; set; }
}

使用 [范围] 验证数字

[Range] 会将数值限制在包含最小值和最大值的范围内。它适用于 int、double、decimal 等类型。

您可以将它用于年龄、数量、评分以及任何有边界的数值。

public class ProductRequest
{
    [Range(1, 1000, ErrorMessage = "Quantity must be between 1 and 1000.")]
    public int Quantity { get; set; }

    [Range(0.01, 9999.99)]
    public decimal Price { get; set; }
}

使用 [电子邮件地址] 验证电子邮件

[EmailAddress] 会检查字符串是否符合有效电子邮件地址的形式。请将它与 [Required] 结合使用，以确保字段既已提供又格式正确。

public class ContactRequest
{
    [Required]
    [EmailAddress(ErrorMessage = "Please enter a valid email.")]
    public string Email { get; set; }
}

字符串长度限制

[StringLength] 会为文本设置最大长度，也可以设置最小长度。[MinLength] 和 [MaxLength] 是更简单的替代方案。

public class RegisterRequest
{
    [Required]
    [StringLength(20, MinimumLength = 3)]
    public string Username { get; set; }

    [MaxLength(500)]
    public string Bio { get; set; }
}

使用 [正则表达式] 进行模式匹配

[RegularExpression] 会根据正则表达式模式验证字符串。它非常适合验证电话号码、邮政编码或标识名等格式。

public class ProfileRequest
{
    [RegularExpression(@"^[a-z0-9-]+$",
        ErrorMessage = "Slug may only contain lowercase letters, digits and dashes.")]
    public string Slug { get; set; }
}

使用 [比较] 比较两个字段

[Compare] 可确保一个属性与另一个属性匹配。最典型的情况是确认密码。

public class RegisterRequest
{
    [Required]
    public string Password { get; set; }

    [Compare(nameof(Password), ErrorMessage = "Passwords do not match.")]
    public string ConfirmPassword { get; set; }
}

ModelState 如何报告错误

验证失败时，ASP.NET Core 会将错误填入 ModelState。在使用 [ApiController] 修饰的 API 控制器中，无效请求会自动返回 400 响应，因此您很少需要手动检查它。

[ApiController]
[Route("api/[controller]")]
public class AccountController : ControllerBase
{
    [HttpPost("register")]
    public IActionResult Register(RegisterRequest request)
    {
        // [ApiController] already returned 400 if invalid
        return Ok("Registered " + request.Username);
    }
}

手动检查 ModelState

如果没有使用 [ApiController]（例如在 MVC 控制器中），您需要自行检查 ModelState.IsValid，并决定如何响应。

public IActionResult Register(RegisterRequest request)
{
    if (!ModelState.IsValid)
    {
        return BadRequest(ModelState);
    }
    return Ok();
}

组合多个注解

注解可以叠加。单个属性可以带有多个特性，并且所有特性都必须通过验证。求值顺序并不重要，但请保持代码易读。

public class SignupRequest
{
    [Required]
    [EmailAddress]
    [StringLength(254)]
    public string Email { get; set; }

    [Required]
    [Range(18, 120, ErrorMessage = "Must be 18 or older.")]
    public int Age { get; set; }
}

数据注解的局限

数据注解非常适合简单的声明式规则。但是，跨属性逻辑、数据库查询或条件规则（“仅当 X 满足条件时才必填”）很快就会变得难以处理。这正是 FluentValidation 的优势所在，我们将在下一部分介绍它。

快速检查

测试您对数据注解的理解。

回顾

您已经学习了如何使用数据注解特性声明验证规则：使用 [Required] 检查是否提供，使用 [Range] 限制数值范围，使用 [EmailAddress] 验证电子邮件格式，以及使用 [StringLength]、[RegularExpression] 和 [Compare]。使用 [ApiController] 时，验证失败会通过 ModelState 自动返回 400。对于复杂规则，接下来可以使用 FluentValidation。

常见问题解答

「数据注解验证」课时是免费的吗？

是的 — 「数据注解验证」的完整文本可在网页上免费阅读。要进行交互式练习（内置代码编辑器和全天候 AI 导师）并解锁 C# Academy 课程的其余内容，请升级到 CoddyKit PRO。 C# Academy 课程共包含 4 节课。

「数据注解验证」这节课中我会学到什么？

使用特性验证模型。你通过在浏览器中直接运行的动手代码来练习 C# Academy，全天候 AI 导师会在你学习这节课的过程中回答你的问题。

学习 C# Academy 需要有经验吗？

无需任何先前经验。CoddyKit 上的 C# Academy 课程适合初学者到高级学习者，你可以从这里开始或从头开始，按照自己的节奏学习。这是第 1 节课，共 4 节。

「数据注解验证」课时需要多长时间？

大多数 CoddyKit 课程大约需要 5–10 分钟。每节课都很精短且互动，所以你能稳步进步，并在网页和应用中从离开的地方继续。

我能在这节 C# Academy 课中编写并运行代码吗？

能。每节 C# Academy 课都包含内置代码编辑器，你可以在浏览器中直接编写并运行真实代码，并获得即时 AI 反馈 — 无需本地设置。

此课程中的所有课时

← 返回 C# Academy