在 ASP.NET Core 里，路由约束用于限制 URL 中参数段所能匹配的值类型或格式。通过在路由模板中使用冒号加约束名的方式，就能快速过滤掉不符合要求的请求，从而减少控制器里的参数校验负担。
内置路由约束写法
最常见的做法是在 MapControllerRoute 或最小 API 的路由模板中直接添加约束。例如下面的代码限制 id 必须是大于 0 的整数：
// 在 Program.cs 中配置控制器路由
app.MapControllerRoute(
name: "default",
pattern: "products/{id:int:min(1)}",
defaults: new { controller = "Products", action = "Details" });
// 最小 API 写法
app.MapGet("/users/{id:int:max(1000)}", (int id) => $"用户编号：{id}");
常用内置约束
int：匹配 32 位整数alpha：只匹配字母length(n)：限定字符串长度regex(表达式)：使用正则表达式
自定义路由约束
当内置约束不够用时，可以实现 IRouteConstraint 接口来编写自己的规则。下面示例限制参数必须为偶数：
using Microsoft.AspNetCore.Routing;
using System.Text.RegularExpressions;
public class EvenNumberConstraint : IRouteConstraint
{
public bool Match(
HttpContext? httpContext,
IRouter? route,
string routeKey,
RouteValueDictionary values,
RouteDirection routeDirection)
{
// 尝试获取路由值并判断是否为偶数
if (values.TryGetValue(routeKey, out var value))
{
if (int.TryParse(value?.ToString(), out int num))
{
return num % 2 == 0;
}
}
return false;
}
}
注册自定义约束
定义好类之后，需要在服务配置中注册，才能在模板里用短名称引用：
// 在 Program.cs 顶部注册
builder.Services.AddRouting(options =>
{
options.ConstraintMap.Add("even", typeof(EvenNumberConstraint));
});
// 使用自定义约束
app.MapGet("/orders/{id:even}", (int id) => $"偶数订单：{id}");
约束失效的常见原因
| 现象 | 可能原因 |
|---|---|
| 约束不生效 | 路由注册顺序靠后，被更宽泛模板先匹配 |
| 404 而非 400 | 约束不匹配时 ASP.NET Core 视为无路由 |
| 自定义名报错 | 未在 ConstraintMap 中注册短名称 |
小结
ASP.NET Core 的路由约束既支持简洁的内置声明，也支持灵活的自定义扩展。合理运用它们，可以让入口层就拦掉非法请求，使业务代码更干净。实际项目中建议把复杂规则做成可复用约束类，并保持路由模板清晰易读。
ASP.NET_Core路由约束RouteConstraint中间件端点路由修改时间：2026-07-25 09:09:09