C# Problem Details规范方法 C#如何返回RFC 7807格式的错误

当C# Web API需要向客户端返回标准化、机器可读的错误信息时，若未遵循RFC 7807（Problem Details for HTTP APIs）规范，则可能导致前端解析困难或语义丢失。以下是实现RFC 7807格式错误响应的多种方法：

一、使用Microsoft.AspNetCore.Mvc.ProblemDetails类直接构造

ASP.NET Core内置了ProblemDetails类型，它严格对应RFC 7807定义的字段结构，可直接实例化并作为ActionResult返回，无需额外依赖。

1、在控制器方法中创建ProblemDetails实例，设置type、title、status、detail、instance等属性。

2、将该实例作为返回值，配合ObjectResult或直接return new ObjectResult(problemDetails)。

3、确保响应Content-Type自动设为application/problem+json，且HTTP状态码与status属性一致。

4、若需全局统一错误格式，可在Startup.cs或Program.cs中配置全局异常过滤器，捕获异常后构造ProblemDetails并写入响应体。

二、继承ProblemDetails并添加自定义扩展属性

RFC 7807允许在标准字段之外添加任意扩展成员，通过派生类可安全注入业务相关错误字段，同时保持兼容性。

1、定义新类如ValidationProblemDetails，继承自ProblemDetails。

2、在类中添加public Dictionary errors { get; set; }等扩展属性。

3、在控制器中实例化该派生类，并赋值标准字段及扩展字段。

4、调用return new ObjectResult(validationProblemDetails)，序列化器会自动包含所有公有属性。

5、注意：扩展属性名不得与RFC 7807保留字段（type、title、status、detail、instance）冲突。

三、使用ActionResult泛型返回并配合IActionResult显式转换

利用ASP.NET Core 6+对泛型ActionResult的支持，可将ProblemDetails作为强类型返回值，在编译期获得类型安全提示，同时保持灵活的响应控制权。

1、将控制器方法签名声明为ActionResult等形式。

2、在逻辑分支中遇到错误时，构造ProblemDetails对象。

3、调用return StatusCode(problemDetails.Status.Value, problemDetails)，显式指定状态码与响应体。

4、避免使用return BadRequest(problemDetails)，因其可能忽略status字段而强制设为400，导致status不一致。

四、通过全局异常处理中间件注入ProblemDetails响应

在请求管道早期拦截未处理异常，统一转换为ProblemDetails响应，避免各控制器重复编写错误构造逻辑。

1、在Program.cs中注册自定义中间件，置于UseRouting和UseEndpoints之间。

2、在中间件InvokeAsync方法中try-catch所有后续委托执行。

3、捕获Exception后，根据异常类型映射到不同status码，例如ArgumentNullException→400，UnauthorizedAccessException→401。

4、构造ProblemDetails，其中detail字段填充exception.Message，instance字段设为当前请求路径。

5、清空响应流，设置StatusCode和ContentType，序列化ProblemDetails并写入响应体。

五、使用第三方库如Hellang.Middleware.ProblemDetails

该库提供开箱即用的中间件支持，自动将异常、验证失败、结果过滤器输出转为RFC 7807格式，大幅减少手动配置代码量。

1、通过NuGet安装Hellang.Middleware.ProblemDetails包。

2、在Program.cs中调用builder.Services.AddProblemDetails()注册服务。

3、调用builder.UseProblemDetails()启用中间件。

4、可选配置ProblemDetailsOptions，例如自定义ShouldLog、Map方法，将特定异常映射为指定type URI和status。

5、验证失败时，该库自动捕获ModelStateDictionary并生成含errors字段的ProblemDetails，无需手动构造ValidationProblemDetails。