practical-aspnetcore 实战:使用 TypedResults.InternalServerError 在 Minimal API 中返回 HTTP 500

原创2026-10-14 21:27:161,642 阅读
文章标签:示例工程

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,由两个文件构成:

按 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();

代码只有三行,逐行拆解:

  1. WebApplication.Create():以最精简的宿主方式创建应用实例(无需 CreateBuilder 与显式配置),这是 Minimal API 的最小化宿主写法,与仓库中 minimal-hosting 系列示例一脉相承。
  2. app.MapGet("/", ...):为根路径 / 注册 GET 端点,委托直接调用 TypedResults.InternalServerError("Something is wrong with the server.")。
  3. 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 场景中的应用,可继续阅读仓库中的以下示例:

登录后查看全文
practical-aspnetcore