开始你的api：NetApiStarter
在此之前，寫過一篇?給新手的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方法中：
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 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 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的子類，看代碼：
[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 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方法中：
{
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 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
總結
以上是生活随笔為你收集整理的开始你的api：NetApiStarter的全部內容，希望文章能夠幫你解決所遇到的問題。
- 上一篇： 被忽略的TraceId，可以用起来了
- 下一篇： 冰雪奇缘，白色世界：四个IT人的四姑娘山