practical-aspnetcore 实战:在 Minimal API 的 Map 路由处理器中通过依赖注入访问自定义对象

原创2026-10-15 20:52:501,711 阅读
文章标签:示例工程

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.Map responds 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 的最大不同在于两处:

  1. 使用了 WebApplication.CreateBuilder() 创建宿主并显式注册服务:
    var builder = WebApplication.CreateBuilder();
    builder.Services.AddSingleton<MyData>();
    
  2. 处理器参数类型 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 三个相互配合的核心机制:

  1. Map 路由:不区分 HTTP 动词,为所有请求方法提供服务,是快速搭建 API 的低摩擦入口;
  2. 参数注入:路由处理器可以直接声明自定义业务对象作为参数,框架自动从请求作用域的 DI 容器解析并注入,无需手动访问 HttpContext.RequestServices;
  3. 服务注册:builder.Services.AddSingleton<T>() 等注册方法决定了对象的生命周期,是对象注入能够工作的前提。

原文(map-3/README.md)只给出了一句话概述,而仓库中的 Program.cs 提供了完整可运行的实现。将它与同系列 map、map-2 以及 DI 生命周期示例 dependency-injection-1 对照阅读,即可快速建立"Minimal API 路由 + 依赖注入"的完整知识框架。

登录后查看全文
practical-aspnetcore