核心内容摘要
聚焦国产精品：品质升级，用户至上的新篇章
目录
路由系统核心认知URL 映射的本质
传统路由MVC5 主流配置式路由统一管理规则
1 核心代码示例ASP.NET MVC
5
2 核心规则说明
3 生活类比
属性路由ASP.NET Core 主流注解式路由灵活标注 Action
1 核心前提ASP.NET Core 启用属性路由
2 基础代码示例Action 直接标注 [Route]
3 进阶技巧控制器 Action 组合路由推荐
4 生活类比
传统路由 vs 属性路由核心区别与选型建议
路由开发常踩的 8 个坑附避坑方案新手必看
1 坑 1传统路由优先级顺序写反特殊规则不生效
2 坑 2属性路由忘记加 HTTP 请求方法特性[HttpGet]/[HttpPost]
3 坑 3可选参数未加也未设置默认值
4 坑 4[controller] 令牌使用错误控制器名后缀未写 Controller
5 坑 5传统路由未设置 controller/action 默认值
6 坑 6同一路由规则重复定义导致启动失败
7 坑 7参数类型不匹配导致路由匹配失败
8 坑 8ASP.NET Core 忘记调用 MapControllers ()属性路由全部失效
互动交流 投票
1 互动话题今天带大家吃透ASP.NET的核心基石 ——URL 路由系统。
路由就像网站的 “导航仪”负责把用户输入的 URL 精准映射到对应的业务代码Controller/Action没有它用户的请求就会像没导航的汽车在程序里 “迷路”。
本文会从传统路由MVC5 主流和属性路由ASP.NET Core 主流两大核心类型入手结合可直接运行的代码示例、易理解的生活类比、避坑指南还有流程图和实战技巧让你从入门到精通再也不踩路由的坑
路由系统核心认知URL 映射的本质小节路由是请求的 “翻译官”连接 URL 与业务逻辑ASP.NET路由系统的核心作用就是脱离物理文件路径的限制将用户请求的 URL如/api/Product/Detail/1解析为程序能识别的 “控制器 - 方法 - 参数” 组合最终找到对应的 Action 执行并返回结果。
生活类比你去快递公司寄件不用知道快递员具体在哪个仓库物理路径只需报上收件人地址URL快递系统路由会自动把包裹请求分配给对应的快递员Action这就是路由的价值。
核心流程图是否用户发起URL请求路由中间件拦截请求匹配路由规则 传统/属性匹配成功?解析为Controller/Action/参数执行对应Action并返回结果返回404未找到请求结束
传统路由MVC5 主流配置式路由统一管理规则小节传统路由是 “统一导航规则表”全局配置一次所有请求通用传统路由也叫配置式路由是ASP.NET MVC5 及之前版本的主流方案核心是在全局配置文件中定义统一的路由模板所有 URL 请求都按照这个模板匹配适合路由规则相对固定的场景。
1 核心代码示例ASP.NET MVC5传统路由的配置入口在App_Start/RouteConfig.cs通过RouteTable.Routes添加路由规则核心是路由模板和默认值usingSystem.Web.Mvc;usingSystem.Web.Routing;namespaceMvc5Demo{publicclassRouteConfig{publicstaticvoidRegisterRoutes(RouteCollectionroutes){// 忽略静态文件路由如css、js、图片避免被路由拦截routes.IgnoreRoute({resource}.axd/{*pathInfo});// 定义默认路由MVC5经典路由模板名称不能重复routes.MapRoute(name:Default,// 路由名称全局唯一url:{controller}/{action}/{id},// 核心路由模板defaults:new{controllerHome,actionIndex,idUrlParameter.Optional}// 默认值);// 自定义路由针对后台管理模块优先级高于默认路由routes.MapRoute(name:Admin,url:Admin/{controller}/{action},defaults:new{controllerDashboard,actionIndex});}}配套 Global.asax 注册MVC5 必须步骤usingSystem.Web;usingSystem.Web.Mvc;usingSystem.Web.Routing;namespaceMvc5Demo{publicclassMvcApplication:System.Web.HttpApplication{protectedvoidApplication_Start(){AreaRegistration.RegisterAllAreas();RouteConfig.RegisterRoutes(RouteTable.Routes);// 注册路由规则}}}
2 核心规则说明
路由模板采用{参数名}格式按URL 分段顺序匹配如/Home/Index/1对应controllerHome、actionIndex、id
UrlParameter.Optional表示参数可选无该参数时 URL 可省略如/Home/Index也能匹配默认路由
**路由优先级从上到下**先定义的路由先匹配因此特殊规则如 Admin要放在默认规则前面
必须指定controller和action默认值除非有其他匹配规则否则无法找到目标方法。
3 生活类比传统路由就像小区的统一快递派送规则所有快递都按 “楼栋 / 单元 / 房间号” 的格式派送路由模板如果没写房间号可选参数就默认送到楼栋大堂默认值快递员只需按这个统一规则执行不用单独记每个住户的派送方式。
属性路由ASP.NET Core 主流注解式路由灵活标注 Action小节属性路由是 “个性化导航标签”直接贴在 Action 上按需定义规则属性路由是ASP.NET CoreMVC Core/Web API Core的主流方案核心是通过特性Attribute直接标注在 Controller/Action 上为每个接口定制独立的路由规则摆脱全局模板的限制尤其适合 RESTful API 开发是目前.NET 开发的推荐方案。
1 核心前提ASP.NET Core 启用属性路由ASP.NET Core 中无需单独配置全局路由表只需在Program.cs中通过MapControllers()或MapControllerRoute()启用 MVC/API 支持默认自动识别属性路由特性核心代码.NET 6 极简模式varbuilderWebApplication.CreateBuilder(args);// 添加MVC/API控制器支持包含属性路由解析builder.Services.AddControllers();varappbuilder.Build();// 配置中间件管道启用控制器路由关键步骤app.MapControllers();app.Run();
2 基础代码示例Action 直接标注 [Route]最核心的[Route]特性可直接标注在 Action 上支持固定 URL、参数占位符、可选参数直接运行无依赖usingMicrosoft.AspNetCore.Mvc;namespaceCoreApiDemo.Controllers{// 控制器基地址可选可省略直接在Action上写完整路由[ApiController]// Web API核心特性自动验证模型、返回标准格式publicclassProductController:ControllerBase{// 固定路由匹配 GET /api/product/list[HttpGet][Route(api/product/list)]publicIActionResultGetProductList(){varlistnew[]{new{Id1,Name手机,Price2999}};returnOk(list);}// 带参数路由匹配 GET /api/product/1[HttpGet][Route(api/product/{id})]publicIActionResultGetProductById(intid){returnOk(new{Idid,Name电脑,Price5999});}// 可选参数路由匹配 GET /api/product/search 或 GET /api/product/search/华为[HttpGet][Route(api/product/search/{keyword?})]// ?表示参数可选publicIActionResultSearchProduct(string?keywordnull){varresultkeywordnull?new[]{new{Id1,Name默认商品}}:new[]{new{Id2,Name${keyword}手机}};returnOk(result);}// POST请求路由匹配 POST /api/product[HttpPost][Route(api/product)]publicIActionResultAddProduct([FromBody]Productmodel){returnCreated($/api/product/{model.Id},model);}publicclassProduct{publicintId{get;set;}publicstringName{get;set;}string.Empty;publicdecimalPrice{get;set;}}}}
3 进阶技巧控制器 Action 组合路由推荐通过在 Controller 上标注 [Route] 定义基地址Action 上标注相对路由实现路由复用简化代码这是实际开发的主流写法usingMicrosoft.AspNetCore.Mvc;namespaceCoreApiDemo.Controllers{[ApiController][Route(api/[controller])]// 控制器基路由[controller]自动替换为控制器名Product最终基地址为/api/ProductpublicclassProductController:ControllerBase{// 组合路由api/Product 空 → 匹配 GET /api/Product[HttpGet]publicIActionResultGetList()Ok(商品列表);// 组合路由api/Product {id} → 匹配 GET /api/Product/1[HttpGet({id})]publicIActionResultGetById(intid)Ok($商品ID{id});// 组合路由api/Product search → 匹配 GET /api/Product/search[HttpGet(search)]publicIActionResultSearch(stringkeyword)Ok($搜索关键词{keyword});// 组合路由api/Product batch-delete → 匹配 POST /api/Product/batch-delete[HttpPost(batch-delete)]publicIActionResultBatchDelete([FromBody]int[]ids)Ok($删除{ids.Length}个商品);}}核心亮点[controller]是路由令牌会自动替换为控制器的类名去掉Controller后缀比如ProductController对应[controller] Product后期修改控制器名时路由基地址会自动同步避免手动修改所有 Action 路由。
4 生活类比属性路由就像商场里的店铺指引牌每个店铺Action都有自己独立的指引牌[Route] 特性直接标注 “楼层 / 区域 / 店铺号”路由规则顾客不用记统一的商场导航规则只需看店铺门口的指引牌就能找到尤其适合店铺类型多、布局复杂的大型商场对应 RESTful API 多接口、多规则的场景。
传统路由 vs 属性路由核心区别与选型建议小节无优劣之分只有场景适配Core 开发优先选属性路由为了让大家快速选择适合自己项目的路由方案整理了核心区别对比表并给出明确的选型建议对比维度传统路由MVC5属性路由ASP.NET Core定义方式全局配置文件RouteConfig.cs控制器 / Action 特性标注规则灵活性低统一全局模板特殊规则需单独定义 高为每个 Action定制独立规则维护成本集中维护适合简单场景规则多了易混乱分散维护路由与代码耦合见码知路由适配场景ASP.NET MVC5 传统项目、路由规则固定的简单系统ASP.NET Core 所有项目、RESTful API、复杂多规则接口核心优势全局统一新手易上手适合团队统一规范灵活高效支持 RESTfulCore 原生推荐开发效率高路由令牌无原生动态令牌需手动写死支持 [controller]、[action] 自动替换简化代码选型建议
若维护老项目MVC5 及之前继续使用传统路由无需改造
若开发新项目ASP.NET Core无脑选属性路由符合.NET 官方推荐适配未来开发趋势
若项目接口少、规则固定如简单后台管理系统两种方案均可属性路由更简洁
若项目是RESTful API如前后端分离、微服务必须选属性路由灵活支持各种 API 规则。
路由开发常踩的 8 个坑附避坑方案新手必看小节路由的坑大多是 “规则理解偏差”记住这些要点少走 99% 的弯路路由开发看似简单但新手很容易因为忽略细节导致404 错误、路由匹配混乱、参数接收失败整理了实际开发中最常踩的 8 个坑每个坑都配原因分析 避坑方案看完再也不踩雷
1 坑 1传统路由优先级顺序写反特殊规则不生效现象自定义的 Admin 路由放在默认路由后面访问/Admin/Users/List跳转到 404原因传统路由从上到下匹配默认路由{controller}/{action}/{id}会先匹配/Admin/Users/List解析为controllerAdmin但项目中没有AdminController导致匹配失败避坑方案特殊路由规则必须放在默认路由前面让特殊规则优先匹配。
2 坑 2属性路由忘记加 HTTP 请求方法特性[HttpGet]/[HttpPost]现象Action 只标注[Route(“api/product”)]访问时返回 405 Method Not Allowed原因ASP.NET Core 中属性路由必须结合HTTP 请求方法特性[HttpGet]/[HttpPost]/[HttpPut]/[HttpDelete]否则程序无法识别该路由支持的请求方式避坑方案所有属性路由的 Action必须同时标注 HTTP 请求方法特性与接口的业务语义匹配查询用 Get、新增用 Post、修改用 Put、删除用 Delete。
3 坑 3可选参数未加也未设置默认值现象属性路由写为[Route(“api/product/search/{keyword}”)]访问/api/product/search返回 404原因未加?的参数是必选参数URL 中必须包含该分段否则匹配失败避坑方案可选参数必须在路由中加?同时在方法中设置默认值如string? keyword null两者缺一不可。
4 坑 4[controller] 令牌使用错误控制器名后缀未写 Controller现象控制器类名写为ProductApi标注[Route(“api/[controller]”)]访问/api/ProductApi返回 404原因[controller]令牌的匹配规则是自动去掉控制器类名的 Controller 后缀只有类名以Controller结尾时才会生效如ProductController→Product避坑方案控制器类名必须严格遵循XXXController的命名规范这是ASP.NET的原生约定。
5 坑 5传统路由未设置 controller/action 默认值现象配置路由时未写 defaults访问根路径/返回 404原因传统路由必须明确知道要匹配哪个控制器和方法无默认值时根路径/无法解析为有效的 controller 和 action避坑方案所有传统路由都必须设置controller和action的默认值至少保证默认路由有明确的默认指向如 Home/Index。
6 坑 6同一路由规则重复定义导致启动失败现象两个 Action 都标注[Route(“api/product/info”)]项目启动时抛出异常原因ASP.NET中路由规则必须全局唯一相同的 URL 请求方法组合不能对应多个 Action否则程序无法判断执行哪个避坑方案为每个 Action 定义唯一的路由规则若需实现 “同 URL 不同逻辑”可通过参数区分或修改路由后缀实现。
7 坑 7参数类型不匹配导致路由匹配失败现象路由写为[Route(“api/product/{id}”)]Action 参数为string id访问/api/product/abc正常访问/api/product/1也正常但路由写为int id时访问/api/product/abc返回 404原因路由会自动进行参数类型匹配若 URL 中的参数值无法转换为 Action 的参数类型匹配失败避坑方案根据业务需求定义正确的参数类型若需支持多种类型可将参数设为string后在方法内手动转换。
8 坑 8ASP.NET Core 忘记调用 MapControllers ()属性路由全部失效现象Action 标注了正确的 [Route] 和 [HttpGet]但所有 URL 都返回 404原因ASP.NET Core 中若未在 Program.cs 中调用app.MapControllers()中间件管道不会启用控制器路由解析属性路由自然失效避坑方案在 Program.cs 的中间件配置中必须添加 app.MapControllers ()放在 AddControllers () 之后这是 Core 中启用属性路由的关键步骤。
互动交流 投票小节学路由的核心是多练欢迎分享你的踩坑经历路由系统是ASP.NET开发的基础看似简单但细节满满很多时候大家遇到的 404 问题90% 都是路由规则的小问题。
希望本文的代码示例、避坑指南能帮到大家光看没用一定要动手敲代码测试把每个规则、每个坑都亲自验证一遍才能真正掌握。
1 互动话题欢迎在评论区分享
你在ASP.NET路由开发中遇到过哪些奇葩的坑最后是怎么解决的
你目前的项目用的是传统路由还是属性路由为什么这么选择
关于ASP.NET路由你还有哪些想了解的知识点如区域路由、自定义路由约束等我会逐一回复大家的评论也会根据大家的需求后续更新更多路由进阶技巧如自定义路由约束、路由参数验证、RESTful API 路由最佳实践等。
最后如果本文对你有帮助欢迎点赞、收藏、关注三连后续会持续更新ASP.NET Core 核心知识点和大家一起深耕.NET 开发