EasyData中间件路由机制深度解析：从正则路由表到EasyDataApiHandler的完整请求链路

EasyData中间件路由机制深度解析从正则路由表到EasyDataApiHandler的完整请求链路【免费下载链接】EasyDataAdaptive CRUD for ASP.NET Core. With EasyData you can get both API endpoints and client-side UI for all CRUD operations in a matter of minutes using just your DbContext and a few lines of code.项目地址: https://gitcode.com/gh_mirrors/ea/EasyDataEasyData 是一款面向 ASP.NET Core 的自适应 CRUD 框架只需一个 DbContext 和几行代码就能自动获得完整的 CRUD API 端点和客户端界面。本文将带你快速看懂它的中间件路由机制——一个由正则路由表和 EasyDataApiHandler 组成的、干净利落的请求处理链路无需手写任何 Controller。 整体架构中间件如何接管 CRUD 请求EasyData 没有采用传统 MVC 的 Controller Action 模式而是把整个 API 封装进一个 ASP.NET Core 中间件。所有 CRUD 请求都走同一个入口由中间件内部的路由表分发到对应的处理方法。整个请求链路可以概括为 4 步挂载通过UseEasyData或MapEasyData把中间件接入请求管道前缀匹配中间件判断请求路径是否以配置的端点前缀默认/api/easydata开头正则路由路径剩余部分依次匹配 6 条正则规则确定要执行的操作和参数处理响应创建EasyDataApiHandler实例调用对应的 Handler 方法并写出统一 JSON 响应核心代码位于 easydata.net/src/EasyData.AspNetCore/Middleware/EasyDataMiddleware.cs 和 easydata.net/src/EasyData.AspNetCore/Middleware/EasyDataApiHandler.cs。 两种挂载方式UseEasyData 与 MapEasyData扩展方法定义在 EasyDataApplicationBuilderExtensions.cs 和 EasyDataEndpointRouteBuilderExtensions.cs 中提供了两种等价但场景不同的挂载方式。方式一UseEasyData传统中间件管道适用于老式Startup.cs写法中间件会捕获所有请求并自行判断是否需要处理app.UseEasyData(options { options.UseDbContextAppDbContext(); });方式二MapEasyData端点路由推荐适用于 .NET 6 的Program.cs写法。它通过 ASP.NET Core 的路由系统用一个捕获全部子路径的通配模式/{**slug}把请求交给中间件未匹配的请求则直接返回 404app.MapEasyData(options { options.UseDbContextAppDbContext(); });示例项目 samples/EasyDataBasicDemo.RazorPages.Net6/Program.cs 中就是这种标准用法。两种方式最终都会注册同一个泛型中间件EasyDataMiddlewareTHandler区别只在于由谁负责拦截请求。 正则路由表6 条规则定义全部 CRUD 端点这是整个机制中最精彩的部分。EasyDataMiddleware内部维护了一张静态路由表每张路由卡由三部分组成操作名Action、正则表达式Regex、HTTP 方法Method操作正则模式方法说明GetModel^/models/([^/]?)$GET获取数据模型元数据FetchRecord^/models/([^/]?)/sources/([^/]?)/fetch$GET按主键查询单条记录FetchDataset^/models/([^/]?)/sources/([^/]?)/fetch$POST分页/过滤查询数据集CreateRecord^/models/([^/]?)/sources/([^/]?)/create$POST创建记录UpdateRecord^/models/([^/]?)/sources/([^/]?)/update$POST更新记录DeleteRecord^/models/([^/]?)/sources/([^/]?)/delete$POST删除记录几个设计亮点同一 URL 靠 HTTP 方法区分读写/fetch路径既可以是 GET取单条也可以是 POST取数据集互不冲突两个捕获组提取参数第 1 组是模型 ID如__default第 2 组是实体类型名如Customer写操作统一 POST创建、更新、删除都使用 POST请求体携带 JSON 数据⚙️ InvokeAsync请求匹配的核心逻辑请求进入EasyDataMiddleware.InvokeAsync后依次执行以下判断前缀判断path.StartsWithSegments(_options.Endpoint, ...)检查路径是否以端点前缀开头取出前缀之后的剩余部分作为命令串。非 EasyData 请求直接await _next(context)放行不影响其他中间件安全校验如果未通过UseManager注册数据管理器直接抛出EasyDataManagerException提示配置遗漏URL 解码命令串经过HttpUtility.UrlDecode防止实体名编码问题逐条匹配遍历路由表当正则恰好命中 1 次且 HTTP 方法相同时提取modelId和entityTypeName记录操作名后跳出创建 Handler通过ManagerResolver拿到EasyDataManager用反射创建THandler默认即EasyDataApiHandler实例分发执行switch语句按操作名调用对应的Handle*Async方法任何异常统一交给HandleExceptionAsync兜底这套前缀 正则 方法的三重匹配让 6 个端点共用一个中间件比手写 6 个 Controller Action 简洁得多。️ EasyDataApiHandler六大 Handler 方法路由命中后真正干活的是EasyDataApiHandler。它持有三样东西HttpContext、EasyDataManager封装全部业务逻辑和EasyDataOptions。Handler 方法数据来源响应内容HandleGetModelAsyncManager.GetModelAsyncmodel字段客户端渲染 UI 所需元数据HandleFetchDatasetAsync请求体中的 offset/limit/filtersmeta.totalRecordsresultSetHandleFetchRecordAsyncURL 查询字符串主键值record字段HandleCreateRecordAsync请求体 JSON新建后的recordHandleUpdateRecordAsync请求体 JSON更新后的recordHandleDeleteRecordAsync请求体 JSON空 body仅result: ok以数据集查询为例Handler 用流式JsonTextReader读取请求体解析出offset、limit、needTotal、lookup、filters等参数再交给 Manager 执行查询。过滤条件通过Options.RegisterFilter注册的类型动态解析——这就是 EasyData 允许用户自定义过滤器的扩展点。统一 JSON 响应格式所有响应都遵循同一信封结构由私有的WriteJsonResponseAsync方法保证{ result: ok, resultSet: { ...: ... } }成功result为ok附带具体数据字段失败result为error并携带message默认 400ContainerNotFoundException/RecordNotFoundException会返回 404响应头固定为application/json; charsetutf-8UTF-8 无 BOM序列化器设置了MaxDepth 1防深层嵌套攻击 泛型 THandler官方留好的扩展点注意中间件签名是EasyDataMiddlewareTHandler where THandler : EasyDataApiHandler——Handler 类型是泛型参数。所有Handle*和Write*Response方法都是virtual的你可以继承EasyDataApiHandler并重写响应写入逻辑例如在 GetModel 响应中附加权限信息然后用MapEasyDataMyCustomHandler(...)挂载即可路由表一行都不用改。 小结一条链路看懂 EasyData 中间件请求 → 前缀匹配(/api/easydata) → 正则路由表(6条规则) → 提取 modelId/entityType → EasyDataApiHandler.Handle*Async → EasyDataManager(业务逻辑) → 统一 JSON 信封响应 { result: ok, ... }EasyData 用一张静态正则路由表 一个可继承的 Handler 基类替代了传统方案里成堆的 Controller 和 Action。理解这条链路后你可以快速自定义端点前缀options.Endpoint注册自定义过滤器options.RegisterFilter继承 Handler 定制响应结构想动手验证可以参考测试项目 easydata.net/test/EasyData.AspNetCore.Tests/EasyDataMiddlewareTests.cs里面覆盖了全部 6 个端点的真实请求与响应断言。【免费下载链接】EasyDataAdaptive CRUD for ASP.NET Core. With EasyData you can get both API endpoints and client-side UI for all CRUD operations in a matter of minutes using just your DbContext and a few lines of code.项目地址: https://gitcode.com/gh_mirrors/ea/EasyData创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考