文章元信息

  • 作者：刚子
  • 系列名称：.NET 8 现代Web开发实战指南
  • 原文链接：https://www.codeobservatory.cn/post/dotnet-8-web-development-part5-data-validation-global-exception-handling
  • 关键词：数据验证, FluentValidation, 模型绑定, 全局异常处理, ExceptionHandler, API健壮性
  • 摘要：本文将聚焦于Web API的防御性编程。通过对比原生数据注解与第三方库FluentValidation，教你如何优雅地拦截非法数据；同时构建全局异常处理中间件，确保系统在崩溃时也能返回标准的JSON错误信息，提升系统的专业度与可维护性。

一、前言：别让“脏数据”搞垮你的系统

在上一篇中，我们实现了数据的增删改查。但现实是残酷的：前端可能会传给你一个空的标题、负数的ID，甚至是一段恶意脚本。如果我们不做防御，这些“脏数据”会像病毒一样侵入数据库。

作为一个有追求的开发者，不仅要“能写”，还要“能防”。这一篇，我们来打造系统的“安全盾牌”。

二、第一道防线：模型绑定与基础验证

ASP.NET Core 自带了基础的验证机制。当请求体（Body）中的JSON数据被反序列化为对象时，框架会自动检查数据注解。

2.1 使用 Data Annotations (数据注解)

这是最简单的方式，通过给属性加“标签”来定义规则。

修改 Models/TodoItem.cs：

using System.ComponentModel.DataAnnotations;

public class TodoItem
{
    public int Id { get; set; }

    [Required(ErrorMessage = "标题不能为空")] // 必填
    [StringLength(100, ErrorMessage = "标题长度不能超过100")] // 最大长度
    public string? Title { get; set; }

    public bool IsDone { get; set; }
    
    public DateTime CreatedAt { get; set; } = DateTime.Now;
}

2.2 在API中检查验证状态

在Minimal API中，我们需要手动检查 ValidationContext，这比传统Controller稍微麻烦一点，但更灵活。

using System.ComponentModel.DataAnnotations;

app.MapPost("/todos/basic-validate", (TodoItem todo) =>
{
    // 手动创建验证上下文
    var validationContext = new ValidationContext(todo);
    var validationResults = new List<ValidationResult>();
    
    // 执行验证
    bool isValid = Validator.TryValidateObject(todo, validationContext, validationResults, true);

    if (!isValid)
    {
        // 如果验证失败，返回400错误和具体错误信息
        return Results.BadRequest(validationResults.Select(r => r.ErrorMessage));
    }

    // 验证通过，执行业务逻辑...
    return Results.Ok("数据合法");
});

刚子小贴士： 这种方式虽然简单，但缺点很明显：验证规则写在了实体类里，导致类变得臃肿。而且复杂的逻辑（比如“标题不能包含敏感词”）很难用标签实现。在企业级项目中，我们更推荐下面要讲的 FluentValidation。

三、进阶利器：FluentValidation

FluentValidation 是一个第三方库，它允许你用流式代码定义验证规则，将验证逻辑与实体类彻底分离。

3.1 安装与基础配置

执行命令安装包：

dotnet add package FluentValidation.AspNetCore

3.2 定义验证器

创建 Validators/TodoItemValidator.cs：

using FluentValidation;
using MyTodoApp.Models;

public class TodoItemValidator : AbstractValidator<TodoItem>
{
    public TodoItemValidator()
    {
        // 规则1：标题不为空
        RuleFor(x => x.Title)
            .NotEmpty().WithMessage("任务标题必须填写")
            .MaximumLength(50).WithMessage("标题太长了，别超过50个字");

        // 规则2：自定义逻辑验证
        RuleFor(x => x.Title)
            .Must(title => !title.Contains("傻子")).WithMessage("标题包含敏感词，请文明用语");
    }
}

3.3 注册与自动验证

在 Program.cs 中注册服务：

builder.Services.AddFluentValidationAutoValidation(); // 开启自动验证
builder.Services.AddValidatorsFromAssemblyContaining<Program>(); // 扫描当前程序集的所有验证器

改造API接口： 现在，当请求进入时，框架会自动验证。如果失败，直接返回400。我们可以这样写：

app.MapPost("/todos", (TodoItem todo, AppDbContext db) =>
{
    // 如果走到这里，说明验证已经通过了
    db.Todos.Add(todo);
    db.SaveChanges();
    return Results.Created($"/todos/{todo.Id}", todo);
});

刚子敲黑板： FluentValidation 最强大的地方在于它的可复用性和可测试性。你可以单独对这个 Validator 类写单元测试，确保验证逻辑的正确性，而不用担心业务逻辑的干扰。

四、第二道防线：全局异常处理

只有验证是不够的。代码运行时总会遇到意想不到的错误：数据库连接断了、文件找不到了、甚至是你写了 int.Parse("abc")。

如果不管这些异常，用户会看到浏览器返回一个黄色的错误页面（开发环境）或者裸露的堆栈信息（生产环境），这非常不专业，甚至可能泄露敏感代码路径。

4.1 构建统一响应格式

我们需要定义一个标准的错误返回格式，无论哪里出错，前端收到的结构都是一样的。

// 定义错误响应模型
public class ErrorResponse
{
    public int StatusCode { get; set; }
    public string Message { get; set; }
    public string? Detail { get; set; } // 仅开发环境显示
}

4.2 编写异常处理中间件

我们在管道的最前端放置一个“捕鱼网”，捕获所有后续抛出的异常。

修改 Program.cs：

var app = builder.Build();

// --- 全局异常处理中间件 ---
app.UseExceptionHandler(errorApp =>
{
    errorApp.Run(async context =>
    {
        // 1. 获取异常详情
        var exceptionHandlerFeature = context.Features.Get<IExceptionHandlerFeature>();
        var exception = exceptionHandlerFeature?.Error;

        // 2. 设置响应状态码和内容类型
        context.Response.StatusCode = 500;
        context.Response.ContentType = "application/json";

        // 3. 构造返回对象
        var response = new ErrorResponse
        {
            StatusCode = 500,
            Message = "服务器内部错误，请稍后重试", // 给用户看的友好信息
            Detail = app.Environment.IsDevelopment() ? exception?.Message : null // 开发环境下显示具体错误
        };

        // 4. 序列化并返回
        await context.Response.WriteAsJsonAsync(response);
    });
});

// ... 其他中间件 ...

4.3 实战模拟异常

我们故意写一个会报错的接口：

app.MapGet("/error-test", () =>
{
    throw new Exception("哎呀，这里发生了一个模拟的严重错误！");
    return "这里永远走不到";
});

访问这个接口，在生产环境下，用户会看到：

{
  "statusCode": 500,
  "message": "服务器内部错误，请稍后重试",
  "detail": null
}

而在开发环境下，你作为开发者可以看到 detail 里的具体错误信息，方便调试。

【配图建议 1】 位置：全局异常处理代码演示之后。 内容：Postman 或 Swagger 的响应截图。展示当后端抛出异常时，前端收到的是标准的 JSON 格式错误信息，而不是默认的HTML错误页面。 Alt文本：全局异常处理中间件捕获异常后返回的标准JSON错误响应截图。

五、整合：验证 + 异常处理 = 稳健

现在我们的系统已经具备了双重防御：

  1. 外层防御：FluentValidation 在数据绑定时拦截非法数据，返回 400 Bad Request。
  2. 内层兜底：Exception Handler 捕获所有未处理的运行时异常，返回 500 Internal Server Error。

刚子敲黑板： 在真实项目中，还有一种常见的做法是使用 ProblemDetails 类。这是微软定义的一种标准错误响应格式（RFC 7807）。在 Minimal API 中，你可以直接使用 Results.Problem("出错了")，它会自动生成符合规范的响应，非常适合对接第三方系统。

六、总结与下篇预告

在这篇文章中，我们完成了系统的防御体系建设。

  • 学会了使用 FluentValidation 替代传统的 Data Annotations，实现验证逻辑的解耦。
  • 学会了使用 Exception Handler Middleware 统一处理异常，提升用户体验。

现在的应用，不仅跑得快，而且“身体倍儿棒，吃嘛嘛香”。

下一篇预告：

后端接口写好了，数据也能存取了。但是，谁来调用这些接口？是手机App？是网页？还是另一个微服务？ 在下一篇教程中，我们将开启 Blazor 之旅。Blazor 是 .NET 生态的黑科技，它允许你只用 C# 语言（无需深入学习复杂的 React/Vue 或 JavaScript）就能构建现代的前端交互页面。后端工程师也能写前端，全栈开发的大门即将打开。

准备好迎接全栈挑战了吗？