一文說通Dotnet Core的中介軟體

Tiger.Wang發表於2020-06-03

前幾天,公眾號後臺有朋友在問Core的中介軟體,所以專門抽時間整理了這樣一篇文章。

一、前言

中介軟體(Middleware)最初是一個機械上的概念,說的是兩個不同的運動結構中間的連線件。後來這個概念延伸到軟體行業,大家把應用作業系統和電腦硬體之間過渡的軟體或系統稱之為中介軟體,比方驅動程式,就是一個典型的中介軟體。再後來,這個概念就泛開了,任何用來連線兩個不同系統的東西,都被叫做中介軟體。

所以,中介軟體只是一個名詞,不用太在意,實際程式碼跟他這個詞,也沒太大關係。

中介軟體技術,早在.Net framework時期就有,只不過,那時候它不是Microsoft官方的東西,是一個叫OWIN的三方框架下的實現。到了.Net core,Microsoft才把中介軟體完整加到框架裡來。

感覺上,應該是Core參考了OWIN的中介軟體技術(猜的,未求證)。在實現方式上,兩個框架下的中介軟體沒什麼區別。

下面,我們用一個實際的例子,來理清這個概念。

    為了防止不提供原網址的轉載,特在這裡加上原文連結:https://www.cnblogs.com/tiger-wang/p/13038419.html

二、開發環境&基礎工程

這個Demo的開發環境是:Mac + VS Code + Dotnet Core 3.1.2。

$ dotnet --info
.NET Core SDK (reflecting any global.json):
 Version:   3.1.201
 Commit:    b1768b4ae7

Runtime Environment:
 OS Name:     Mac OS X
 OS Version:  10.15
 OS Platform: Darwin
 RID:         osx.10.15-x64
 Base Path:   /usr/local/share/dotnet/sdk/3.1.201/

Host (useful for support):
  Version: 3.1.3
  Commit:  4a9f85e9f8

.NET Core SDKs installed:
  3.1.201 [/usr/local/share/dotnet/sdk]

.NET Core runtimes installed:
  Microsoft.AspNetCore.App 3.1.3 [/usr/local/share/dotnet/shared/Microsoft.AspNetCore.App]
  Microsoft.NETCore.App 3.1.3 [/usr/local/share/dotnet/shared/Microsoft.NETCore.App]

首先,在這個環境下建立工程:

  1. 建立Solution
% dotnet new sln -o demo
The template "Solution File" was created successfully.
  1. 這次,我們用Webapi建立工程
cd demo
% dotnet new webapi -o demo
The template "ASP.NET Core Web API" was created successfully.

Processing post-creation actions...
Running 'dotnet restore' on demo/demo.csproj...
  Restore completed in 179.13 ms for demo/demo.csproj.

Restore succeeded.
  1. 把工程加到Solution中
% dotnet sln add demo/demo.csproj

基礎工程搭建完成。

三、建立第一個中介軟體

我們先看下Demo專案的Startup.cs檔案:

namespace demo
{
    public class Startup
    {

        public Startup(IConfiguration configuration)
        
{
            Configuration = configuration;
        }

        public IConfiguration Configuration { get; }

        // This method gets called by the runtime. Use this method to add services to the container.
        public void ConfigureServices(IServiceCollection services)
        
{
            services.AddControllers();
        }

        // This method gets called by the runtime. Use this method to configure the HTTP request pipeline.
        public void Configure(IApplicationBuilder app, IWebHostEnvironment env)
        
{
            if (env.IsDevelopment())
            {
                app.UseDeveloperExceptionPage();
            }

            app.UseHttpsRedirection();

            app.UseRouting();

            app.UseAuthorization();

            app.UseEndpoints(endpoints =>
            {
                endpoints.MapControllers();
            });
        }
    }
}

這是Startup預設生成後的樣子(注意,不同的作業系統下生成的程式碼會略有不同,但本質上沒區別)。

其中,Configure是中介軟體的執行定義,ConfigureServices是中介軟體的引數設定注入。

我們在Configure方法裡,加入一個簡單的中介軟體:

app.UseAuthorization();
/////////////////////下面是加入的程式碼
app.Use(async (context, next) =>
{
    // your code
    await next.Invoke();
    // your code
});
/////////////////////////
app.UseEndpoints(endpoints =>
{
        endpoints.MapControllers();
});

在這個程式碼中,app.Use是引入中介軟體的方式,而真正的中介軟體,是async (context, next),這是一個delegate方法。

中介軟體方法的兩個引數,context是上下文HttpContextnext指向下一個中介軟體。

其中,next引數很重要。中介軟體採用管道的形式執行。多箇中介軟體,通過next進行呼叫。

四、中介軟體的短路

在前一節,我們看到了中介軟體的標準形式。

有時候,我們希望中介軟體執行完成後就退出執行,而不進入下一個中介軟體。這時候,我們可以把await next.Invoke()從程式碼中去掉。變成下面的形式:

app.Use(async (context, next) =>
{
    // your code
});

對於這種形式,Microsoft給出了另一個方式的寫法:

app.Run(async context =>
{
    // your code
});

這兩種形式,效果完全一樣。

這種形式,我們稱之為短路,就是說在這個中介軟體執行後,程式即返回資料給客戶端,而不執行下面的中介軟體。

五、中介軟體的對映

有時候,我們需要把一箇中介軟體對映到一個Endpoint,用以對外提供簡單的API處理。這種時間,我們需要用到對映:

app.Map("/apiname", apiname => {
    app.Use(async (context, next) =>
    {
        // your code
        await next.Invoke();
    });  
});

此外,對映支援巢狀:

app.Map("/router", router => {
        router.Map("/api1name", api1Name => {
        app.Use(async (context, next) =>
        {
            // your code
            await next.Invoke();
        }); 
        });
      router.Map("/api2name", api2Name => {
        app.Use(async (context, next) =>
        {
            // your code
            await next.Invoke();
        });     
    });
})

對於這兩個巢狀的對映,我們訪問的Endpoint分別是/router/api1name/router/api2name

以上部分,就是中介軟體的基本內容。

但是,這兒有個問題:為什麼我們從各處文章裡看到的中介軟體,好像都不是這麼寫的?

嗯,答案其實很簡單,我們看到的方式,也都是中介軟體。只不過,那些程式碼,是這個中介軟體的最基本樣式的變形。

下面,我們就來說說變形。

六、變形1: 獨立成一個類

大多數情況下,我們希望中介軟體能獨立成一個類,方便控制,也方便程式編寫。

這時候,我們可以這樣做:先寫一個類:

public class TestMiddleware
{

    private readonly RequestDelegate _next;

    public TestMiddleware(RequestDelegate next)
    
{
        _next = next;
    }

    public async Task Invoke(HttpContext context)
    
{
        // Your code
        await _next.Invoke(context);
    }
}

這個類裡contextnext和上面簡單形式下的兩個引數,型別和意義是完全一樣的。

下面,我們把這個類引入到Configure中:

app.UseMiddleware<TestMiddleware>();

注意,引入Middleware類,需要用app.UseMiddleware而不是app.Use

app.Use引入的是方法,而app.UseMiddleware引入的是類。就這點區別。

如果再想高大上一點,可以做個Extensions:

public static class TestMiddlewareExtensions
{

    public static IApplicationBuilder UseTestMiddleware(this IApplicationBuilder app)
    
{
        return app.UseMiddleware<TestMiddleware>();
    }
}

然後,在Configure中,就可以換成:

app.UseTestMiddleware();

看著高大上了有沒有?

七、變形2: 簡單引入引數

有時候,我們需要給在中介軟體初始化時,給它傳遞一些引數。

看類:

public class TestMiddleware
{

    private readonly RequestDelegate _next;
    private static object _parameter

    public TestMiddleware(RequestDelegate next, object parameter)
    
{
        _next = next;
        _parameter = parameter;
    }

    public async Task Invoke(HttpContext context)
    
{
        // Your code
        await _next.Invoke(context);
    }
}

那相應的,我們在Configure中引入時,需要寫成:

app.UseMiddleware<TestMiddleware>(new object());

同理,如果我們用Extensions時:

public static class TestMiddlewareExtensions
{

    public static IApplicationBuilder UseTestMiddleware(this IApplicationBuilder app, object parameter)
    
{
        return app.UseMiddleware<TestMiddleware>(parameter);
    }
}

同時,引入變為:

app.UseTestMiddleware(new object());

八、變形3: 依賴注入引數

跟前一節一樣,我們需要引入引數。這一節,我們用另一種更優雅的方式:依賴注入引數。

先建立一個interface:

public interface IParaInterface
{
    void someFunction();
}

再根據interface建立一個實體類:

public class ParaClass : IParaInterface
{
    public void someFunction()
    
{
    }
}

引數類有了。下面建立中介軟體:

public class TestMiddleware
{

    private readonly RequestDelegate _next;
    private static IParaInterface _parameter

    public TestMiddleware(RequestDelegate next, IParaInterface parameter)
    
{
        _next = next;
        _parameter = parameter;
    }

    public async Task Invoke(HttpContext context)
    
{
        // Your code
        // Example: _parameter.someFunction();

        await _next.Invoke(context);
    }
}

因為我們要採用注入而不是傳遞引數,所以Extensions不需要關心引數:

public static class TestMiddlewareExtensions
{

    public static IApplicationBuilder UseTestMiddleware(this IApplicationBuilder app)
    
{
        return app.UseMiddleware<TestMiddleware>();
    }
}

最後一步,我們在StartupConfigureServices中加入注入程式碼:

services.AddTransient<IParaInterface, ParaClass>();

完成 !

這個方式是Microsoft推薦的方式。

我在前文Dotnet core使用JWT認證授權最佳實踐中,在介紹JWT配置時,實際使用的也是這種方式。

  1. 中介軟體
app.UseAuthentication();

這是Microsoft已經寫好的認證中介軟體,我們只簡單做了引用。

  1. 注入引數
services.AddAuthentication(JwtBearerDefaults.AuthenticationScheme)
            .AddJwtBearer(option =>
            {
                option.RequireHttpsMetadata = false;
                option.SaveToken = true;

                var token = Configuration.GetSection("tokenParameter").Get<tokenParameter>();

                option.TokenValidationParameters = new TokenValidationParameters
                {
                    ValidateIssuerSigningKey = true,
                    IssuerSigningKey = new SymmetricSecurityKey(Encoding.ASCII.GetBytes(token.Secret)),
                    ValidIssuer = token.Issuer,
                    ValidateIssuer = true,
                    ValidateAudience = false,
                    ClockSkew = TimeSpan.Zero,
                };
            });

這部分程式碼,是我們注入的引數設定。其中,幾個方法又是Microsoft庫提供的Builder。

Builder是注入引數的另一種變形。我會在關於注入和依賴注入中詳細說明。

九、中介軟體的引入次序

中介軟體的引入次序,從程式碼上來說沒有那麼嚴格。就是說,某些型別的中介軟體交換次序不會有太大問題。

一般來說,使用中介軟體的時候,可以考慮以下規則:

  1. 實現Endpoint的中介軟體,應該放在最後,但要放在控制器引入的中介軟體之前。通常Endpoint中介軟體提供的是API或類似的內容,它會有Response的返回。而中介軟體在Response返回後,就不會呼叫Next了。
  2. 具有資料過濾內容的中介軟體,應該往前放,而且有個規則:當有過濾到規則外的情況時,應該越早返回越好。

以這兩個規則來決定中介軟體的引入次序,就足夠了。

(全文完)

 


 

微信公眾號:老王Plus

掃描二維碼,關注個人公眾號,可以第一時間得到最新的個人文章和內容推送

本文版權歸作者所有,轉載請保留此宣告和原文連結

相關文章