1. 首页
  2. .NET
  3. 正文

浅入ABP(2)：添加基础集成服务

2020年9月15日 2488点热度 1人点赞 0条评论
内容目录

版权护体©作者：痴者工良，微信公众号转载文章需要 《NCC开源社区》同意。

上一篇，我们已经搭建起了一个基本的程序结构，下面我们来添加一些必要的服务，例如异常拦截器、跨域等。

本教程的代码比较多，关联性比较强，需要整体写好后，才能正常使用，所以可以先按照过程做一次，再回头看解析。

本章的内容不仅适合 ABP， ASP.NET Core 也可以直接使用。

源码地址：https://github.com/whuanle/AbpBaseStruct

本教程结果代码位置：https://github.com/whuanle/AbpBaseStruct/tree/master/src/2/AbpBase

定义一个特性标记

这个标记用于标记一个枚举代表的信息。

在 AbpBase.Domain.Shared 项目，创建 Attributes目录，然后创建一个 SchemeNameAttribute 类，其内容如下：

    /// <summary>
    /// 标记枚举代表的信息
    /// </summary>
    [AttributeUsage(AttributeTargets.Field)]
    public class SchemeNameAttribute : Attribute
    {
        public string Message { get; set; }
        public SchemeNameAttribute(string message)
        {
            Message = message;
        }
    }

全局统一消息格式

为了使得 Web 应用统一响应格式以及方便编写 API 时有一个统一的标准，我们需要定义一个合适的模板。

在 AbpBase.Domain.Shared 创建一个Apis 目录。

Http 状态码

为了适配各种 HTTP 请求的响应状态，我们定义一个识别状态码的枚举。

在 Apis 目录，创建一个 HttpStateCode.cs 文件，其内容如下：

namespace AbpBase.Domain.Shared.Apis
{
    /// <summary>
    /// 标准 HTTP 状态码
    /// <para>文档地址<inheritdoc cref="https://www.runoob.com/http/http-status-codes.html"/></para>
    /// </summary>
    public enum HttpStateCode
    {
        Status412PreconditionFailed = 412,
        Status413PayloadTooLarge = 413,
        Status413RequestEntityTooLarge = 413,
        Status414RequestUriTooLong = 414,
        Status414UriTooLong = 414,
        Status415UnsupportedMediaType = 415,
        Status416RangeNotSatisfiable = 416,
        Status416RequestedRangeNotSatisfiable = 416,
        Status417ExpectationFailed = 417,
        Status418ImATeapot = 418,
        Status419AuthenticationTimeout = 419,
        Status421MisdirectedRequest = 421,
        Status422UnprocessableEntity = 422,
        Status423Locked = 423,
        Status424FailedDependency = 424,
        Status426UpgradeRequired = 426,
        Status428PreconditionRequired = 428,
        Status429TooManyRequests = 429,
        Status431RequestHeaderFieldsTooLarge = 431,
        Status451UnavailableForLegalReasons = 451,
        Status500InternalServerError = 500,
        Status501NotImplemented = 501,
        Status502BadGateway = 502,
        Status503ServiceUnavailable = 503,
        Status504GatewayTimeout = 504,
        Status505HttpVersionNotsupported = 505,
        Status506VariantAlsoNegotiates = 506,
        Status507InsufficientStorage = 507,
        Status508LoopDetected = 508,
        Status411LengthRequired = 411,
        Status510NotExtended = 510,
        Status410Gone = 410,
        Status408RequestTimeout = 408,
        Status101SwitchingProtocols = 101,
        Status102Processing = 102,
        Status200OK = 200,
        Status201Created = 201,
        Status202Accepted = 202,
        Status203NonAuthoritative = 203,
        Status204NoContent = 204,
        Status205ResetContent = 205,
        Status206PartialContent = 206,
        Status207MultiStatus = 207,
        Status208AlreadyReported = 208,
        Status226IMUsed = 226,
        Status300MultipleChoices = 300,
        Status301MovedPermanently = 301,
        Status302Found = 302,
        Status303SeeOther = 303,
        Status304NotModified = 304,
        Status305UseProxy = 305,
        Status306SwitchProxy = 306,
        Status307TemporaryRedirect = 307,
        Status308PermanentRedirect = 308,
        Status400BadRequest = 400,
        Status401Unauthorized = 401,
        Status402PaymentRequired = 402,
        Status403Forbidden = 403,
        Status404NotFound = 404,
        Status405MethodNotAllowed = 405,
        Status406NotAcceptable = 406,
        Status407ProxyAuthenticationRequired = 407,
        Status409Conflict = 409,
        Status511NetworkAuthenticationRequired = 511
    }
}

常用的请求结果

在相同目录，创建一个 CommonResponseType 枚举，其内容如下：

    /// <summary>
    /// 常用的 API 响应信息
    /// </summary>
    public enum CommonResponseType
    {
        [SchemeName("")] Default = 0,

        [SchemeName("请求成功")] RequstSuccess = 1,

        [SchemeName("请求失败")] RequstFail = 2,

        [SchemeName("创建资源成功")] CreateSuccess = 4,

        [SchemeName("创建资源失败")] CreateFail = 8,

        [SchemeName("更新资源成功")] UpdateSuccess = 16,

        [SchemeName("更新资源失败")] UpdateFail = 32,

        [SchemeName("删除资源成功")] DeleteSuccess = 64,

        [SchemeName("删除资源失败")] DeleteFail = 128,

        [SchemeName("请求的数据未能通过验证")] BadRequest = 256,

        [SchemeName("服务器出现严重错误")] Status500InternalServerError = 512
    }

响应模型

在 Apis 目录，创建一个 `ApiResponseModel.cs`` 泛型类文件，其内容如下：

namespace AbpBase.Domain.Shared.Apis
{
    /// <summary>
    /// API 响应格式
    /// <para>避免滥用，此类不能实例化，只能通过预定义的静态方法生成</para>
    /// </summary>
    /// <typeparam name="TData"></typeparam>
    public abstract class ApiResponseModel<TData>
    {
        public HttpStateCode StatuCode { get; set; }
        public string Message { get; set; }
        public TData Data { get; set; }

        /// <summary>
        /// 私有类
        /// </summary>
        /// <typeparam name="TResult"></typeparam>
        private class PrivateApiResponseModel<TResult> : ApiResponseModel<TResult> { }
    }
}

StatuCode：用于说明此次响应的状态；

Message：响应的信息；

Data：响应的数据；

可能你会觉得这样很奇怪，先不要问，也不要猜，照着做，后面我会告诉你为什么这样写。

然后再创建一个类：

using AbpBase.Domain.Shared.Helpers;
using System;

namespace AbpBase.Domain.Shared.Apis
{
    /// <summary>
    /// Web 响应格式
    /// <para>避免滥用，此类不能实例化，只能通过预定义的静态方法生成</para>
    /// </summary>
    public abstract class ApiResponseModel : ApiResponseModel<dynamic>
    {
        /// <summary>
        /// 根据枚举创建响应格式
        /// </summary>
        /// <typeparam name="TEnum"></typeparam>
        /// <param name="code"></param>
        /// <param name="enumType"></param>
        /// <returns></returns>
        public static ApiResponseModel Create<TEnum>(HttpStateCode code, TEnum enumType) where TEnum : Enum
        {
            return new PrivateApiResponseModel
            {
                StatuCode = code,
                Message = SchemeHelper.Get(enumType),
            };
        }

        /// <summary>
        /// 创建标准的响应
        /// </summary>
        /// <typeparam name="TEnum"></typeparam>
        /// <typeparam name="TData"></typeparam>
        /// <param name="code"></param>
        /// <param name="enumType"></param>
        /// <param name="Data"></param>
        /// <returns></returns>
        public static ApiResponseModel Create<TEnum>(HttpStateCode code, TEnum enumType, dynamic Data)
        {
            return new PrivateApiResponseModel
            {
                StatuCode = code,
                Message = SchemeHelper.Get(enumType),
                Data = Data
            };
        }

        /// <summary>
        /// 请求成功
        /// </summary>
        /// <param name="code"></param>
        /// <param name="Data"></param>
        /// <returns></returns>
        public static ApiResponseModel CreateSuccess(HttpStateCode code, dynamic Data)
        {
            return new PrivateApiResponseModel
            {
                StatuCode = code,
                Message = "Success",
                Data = Data
            };
        }

        /// <summary>
        /// 私有类
        /// </summary>
        private class PrivateApiResponseModel : ApiResponseModel { }
    }
}

同时在项目中创建一个 Helpers 文件夹，再创建一个 SchemeHelper 类，其内容如下：

using AbpBase.Domain.Shared.Attributes;
using System;
using System.Linq;
using System.Reflection;

namespace AbpBase.Domain.Shared.Helpers
{
    /// <summary>
    /// 获取各种枚举代表的信息
    /// </summary>
    public static class SchemeHelper
    {
        private static readonly PropertyInfo SchemeNameAttributeMessage = typeof(SchemeNameAttribute).GetProperty(nameof(SchemeNameAttribute.Message));

        /// <summary>
        /// 获取一个使用了 SchemeNameAttribute 特性的 Message 属性值
        /// </summary>
        /// <typeparam name="T"></typeparam>
        /// <param name="type"></param>
        /// <returns></returns>
        public static string Get<T>(T type)
        {
            return GetValue(type);
        }

        private static string GetValue<T>(T type)
        {
            var attr = typeof(T).GetField(Enum.GetName(type.GetType(), type))
                .GetCustomAttributes()
                .FirstOrDefault(x => x.GetType() == typeof(SchemeNameAttribute));

            if (attr == null)
                return string.Empty;

            var value = (string)SchemeNameAttributeMessage.GetValue(attr);
            return value;
        }
    }
}

上面的类到底是干嘛的，你先不要问。

全局异常拦截器

在 AbpBase.Web 项目中，新建一个 Filters 文件夹，添加一个 WebGlobalExceptionFilter.cs 文件，其文件内容如下：

using AbpBase.Domain.Shared.Apis;
using Microsoft.AspNetCore.Http;
using Microsoft.AspNetCore.Mvc;
using Microsoft.AspNetCore.Mvc.Filters;
using Newtonsoft.Json;
using System.Threading.Tasks;

namespace AbpBase.HttpApi.Filters
{

    /// <summary>
    /// Web 全局异常过滤器，处理 Web 中出现的、运行时未处理的异常
    /// </summary>
    public class WebGlobalExceptionFilter : IAsyncExceptionFilter
    {

        public async Task OnExceptionAsync(ExceptionContext context)
        {
            if (!context.ExceptionHandled)
            {

                ApiResponseModel model = ApiResponseModel.Create(HttpStateCode.Status500InternalServerError,
                    CommonResponseType.Status500InternalServerError);
                context.Result = new ContentResult
                {
                    Content = JsonConvert.SerializeObject(model),
                    StatusCode = StatusCodes.Status200OK,
                    ContentType = "application/json; charset=utf-8"
                };
            }

            context.ExceptionHandled = true;

            await Task.CompletedTask;
        }
    }
}

然后 在 AbpBaseWebModule 模块的 ConfigureServices 函数中，加上：

            Configure<MvcOptions>(options =>
            {
                options.Filters.Add(typeof(WebGlobalExceptionFilter));
            });

这里我们还没有将写入日志，后面再增加这方面的功能。

先说明一下

前面我们定义了 ApiResponseModel 和其他一些特性还有枚举，这里解释一下原因。

ApiResponseModel 是抽象类

ApiResponseModel<T> 和 ApiResponseModel 是抽象类，是为了避免开发者使用时，直接这样用：

            ApiResponseModel mode = new ApiResponseModel
            {
                Code = 500,
                Message = "失败",
                Data = xxx
            };

首先这个 Code 需要按照 HTTP 状态的标准来填写，我们使用 HttpStateCode 枚举来标记，代表异常时，使用 Status500InternalServerError 来标识。

我非常讨厌一个 Action 的一个返回，就写一次消息的。

if(... ...)
    return xxxx("请求数据不能为空");

if(... ...)
    return xxxx("xxx 要大于 10");
... ..

这样每个地方一个消息说明，十分不统一，也不便于修改。

直接使用一个枚举来代表消息，而不能直接写出来，这样就可以达到统一了。

使用抽象类，可以避免开发者直接 new 一个，强制要求一定的消息格式来响应。后面可以进行更多的尝试，来体会我这样设计的便利性。

跨域请求

这里我们将配置 Web 全局允许跨域请求。

在 AbpBaseWebModule 模块中：

添加一个静态变量

private const string AbpBaseWebCosr = "AllowSpecificOrigins";

创建一个配置函数：

        /// <summary>
        /// 配置跨域
        /// </summary>
        /// <param name="context"></param>
        private void ConfigureCors(ServiceConfigurationContext context)
        {
            context.Services.AddCors(options =>
            {
                options.AddPolicy(AbpBaseWebCosr,
                    builder => builder.AllowAnyHeader()
                        .AllowAnyMethod()
                        .AllowAnyOrigin());
            });
        }

在 ConfigureServices 函数中添加：

            // 跨域请求
            ConfigureCors(context);

在 OnApplicationInitialization 中添加：

            app.UseCors(AbpBaseWebCosr);    // 位置在 app.UseRouting(); 后面

就这样，允许全局跨域请求就完成了。

配置 API 服务

你可以使用以下模块来配置一个 API 模块服务：

            Configure<AbpAspNetCoreMvcOptions>(options =>
            {
                options
                    .ConventionalControllers
                    .Create(typeof(AbpBaseHttpApiModule).Assembly, opts =>
                    {
                        opts.RootPath = "api/1.0";
                    });
            });

我们在 AbpBase.HttpApi 中将其本身用于创建一个 API 服务，ABP 会将继承了 AbpController 、ControllerBase 等的类识别为 API控制器。上面的代码同时将其默认路由的前缀设置为 api/1.0。

也可以不设置前缀：

            Configure<AbpAspNetCoreMvcOptions>(options =>
            {                options.ConventionalControllers.Create(typeof(IoTCenterWebModule).Assembly);
            });

由于 API 模块已经在自己的 ConfigureServices 创建了 API 服务，因此可以不在 Web 模块里面编写这部分代码。当然，也可以统一在 Web 中定义所有的 API 模块。

统一 API 模型验证消息

创建前

首先，如果我们这样定义一个 Action：

        public class TestModel
        {
            [Required]
            public int Id { get; set; }

            [MaxLength(11)]
            public int Iphone { get; set; }

            [Required]
            [MinLength(5)]
            public string Message { get; set; }
        }

        [HttpPost("/T2")]
        public string MyWebApi2([FromBody] TestModel model)
        {
            return "请求完成";
        }

使用以下参数请求：

{
    "Id": "1",
    "Iphone": 123456789001234567890,
    "Message": null
}

会得到以下结果：

{
    "errors": {
        "Iphone": [
            "JSON integer 123456789001234567890 is too large or small for an Int32. Path 'Iphone', line 3, position 35."
        ]
    },
    "type": "https://tools.ietf.org/html/rfc7231#section-6.5.1",
    "title": "One or more validation errors occurred.",
    "status": 400,
    "traceId": "|af964c79-41367b2145701111."
}

这样的信息阅读起来十分不友好，前端对接也会有一定的麻烦。

这个时候我们可以统一模型验证拦截器，定义一个友好的响应格式。

创建方式

在 AbpBase.Web 的项目 的 Filters 文件夹中，创建一个 InvalidModelStateFilter 文件，其文件内容如下：

using AbpBase.Domain.Shared.Apis;
using Microsoft.AspNetCore.Http;
using Microsoft.AspNetCore.Mvc;
using Microsoft.Extensions.DependencyInjection;
using System.Linq;

namespace AbpBase.Web.Filters
{
    public static class InvalidModelStateFilter
    {
        /// <summary>
        /// 统一模型验证
        /// <para>控制器必须添加 [ApiController] 才能被此过滤器拦截</para>
        /// </summary>
        /// <param name="services"></param>
        public static void GlabalInvalidModelStateFilter(this IServiceCollection services)
        {
            services.Configure<ApiBehaviorOptions>(options =>
            {
                options.InvalidModelStateResponseFactory = actionContext =>
                {
                    if (actionContext.ModelState.IsValid)
                        return new BadRequestObjectResult(actionContext.ModelState);

                    int count = actionContext.ModelState.Count;
                    ValidationErrors[] errors = new ValidationErrors[count];
                    int i = 0;
                    foreach (var item in actionContext.ModelState)
                    {
                        errors[i] = new ValidationErrors
                        {
                            Member = item.Key,
                            Messages = item.Value.Errors?.Select(x => x.ErrorMessage).ToArray()
                        };
                        i++;
                    }

                    // 响应消息
                    var result = ApiResponseModel.Create(HttpStateCode.Status400BadRequest, CommonResponseType.BadRequest, errors);
                    var objectResult = new BadRequestObjectResult(result);
                    objectResult.StatusCode = StatusCodes.Status400BadRequest;
                    return objectResult;
                };
            });
        }

        /// <summary>
        /// 用于格式化实体验证信息的模型
        /// </summary>
        private class ValidationErrors
        {
            /// <summary>
            /// 验证失败的字段
            /// </summary>
            public string Member { get; set; }

            /// <summary>
            /// 此字段有何种错误
            /// </summary>
            public string[] Messages { get; set; }
        }
    }
}

在 ConfigureServices 函数中，添加以下代码：

            // 全局 API 请求实体验证失败信息格式化
            context.Services.GlabalInvalidModelStateFilter();

创建后

让我们看看增加了统一模型验证器后，同样的请求返回的消息。

请求：

{
    "Id": "1",
    "Iphone": 123456789001234567890,
    "Message": null
}

返回：

{
    "statuCode": 400,
    "message": "请求的数据未能通过验证",
    "data": [
        {
            "member": "Iphone",
            "messages": [
                "JSON integer 123456789001234567890 is too large or small for an Int32. Path 'Iphone', line 3, position 35."
            ]
        }
    ]
}

说明我们的统一模型验证响应起到了作用。

但是有些验证会直接报异常而不会流转到上面的拦截器中，有些模型验证特性用错对象的话，他会报错异常的。例如上面的 MaxLength ，已经用错了，MaxLength 是指定属性中允许的数组或字符串数据的最大长度，不能用在 int 类型上。大家测试一下请求下面的 json，会发现报异常。

{
    "Id": 1,
    "Iphone": 1234567900,
    "Message": "nullable"
}

以下是一些 ASP.NET Core 内置验证特性，大家记得别用错：

  • [CreditCard]：验证属性是否具有信用卡格式。 需要 JQuery 验证其他方法。
  • [Compare]：验证模型中的两个属性是否匹配。
  • [EmailAddress]：验证属性是否具有电子邮件格式。
  • [Phone]：验证属性是否具有电话号码格式。
  • [Range]：验证属性值是否在指定的范围内。
  • [RegularExpression]：验证属性值是否与指定的正则表达式匹配。
  • [Required]：验证字段是否不为 null。 有关此属性的行为的详细信息
  • [StringLength]：验证字符串属性值是否不超过指定长度限制。
  • [Url]：验证属性是否具有 URL 格式。
  • [Remote]：通过在服务器上调用操作方法来验证客户端上的输入。
  • [MaxLength ] MaxLength 是指定属性中允许的数组或字符串数据的最大长度

参考：https://docs.microsoft.com/zh-cn/dotnet/api/system.componentmodel.dataannotations?view=netcore-3.1

本系列第二篇到此，接下来第三篇会继续添加一些基础服务。

补充：为什么需要统一格式

首先，你看一下这样的代码：

在每个 Action 中，都充满了这种写法，每个相同的验证问题，在每个 Action 返回的文字都不一样，没有规范可言。一个人写一个 return，就加上一下自己要表达的 文字，一个项目下来，多少 return ？全是这种代码，不堪入目。
通过统一模型验证和统一消息返回格式，就可以避免这些情况。

本作品采用 知识共享署名-非商业性使用-相同方式共享 4.0 国际许可协议 进行许可
标签：
最后更新：2021年2月21日

痴者工良

高级程序员劝退师

文章评论

razz evil exclaim smile redface biggrin eek confused idea lol mad twisted rolleyes wink cool arrow neutral cry mrgreen drooling persevering

文章目录

COPYRIGHT © 2024 whuanle.cn. ALL RIGHTS RESERVED.

Theme Kratos Made By Seaton Jiang

粤ICP备18051778号

粤公网安备 44030902003257号