一个简单的ASP.NET 一致性返回工具库

本文主要介绍了 Sang.AspNetCore.CommonLibraries 这个 ASP.NET 通用库，它目前提供了一致性返回和简单提示页面的功能，旨在简化开发工作，提高代码的复用性和可维护性。

1. 介绍

Sang.AspNetCore.CommonLibraries 是一个为 ASP.NET Core 提供常用功能和工具的通用库，旨在简化开发工作，提高代码的复用性和可维护性。目前主要提供了一致性返回和简单提示页面的功能，后续将继续扩展更多实用功能：

异常处理：提供未处理异常的过滤器，允许自定义异常处理行为（详见 FilterExtensions.cs）。
模型验证：提供模型验证的过滤器，允许自定义模型验证失败时的处理行为（详见 FilterExtensions.cs）。
消息模型：定义了一个通用的 API 响应消息模型（详见 MessageModel.cs）。
消息页面：定义了一个用于生成 HTML 消息页面的类，支持 Markdown 链接（详见 MessagePage.cs）。

项目开源地址：https://github.com/sangyuxiaowu/Sang.AspNetCore.CommonLibraries?WT.mc_id=DT-MVP-5005195

2. 使用方法

2.1 安装

可以通过 NuGet 包管理器安装此库：

bash 复制代码

Install-Package Sang.AspNetCore.CommonLibraries

或者使用 .NET CLI：

bash 复制代码

dotnet add package Sang.AspNetCore.CommonLibraries

2.2 一致的返回模型

将 API 控制器的返回类型更改为 MessageModel<T>，其中 T 是返回数据的类型。例如：

csharp 复制代码

[HttpGet]
public MessageModel<string> Get()
{
    return new MessageModel<string>
    {
        Status = 0,
        Msg = "Success",
        Data = "Hello, World!"
    };
}

添加未处理异常和模型验证失败的过滤器：

csharp 复制代码

builder.Services.AddUnhandledExceptionFilter(config =>
{
    config.Status = 500;
    config.StatusCode = 500;
    config.WithTraceId = false; // 是否返回 TraceId
    config.Message = "Unhandled Exception";
});

添加模型验证失败的过滤器：

csharp 复制代码

builder.Services.AddModelValidationExceptionFilter(config =>
{
    config.Status = 400; // 业务状态码
    config.StatusCode = 400; // HTTP 状态码
    config.Message = "Model Validation Exception"; // 自定义消息
});

2.3 生成 HTML 消息页面

要生成 HTML 消息页面，可以使用 MessagePage 类。该类提供了一些属性用于设置页面内容，然后可以调用 Render 方法生成 HTML 页面。

页面 UI 采用 WeUI 2.5.11 版本，风格类似微信官方账号，包括标题、图标、内容、列表、链接、按钮和页脚链接。

csharp 复制代码

public ContentResult Page()
{
    var page = new MessagePage
    {
        Icon = MsgIcon.Safe_Warn,
        HtmlTitle = "网页标题",
        Title = "消息标题",
        Desc = "详细内容，可以根据实际需要安排，如果换行不要超过规定长度，居中显示 [支持超链接](http://www.example.com)",
        DescInfo = "详细内容，可以根据实际需要安排，如果换行不要超过规定长度，居中显示",
        Custom = "<textarea>自定义html区域</textarea>",
        ListInfo = new List<string> { "列表提示项", "列表提示项", "列表提示项" },
        KeyValues = new Dictionary<string, string> { { "姓名", "张三" }, { "年龄", "123" } },
        ListUrl = new List<UrlInfo> { new("链接1", "javascript:"), new("链接2", "javascript:") },
        TipsPre = "详细内容，可以根据实际需要安排，如果换行不要超过规定长度，居中显示 [支持超链接](http://www.example.com)",
        TipsNext = "详细内容，可以根据实际需要安排，如果换行不要超过规定长度，居中显示 [支持超链接](http://www.example.com)",
        OprBtn = new List<UrlInfo> { new("链接1", "javascript:"), new ("链接2", "javascript:", "default") },
        FooterLink = new UrlInfo("页脚链接", "javascript:"),
        CopyRight = "Sang Late Autumn 版权信息<br>© 2014-2021 Sang. All Rights Reserved."
    };
    return new ContentResult
    {
        ContentType = "text/html",
        StatusCode = 200,
        Content = page.Render()
    };
}

3. 实际应用场景

3.1 API 开发

在开发 RESTful API 时，使用一致的返回模型可以简化客户端处理响应的逻辑。通过 MessageModel<T>，所有的 API 响应都遵循相同的结构，客户端只需处理一种格式，大大减少了解析和处理响应的复杂性。

3.2 错误处理

通过添加未处理异常和模型验证失败的过滤器，可以确保所有的异常和错误都能被捕获并返回一致的错误信息。这不仅提升了应用的稳定性，还简化了错误处理逻辑，使得开发者可以专注于业务逻辑而不是错误处理。

3.3 用户提示页面

在某些场景下，需要向用户展示提示信息或错误信息，例如表单提交失败、权限不足等。使用 MessagePage 类，可以快速生成风格统一的提示页面，提升用户体验。

4. 总结

Sang.AspNetCore.CommonLibraries 是一个简单的 ASP.NET 通用库，提供了一致性返回和简单提示页面的功能，旨在简化开发工作，提高代码的复用性和可维护性。如果你正在开发一个 ASP.NET 项目，可以考虑使用这个库，它会为你的项目带来很多便利。