practical-aspnetcore 实战:在 Minimal API 的 Map 路由处理器中通过依赖注入访问自定义对象
practical-aspnetcore 实战:在 Minimal API 的 Map 路由处理器中通过依赖注入访问自定义对象
导读
本文围绕 practical-aspnetcore 仓库中 projects/minimal-api/map-3 示例,深入讲解 ASP.NET Core Minimal API 中 Map 路由处理器的参数注入机制:如何把注册在 DI 容器中的自定义业务对象直接作为处理器方法参数,由框架自动完成解析与绑定,无需手动从 HttpContext.RequestServices 取用。读完本文你将掌握 IEndpointConventionBuilder.Map 的用法、服务注册生命周期(Singleton / Scoped / Transient)的选择依据,以及如何用依赖注入写出更简洁、可测试的 Minimal API 端点。
一、示例概述:在 Map 中访问你自己的对象
仓库中 map-3 是一个只有 13 行核心代码的最小示例,完整源码位于 projects/minimal-api/map-3/Program.cs:
IResult TryContext(MyData data) => Results.Json(new { greetings = $"Hello {data.Name}" });
var builder = WebApplication.CreateBuilder();
builder.Services.AddSingleton<MyData>();
var app = builder.Build();
app.Map("/", TryContext);
app.Run();
public class MyData
{
public string Name => "Anne";
}
示例项目的目标框架为 .NET 10(见 map-3.csproj,<TargetFramework>net10.0</TargetFramework>),仓库根目录的 global.json 指定 SDK 版本 10.0.0 并允许 rollForward。
代码要表达的核心能力只有一句话:Map 路由处理器不只是能接收 HttpContext、HttpRequest 等框架内置类型,还能直接接收你自己定义的、已注册到依赖注入容器的业务对象。框架会自动把请求作用域(RequestServices)中的服务实例注入到处理器的参数里。
运行方式与其他示例一致,在项目目录下执行:
dotnet run
然后访问 http://localhost:5000/(具体端口以启动日志为准),浏览器会收到如下 JSON 响应:
{"greetings":"Hello Anne"}
二、Map 路由处理器:响应所有 HTTP 动词的 Minimal API 入口
在进入依赖注入主题之前,先明确 Map 在 Minimal API 中的位置。
Minimal API 是 ASP.NET Core 中不依赖 Controller 即可构建 Web API 的方式。仓库 projects/minimal-api/README.md 中把 map 系列归纳为 "Minimal Routing",并说明这些示例既适用于传统 Host.CreateDefaultBuilder(args) 宿主配置风格,也适用于新的 WebApplication 最小宿主 API。
Map 与其他路由方法(MapGet、MapPost、MapPut、MapDelete)的关键区别在于:Map 不限定 HTTP 动词,对 GET、POST、PUT、PATCH、DELETE 等所有请求都做出响应。这一结论在 projects/minimal-api/map/README.md 中被明确记录:
IEndpointConventionBuilder.Mapresponds to all HTTP Verbs.
map 系列在仓库中是循序渐进的一组实验:
| 示例 | 主题 |
|---|---|
| map | 用 Map 返回 JSON(Results.Json) |
| map-2 | 在 Map 中访问 HttpContext |
| map-3 | 在 Map 中访问自定义对象(本文主题) |
| map-4 | 用 .NET 10 内置 OpenAPI 扩展端点描述 |
| map-5 | 直接注入 HttpRequest,不依赖 HttpContext |
| map-6 | 用 IEndpointRouteBuilder 组织路由代码 |
把三个示例放在一起对比,能更直观地理解"对象注入"的演进逻辑:
// map:直接返回 JsonResult,不接收任何参数
IResult Index() => Results.Json(new Greeting("Hello World"));
app.Map("/", Index);
// map-2:注入框架内置类型 HttpContext
IResult TryContext(HttpContext context) => Results.Json(new { path = context.Request.Path });
app.Map("/", TryContext);
// map-3:注入自定义业务对象 MyData
IResult TryContext(MyData data) => Results.Json(new { greetings = $"Hello {data.Name}" });
app.Map("/", TryContext);
从 map 到 map-2 再到 map-3,恰好展示了 Minimal API 处理器参数绑定的完整谱系:无参 → 框架内置类型 → 自定义注册服务。
三、依赖注入解析:自定义对象如何进入处理器
3.1 服务注册是关键前提
map-3 与 map、map-2 的最大不同在于两处:
- 使用了
WebApplication.CreateBuilder()创建宿主并显式注册服务:var builder = WebApplication.CreateBuilder(); builder.Services.AddSingleton<MyData>(); - 处理器参数类型
MyData是自定义类,而不是框架内置类型:public class MyData { public string Name => "Anne"; }
builder.Services 就是 ASP.NET Core 的 IServiceCollection。AddSingleton<MyData>() 把 MyData 注册为单例服务,此后 Minimal API 的路由处理器就能把 MyData 声明为参数,框架在每次请求到来时自动从服务容器中解析并注入。
值得注意的一个细节:处理器方法 TryContext 被定义在 Program.cs 顶层(top-level statements 中的局部函数),方法名保留了来自 map-2 的命名习惯 TryContext——在 map-2 里它接收 HttpContext,在 map-3 里参数变成了 MyData,这正好说明了 Minimal API 的处理器签名可以由开发者自由定义,框架按参数类型做绑定,方法名本身没有语义约束。
3.2 注入的服务从哪里来
Minimal API 的参数绑定规则中,有一部分类型不会走请求正文(body)绑定,而是直接从 DI 容器解析,这包括:
- 框架内置类型:
HttpContext、HttpRequest、HttpResponse、CancellationToken、ClaimsPrincipal等(参见 parameter-binding-special-types 示例); - 注册到
IServiceCollection的任何自定义服务类型,即本文MyData所属的类别。
处理器的每个请求都会在一个请求作用域(request scope)中执行,因此从实现机制上讲,MyData data 这一参数相当于在每次请求时执行了:
var data = context.RequestServices.GetService<MyData>();
即"从请求作用域解析服务",然后再调用 TryContext。这一点可以从仓库中另一个更"手动"的示例得到印证:projects/dependency-injection/dependency-injection-1/Program.cs 展示了不依赖参数注入、而是通过 context.RequestServices.GetService<T>() 显式取用 Singleton / Scoped / Transient 服务的写法。map-3 的意义在于:Minimal API 把这一步自动化了,你不需要触碰 HttpContext.RequestServices,只要在方法签名里声明类型即可。
3.3 响应构造:Results.Json 与匿名对象
处理器返回类型是 IResult,实际返回的是 Results.Json(...):
IResult TryContext(MyData data) => Results.Json(new { greetings = $"Hello {data.Name}" });
这里把 MyData.Name(固定返回 "Anne")插值进字符串,封装进匿名对象,再交给 Results.Json 序列化为 JSON。这是 Minimal API 中最常见的 JSON 响应构造方式之一;在 map 示例中还有使用强类型 record(Greeting)配合 Results.Json 的写法。若需要强类型返回并让测试断言更精确,也可以使用 TypedResults.Json(参见 typed-results-1 中 JsonHttpResult<Person> 的 Xunit 断言示例)。
四、服务生命周期选择:为什么这里用 Singleton
map-3 使用 AddSingleton<MyData>() 注册服务。ASP.NET Core 的 DI 容器提供三种主要生命周期:
| 生命周期 | 注册方法 | 实例存活范围 | 适用场景 |
|---|---|---|---|
| 单例 | AddSingleton<T>() |
整个应用进程生命周期内只有一个实例 | 无状态或共享状态的服务、配置对象、只读数据 |
| 作用域 | AddScoped<T>() |
每个请求(scope)一个实例 | EF Core DbContext、与请求绑定的状态 |
| 瞬态 | AddTransient<T>() |
每次解析都新建实例 | 轻量、无状态、构造开销小的服务 |
MyData 只暴露一个只读属性 Name => "Anne",不携带任何可变状态,属于典型的无状态服务,因此单例注册既正确又高效。仓库中的 dependency-injection-1 通过在不同生命周期类中记录 DateTime.Now 并刷新页面,直观演示了三种生命周期的差异;如果 MyData 被改为 Scoped 或 Transient 注册,对当前示例的输出结果没有任何影响(因为 Name 恒定),但这正是理解生命周期语义的好起点。
五、实战扩展:对象注入与内置类型混合使用
map-3 只演示了单一自定义参数。在实际项目中,处理器参数可以自由混合"内置类型 + 自定义服务",例如同时接收 HttpContext 和业务服务:
IResult TryContext(MyData data, HttpContext context)
=> Results.Json(new { greetings = $"Hello {data.Name}", path = context.Request.Path.ToString() });
框架会按类型分别处理:MyData 从 DI 解析,HttpContext 由框架直接提供。这种"声明式取依赖"的写法让处理器签名本身就成为依赖清单,可读性和可测试性都比手写 RequestServices.GetService<T>() 更好。
同理,如果想处理 POST 请求并把 JSON 请求体绑定到模型,可以在 MapPost 中结合 <a href="https://link.gitcode.com/i/23db1716519113c8728f8af3ae9b6438" target="_blank">FromBody] 与 DI 服务,参考 [map-post 与 map-post-2 的写法;若需要同时支持多个动词,则使用 MapMethods(见 map-methods)。
六、小结
map-3 示例虽然只有十几行代码,却浓缩了 Minimal API 三个相互配合的核心机制:
Map路由:不区分 HTTP 动词,为所有请求方法提供服务,是快速搭建 API 的低摩擦入口;- 参数注入:路由处理器可以直接声明自定义业务对象作为参数,框架自动从请求作用域的 DI 容器解析并注入,无需手动访问
HttpContext.RequestServices; - 服务注册:
builder.Services.AddSingleton<T>()等注册方法决定了对象的生命周期,是对象注入能够工作的前提。
原文(map-3/README.md)只给出了一句话概述,而仓库中的 Program.cs 提供了完整可运行的实现。将它与同系列 map、map-2 以及 DI 生命周期示例 dependency-injection-1 对照阅读,即可快速建立"Minimal API 路由 + 依赖注入"的完整知识框架。