在此之前,写过一篇 [链接] ,获得了很多新人的认可,那时还是基于。net mvc,文档生成还是自己闹洞大开写出来的,经过这两年的时间,netcore 的发展已经势不可挡,自己也在不断的学习,公司的项目也转向了 netcore。大部分也都是前后分离的架构,后端 API 开发居多,从中整理了一些东西在这里分享给大家。 源 ..

NetApiStarter- 开始你的 api

在此之前,写过一篇 给新手的WebAPI实践 ,获得了很多新人的认可,那时还是基于。net mvc,文档生成还是自己闹洞大开写出来的,经过这两年的时间,netcore 的发展已经势不可挡,自己也在不断的学习,公司的项目也转向了 netcore。大部分也都是前后分离的架构,后端 API 开发居多,从中整理了一些东西在这里分享给大家。

源码地址:https://gitee.com/loogn/NetApiStarter,这是一个基于 netcore mvc 3.0 的模板项目,如果你使用的 netcore 2.x,除了引用不通用外,代码基本是可以复用的。下面介绍一下其中的功能。

登录验证

这里我默认使用了 jwt 登录验证,因为它足够简单和轻量,在 netcore mvc 中使用 jwt 验证非常简单,首先在 startup.cs 文件中配置服务并启用:
ConfigureServices 方法中:

            var jwtSection = Configuration.GetSection("Jwt");
            services.AddAuthentication(JwtBearerDefaults.AuthenticationScheme)
                .AddJwtBearer(options =>
                {
                    options.TokenValidationParameters = new TokenValidationParameters
                    {
                        ValidateIssuer = true,
                        ValidateAudience = true,
                        ValidateLifetime = true,
                        ValidateIssuerSigningKey = true,
                        ValidAudience = jwtSection["Audience"],
                        ValidIssuer = jwtSection["Issuer"],
                        IssuerSigningKey = new SymmetricSecurityKey(Encoding.UTF8.GetBytes(jwtSection["SigningKey"]))
                    };
                });

Configure 方法中,在 UseRouting 和 UseEndpoints 方法之前:

app.UseAuthorization();

上面我们使用到了 jwt 配置块,对应 appsettings.json 文件中有这样的配置:

{
  "Jwt": {
    "SigningKey": "1234567812345678",
    "Issuer": "NetApiStarter",
    "Audience": "NetApiStarter"
  }
}

我们再操作两步来实现登录验证,
一、提供一个接口生成 jwt,
二、在客户端请求头部加上Authorization: Bearer {jwt}
我先封装了一个生成 jwt 的方法

    public static class JwtHelper
    {
        public static string WriteToken(Dictionary<string, string> claimDict, DateTime exp)
        {
            var key = new SymmetricSecurityKey(Encoding.UTF8.GetBytes(AppSettings.Instance.Jwt.SigningKey));
            var creds = new SigningCredentials(key, SecurityAlgorithms.HmacSha256);
            var token = new JwtSecurityToken(
                issuer: AppSettings.Instance.Jwt.Issuer,
                audience: AppSettings.Instance.Jwt.Audience,
                claims: claimDict.Select(x => new Claim(x.Key, x.Value)),
                expires: exp,
                signingCredentials: creds);
            var jwt = new JwtSecurityTokenHandler().WriteToken(token);
            return jwt;
        }
}

然后在登录服务中调用

        /// <summary>
        /// 登录,获取jwt
        /// </summary>
        /// <param name="request"></param>
        /// <returns></returns>
        public ResultObject<LoginResponse> Login(LoginRequest request)
        {
            var user = userDao.GetUser(request.Account, request.Password);
            if (user == null)
            {
                return new ResultObject<LoginResponse>("用户名或密码错误");
            }
            var dict = new Dictionary<string, string>();
            dict.Add("userid", user.Id.ToString());
            var jwt = JwtHelper.WriteToken(dict, DateTime.Now.AddDays(7));
            var response = new LoginResponse { Jwt = jwt };
            return new ResultObject<LoginResponse>(response);
        }

在 Controller 和 Action 上添加[Authorize]和[AllowAnonymous]两个特性就可以实现登录验证了。

请求响应

这里请求响应的设计依然没有使用 RESTFul 风格,一是感觉太麻烦,二是真的不太懂(实事求是),所以请求还是以 POST 方式投递 JSON 数据,响应当然也是 JSON 数据这个没啥异议的。
为啥使用 POST+JSON 呢,主要是简单,大家都懂,而且规则统一、繁简皆宜,比如什么参数都不需要,就传{},根据 ID 查询文章{articleId:23},或者复杂的查询条件和表单提交{ name:'abc', addr:{provice:'HeNan', city:'ZhengZhou'},tags:['骑马','射箭'] } 等等都可以优雅的传递。
这只是我个人的风格,netcore mvc 是支持其他的方式的,选自己喜欢的就行了。
下面的内容还是按照 POST+JSON 来说。

首先提供请求基类:

    /// <summary>
    /// 登录用户请求的基类
    /// </summary>
    public class LoginedRequest
    {
        #region jwt相关用户
        private ClaimsPrincipal _claimsPrincipal { get; set; }

        public ClaimsPrincipal GetPrincipal()
        {
            return _claimsPrincipal;
        }
        public void SetPrincipal(ClaimsPrincipal user)
        {
            _claimsPrincipal = user;
        }

        public string GetClaimValue(string name)
        {
            return _claimsPrincipal?.FindFirst(name)?.Value;
        }
        #endregion

        #region 数据库相关用户 (如果有必要的话)
        //不用属性是因为swagger中会显示出来
        private User _user;
        public User GetUser()
        {
            return _user;
        }
        public void SetUser(User user)
        {
            _user = user;
        }
        #endregion
    }

这个类中说白了就是两个手写属性,一个 ClaimsPrincipal 用来保存从 jwt 解析出来的用户,一个 User 用来保存数据库中完整的用户信息,为啥不直接使用属性呢,上面注释也提到了,不想在 API 文档中显示出来。这个用户信息是在服务层使用的,而且 User 不是必须的,比如 jwt 中的信息够服务层使用,不定义 User 也是可以的,总之这里的信息是为服务层逻辑服务的。
我们还可以定义其他的基类,比如经常用的分页基类:

    public class PagedRequest : LoginedRequest
    {
        public int PageIndex { get; set; }
        public int PageSize { get; set; }
    }

根据项目的实际情况还可以定义更多的基类来方便开发。

响应类使用统一的格式,这里直接提供 JSON 方便查看:

{
  "result": {
    "jwt": "string"
  },
  "success": true,
  "code": 0,
  "msg": "错误信息"
}

result 是具体的响应对象,如果 success 为 false 的话,result 一般是 null。

ActionFilter

mvc 本身是一个扩展性极强的框架,层层有拦截,ActionFilter 就是其中之一,IActionFilter 接口有两个方法,一个是 OnActionExecuted,一个是 OnActionExecuting,从命名也能看出,就是在 Action 的前后分别执行的方法。我们这里主要重写 OnActionExecuting 方法来做两件事:
一、将登陆信息赋值给请求对象
二、验证请求对象
这里说的请求对象,其类型就是 LoginedRequest 或者 LoginedRequest 的子类,看代码:

    [AppService]
    [AttributeUsage(AttributeTargets.Class | AttributeTargets.Method, AllowMultiple = false, Inherited = true)]
    public class MyActionFilterAttribute : ActionFilterAttribute
    {
        /// <summary>
        /// 是否验证参数有效性
        /// </summary>
        public bool ValidParams { get; set; } = true;

        public override void OnActionExecuting(ActionExecutingContext context)
        {
            //由于Filters是套娃模式,使用以下逻辑保证作用域的覆盖 Action > Controller > Global
            if (context.Filters.OfType<MyActionFilterAttribute>().Last() != this)
            {
                return;
            }

            //默认只有一个参数
            var firstParam = context.ActionArguments.FirstOrDefault().Value;
            if (firstParam != null && firstParam.GetType().IsClass)
            {
                //验证参数合法性
                if (ValidParams)
                {
                    var validationResults = new List<ValidationResult>();
                    var validationFlag = Validator.TryValidateObject(firstParam, new ValidationContext(firstParam), validationResults, false);
                    if (!validationFlag)
                    {
                        var ro = new ResultObject(validationResults.First().ErrorMessage);
                        context.Result = new JsonResult(ro);
                        return;
                    }
                }
            }

            var requestParams = firstParam as LoginedRequest;
            if (requestParams != null)
            {
                //设置jwt用户
                requestParams.SetPrincipal(context.HttpContext.User);
                var userid = requestParams.GetClaimValue("userid");
                //如果有必要,可以每次都获取数据库中的用户
                if (!string.IsNullOrEmpty(userid))
                {
                    var user = ((UserService)context.HttpContext.RequestServices.GetService(typeof(UserService))).SingleById(long.Parse(userid));
                    requestParams.SetUser(user);
                }
            }

            base.OnActionExecuting(context);
        }
    }

模型验证这块使用的是系统自带的,从上面代码也可以看出,如果请求对象定义为 LoginedRequest 及其子类,每次请求会填充 ClaimsPrincipal,如果有必要,可以从数据库中读取 User 信息填充。
请求经过 ActionFilter 时,模型验证不通过的,直接返回了验证错误信息,通过之后到达 Action 和 Service 时,用户信息已经可以直接使用了。

API 文档和日志

API 文档首选 swagger 了,aspnetcore 官方文档也是使用的这个,我这里用的是 Swashbuckle,首先安装引用

Install-Package Swashbuckle.AspNetCore -Version 5.0.0-rc4
定义一个扩展类,方便把 swagger 注入容器中:

public static class SwaggerServiceExtensions
    {
        public static IServiceCollection AddSwagger(this IServiceCollection services)
        {
            //https://github.com/domaindrivendev/Swashbuckle.AspNetCore
            services.AddSwaggerGen(c =>
            {
                c.SwaggerDoc("v1", new OpenApiInfo
                {
                    Title = "My Api",
                    Version = "v1"
                });
                c.IgnoreObsoleteActions();
                c.IgnoreObsoleteProperties();
                c.DocumentFilter<SwaggerDocumentFilter>();
                //自定义类型映射
                c.MapType<byte>(() => new OpenApiSchema { Type = "byte", Example = new OpenApiByte(0) });
                c.MapType<long>(() => new OpenApiSchema { Type = "long", Example = new OpenApiLong(0L) });
                c.MapType<int>(() => new OpenApiSchema { Type = "integer", Example = new OpenApiInteger(0) });
                c.MapType<DateTime>(() => new OpenApiSchema { Type = "DateTime", Example = new OpenApiDateTime(DateTimeOffset.Now) });

                //xml注释
                foreach (var file in Directory.GetFiles(AppContext.BaseDirectory, "*.xml"))
                {
                    c.IncludeXmlComments(file);
                }

                //Authorization的设置
                c.AddSecurityDefinition("Bearer", new OpenApiSecurityScheme
                {
                    In = ParameterLocation.Header,
                    Description = "请输入验证的jwt。示例:Bearer {jwt}",
                    Name = "Authorization",

                    Type = SecuritySchemeType.ApiKey,
                });
            });
            return services;
        }

        /// <summary>
        /// Swagger控制器描述文字
        /// </summary>
        class SwaggerDocumentFilter : IDocumentFilter
        {
            public void Apply(OpenApiDocument swaggerDoc, DocumentFilterContext context)
            {
                swaggerDoc.Tags = new List<OpenApiTag>
                {
                    new OpenApiTag{ Name="User", Description="用户相关"},
                    new OpenApiTag{ Name="Common", Description="公共功能"},
                };
            }
        }
    }

主要是验证部分,加上去之后就可以在文档中使用 jwt 测试了
然后在 startup.cs 的 ConfigureServices 方法中
services.AddSwagger();
Configure 方法中:

            if (env.IsDevelopment())
            {
                app.UseSwagger();
                app.UseSwaggerUI(options =>
                {
                    options.SwaggerEndpoint("/swagger/v1/swagger.json", "My API V1");
                    options.DocExpansion(DocExpansion.None);
                });
            }

这里限制了只有在开发环境才显示 API 文档,如果是需要外部调用的话,可以不做这个限制。

日志组件使用 Serilog。
首先也是安装引用
Install-Package Serilog
Install-Package Serilog.AspNetCore
Install-Package Serilog.Settings.Configuration
Install-Package Serilog.Sinks.RollingFile

然后在 appsettings.json 中添加配置

{
  "Serilog": {
    "WriteTo": [
      { "Name": "Console" },
      {
        "Name": "RollingFile",
        "Args": { "pathFormat": "logs/{Date}.log" }
      }
    ],
    "Enrich": [ "FromLogContext" ],
    "MinimumLevel": {
      "Default": "Debug",
      "Override": {
        "Microsoft": "Warning",
        "System": "Warning"
      }
    }
  },
}

更多配置请查看https://github.com/serilog/serilog-settings-configuration

上述配置会在应用程序根目录的 logs 文件夹下,每天生成一个命名类似 20191129.log 的日志文件

最后要修改一下 Program.cs,代替默认的日志组件

public static IHostBuilder CreateHostBuilder(string[] args) =>
            Host.CreateDefaultBuilder(args)
                .ConfigureWebHostDefaults(webBuilder =>
                {
                    webBuilder.UseConfiguration(new ConfigurationBuilder().SetBasePath(Environment.CurrentDirectory).AddJsonFile("appsettings.json").Build());

                    webBuilder.UseStartup<Startup>();

                    webBuilder.UseSerilog((whbContext, configureLogger) =>
                    {
configureLogger.ReadFrom.Configuration(whbContext.Configuration);
                    });
                });

文件分块上传

文件上传就像登录验证一样常用,哪个应用还不上传个头像啥的,所以我也打算整合到模板项目中,如果是单纯的上传也就没必要说了,这里主要说的是一种大文件上传的解决方法: 分块上传。

分块上传是需要客户端配合的,客户端把一个大文件分好块,一小块一小块的上传,上传完成之后服务端按照顺序合并到一起就是整个文件了。

所以我们先定义分块上传的参数:

string identifier : 文件标识,一个文件的唯一标识,
int chunkNumber :当前块所以,我是从1开始的
int chunkSize :每块大小,客户端设置的固定值,单位为byte,一般2M左右就可以了
long totalSize:文件总大小,单位为byte
int totalChunks:总块数

这些参数都好理解,在服务端验证和合并文件时需要。

开始的时候我是这样处理的,客户端每上传一块,我会把这块的内容写到一个临时文件中,使用 identifier 和 chunkNumber 来命名,这样就知道是哪个文件的哪一块了,当上传完最后一块之后,也就是 chunkNumber==totalChunks 的时候,我将所有的分块小文件合并到目标文件,然后返回 url。

这个逻辑是没什么问题,只需要一个机制保证合并文件的时候所有块都已上传就可以了,为什么要这样一个机制呢,主要是因为客户端的上传可能是多线程的,而且也不能完全保证 http 的响应顺序和请求顺序是一样的,所以虽然上传完最后一块才会合并,但是还是需要一个机制判断一下是否所有块都上传完毕,没有上传完还要等待一下(想一想怎么实现!)。

后来在实际上传过程中发现最后一块响应会比较慢,特别是文件很大的时候,这个也好理解,因为最后一块上传会合并文件,所以需要优化一下。

这里就使用到了队列的概念了,我们可以把每次上传的内容都放在队列中,然后使用另一个线程从队列中读取并写入目标文件。在这个场景中BlockingCollection是最合适不过的了。
我们定义一个实体类,用于保存入列的数据:

    public class UploadChunkItem
    {
        public byte[] Data { get; set; }
        public int ChunkNumber { get; set; }
        public int ChunkSize { get; set; }
        public string FilePath { get; set; }
    }

然后定义一个队列写入器

public class UploadChunkWriter
    {
        public static UploadChunkWriter Instance = new UploadChunkWriter();
        private BlockingCollection<UploadChunkItem> _queue;
        private int _writeWorkerCount = 3;
        private Thread _writeThread;
        public UploadChunkWriter()
        {
            _queue = new BlockingCollection<UploadChunkItem>(500);
            _writeThread = new Thread(this.Write);
        }

        public void Write()
        {
            while (true)
            {
                //单线程写入
                //var item = _queue.Take();
                //using (var fileStream = File.Open(item.FilePath, FileMode.Open, FileAccess.Write, FileShare.ReadWrite))
                //{
                //    fileStream.Position = (item.ChunkNumber - 1) * item.ChunkSize;
                //    fileStream.Write(item.Data, 0, item.Data.Length);
                //    item.Data = null;
                //}

                //多线程写入
                Task[] tasks = new Task[_writeWorkerCount];
                for (int i = 0; i < _writeWorkerCount; i++)
                {
                    var item = _queue.Take();
                    tasks[i] = Task.Run(() =>
                     {
                         using (var fileStream = File.Open(item.FilePath, FileMode.Open, FileAccess.Write, FileShare.ReadWrite))
                         {
                             fileStream.Position = (item.ChunkNumber - 1) * item.ChunkSize;
                             fileStream.Write(item.Data, 0, item.Data.Length);
                             item.Data = null;
                         }
                     });
                }
                Task.WaitAll(tasks);
            }
        }

        public void Add(UploadChunkItem item)
        {
            _queue.Add(item);
        }

        public void Start()
        {
            _writeThread.Start();
        }
    }

主要是 Write 方法的逻辑,调用_queue.Take()方法从队列中获取一项,如果队列中没有数据,这个方法会堵塞当前线程,这也是我们所期望的,获取到数据之后,打开目标文件(在上传第一块的时候会创建),根据 ChunkNumber 和 ChunkSize 找到开始写入的位置,然后把本块数据写入。
打开目标文件的时候使用了 FileShare.ReadWrite,表示这个文件可以同时被多个线程读取和写入。

文件上传方法也简单:

        /// <summary>
        /// 分片上传
        /// </summary>
        /// <param name="formFile"></param>
        /// <param name="chunkNumber"></param>
        /// <param name="chunkSize"></param>
        /// <param name="totalSize"></param>
        /// <param name="identifier"></param>
        /// <param name="totalChunks"></param>
        /// <returns></returns>
        public ResultObject<UploadFileResponse> ChunkUploadfile(IFormFile formFile, int chunkNumber, int chunkSize, long totalSize,
            string identifier, int totalChunks)
        {
            var appSetting = AppSettings.Instance;
            #region 验证
            if (formFile == null && formFile.Length == 0)
            {
                return new ResultObject<UploadFileResponse>("文件不能为空");
            }
            if (formFile.Length > appSetting.Upload.LimitSize)
            {
                return new ResultObject<UploadFileResponse>("文件超过了最大限制");
            }
            var ext = Path.GetExtension(formFile.FileName).ToLower();
            if (!appSetting.Upload.AllowExts.Contains(ext))
            {
                return new ResultObject<UploadFileResponse>("文件类型不允许");
            }
            if (chunkNumber == 0 || chunkSize == 0 || totalSize == 0 || identifier.Length == 0 || totalChunks == 0)
            {
                return new ResultObject<UploadFileResponse>("参数错误0");
            }
            if (chunkNumber > totalChunks)
            {
                return new ResultObject<UploadFileResponse>("参数错误1");
            }
            if (totalSize > appSetting.Upload.TotalLimitSize)
            {
                return new ResultObject<UploadFileResponse>("参数错误2");
            }
            if (chunkNumber < totalChunks && formFile.Length != chunkSize)
            {
                return new ResultObject<UploadFileResponse>("参数错误3");
            }
            if (totalChunks == 1 && formFile.Length != totalSize)
            {
                return new ResultObject<UploadFileResponse>("参数错误4");
            }
            #endregion

            //写入逻辑
            var now = DateTime.Now;
            var yy = now.ToString("yyyy");
            var mm = now.ToString("MM");
            var dd = now.ToString("dd");

            var fileName = EncryptHelper.MD5Encrypt(identifier) + ext;
            var folder = Path.Combine(appSetting.Upload.UploadPath, yy, mm, dd);
            var filePath = Path.Combine(folder, fileName);

            //线程安全的创建文件
            if (!File.Exists(filePath))
            {
                lock (lockObj)
                {
                    if (!File.Exists(filePath))
                    {
                        if (!Directory.Exists(folder))
                        {
                            Directory.CreateDirectory(folder);
                        }
                        File.Create(filePath).Dispose();
                    }
                }
            }

            var data = new byte[formFile.Length];
            formFile.OpenReadStream().Read(data, 0, data.Length);

            UploadChunkWriter.Instance.Add(new UploadChunkItem
            {
                ChunkNumber = chunkNumber,
                ChunkSize = chunkSize,
                Data = data,
                FilePath = filePath
            });
            if (chunkNumber == totalChunks)
            {
                //等等写入完成
                int i = 0;
                while (true)
                {
                    if (i >= 20)
                    {
                        return new ResultObject<UploadFileResponse>
                        {
                            Success = false,
                            Msg = $"上传失败,总大小:{totalSize},实际大小:{new FileInfo(filePath).Length}",
                            Result = new UploadFileResponse { Url = "" }
                        };
                    }
                    if (new FileInfo(filePath).Length != totalSize)
                    {
                        Thread.Sleep(TimeSpan.FromMilliseconds(1000));
                        i++;
                    }
                    else
                    {
                        break;
                    }
                }
                var fileUrl = $"{appSetting.RootUrl}{appSetting.Upload.RequestPath}/{yy}/{mm}/{dd}/{fileName}";
                var response = new UploadFileResponse { Url = fileUrl };
                return new ResultObject<UploadFileResponse>(response);
            }
            else
            {
                return new ResultObject<UploadFileResponse>
                {
                    Success = true,
                    Msg = "uploading...",
                    Result = new UploadFileResponse { Url = "" }
                };
            }
        }

撇开上面的参数验证,主要逻辑也就是三个,一是创建目标文件,二是分块数据加入队列,三是最后一块的时候要验证文件的完整性(也就是所有的块都上传了,并都写入到了目标文件)

创建目标文件需要保证线程安全,这里使用了双重检查加锁机制,双重检查的优点是避免了不必要的加锁情况。

完整性我只是验证了文件的大小,这只是一种简单的机制,一般是够用了,别忘了我们的接口都是受 jwt 保护的,包括这里的上传文件。如果要求更高的话,可以让客户端传参整个文件的 md5 值,然后服务端验证合并之后文件的 md5 是否和客户端给的一致。

最后要开启写入线程,可以在 Startup.cs 的 Configure 方法中开启:

UploadChunkWriter.Instance.Start();

经过这样的整改,上传速度溜溜的,最后一块也不用长时间等待啦!

(项目中当然也包含了不分块上传)

其他功能

自从 netcore 提供了依赖注入,我也习惯了这种写法,不过在构造函数中写一堆注入实在是难看,而且既要声明字段接收,又要写参数赋值,挺麻烦的,于是乎自己写了个小组件,已经用于手头所有的项目,当然也包含在了 NetApiStarter 中,不仅解决了属性和字段注入,同时也解决了实现多接口注入的问题,以及一个接口多个实现精准注入的问题,详细说明可查看项目文档Autowired.Core

如果你听过 MediatR,那么这个功能不需要介绍了,项目中包含一个应用程序级别的事件发布和订阅的功能,具体使用可查看文档AppEventService

如果你听过 AutoMapper,那么这个功能也不需要介绍了,项目中包含一个 SimpleMapper,代码不多功能还行,支持嵌套类、数组、IList<>、IDictionary<,> 实体映射在多层数据传输的时候可谓是必不可少的功能,用法嘛就不说了,只有一个 Map 方法太简单了

重中之重

如果你感觉这个项目对你、或者其他人(You or others,没毛病)有稍许帮助,请给个 Star 好吗!

NetApiStarter 仓库地址:https://gitee.com/loogn/NetApiStarter

  • .NET
    25 引用 • 6 回帖 • 3 关注
  • API

    应用程序编程接口(Application Programming Interface)是一些预先定义的函数,目的是提供应用程序与开发人员基于某软件或硬件得以访问一组例程的能力,而又无需访问源码,或理解内部工作机制的细节。

    52 引用 • 310 回帖 • 2 关注
回帖
请输入回帖内容...