.NET Web API、路由、模型验证、过滤器、全局异常

爱吃大洋芋

一、.NET Web API 是什么

 

ASP.NET Web API 是微软用于构建 HTTP 服务 的框架，专门用来开发：

 

• 前后端分离接口
• 移动端 API
• 微服务接口

 

它基于 Controller + Action 模式，返回 JSON/XML 数据，不返回页面。

 

---

 

二、路由（Routing）

 

路由的作用：把 URL 映射到控制器的方法

 

1. 两种路由方式

 

（1）特性路由

 

直接在控制器 / 方法上写 [Route] 定义 URL

 

[Route("api/[controller]")]
[ApiController]
public class UserController : ControllerBase
{
    // GET api/user
    [HttpGet]
    public IActionResult GetAll() { ... }

    // GET api/user/10
    [HttpGet("{id}")]
    public IActionResult GetById(int id) { ... }

    // POST api/user
    [HttpPost]
    public IActionResult Add([FromBody] User user) { ... }
}

 

（2）传统路由（少用）

 

在 Program.cs 统一配置

 

app.MapControllerRoute(
    name: "default",
    pattern: "api/{controller}/{action}/{id?}");

 

2. 路由常用特性

 

• [HttpGet] / [HttpPost] / [HttpPut] / [HttpDelete]
• [Route("xxx")] 自定义路由
• [FromBody] 从请求体取数据
• [FromQuery] 从 URL 参数取数据
• [FromRoute] 从路由取数据

 

---

 

三、模型验证（Model Validation）

 

模型验证 = 自动校验前端传入的参数是否合法

 

1. 给模型加数据注解

 

public class User
{
    [Required(ErrorMessage = "姓名不能为空")]
    [StringLength(10, ErrorMessage = "姓名最长10个字符")]
    public string Name { get; set; }

    [Range(18, 60, ErrorMessage = "年龄必须在18-60之间")]
    public int Age { get; set; }

    [EmailAddress(ErrorMessage = "邮箱格式不正确")]
    public string Email { get; set; }
}

 

2. 常用验证特性

 

• [Required] 必填
• [StringLength] 字符串长度
• [Range] 数值范围
• [EmailAddress] 邮箱
• [Phone] 手机号
• [RegularExpression] 正则

 

3. API 中自动验证

 

[ApiController] 特性会自动触发模型验证，验证失败自动返回 400，无需手动判断。

 

返回格式示例：

 

json

 

{
  "errors": {
    "Name": ["姓名不能为空"],
    "Age": ["年龄必须在18-60之间"]
  },
  "title": "One or more validation errors occurred.",
  "status": 400
}

 

---

 

四、过滤器（Filters）

 

过滤器 = 在 Action 执行前后插入逻辑，实现横切关注点（日志、授权、缓存等）

 

1. 5 种过滤器

 

1. Authorization Filter 授权过滤器（最先执行）
2. Resource Filter 资源过滤器
3. Action Filter 方法过滤器（最常用）
4. Exception Filter 异常过滤器
5. Result Filter 结果过滤器

 

2. 自定义 Action 过滤器（示例）

 

public class LogFilter : IActionFilter
{
    // 方法执行前
    public void OnActionExecuting(ActionExecutingContext context)
    {
        Console.WriteLine("API 调用前：" + context.HttpContext.Request.Path);
    }

    // 方法执行后
    public void OnActionExecuted(ActionExecutedContext context)
    {
        Console.WriteLine("API 调用完成");
    }
}

 

3. 注册使用

 

// 全局注册（所有接口生效）
builder.Services.AddControllers(options =>
{
    options.Filters.Add<LogFilter>();
});

// 或控制器/方法单独使用
[ServiceFilter(typeof(LogFilter))]
public IActionResult Test() { ... }

 

---

 

五、全局异常处理（Global Exception）

 

作用：统一捕获所有接口的异常，返回规范错误信息，不暴露敏感堆栈

 

1. 自定义全局异常过滤器

 

public class GlobalExceptionFilter : IExceptionFilter
{
    public void OnException(ExceptionContext context)
    {
        var exception = context.Exception;

        // 统一返回格式
        var result = new
        {
            code = 500,
            message = "服务器异常：" + exception.Message,
            path = context.HttpContext.Request.Path
        };

        context.Result = new JsonResult(result)
        {
            StatusCode = 500
        };

        // 标记异常已处理
        context.ExceptionHandled = true;
    }
}

 

2. 注册全局生效

 

builder.Services.AddControllers(options =>
{
    options.Filters.Add<GlobalExceptionFilter>();
});

 

3. 效果

 

任何接口报错都会返回：

 

json

 

{
  "code": 500,
  "message": "服务器异常：尝试除以零",
  "path": "/api/user"
}

 

---

 

总结

 

1. Web API：构建 HTTP 接口，返回数据
2. 路由：URL 映射到方法，特性路由最常用
3. 模型验证：自动校验参数，[ApiController] 自动处理
4. 过滤器：在接口执行前后插入逻辑（日志、授权）
5. 全局异常：统一捕获错误，返回规范错误信息

来源：https://www.cnblogs.com/chuansheng/p/19913479