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

2026年5月5日
| 没有评论

一、.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

.net, abp