前阵子看了一套“[中文字幕]使用 ASP.NET Core 10 构建 Minimal APIs”的实战教程前十分钟给人的感觉非常理想新建空项目一行代码启动 Web 服务再补一个 lambda 表达式一个接口就这么通了。二十分钟后画风变了——要加配置、日志、异常处理、参数校验视频从“十分钟快速上手”变成“一个接口的完整生命周期”弹幕里有人开始问说好的 Minimal API为什么越写越长这个问题恰好是理解 Minimal APIs 的起点。表面上它的卖点是“少写代码”真正放到项目里它重新定义的是“从想法到可运行接口之间的距离”。少不等于简单更不等于不需要工程纪律。一个只有三行代码的接口能跑通和它能经得起来自客户端的乱传参数、失败重试、日志审计、版本升级是两种完全不同的能力。这套教程最有价值的部分恰恰是它没有停在“最短路径”而是继续演示了把最小的接口放在真实应用里需要补齐的东西。如果你想快速了解 ASP.NET Core 10 里如何构建 Minimal APIs这篇会先帮你把“最小”这件事想清楚再给你一条从最小接口逐步走向工程化的落地路线。1. 先理解 Minimal APIs 解决的是一类比“代码量”更麻烦的问题很多人第一次看到 Minimal APIs 时的反应是觉得它把 Controller、Action、模型绑定这些“脚手架”全部藏了起来。写起来确实很轻但为什么要把这些熟悉的东西藏起来只有理解了它想解决的问题你才知道什么场景该用、什么场景不该用。1.1 Controller 式开发为什么会让小服务显得笨重传统 ASP.NET Core 接口通常是一个 Controller 类类里面有一些 Action 方法。即便是最简单的“健康检查”也要创建类、引入命名空间、标注[ApiController]、写路由特性再注册到控制器映射里。一个刚接触框架的人看到这些代码很难分清哪些是必须的业务逻辑哪些只是框架要求的外壳。当业务本身很复杂时Controller 这个分层是值得的——它提供了统一的入口、可以集中处理鉴权、模型绑定、动作选择大量约定可以让多人协作时保持同一套心智。但如果只是想做一个极轻量的 BFF、一个内部工具的小端点、一个返回 JSON 的转发服务Controller 的厚度就会大于收益。你会发现为了送一个ok响应却要组织一堆类和方法这种摩擦积攒多了会让人开始考虑是否必须使用 ASP.NET Core。Minimal APIs 顺着这个问题给出了另一种默认一个请求可以直接对应一个 lambda 表达式或者对应一个被显式调用的方法。框架不再要求你“继承某个类”也不再隐含地扫描程序集找控制器。路由、绑定、执行逻辑都集中在一段肉眼可见的代码里人脑的上下文负担小很多。1.2 “最短路径跑通一次请求”才是它真正的效率来源如果说 Controller 模板代表的是大团队、多模块、高度约定化的风格那么 Minimal APIs 代表的是独立开发者或小团队最原始的直觉给我一个 URL给我一段处理逻辑然后让我看到结果。这种直觉的真正价值不是代码美观而是“试错速度”。当你面对一个新需求、一个不熟悉的新库、一个数据源格式有待验证时你能不能在五分钟内写出一个可访问的接口决定了你迭代想法的方式。Minimal APIs 允许你从“立刻能返回一句话”开始然后一步一步加上校验加上数据库访问加上失败处理。每增加一步你都能马上看到效果而不是先花时间把控制器骨架搭好。所以它解决的并不是“把 1000 行缩到 100 行”的文本压缩问题而是“把一次验证的成本降下来”。这一点在我后续要讲的分层、测试、路由分组中仍然会反复出现——真正成体系的设计不是一开始就要把所有结构摆上来而是允许你随着理解加深逐步引入结构。## 2. 用 ASP.NET Core 10 搭建最小接口的正确姿势 现在我们把视角拉到实际构建步骤。由于 ASP.NET Core 10 仍然沿用了 .NET SDK 中成熟的项目模板如果你之前用过 .NET 6、.NET 8会熟悉绝大多数操作。 ### 2.1 环境准备与版本认知 在开始写代码之前要确保你的 SDK 版本与目标框架匹配。标题里既然提到 ASP.NET Core 10那么你需要在机器上安装 .NET 10 SDK。不同 SDK 版本对应的模板差异不大但个别命令可能存在细微区别。 这里有一条非常稳妥的实践方案 1. 先执行 dotnet --version 查看当前 SDK 版本。 2. 如果低于 .NET 10去对应下载页安装 .NET 10 SDK或者在项目文件里显式指定目标框架。 3. 执行 dotnet new list确认模板列表中有 web 或 webapi 模板。 4. 如果只是学习不要纠结于“ASP.NET Core 10 是否包含某个新特性”这种问题先跑通项目再说。 ASP.NET Core 10 是 .NET 10 框架的一部分它的正式发布节奏要以官方发布说明为准。实际开发中如果你的团队还在使用 .NET 8 LTS那本篇文章里提到的所有 Minimal APIs 基础写法在 .NET 8 和 .NET 9、.NET 10 中依然适用。版本变化更多体现在一些新增容器的语法糖和边界行为上而不是基础模式的天翻地覆。 ### 2.2 从模板开始创建项目和第一个 MapGet 首先创建一个最精简的 Web 项目 bash dotnet new web -n MinimalDemo cd MinimalDemo这样得到的模板中Program.cs会包含大约 4 行代码var builder WebApplication.CreateBuilder(args); var app builder.Build(); app.MapGet(/, () Hello World); app.Run();这段代码已经构成了一个可以运行的服务。builder负责组装应用所需的配置、服务、日志和中间件app代表已经构建好的请求处理管道MapGet把 HTTP GET 请求映射到一个 lambda 表达式上。app.Run启动服务并开始监听。这里有个初学者容易忽略的点WebApplication.CreateBuilder不仅创建了 builder还默认配置了appsettings.json文件、环境变量、命令行参数、控制台日志。也就是说所谓“最小”隐藏了很多合理默认项。不要觉得里面“什么都没有”恰恰相反模板已经帮你解决了大部分跨进程启动问题。你也可以把 lambda 替换为一个普通方法让逻辑更清晰app.MapGet(/hello, (string name) $Hello, {name});“运行dotnet run访问/hello?nameaspnet你会看到Hello, aspnet。到这里一个最小接口就建立了。2.3 请求中的变量、绑定与返回内容Minimal APIs 在参数绑定上有一套由框架自动推断的规则。简单来说它按照参数类型把值从不同位置取出来基本类型默认从查询字符串取复杂类型会尝试从 JSON Body 反序列化带{id}这样的路由参数时变量从路由模板中取。下面是一个同时使用路由参数、查询参数和请求体的例子app.MapPost(/products/{id}, (int id, [FromBody] Product product, bool includeDetails false) { return includeDetails ? Results.Ok(new { Id id, Product product, Time DateTime.UtcNow }) : Results.Ok(new { Id id }); });要注意当你直接返回一个匿名对象时框架会把它序列化成 JSON如果你需要显式控制状态码和响应结构可以使用Results类型。比如Results.Ok(data)返回 200。Results.BadRequest()返回 400。Results.NotFound()返回 404。Results.Created(/products/1, data)返回 201。把返回类型设计成IResult便于在代码里集中管理各个分支的响应而不是依赖某些隐式转换。## 3. 从单接口走向完整业务逻辑最少还要补五件事 一个接口能访问不代表它已经具备了进入真实系统的资格。真实系统通常要面对配置环境、依赖外部服务、记录操作日志、拦截异常、防止非法输入等一系列问题。下面这五件事是你在写完第一个测试接口之后最应该优先补齐的能力。 ### 3.1 依赖注入的接入点builder.Services 和 app.Services Asp.NET Core 的核心容器在 Minimal APIs 里依然存在它只是把注册和使用的动作变得更明显。一个典型业务接口可能有仓储、HttpClient、邮件服务等依赖。你可以在 WebApplication.CreateBuilder 后通过 builder.Services 注册这些服务 csharp builder.Services.AddSingletonTimeService(); builder.Services.AddHttpClientWeatherClient();然后在 MapGet 参数列表中加入服务类型框架会根据 DI 容器自动解析app.MapGet(/time, (TimeService time) time.Now);“凡是写在 lambda 参数里的类型框架会先尝试按服务解析解析不了再按绑定逻辑处理。如果没有注册某个服务但参数里写了这个类型程序启动阶段不会报错真正请求到来时会因为无法确认是“服务”还是“模型”而混淆。为了可读性我建议对需要注入的服务明确使用其类型或直接用方法组模式把业务逻辑放到一个单独方法里这样参数角色更清楚。3.2 输入校验与结果统一很多教程中的 lambda 只有一部快乐路径但客户端从来不会保证一定按文档传参。Minimal APIs 允许你使用各种验证手段但你必须自己决定错误返回。一个简单做法是在 handler 开头做手动判断并返回错误app.MapPost(/products, (Product product) { if (string.IsNullOrWhiteSpace(product.Name)) return Results.BadRequest(new { Error Name is required }); if (product.Price 0) return Results.BadRequest(new { Error Price must be greater than 0 }); return Results.Ok(product); });在 ASP.NET Core 中也可以使用DataAnnotations标注模型属性然后通过调用ValidationResult或使用IValidatableObject来校验。不过Minimal APIs 默认不等于[ApiController]那样的自动 400 响应。你需要把验证结果映射为自己的 API 错误结构让前端或客户端能够理解。一个值得推荐的做法是把“参数校验”和“业务处理”拆开。让每个 handler 只负责处理已经校验过的输入而校验逻辑放在接口入口附近这样既不会漏掉错误分支也不会让核心业务逻辑被 if 包满。3.3 配置、日志和异常处理当环境从一个变成多个接口里写死的字符串就要挪到配置文件中。ASP.NET Core 的IConfiguration可以直接注入到 handler 中app.MapGet(/config, (IConfiguration config) config[App:Name] ?? DefaultName);日志同样可以用注入的ILoggerT或ILoggerFactory输出。如果你用了业务服务类那么日志最好放在服务类里只在 handler 层记录和请求相关的摘要。异常处理需要特别强调。一个未捕获异常如果直接抛给框架在开发环境会显示开发者异常页在生成环境通常会变成 500 空响应客户端看不到任何细节。建议在应用的请求管道中加一个全局异常处理中间件app.Use(async (context, next) { try { await next(); } catch (Exception ex) { // 记录日志或发送警报 context.Response.StatusCode 500; await context.Response.WriteAsJsonAsync(new { Error 内部错误 }); } });统一异常处理的价值不只是防止暴露堆栈更在于你能够把所有未预期问题收敛到同一条观测路径上。3.4 路由分组与路由结构化当接口从 1 个变成 10 个再变成 50 个直接在Program.cs里平铺MapGet、MapPost会越来越混乱。对此较新版本的 ASP.NET Core 提供了MapGroup可以对相同前缀的路由做分组var products app.MapGroup(/api/products); products.MapGet(/, (ProductService service) service.GetAll()); products.MapGet(/{id}, (int id, ProductService service) service.GetById(id)); products.MapPost(/, (Product product, ProductService service) service.Add(product));MapGroup 还可以统一配置过滤器、标签、说明文档等。这不仅让文件更容易阅读也为后面引入“竖切模块”打下了基础。3.5 使用 Filters 避免重复逻辑接口往往需要做认证、鉴权、请求日志、响应头附加等横切逻辑。在 Minimal APIs 中这些逻辑既可以用中间件实现也可以挂在路由分组或单个路由上。以下几种方式要分清中间件影响所有进入管道的请求适合做全局的异常处理、请求日志、请求体缓存。路由过滤器Route Filters只影响特定路由适合只对某个 API 组做认证或行为扩展。参数绑定负责将原始请求转换成 handler 需要的数据。Handler 本身只关注该接口的业务输出。比如给一个分组统一加上请求日志过滤器var group app.MapGroup(/api).AddEndpointFilter(async (context, next) { app.Logger.LogInformation($Request to {context.HttpContext.Request.Path}); return await next(context); });这些机制在 ASP.NET Core 8 之后已经比较成熟ASP.NET Core 10 一般会继续兼容但具体 API 命名如果有变化要以当前 SDK 的提示为准。## 4. 实际使用中最容易被低估的三个边界 技术教程通常展示的是风光的一面但在职业生涯里真正决定一个方案是否好用的是它的边界。不带边界地推荐技术和带货没什么区别。 ### 4.1 边界一它适合多少接口的服务 Minimal APIs 没有硬性规定最多支持多少个接口。但从维护性看如果项目里有几百个接口、几十个领域实体、权限规则复杂全部用 MapGet 写在入口点最终一定会变成另一个巨石文件。到时你还是要把 handler 拆到不同类里而这些类已经与传统 Controller 的 Action 差异很小。 我个人的判断是 - 少于 20 个接口Minimal APIs 的组织收益最大。 - 几十到上百个接口只要把 handler 和业务逻辑分层清晰依然可以保持生产力。 - 几百个接口且团队规模大时Controller 的约定扫描、路由前缀语义、模型绑定行为反而能带来更高的统一性。 这意味着选型不是“Minimal APIs 好还是 Controller 好”而是“当前业务有没有复杂到需要强约定。” ### 4.2 边界二不是所有实现都能叫“简单” 一个很容易掉进去的坑是把“逻辑没法用一行 lambda 表达”的问题硬塞进一个 lambda。你为了少创建一个类把所有校验、反序列化后的调整、数据库调用、邮件发送、日志全都写在一个大括号里最后那个方法可能有 300 行。这种代码虽然写着 Minimal APIs却完全违背了它“最小认知负担”的原则。 如果一个 handler 的职责超过“接收输入、调用服务、返回结果”你就应该把真正的业务逻辑提取到独立服务类中。Minimal APIs 不强迫你建类但也不阻止你建类。动态和简洁的边界是不要让一个方法承载你无法完整说清的多项职责。 ### 4.3 边界三版本变化带来的代码迁移成本 ASP.NET Core 的版本演进速度并不慢。今天你用 ASP.NET Core 10 学到的写法如果重视频教程是几个月前录制的出现 API 差异非常正常。迁移成本通常体现在三方面 - **框架版本升级**比如从 .NET 8 迁移到 .NET 10要检查路由、Host 构建、Filter、依赖注入注册方式是否有 breaking change。 - **目标框架重建**因为引入了不同版本 SDK项目文件里目标框架变更后依赖包版本也要跟随调整。 - **语义变化**某些方法的默认行为如结果类型序列化、状态码设置、路由匹配顺序可能在不同版本里有所调整。 在学习时最好给自己保留一个“以当前官方文档和当前 SDK 实际行为为准”的检查习惯。不要因为看了一篇 2023 年的旧文章就觉得所有 API 会永远保持原样。5. 一次完整排查链路从“程序能启动但请求 400”开始使用 Minimal APIs 时最常见的报错往往不是编译错误而是运行时请求不符合预期。下面用一条典型链路展示遇到问题时要怎样按顺序排查。5.1 确认输入是否在预期的位置假设你的接口如下app.MapPost(/products/{id}, (int id, Product product) ...);客户端发送了POST /products/abc以及 JSON 结构体但收到 400。第一件事不是猜是不是程序 bug而是检查id是否能被转换为int。如果客户端把/products/1写成/products/abc模型绑定失败、框架默认会返回 400。根据经验排查顺序建议是先看 URL路径中的内容是字符串还是可以有数字。再看查询字符串对应的参数名是否完全一致大小写通常不敏感但不能多了空格。再看请求体JSON 字段名与 C# 属性的匹配方式是否区分大小写、是否需要[JsonPropertyName]。检查 Content-Typeapplication/json还是text/plain会影响反序列化。5.2 检查路由约束而不是只看路由模板如果你定义了两个相似模板app.MapGet(/users/{id:int}, (int id) ...); app.MapGet(/users/{name}, (string name) ...);客户端请求/users/123会匹配第一个请求/users/abc会匹配第二个。如果参数类型写错路由可能走到意外分支。此时光看路由模板不够还要看参数约束。比如没有写:int约束路径段 123 可能也会被当作字符串导致两个路由发生冲突或选择错误。遇到路由执行结果不符合预期较直接的方法是打开控制台日志查看Microsoft.AspNetCore.Routing的日志确认最终选中的 Endpoint。5.3 把日志和中间件加上以后再复测如果接口仍然报错不要直接改代码先给应用加上适当日志。常见做法是在 Program.cs 中设置日志级别Logging:LogLevel:Microsoft.AspNetCoreInformation或在启动时加环境变量Logging__LogLevel__Microsoft.AspNetCoreInformation这样启动日志会输出路由匹配和请求处理信息。如果你能看到请求进来了但返回不符合预期大概率是 handler 里的分支逻辑有问题如果日志里根本没出现请求则需要检查监听地址、代理转发、防火墙或前置网关。另外如果你添加了自定义中间件或过滤器排查时可以先临时注释掉它们验证基础 handler 是否正常。通过加日志、划分边界可以将问题从“整条链路”缩小到“某一环”。5.4 把工具边界和依赖版本纳入最后一步排查如果代码逻辑看起来没问题日志也没报错那就要检查依赖环境是否运行了正确的 SDKdotnet --info可以查看当前 SDK 和运行时。项目文件中目标框架是否匹配你安装的运行时外部依赖包版本是否与 ASP.NET Core 10 兼容有些第三方库可能还没有发行适配新版本的包。是否使用了某个在新版本中已经过时或行为变化的 API可以到迁移文档中查一下。排查问题的核心不是“快速定位到某一行”而是“先确定问题出在哪一层”。输入、路由、服务、响应、环境每一步都要有证据。## 6. 让 Minimal APIs 项目在 ASP.NET Core 10 里持续演进 最后一个模块我想把前面所有内容收束成一套你可以长期使用的工作方法。看完教程、做出演示项目只算起点。真正有长期价值的是你是否形成一套持续演进的路径。 ### 6.1 先跑通一条最小路径再做目录拆分 新的脚手架项目默认只有一个 Program.cs这很正常。不要一开始就创建大量文件夹和接口。建议先按“一个接口、一个服务、一个模型”的最小闭环跑通然后再把这套闭环里的元素移入各自目录比如 bash Endpoints/ Models/ Services/ Data/这个过程的顺序很有讲究。先跑通意味着你可以随时运行、随时验证后拆分意味着每一次变化都有可验证版本。如果反过来一上来就建大量抽象很容易因为过度设计让一个小项目看起来像企业级应用但运行起来却什么也没做。6.2 结构化而不是硬编码当接口数量增加后你可以按业务模块建立扩展方法public static class ProductEndpoints { public static void MapProductEndpoints(this WebApplication app) { var group app.MapGroup(/api/products); group.MapGet(/, ...); group.MapGet(/{id:int}, ...); group.MapPost(/, ...); } }在 Program.cs 里调用app.MapProductEndpoints(); app.MapUserEndpoints();这种方式没有引入 Controller 的复杂生命周期却能让模块边界保持清晰。它告诉读者“这个模块暴露了哪些端点、端点做什么业务”而把每个端点的实现细节分散到对应的静态类中又不失可读性。6.3 自动化测试是“最小”清单里最该投资的一项Minimal APIs 的 lambda 函数不好测试吗并不是。你完全可以把 lambda 里的逻辑抽象成服务类然后对服务层进行单元测试。同时ASP.NET Core 也提供WebApplicationFactoryT来测试整个应用包括路由匹配、中间件、过滤器等。对于偏内聚的小服务最重要的是接口合约测试用一组固定输入访问某个 URL断言返回的状态码、响应头、JSON 字段名。这些测试价值很高因为接口结构一旦被外部消费改动就不只是改代码的问题。### 6.4 回到主判断少写代码只是结果快速反馈才是原因 当你在 ASP.NET Core 10 中继续探索 Minimal APIs希望对它的理解不再停留在“代码行数少”这个表面印象上。行数少是结果不是原因。原因是框架希望用最小的心智摩擦让你能快速试验一个想法、验证一个协议、暴露一个数据点。 学会三行代码创建接口只是拿到了钥匙真正要掌握的是在保持低启动成本的同时逐步加入团队协作所需的结构和纪律。最小 API不等于“不用学习软件工程”的 API。它仍然需要依赖注入、日志、异常处理、校验、测试和边界意识。区别是这些能力可以由你决定何时引入、以什么形态引入而不是框架强制你一开始就全盘接受。 如果你现在正要上手我用亲身经历给你一条最直接的行动建议先创建项目亲手写一个带路径参数的 MapGet再写一个读请求体的 MapPost然后把校验和日志补上。做完这一步你自然能体会为什么 Microsoft 自从 .NET 6 推出这一模式后一直没有放弃它反而持续在路由分组、过滤器、结果类型上做了大量演进。ASP.NET Core 10 的很多新打磨都会继续围绕这个核心展开让最常用的做法最顺手让不常用的能力在需要时依然触手可及。 ASP.NET Core 10 实战：Minimal APIs 从最小代码到工程化落地
前阵子看了一套“[中文字幕]使用 ASP.NET Core 10 构建 Minimal APIs”的实战教程前十分钟给人的感觉非常理想新建空项目一行代码启动 Web 服务再补一个 lambda 表达式一个接口就这么通了。二十分钟后画风变了——要加配置、日志、异常处理、参数校验视频从“十分钟快速上手”变成“一个接口的完整生命周期”弹幕里有人开始问说好的 Minimal API为什么越写越长这个问题恰好是理解 Minimal APIs 的起点。表面上它的卖点是“少写代码”真正放到项目里它重新定义的是“从想法到可运行接口之间的距离”。少不等于简单更不等于不需要工程纪律。一个只有三行代码的接口能跑通和它能经得起来自客户端的乱传参数、失败重试、日志审计、版本升级是两种完全不同的能力。这套教程最有价值的部分恰恰是它没有停在“最短路径”而是继续演示了把最小的接口放在真实应用里需要补齐的东西。如果你想快速了解 ASP.NET Core 10 里如何构建 Minimal APIs这篇会先帮你把“最小”这件事想清楚再给你一条从最小接口逐步走向工程化的落地路线。1. 先理解 Minimal APIs 解决的是一类比“代码量”更麻烦的问题很多人第一次看到 Minimal APIs 时的反应是觉得它把 Controller、Action、模型绑定这些“脚手架”全部藏了起来。写起来确实很轻但为什么要把这些熟悉的东西藏起来只有理解了它想解决的问题你才知道什么场景该用、什么场景不该用。1.1 Controller 式开发为什么会让小服务显得笨重传统 ASP.NET Core 接口通常是一个 Controller 类类里面有一些 Action 方法。即便是最简单的“健康检查”也要创建类、引入命名空间、标注[ApiController]、写路由特性再注册到控制器映射里。一个刚接触框架的人看到这些代码很难分清哪些是必须的业务逻辑哪些只是框架要求的外壳。当业务本身很复杂时Controller 这个分层是值得的——它提供了统一的入口、可以集中处理鉴权、模型绑定、动作选择大量约定可以让多人协作时保持同一套心智。但如果只是想做一个极轻量的 BFF、一个内部工具的小端点、一个返回 JSON 的转发服务Controller 的厚度就会大于收益。你会发现为了送一个ok响应却要组织一堆类和方法这种摩擦积攒多了会让人开始考虑是否必须使用 ASP.NET Core。Minimal APIs 顺着这个问题给出了另一种默认一个请求可以直接对应一个 lambda 表达式或者对应一个被显式调用的方法。框架不再要求你“继承某个类”也不再隐含地扫描程序集找控制器。路由、绑定、执行逻辑都集中在一段肉眼可见的代码里人脑的上下文负担小很多。1.2 “最短路径跑通一次请求”才是它真正的效率来源如果说 Controller 模板代表的是大团队、多模块、高度约定化的风格那么 Minimal APIs 代表的是独立开发者或小团队最原始的直觉给我一个 URL给我一段处理逻辑然后让我看到结果。这种直觉的真正价值不是代码美观而是“试错速度”。当你面对一个新需求、一个不熟悉的新库、一个数据源格式有待验证时你能不能在五分钟内写出一个可访问的接口决定了你迭代想法的方式。Minimal APIs 允许你从“立刻能返回一句话”开始然后一步一步加上校验加上数据库访问加上失败处理。每增加一步你都能马上看到效果而不是先花时间把控制器骨架搭好。所以它解决的并不是“把 1000 行缩到 100 行”的文本压缩问题而是“把一次验证的成本降下来”。这一点在我后续要讲的分层、测试、路由分组中仍然会反复出现——真正成体系的设计不是一开始就要把所有结构摆上来而是允许你随着理解加深逐步引入结构。## 2. 用 ASP.NET Core 10 搭建最小接口的正确姿势 现在我们把视角拉到实际构建步骤。由于 ASP.NET Core 10 仍然沿用了 .NET SDK 中成熟的项目模板如果你之前用过 .NET 6、.NET 8会熟悉绝大多数操作。 ### 2.1 环境准备与版本认知 在开始写代码之前要确保你的 SDK 版本与目标框架匹配。标题里既然提到 ASP.NET Core 10那么你需要在机器上安装 .NET 10 SDK。不同 SDK 版本对应的模板差异不大但个别命令可能存在细微区别。 这里有一条非常稳妥的实践方案 1. 先执行 dotnet --version 查看当前 SDK 版本。 2. 如果低于 .NET 10去对应下载页安装 .NET 10 SDK或者在项目文件里显式指定目标框架。 3. 执行 dotnet new list确认模板列表中有 web 或 webapi 模板。 4. 如果只是学习不要纠结于“ASP.NET Core 10 是否包含某个新特性”这种问题先跑通项目再说。 ASP.NET Core 10 是 .NET 10 框架的一部分它的正式发布节奏要以官方发布说明为准。实际开发中如果你的团队还在使用 .NET 8 LTS那本篇文章里提到的所有 Minimal APIs 基础写法在 .NET 8 和 .NET 9、.NET 10 中依然适用。版本变化更多体现在一些新增容器的语法糖和边界行为上而不是基础模式的天翻地覆。 ### 2.2 从模板开始创建项目和第一个 MapGet 首先创建一个最精简的 Web 项目 bash dotnet new web -n MinimalDemo cd MinimalDemo这样得到的模板中Program.cs会包含大约 4 行代码var builder WebApplication.CreateBuilder(args); var app builder.Build(); app.MapGet(/, () Hello World); app.Run();这段代码已经构成了一个可以运行的服务。builder负责组装应用所需的配置、服务、日志和中间件app代表已经构建好的请求处理管道MapGet把 HTTP GET 请求映射到一个 lambda 表达式上。app.Run启动服务并开始监听。这里有个初学者容易忽略的点WebApplication.CreateBuilder不仅创建了 builder还默认配置了appsettings.json文件、环境变量、命令行参数、控制台日志。也就是说所谓“最小”隐藏了很多合理默认项。不要觉得里面“什么都没有”恰恰相反模板已经帮你解决了大部分跨进程启动问题。你也可以把 lambda 替换为一个普通方法让逻辑更清晰app.MapGet(/hello, (string name) $Hello, {name});“运行dotnet run访问/hello?nameaspnet你会看到Hello, aspnet。到这里一个最小接口就建立了。2.3 请求中的变量、绑定与返回内容Minimal APIs 在参数绑定上有一套由框架自动推断的规则。简单来说它按照参数类型把值从不同位置取出来基本类型默认从查询字符串取复杂类型会尝试从 JSON Body 反序列化带{id}这样的路由参数时变量从路由模板中取。下面是一个同时使用路由参数、查询参数和请求体的例子app.MapPost(/products/{id}, (int id, [FromBody] Product product, bool includeDetails false) { return includeDetails ? Results.Ok(new { Id id, Product product, Time DateTime.UtcNow }) : Results.Ok(new { Id id }); });要注意当你直接返回一个匿名对象时框架会把它序列化成 JSON如果你需要显式控制状态码和响应结构可以使用Results类型。比如Results.Ok(data)返回 200。Results.BadRequest()返回 400。Results.NotFound()返回 404。Results.Created(/products/1, data)返回 201。把返回类型设计成IResult便于在代码里集中管理各个分支的响应而不是依赖某些隐式转换。## 3. 从单接口走向完整业务逻辑最少还要补五件事 一个接口能访问不代表它已经具备了进入真实系统的资格。真实系统通常要面对配置环境、依赖外部服务、记录操作日志、拦截异常、防止非法输入等一系列问题。下面这五件事是你在写完第一个测试接口之后最应该优先补齐的能力。 ### 3.1 依赖注入的接入点builder.Services 和 app.Services Asp.NET Core 的核心容器在 Minimal APIs 里依然存在它只是把注册和使用的动作变得更明显。一个典型业务接口可能有仓储、HttpClient、邮件服务等依赖。你可以在 WebApplication.CreateBuilder 后通过 builder.Services 注册这些服务 csharp builder.Services.AddSingletonTimeService(); builder.Services.AddHttpClientWeatherClient();然后在 MapGet 参数列表中加入服务类型框架会根据 DI 容器自动解析app.MapGet(/time, (TimeService time) time.Now);“凡是写在 lambda 参数里的类型框架会先尝试按服务解析解析不了再按绑定逻辑处理。如果没有注册某个服务但参数里写了这个类型程序启动阶段不会报错真正请求到来时会因为无法确认是“服务”还是“模型”而混淆。为了可读性我建议对需要注入的服务明确使用其类型或直接用方法组模式把业务逻辑放到一个单独方法里这样参数角色更清楚。3.2 输入校验与结果统一很多教程中的 lambda 只有一部快乐路径但客户端从来不会保证一定按文档传参。Minimal APIs 允许你使用各种验证手段但你必须自己决定错误返回。一个简单做法是在 handler 开头做手动判断并返回错误app.MapPost(/products, (Product product) { if (string.IsNullOrWhiteSpace(product.Name)) return Results.BadRequest(new { Error Name is required }); if (product.Price 0) return Results.BadRequest(new { Error Price must be greater than 0 }); return Results.Ok(product); });在 ASP.NET Core 中也可以使用DataAnnotations标注模型属性然后通过调用ValidationResult或使用IValidatableObject来校验。不过Minimal APIs 默认不等于[ApiController]那样的自动 400 响应。你需要把验证结果映射为自己的 API 错误结构让前端或客户端能够理解。一个值得推荐的做法是把“参数校验”和“业务处理”拆开。让每个 handler 只负责处理已经校验过的输入而校验逻辑放在接口入口附近这样既不会漏掉错误分支也不会让核心业务逻辑被 if 包满。3.3 配置、日志和异常处理当环境从一个变成多个接口里写死的字符串就要挪到配置文件中。ASP.NET Core 的IConfiguration可以直接注入到 handler 中app.MapGet(/config, (IConfiguration config) config[App:Name] ?? DefaultName);日志同样可以用注入的ILoggerT或ILoggerFactory输出。如果你用了业务服务类那么日志最好放在服务类里只在 handler 层记录和请求相关的摘要。异常处理需要特别强调。一个未捕获异常如果直接抛给框架在开发环境会显示开发者异常页在生成环境通常会变成 500 空响应客户端看不到任何细节。建议在应用的请求管道中加一个全局异常处理中间件app.Use(async (context, next) { try { await next(); } catch (Exception ex) { // 记录日志或发送警报 context.Response.StatusCode 500; await context.Response.WriteAsJsonAsync(new { Error 内部错误 }); } });统一异常处理的价值不只是防止暴露堆栈更在于你能够把所有未预期问题收敛到同一条观测路径上。3.4 路由分组与路由结构化当接口从 1 个变成 10 个再变成 50 个直接在Program.cs里平铺MapGet、MapPost会越来越混乱。对此较新版本的 ASP.NET Core 提供了MapGroup可以对相同前缀的路由做分组var products app.MapGroup(/api/products); products.MapGet(/, (ProductService service) service.GetAll()); products.MapGet(/{id}, (int id, ProductService service) service.GetById(id)); products.MapPost(/, (Product product, ProductService service) service.Add(product));MapGroup 还可以统一配置过滤器、标签、说明文档等。这不仅让文件更容易阅读也为后面引入“竖切模块”打下了基础。3.5 使用 Filters 避免重复逻辑接口往往需要做认证、鉴权、请求日志、响应头附加等横切逻辑。在 Minimal APIs 中这些逻辑既可以用中间件实现也可以挂在路由分组或单个路由上。以下几种方式要分清中间件影响所有进入管道的请求适合做全局的异常处理、请求日志、请求体缓存。路由过滤器Route Filters只影响特定路由适合只对某个 API 组做认证或行为扩展。参数绑定负责将原始请求转换成 handler 需要的数据。Handler 本身只关注该接口的业务输出。比如给一个分组统一加上请求日志过滤器var group app.MapGroup(/api).AddEndpointFilter(async (context, next) { app.Logger.LogInformation($Request to {context.HttpContext.Request.Path}); return await next(context); });这些机制在 ASP.NET Core 8 之后已经比较成熟ASP.NET Core 10 一般会继续兼容但具体 API 命名如果有变化要以当前 SDK 的提示为准。## 4. 实际使用中最容易被低估的三个边界 技术教程通常展示的是风光的一面但在职业生涯里真正决定一个方案是否好用的是它的边界。不带边界地推荐技术和带货没什么区别。 ### 4.1 边界一它适合多少接口的服务 Minimal APIs 没有硬性规定最多支持多少个接口。但从维护性看如果项目里有几百个接口、几十个领域实体、权限规则复杂全部用 MapGet 写在入口点最终一定会变成另一个巨石文件。到时你还是要把 handler 拆到不同类里而这些类已经与传统 Controller 的 Action 差异很小。 我个人的判断是 - 少于 20 个接口Minimal APIs 的组织收益最大。 - 几十到上百个接口只要把 handler 和业务逻辑分层清晰依然可以保持生产力。 - 几百个接口且团队规模大时Controller 的约定扫描、路由前缀语义、模型绑定行为反而能带来更高的统一性。 这意味着选型不是“Minimal APIs 好还是 Controller 好”而是“当前业务有没有复杂到需要强约定。” ### 4.2 边界二不是所有实现都能叫“简单” 一个很容易掉进去的坑是把“逻辑没法用一行 lambda 表达”的问题硬塞进一个 lambda。你为了少创建一个类把所有校验、反序列化后的调整、数据库调用、邮件发送、日志全都写在一个大括号里最后那个方法可能有 300 行。这种代码虽然写着 Minimal APIs却完全违背了它“最小认知负担”的原则。 如果一个 handler 的职责超过“接收输入、调用服务、返回结果”你就应该把真正的业务逻辑提取到独立服务类中。Minimal APIs 不强迫你建类但也不阻止你建类。动态和简洁的边界是不要让一个方法承载你无法完整说清的多项职责。 ### 4.3 边界三版本变化带来的代码迁移成本 ASP.NET Core 的版本演进速度并不慢。今天你用 ASP.NET Core 10 学到的写法如果重视频教程是几个月前录制的出现 API 差异非常正常。迁移成本通常体现在三方面 - **框架版本升级**比如从 .NET 8 迁移到 .NET 10要检查路由、Host 构建、Filter、依赖注入注册方式是否有 breaking change。 - **目标框架重建**因为引入了不同版本 SDK项目文件里目标框架变更后依赖包版本也要跟随调整。 - **语义变化**某些方法的默认行为如结果类型序列化、状态码设置、路由匹配顺序可能在不同版本里有所调整。 在学习时最好给自己保留一个“以当前官方文档和当前 SDK 实际行为为准”的检查习惯。不要因为看了一篇 2023 年的旧文章就觉得所有 API 会永远保持原样。5. 一次完整排查链路从“程序能启动但请求 400”开始使用 Minimal APIs 时最常见的报错往往不是编译错误而是运行时请求不符合预期。下面用一条典型链路展示遇到问题时要怎样按顺序排查。5.1 确认输入是否在预期的位置假设你的接口如下app.MapPost(/products/{id}, (int id, Product product) ...);客户端发送了POST /products/abc以及 JSON 结构体但收到 400。第一件事不是猜是不是程序 bug而是检查id是否能被转换为int。如果客户端把/products/1写成/products/abc模型绑定失败、框架默认会返回 400。根据经验排查顺序建议是先看 URL路径中的内容是字符串还是可以有数字。再看查询字符串对应的参数名是否完全一致大小写通常不敏感但不能多了空格。再看请求体JSON 字段名与 C# 属性的匹配方式是否区分大小写、是否需要[JsonPropertyName]。检查 Content-Typeapplication/json还是text/plain会影响反序列化。5.2 检查路由约束而不是只看路由模板如果你定义了两个相似模板app.MapGet(/users/{id:int}, (int id) ...); app.MapGet(/users/{name}, (string name) ...);客户端请求/users/123会匹配第一个请求/users/abc会匹配第二个。如果参数类型写错路由可能走到意外分支。此时光看路由模板不够还要看参数约束。比如没有写:int约束路径段 123 可能也会被当作字符串导致两个路由发生冲突或选择错误。遇到路由执行结果不符合预期较直接的方法是打开控制台日志查看Microsoft.AspNetCore.Routing的日志确认最终选中的 Endpoint。5.3 把日志和中间件加上以后再复测如果接口仍然报错不要直接改代码先给应用加上适当日志。常见做法是在 Program.cs 中设置日志级别Logging:LogLevel:Microsoft.AspNetCoreInformation或在启动时加环境变量Logging__LogLevel__Microsoft.AspNetCoreInformation这样启动日志会输出路由匹配和请求处理信息。如果你能看到请求进来了但返回不符合预期大概率是 handler 里的分支逻辑有问题如果日志里根本没出现请求则需要检查监听地址、代理转发、防火墙或前置网关。另外如果你添加了自定义中间件或过滤器排查时可以先临时注释掉它们验证基础 handler 是否正常。通过加日志、划分边界可以将问题从“整条链路”缩小到“某一环”。5.4 把工具边界和依赖版本纳入最后一步排查如果代码逻辑看起来没问题日志也没报错那就要检查依赖环境是否运行了正确的 SDKdotnet --info可以查看当前 SDK 和运行时。项目文件中目标框架是否匹配你安装的运行时外部依赖包版本是否与 ASP.NET Core 10 兼容有些第三方库可能还没有发行适配新版本的包。是否使用了某个在新版本中已经过时或行为变化的 API可以到迁移文档中查一下。排查问题的核心不是“快速定位到某一行”而是“先确定问题出在哪一层”。输入、路由、服务、响应、环境每一步都要有证据。## 6. 让 Minimal APIs 项目在 ASP.NET Core 10 里持续演进 最后一个模块我想把前面所有内容收束成一套你可以长期使用的工作方法。看完教程、做出演示项目只算起点。真正有长期价值的是你是否形成一套持续演进的路径。 ### 6.1 先跑通一条最小路径再做目录拆分 新的脚手架项目默认只有一个 Program.cs这很正常。不要一开始就创建大量文件夹和接口。建议先按“一个接口、一个服务、一个模型”的最小闭环跑通然后再把这套闭环里的元素移入各自目录比如 bash Endpoints/ Models/ Services/ Data/这个过程的顺序很有讲究。先跑通意味着你可以随时运行、随时验证后拆分意味着每一次变化都有可验证版本。如果反过来一上来就建大量抽象很容易因为过度设计让一个小项目看起来像企业级应用但运行起来却什么也没做。6.2 结构化而不是硬编码当接口数量增加后你可以按业务模块建立扩展方法public static class ProductEndpoints { public static void MapProductEndpoints(this WebApplication app) { var group app.MapGroup(/api/products); group.MapGet(/, ...); group.MapGet(/{id:int}, ...); group.MapPost(/, ...); } }在 Program.cs 里调用app.MapProductEndpoints(); app.MapUserEndpoints();这种方式没有引入 Controller 的复杂生命周期却能让模块边界保持清晰。它告诉读者“这个模块暴露了哪些端点、端点做什么业务”而把每个端点的实现细节分散到对应的静态类中又不失可读性。6.3 自动化测试是“最小”清单里最该投资的一项Minimal APIs 的 lambda 函数不好测试吗并不是。你完全可以把 lambda 里的逻辑抽象成服务类然后对服务层进行单元测试。同时ASP.NET Core 也提供WebApplicationFactoryT来测试整个应用包括路由匹配、中间件、过滤器等。对于偏内聚的小服务最重要的是接口合约测试用一组固定输入访问某个 URL断言返回的状态码、响应头、JSON 字段名。这些测试价值很高因为接口结构一旦被外部消费改动就不只是改代码的问题。### 6.4 回到主判断少写代码只是结果快速反馈才是原因 当你在 ASP.NET Core 10 中继续探索 Minimal APIs希望对它的理解不再停留在“代码行数少”这个表面印象上。行数少是结果不是原因。原因是框架希望用最小的心智摩擦让你能快速试验一个想法、验证一个协议、暴露一个数据点。 学会三行代码创建接口只是拿到了钥匙真正要掌握的是在保持低启动成本的同时逐步加入团队协作所需的结构和纪律。最小 API不等于“不用学习软件工程”的 API。它仍然需要依赖注入、日志、异常处理、校验、测试和边界意识。区别是这些能力可以由你决定何时引入、以什么形态引入而不是框架强制你一开始就全盘接受。 如果你现在正要上手我用亲身经历给你一条最直接的行动建议先创建项目亲手写一个带路径参数的 MapGet再写一个读请求体的 MapPost然后把校验和日志补上。做完这一步你自然能体会为什么 Microsoft 自从 .NET 6 推出这一模式后一直没有放弃它反而持续在路由分组、过滤器、结果类型上做了大量演进。ASP.NET Core 10 的很多新打磨都会继续围绕这个核心展开让最常用的做法最顺手让不常用的能力在需要时依然触手可及。