@elf-express/admin-net-mcp 1.0.0 → 1.1.0

package/knowledge/Furion_Teaching_Manual/05-5-/344/270/255/344/273/213/350/273/237/351/253/224Middleware.md

@@ -0,0 +1,328 @@
+# 5.5 中介軟體（Middleware）
+
+## 5.5.1 關於中介軟體
+
+中介軟體是一種裝配到應用管線以處理請求和回應的軟體。每個組件：
+
+- 選擇是否將請求傳遞到管線中的下一個組件
+- 可在管線中的下一個組件前後執行工作
+
+請求委派用於產生請求管線，請求委派處理每個 HTTP 請求。
+
+> 一句話總結：中介軟體是比篩選器更底層、更上游的面向切面技術，其效能最高，可處理的應用範圍遠比過濾器廣，如實現閘道、URL 轉發、限流等等。
+
+---
+
+## 5.5.2 常見中介軟體
+
+### 5.5.2.1 所有請求回傳同一個結果
+
+```csharp
+app.Run(async context =>
+{
+    await context.Response.WriteAsync("Hello world!");
+});
+```
+
+### 5.5.2.2 攔截所有請求（可多個）
+
+```csharp
+app.Use(async (context, next) =>
+{
+    // 比如設定統一標頭
+    context.Response.Headers["framework"] = "Furion";
+
+    // 執行下一個中介軟體
+    await next.Invoke();
+});
+
+// 多個
+app.Use(...);
+```
+
+### 5.5.2.3 特定路由中介軟體（可多個）
+
+```csharp
+app.Map("/hello", app => {
+    app.Run(async context =>
+    {
+        await context.Response.WriteAsync("Map Test 1");
+    });
+});
+
+app.Map("/hello/say", app => {
+    // ....
+});
+```
+
+### 5.5.2.4 巢狀路由中介軟體（可多個）
+
+```csharp
+app.Map("/level1", level1App => {
+    level1App.Map("/level2a", level2AApp => {
+        // "/level1/level2a" processing
+    });
+    level1App.Map("/level2b", level2BApp => {
+        // "/level1/level2b" processing
+    });
+});
+```
+
+---
+
+## 5.5.3 自訂中介軟體
+
+自訂中介軟體有多種方式，最簡單的是透過 `app.Use` 方式，另外還支援獨立類別定義方式。
+
+### 5.5.3.1 app.Use 方式（不推薦）
+
+```csharp
+app.Use(async (context, next) =>
+{
+    var cultureQuery = context.Request.Query["culture"];
+    if (!string.IsNullOrWhiteSpace(cultureQuery))
+    {
+        var culture = new CultureInfo(cultureQuery);
+        CultureInfo.CurrentCulture = culture;
+        CultureInfo.CurrentUICulture = culture;
+    }
+
+    await next(context);
+});
+```
+
+### 5.5.3.2 獨立類別方式（推薦）
+
+獨立類別的方式是目前最為推薦的方式，擴充性強，維護性高。
+
+**定義中介軟體（建議以 `Middleware` 結尾）：**
+
+```csharp
+using System.Globalization;
+
+namespace Middleware.Example;
+
+public class RequestCultureMiddleware
+{
+    private readonly RequestDelegate _next;
+
+    public RequestCultureMiddleware(RequestDelegate next)
+    {
+        _next = next;
+    }
+
+    public async Task InvokeAsync(HttpContext context)
+    {
+        var cultureQuery = context.Request.Query["culture"];
+        if (!string.IsNullOrWhiteSpace(cultureQuery))
+        {
+            var culture = new CultureInfo(cultureQuery);
+            CultureInfo.CurrentCulture = culture;
+            CultureInfo.CurrentUICulture = culture;
+        }
+
+        // 呼叫下一個中介軟體
+        await _next(context);
+    }
+}
+```
+
+**新增中介軟體擴充類別（建議以 `Use` 開頭）：**
+
+```csharp
+public static class RequestCultureMiddlewareExtensions
+{
+    public static IApplicationBuilder UseRequestCulture(this IApplicationBuilder builder)
+    {
+        return builder.UseMiddleware<RequestCultureMiddleware>();
+    }
+}
+```
+
+**在 Startup.cs 中使用：**
+
+```csharp
+public void Configure(IApplicationBuilder app, IWebHostEnvironment env)
+{
+    // ... 其他中介軟體
+    app.UseRequestCulture();
+    // ... 其他中介軟體
+}
+```
+
+### 5.5.3.3 設定更多參數
+
+預設情況下，自訂獨立類別中介軟體建構函式只有一個 `RequestDelegate` 參數，除此之外還可以注入服務介面/類別，另外還支援傳入任何其他類型。
+
+**服務類型參數：**
+
+```csharp
+public class RequestCultureMiddleware
+{
+    private readonly RequestDelegate _next;
+    private readonly ILogger<RequestCultureMiddleware> _logger;
+
+    public RequestCultureMiddleware(RequestDelegate next, ILogger<RequestCultureMiddleware> logger)
+    {
+        _next = next;
+        _logger = logger;
+    }
+
+    public async Task InvokeAsync(HttpContext context)
+    {
+        _logger.LogInformation("...");
+        await _next(context);
+    }
+}
+```
+
+**非服務類型參數**（必須宣告在服務參數之後）：
+
+```csharp
+public class RequestCultureMiddleware
+{
+    private readonly RequestDelegate _next;
+    private readonly ILogger<RequestCultureMiddleware> _logger;
+
+    public RequestCultureMiddleware(RequestDelegate next,
+        ILogger<RequestCultureMiddleware> logger,
+        int age,
+        string name)
+    {
+        _next = next;
+        _logger = logger;
+    }
+
+    public async Task InvokeAsync(HttpContext context)
+    {
+        _logger.LogInformation("...");
+        await _next(context);
+    }
+}
+```
+
+修改中介軟體擴充類別：
+
+```csharp
+public static class RequestCultureMiddlewareExtensions
+{
+    public static IApplicationBuilder UseRequestCulture(this IApplicationBuilder builder, int age, string name)
+    {
+        return builder.UseMiddleware<RequestCultureMiddleware>(new object[] { age, name });
+    }
+}
+```
+
+使用：
+
+```csharp
+app.UseRequestCulture(30, "百小僧");
+```
+
+---
+
+## 5.5.4 中介軟體順序
+
+中介軟體是有執行順序的，而且是先註冊的先執行，無法透過其他方式更改。
+
+---
+
+## 5.5.5 相依性注入/解析服務
+
+中介軟體有兩種方式注入服務：一種是透過建構函式注入，一種是透過 `httpContext.RequestServices` 方式解析。
+
+### 5.5.5.1 建構函式方式
+
+```csharp
+public class RequestCultureMiddleware
+{
+    private readonly RequestDelegate _next;
+    private readonly ILogger<RequestCultureMiddleware> _logger;
+
+    public RequestCultureMiddleware(RequestDelegate next,
+        ILogger<RequestCultureMiddleware> logger,
+        IHostEnvironment hostEnvironment)
+    {
+        _next = next;
+        _logger = logger;
+    }
+
+    public async Task InvokeAsync(HttpContext context)
+    {
+        await _next(context);
+    }
+}
+```
+
+### 5.5.5.2 httpContext.RequestServices 方式
+
+`HttpContext` 提供了 `RequestServices` 屬性方便解析服務：
+
+```csharp
+public class RequestCultureMiddleware
+{
+    private readonly RequestDelegate _next;
+    private readonly ILogger<RequestCultureMiddleware> _logger;
+
+    public RequestCultureMiddleware(RequestDelegate next,
+        ILogger<RequestCultureMiddleware> logger,
+        IHostEnvironment hostEnvironment)
+    {
+        _next = next;
+        _logger = logger;
+    }
+
+    public async Task InvokeAsync(HttpContext context)
+    {
+        // 透過 context.RequestServices 解析
+        var repository = context.RequestServices.GetService<IRepository>();
+
+        await _next(context);
+    }
+}
+```
+
+---
+
+## 5.5.6 刪除特定的 HTTP 回應標頭
+
+預設情況下，Furion 框架會輸出當前的執行環境和 Furion 版本資訊，如無需顯示，可在 `Startup.cs` 中移除：
+
+```csharp
+public void Configure(IApplicationBuilder app, IWebHostEnvironment env)
+{
+    if (env.IsDevelopment())
+    {
+        app.UseDeveloperExceptionPage();
+    }
+
+    app.Use(async (context, next) =>
+    {
+        context.Response.Headers.Remove("furion");
+        context.Response.Headers.Remove("environment");
+
+        await next();
+    });
+
+    // .... 其他程式碼
+}
+```
+
+---
+
+## 5.5.7 常見問題
+
+有時候我們需要在中介軟體中取得終點路由的特性或其他資訊：
+
+```csharp
+// 取得終點路由特性
+var endpointFeature = context.Features.Get<IEndpointFeature>();
+
+// 取得是否定義了特性
+var attribute = endpointFeature?.Endpoint?.Metadata?.GetMetadata<YourAttribute>();
+```
+
+> **注意事項**：要想上面操作有效（不為 `null`），需要滿足以下條件：
+>
+> - 啟用端點路由 `AddControllers()` 而不是 `AddMvc()`
+> - 在 `UseRouting()` 和 `UseEndpoints()` 之間呼叫你的中介軟體

package/knowledge/Furion_Teaching_Manual/05-6-Vue-React-Angular/344/273/213/351/235/242/344/273/243/347/220/206.md

@@ -0,0 +1,317 @@
+# 5.6 Vue/React/Angular 介面代理
+
+> **影片教學**：https://www.bilibili.com/video/BV1EW4y1C71D
+
+---
+
+## 5.6.1 歷史背景
+
+在現在主流的 Web 專案開發中，越來越多的開發者選擇使用 Vue/React/Angular 三大框架進行開發，這三大框架和傳統開發模式最大的不同是前者採用前後端分離的方式。
+
+在前後端分離的模式中，前後端程式設計師各司其職，後端程式負責編寫介面（API），前端程式設計師負責編寫客戶端請求後端介面（API）並進行資料繫結。
+
+但這裡暴露出了一個工作效率極低且易出錯的問題：前端程式需要將後端數百個甚至上千個介面進行一一對應編寫，大多都是採用 `$.ajax` 或 `axios` 的方式。一旦後端介面參數或回傳值發生改變，前端程式設計師需要一一進行勘正。
+
+---
+
+## 5.6.2 如何解決？
+
+Furion 框架編寫的所有後端介面都會產生規範化的 `swagger.json` 檔案，使用該檔案可以在 https://editor.swagger.io 產生任何支援標準 Swagger 的介面或客戶端程式碼。
+
+自此，前端程式設計師再也無需自己手寫 `$.ajax` 和 `axios` 程式碼，這部分程式碼全部自動產生。
+
+---
+
+## 5.6.3 產生客戶端請求程式碼
+
+> **關於 TypeScript 和 JavaScript**：以下教學僅適用於 Vue/React/Angular 的 TypeScript 類型專案，暫不支援 JavaScript。建議使用 TypeScript 進行編寫。
+
+### 5.6.3.1 產生客戶端程式碼
+
+1. 開啟規範化文件（Swagger）首頁，並點擊頂部 `/swagger/xxxx/swagger.json` 到新視窗開啟
+2. 全選並複製全部內容
+3. 開啟 https://editor.swagger.io 官網並貼上進去
+
+> **無法連網**：Furion 也提供了 `Swagger-Editor.rar` 離線包，可直接下載解壓縮並雙擊 `index.html` 即可。
+
+4. 最後點擊頂部的 **Generate Client** 選擇對應的語言/框架進行產生即可
+
+### 5.6.3.2 Vue/React 設定
+
+1. 點擊 **Generate Client** 頂部選單並選擇 `typescript-axios` 進行下載
+2. 下載成功之後拷貝產生的目錄和檔案
+3. 在你的 Vue 或 React 專案的 `src` 目錄下建立 `api-services` 目錄並將剛剛複製的目錄檔案放在裡面
+4. 透過 npm 或 yarn 安裝 `axios` 套件：
+
+```bash
+# npm 方式
+npm i axios@0.21.4
+
+# yarn 方式
+yarn add axios@0.21.4
+```
+
+> ⚠️ **axios 版本說明**：注意 axios 版本必須是 `0.21.4` 版本，如果安裝其他版本可能會出現無法編譯的情況。
+
+5. 下載 Furion 提供的 Vue/React 工具庫 `axios-utils.ts` 並拷貝到和 `api-services` 同級目錄下
+
+> **Vue3 專案不能編譯問題**：如果在 Vue3 專案中無法編譯通過，則需要修改根目錄下的 `tsconfig.app.json`、`tsconfig.vite-config.json` 和 `tsconfig.vitest.json` 檔案並新增下列設定：
+
+```json
+"compilerOptions": {
+    "importsNotUsedAsValues": "remove",
+    "preserveValueImports": false
+    // TypeScript 5.0+ 使用以下設定代替上面兩行
+    // "verbatimModuleSyntax": false
+}
+```
+
+### 5.6.3.3 Angular 設定
+
+1. 點擊 **Generate Client** 頂部選單並選擇 `typescript-angular` 進行下載
+2. 下載成功之後拷貝產生的目錄和檔案
+3. 在你的 Angular 專案的 `src` 目錄下建立 `api-services` 目錄並將剛剛複製的目錄檔案放在裡面
+4. 下載 Furion 提供的 Angular 工具庫 `angular-utils.ts` 並拷貝到和 `api-services` 同級目錄下
+
+> **Angular 專案不能編譯問題**：如果無法編譯通過，需要修改 `api-services/encoder.ts` 檔案，在 `encodeKey` 和 `encodeValue` 前新增 `override`：
+
+```typescript
+// api-services/encoder.ts
+export class CustomHttpUrlEncodingCodec extends HttpUrlEncodingCodec {
+  override encodeKey(k: string): string {
+    k = super.encodeKey(k);
+    return k.replace(/\+/gi, "%2B");
+  }
+  override encodeValue(v: string): string {
+    v = super.encodeValue(v);
+    return v.replace(/\+/gi, "%2B");
+  }
+}
+```
+
+5. 在 `src/app/app.module.ts` 中註冊 `ServeModule`：
+
+```typescript
+import { NgModule } from "@angular/core";
+import { BrowserModule } from "@angular/platform-browser";
+import { AppRoutingModule } from "./app-routing.module";
+import { AppComponent } from "./app.component";
+import { ServeModule } from "src/angular-utils";
+
+@NgModule({
+  declarations: [AppComponent],
+  imports: [
+    BrowserModule,
+    AppRoutingModule,
+    ServeModule, // 註冊代理服務模組
+  ],
+  providers: [],
+  bootstrap: [AppComponent],
+})
+export class AppModule {}
+```
+
+---
+
+## 5.6.4 初始設定
+
+完成上面步驟之後還需要最後一步：修改伺服端（後端）介面（API）位址。
+
+### 5.6.4.1 Vue/React 設定
+
+編輯 `axios-utils.ts` 檔案，將 `serveConfig` 修改為對應的後端位址：
+
+```typescript
+import globalAxios, { AxiosInstance } from "axios";
+import { Configuration } from "./api-services";
+import { BaseAPI, BASE_PATH } from "./api-services/base";
+
+export const serveConfig = new Configuration({
+  basePath:
+    process.env.NODE_ENV !== "production"
+      ? "https://localhost:44342"  // 開發環境伺服器介面位址
+      : "https://furion.net",      // 生產環境伺服器介面位址
+});
+```
+
+### 5.6.4.2 Angular 設定
+
+編輯 `angular-utils.ts` 檔案，將 `serveConfig` 修改為對應的後端位址：
+
+```typescript
+import { environment } from "./environments/environment";
+
+export const serveConfig = new Configuration({
+  basePath: !environment.production
+    ? "https://localhost:44316"  // 開發環境伺服器介面位址
+    : "https://furion.net",      // 生產環境伺服器介面位址
+});
+```
+
+---
+
+## 5.6.5 基本使用
+
+### 5.6.5.1 Vue/React 中使用
+
+在 Vue/React 中使用有兩種方式：Promise 和 async/await，推薦使用後者。
+
+**Promise 方式：**
+
+```typescript
+import { getAPI } from "../axios-utils";
+
+getAPI(SystemAPI)
+  .apiGetXXXX()
+  .then((res) => {
+    var data = res.data.data!;
+  })
+  .catch((err) => {
+    console.log(err);
+  })
+  .finally(() => {
+    console.log("api request completed.");
+  });
+```
+
+**async/await 方式：**
+
+```typescript
+import { getAPI, feature } from "../axios-utils";
+
+const [err, res] = await feature(getAPI(SystemAPI).apiGetXXX());
+
+if (err) {
+  console.log(err);
+} else {
+  var data = res.data.data!;
+}
+
+console.log("api request completed.");
+```
+
+> **關於檔案串流下載**：對於檔案串流下載可能存在下載檔案過大的情況，需要新增 `options` 參數 `responseType: "blob"`：
+
+```typescript
+getAPI(SystemAPI, { responseType: "blob" }).apiGetXXX();
+```
+
+### 5.6.5.2 Angular 中使用
+
+在 Angular 專案中，透過建構函式注入對應的服務即可：
+
+```typescript
+import { Component } from "@angular/core";
+import { PersonService } from "src/api-services";
+
+@Component({
+  selector: "app-root",
+  templateUrl: "./app.component.html",
+  styleUrls: ["./app.component.css"],
+})
+export class AppComponent {
+  title = "angulars";
+
+  constructor(private personService: PersonService) {}
+
+  ngOnInit(): void {
+    this.personService.apiPersonAllGet().subscribe({
+      next: (res) => {
+        console.log(res);
+      },
+      error: (err) => {
+        // 請求失敗
+      },
+      complete: () => {
+        // 請求完成
+      },
+    });
+  }
+}
+```
+
+---
+
+## 5.6.6 重新產生程式碼
+
+如果後端介面（API）發生改變，只需要刪除 `api-services` 下所有目錄檔案並重新產生複製進去即可。
+
+> **關於 Angular 專案**：可以保留 `api-services/encoder.ts` 檔案並刪除其他目錄檔案，新產生的目錄檔案無需複製 `encoder.ts`，這樣可以避免每次修改。
+
+---
+
+## 5.6.7 Swagger 多分組產生
+
+在很多大型系統中，為了方便對介面進行歸類，往往使用了 Swagger 多分組功能，這樣會使系統的介面散落在多個 `swagger.json` 中。
+
+這個時候，需要在後端規範化文件中啟用多分組設定：
+
+```json
+{
+  "SpecificationDocumentSettings": {
+    "EnableAllGroups": true
+  }
+}
+```
+
+啟用設定之後在 Swagger 導覽列頂部下拉分組將出現 **All Groups** 選項，使用這個 All Groups 的 `swagger.json` 進行產生。
+
+---
+
+## 5.6.8 自訂產生前端方法名
+
+> **版本說明**：僅限 Furion 4.1.7+ 版本使用。
+
+透過 `[OperationId]` 來設定產生的前端名稱：
+
+```csharp
+using Furion.SpecificationDocument;
+
+public class PersonDto
+{
+    [OperationId(nameof(TestMethod))]
+    public string TestMethod()
+    {
+        // ...
+    }
+}
+```
+
+---
+
+## 5.6.9 框架客戶端工具庫介紹
+
+`axios-utils.ts` 和 `angular-utils.ts` 是 Furion 框架專門針對 Furion 開發的 WebAPI 專案編寫的客戶端代理庫，在這個代理庫中已經處理了跨域、授權、自動重新整理 Token 以及解密客戶端 JWT Token 問題。
+
+同時提供了非常方便的 `feature` 方法，可將非同步方法進行同步化處理。
+
+---
+
+## 5.6.10 處理 GET 請求 Url 位址陣列參數
+
+預設情況下，axios 會將陣列類型的 Url 參數透過 `,` 逗號傳遞（如 `https://furion.net?arr=1,2,3`），但後端通常支援的格式為 `https://furion.net?arr[0]=1&arr[1]=2&arr[2]=3`。
+
+透過安裝 `qs` 套件並設定 `paramsSerializer` 即可：
+
+```bash
+npm install qs
+```
+
+```typescript
+// 頂部位置
+import qs from 'qs';
+
+// 設定 axios
+axiosInstance.defaults.timeout = 1000 * 60 * 10; // 設定逾時，預設 10 分鐘
+axiosInstance.defaults.paramsSerializer = (params) => qs.stringify(params);
+```
+
+---
+
+## 5.6.11 無法連線外網/內網情況/離線包
+
+在一些比較注重程式碼安全的組織或公司中，可能不能連線外網進行產生，這個時候只需要下載 https://github.com/swagger-api/swagger-editor 程式碼在本地部署即可。
+
+Furion 官網也提供了離線包下載：https://gitee.com/dotnetchina/Furion/blob/v4/clients/Swagger-Editor.rar
+
+下載離線包後直接雙擊 `index.html` 啟動即可。