practical-aspnetcore 实战:使用 TypedResults.InternalServerError 在 Minimal API 中返回 HTTP 500
practical-aspnetcore 实战:使用 TypedResults.InternalServerError 在 Minimal API 中返回 HTTP 500
本篇文章以 practical-aspnetcore 仓库中 net9/typed-results-2 示例为主体,讲解 ASP.NET Core Minimal API 中 TypedResults.InternalServerError 的用法:如何用一条语句返回 HTTP 500(服务器内部错误)状态码并携带错误消息。读完本文,你将掌握 TypedResults 的"类型保留"设计思想、InternalServerError 在简单场景与联合返回类型场景下的两种写法,以及如何运行并验证该示例。
一、示例概览:一个极简的 500 返回样例
该示例位于 projects/net9/typed-results-2,由两个文件构成:
- Program.cs:全部应用逻辑
- typed-results-2.csproj:工程配置
按 projects/net9/README.md 的说明,该示例的核心目标就是:展示如何使用 TypedResults.InternalServerError 返回 HTTP 500 状态码。原文档指出,TypedResults.InternalServerError 是在该静态类已支持的各 HTTP 状态码之上新增的成员。
二、完整源码解析
示例的 Program.cs 全貌如下:
var app = WebApplication.Create();
app.MapGet("/", () => TypedResults.InternalServerError("Something is wrong with the server."));
app.Run();
代码只有三行,逐行拆解:
WebApplication.Create():以最精简的宿主方式创建应用实例(无需CreateBuilder与显式配置),这是 Minimal API 的最小化宿主写法,与仓库中 minimal-hosting 系列示例一脉相承。app.MapGet("/", ...):为根路径/注册 GET 端点,委托直接调用TypedResults.InternalServerError("Something is wrong with the server.")。app.Run():启动应用并开始监听请求。
三、TypedResults.InternalServerError 做什么
TypedResults.InternalServerError 是 Microsoft.AspNetCore.Http.TypedResults 静态类提供的结果工厂方法,调用后返回一个实现了 IResult 的具体结果类型,其效果是:
- 响应状态码固定为 500(Internal Server Error);
- 传入的字符串参数作为响应体返回(本例中即
"Something is wrong with the server."); - 返回对象是具体类型
InternalServerError<string>,而不是非类型化的IResult。
这意味着,当你的 Minimal API 处理过程中捕获到未预期异常、外部服务调用失败或数据不一致等"服务器端错误"时,可以直接用一行代码向客户端传达"服务器出错了"这一语义明确的信号,而不必手工拼装 Results.StatusCode(500) 之类较底层的写法。
TypedResults 与 Results 的差异
依据仓库 minimal-api/typed-results-1/README.md 的说明:TypedResults 是既有 Results 静态类的"类型化(typed)"等价物。二者都能创建框架内置的 IResult 实现,关键区别在于:
Results返回的接口类型是IResult,运行时才能确定具体类型;TypedResults直接返回具体的实现类型,例如JsonHttpResult<T>、InternalServerError<T>,编译期即可保留完整类型信息。
在 typed-results-1 示例中,这一点得到了直接验证——它的 Program.cs 内置了 Xunit 测试,断言 TypedResults.Json(...) 的返回类型确实是 JsonHttpResult<Person>:
var result = Hello.GetGreeting("anne");
Assert.IsType<JsonHttpResult<Person>>(result);
同理,TypedResults.InternalServerError(...) 的返回值类型就是 InternalServerError<string>,类型信息在编译期可用、可被 OpenAPI 描述、也可被测试代码断言。
四、类型保留的实际价值:联合返回类型
"返回具体类型"最直接的好处,是能与 Results<T1, T2, ...> 联合类型组合使用,把"成功"与"失败"两种路径显式声明在方法签名里。仓库中 projects/net10/open-api-10/Program.cs 给出了一个完整范例:
using Microsoft.AspNetCore.Http.HttpResults;
public static Results<Ok<string>, InternalServerError<string>> Hello(string name)
{
try
{
return TypedResults.Ok($"Hello, {name}");
}
catch
{
return TypedResults.InternalServerError("An error occurred while processing your request.");
}
}
这个方法的返回类型 Results<Ok<string>, InternalServerError<string>> 向框架声明了"该端点可能返回 200(携带字符串)或 500(携带字符串)"。相比直接返回 IResult,这种写法让:
- OpenAPI 文档生成能自动推断两种可能的响应状态码(示例中的 Program.cs 同时开启了
AddOpenApi()内置文档支持); - 调用方与测试代码能在编译期了解所有可能的返回形态;
- 异常分支与正常分支的语义各自清晰、互不混淆。
可以看到,InternalServerError 的典型使用场景并非"默认响应",而是与 TypedResults.Ok 等结果配合,构成一个端点完整的状态空间。
五、运行与验证
在仓库根目录下进入示例目录即可运行:
cd projects/net9/typed-results-2
dotnet run
启动后访问根路径 /,响应即为 HTTP 500:
HTTP/1.1 500 Internal Server Error
Something is wrong with the server.
也可以直接用 curl 验证状态码与响应体:
curl -i http://localhost:5000/
其中 -i 会同时输出响应头与响应体,可看到 HTTP/1.1 500 Internal Server Error 及消息文本。
工程配置说明
从仓库文件看,typed-results-2.csproj 的目标框架为 net10.0,并开启了 ImplicitUsings(因此代码中无需显式 using Microsoft.AspNetCore.Http;):
<Project Sdk="Microsoft.NET.Sdk.Web">
<PropertyGroup>
<TargetFramework>net10.0</TargetFramework>
<ImplicitUsings>true</ImplicitUsings>
</PropertyGroup>
</Project>
该示例收录在 net9 分类下(其 README 注明该分类示例需要 SDK 9.0.100,见 projects/net9/global.json),而仓库根目录 global.json 要求的 SDK 为 10.0.0(rollForward: major)。实际构建时请以本机安装的 SDK 与 dotnet run 的输出为准,若提示需要更高版本 SDK,可按仓库的 rollForward 策略自动向上兼容。
六、延伸阅读
想进一步理解 TypedResults 的"类型化"设计及其在 OpenAPI 场景中的应用,可继续阅读仓库中的以下示例:
- projects/minimal-api/typed-results-1:TypedResults 基础概念 + Xunit 类型断言验证;
- projects/net10/open-api-10:
Results<Ok<T>, InternalServerError<T>>联合返回类型 + 内置 OpenAPI 文档; - projects/net9/open-api-3:内置 OpenAPI 文档生成;
- projects/net9/open-api-4:用 NSwag 的 Swagger UI 可视化内置 OpenAPI 文档;
- projects/net10/validation-1:
TypedResults.Ok在路由参数校验场景下的组合用法。