開始你的api：NetApiStarter

時間 2019-11-30

標籤開始 api netapistarter 简体版

原文原文鏈接

在此以前，寫過一篇給新手的WebAPI實踐，得到了不少新人的承認，那時仍是基於.net mvc，文檔生成仍是本身鬧洞大開寫出來的，通過這兩年的時間，netcore的發展已經勢不可擋，本身也在不斷的學習，公司的項目也轉向了netcore。大部分也都是先後分離的架構，後端api開發居多，從中整理了一些東西在這裏分享給你們。html

源碼地址：https://gitee.com/loogn/NetApiStarter，這是一個基於netcore mvc 3.0的模板項目，若是你使用的netcore 2.x，除了引用不通用外，代碼基本是能夠複用的。下面介紹一下其中的功能。git

登陸驗證

這裏我默認使用了jwt登陸驗證，由於它足夠簡單和輕量，在netcore mvc中使用jwt驗證很是簡單，首先在startup.cs文件中配置服務並啓用：
ConfigureServices方法中：github

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方法以前：web

app.UseAuthorization();

上面咱們使用到了jwt配置塊，對應appsettings.json文件中有這樣的配置：數據庫

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

咱們再操做兩步來實現登陸驗證，
1、提供一個接口生成jwt，
2、在客戶端請求頭部加上Authorization: Bearer {jwt}
我先封裝了一個生成jwt的方法json

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]兩個特性就能夠實現登陸驗證了。api

請求響應

這裏請求響應的設計依然沒有使用restful風格，一是感受太麻煩，二是真的不太懂(實事求是)，因此請求仍是以POST方式投遞JSON數據，響應固然也是JSON數據這個沒啥異議的。
爲啥使用POST+JSON呢，主要是簡單，你們都懂，並且規則統1、繁簡皆宜，好比什麼參數都不須要，就傳{}，根據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方法來作兩件事：
1、將登錄信息賦值給請求對象
2、驗證請求對象
這裏說的請求對象，其類型就是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"
      }
    }
  },
}

上述配置會在應用程序根目錄的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方法太簡單了