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

package/knowledge/Furion_Teaching_Manual/06-2/347/254/254/344/270/211/346/226/271API_Scalar.md

@@ -0,0 +1,91 @@
+---
+title: "导语"
+author: "dotNET China"
+source: "https://gitee.com/dotnetchina/Furion/commit/02ba49cd3c84b13d3fc152fd1ceb084c07680029#note_49016014"
+platform: "web"
+extracted_at: "2026-03-17T07:37:35.976Z"
+created: 2026-03-17T07:37:35.976Z
+modified: 2026-03-17T07:37:35.976Z
+tags: ["converted", "document", "web-extract"]
+word_count: 1961
+source_type: "html"
+---
+
+**来源**：https://gitee.com/dotnetchina/Furion/commit/02ba49cd3c84b13d3fc152fd1ceb084c07680029#note_49016014
+**作者**：dotNET China
+
+---
+
+## 导语
+
+一直以来，`Furion` 默认内置的接口文档组件为 `Swagger`，这也是框架唯一的第三方依赖。许多开发者曾尝试替换为 `Knife4jUI`，但体验仍不够理想。为此，**`Furion` 现已提供对新一代现代化文档工具 `Scalar` 的开箱支持，带来更优雅、更直观的 API 文档体验。**
+
+## 快速集成 Scalar 文档
+
+[![Scalar 界面截图](https://foruda.gitee.com/images/1768500455893653516/a2887772_974299.png "Scalar 界面")](https://foruda.gitee.com/images/1768500455893653516/a2887772_974299.png)
+
+### 集成步骤
+
+#### 1. 安装 NuGet 包
+
+在项目文件中添加 `Scalar.AspNetCore` 包引用：
+
+```
+<ItemGroup>
+  <PackageReference Include="Scalar.AspNetCore" Version="2.12.8" />
+</ItemGroup>
+```
+
+#### 2. 配置中间件
+
+在 `Startup.cs` 或对应程序入口中，加入 `Scalar` 的映射配置：
+
+```
+app.UseInject();
+
+
+
+**app.UseEndpoints(endpoints =>**
+- {
+- endpoints.MapScalarApiReference(options =>
+- {
+- // options.WithTitle("项目 API 文档"); // 可自定义标题
+
+
+        // 自动映射所有已配置的 OpenAPI 分组
+        foreach (var groupInfo in SpecificationDocumentBuilder.GetOpenApiGroups())
+
+
+**{**
+- options.AddDocument(
+- groupInfo.Group,
+- groupInfo.Title,
+- groupInfo.RouteTemplate
+- );
+- }
+- });
+- });
+
+```
+
+#### 3. 启动访问
+
+运行项目后，通过以下地址即可访问 Scalar 文档界面：
+
+> **入口地址**：`/scalar`
+
+[![访问入口](https://foruda.gitee.com/images/1768500620064987747/c9e783eb_974299.png "入口截图")](https://foruda.gitee.com/images/1768500620064987747/c9e783eb_974299.png)  
+[![文档界面](https://foruda.gitee.com/images/1768500663810888333/e4d9a4aa_974299.png "文档示例")](https://foruda.gitee.com/images/1768500663810888333/e4d9a4aa_974299.png)
+
+---
+
+### 更多资源
+
+- Scalar 官方集成文档：[https://scalar.com/products/api-references/integrations/aspnetcore/integration](https://gitee.com/link?target=https%3A%2F%2Fscalar.com%2Fproducts%2Fapi-references%2Fintegrations%2Faspnetcore%2Fintegration)
+- Furion 框架文档：[查看完整指南](https://gitee.com/link?target=https%3A%2F%2Ffurion.net%2F)
+
+[![Furion 文档截图](https://foruda.gitee.com/images/1768501430444373270/62ec5790_974299.png "Furion 文档")](https://foruda.gitee.com/images/1768501430444373270/62ec5790_974299.png)
+
+---
+
+**说明**：本次集成保留了 Furion 原有的 OpenAPI 分组配置机制，仅替换了文档渲染层。开发者无需修改原有接口定义或注解，即可获得更现代的交互式文档体验。

package/knowledge/Furion_Teaching_Manual/07-/345/217/213/345/245/275/344/276/213/345/244/226/350/231/225/347/220/206.md

@@ -0,0 +1,511 @@
+# 7. 友好例外處理
+
+## 7.1 什麼是例外
+
+例外一般是指執行期（此處特指 `Exception` 類別）會發生的導致程式意外中止的問題，是一種對問題的描述後的封裝物件。
+
+在過去開發中，通常例外由系統執行時出錯拋出，但現在的開發過程中，我們應在程式開發中合理地拋出例外，比如更新一條不存在的實體，或查詢一個不存在的資料等等。
+
+---
+
+## 7.2 處理例外方式
+
+- 不處理，直接中斷程式執行（不推薦）
+- 透過 `try catch finally` 處理（不推薦）
+- 全域統一處理，並記錄例外資訊（推薦）
+- 例外註解方式處理，支援本地化（推薦）
+
+---
+
+## 7.3 什麼是友好例外處理
+
+### 7.3.1 非友好例外處理
+
+- 對終端使用者拋出 500 狀態碼堆疊資訊
+- 大量的 `try catch` 程式碼，污染正常業務邏輯
+- 沒有規範化的例外狀態碼和例外訊息管理
+- 沒有例外日誌收集記錄
+- 不支援例外訊息本地化處理
+- 不支援例外策略，失敗後程式立即終止
+- 不支援分散式交易 CAP
+- 不支援例外傳播
+- 回傳的例外格式雜亂
+
+### 7.3.2 友好例外處理
+
+- 對終端使用者提示友好
+- 對後端開發人員提供詳細的例外堆疊
+- 不干擾正常業務邏輯程式碼（沒有 `try catch`）
+- 支援例外狀態碼多方設定
+- 支援例外訊息本地化
+- 例外資訊統一設定管理
+- 支援例外策略，如重試
+- 支援例外日誌收集記錄
+- 支援 CAP 分散式交易關聯
+- 支援內部例外外部傳播
+- 支援回傳統一的例外格式資料
+
+---
+
+## 7.4 友好例外處理使用示例
+
+> **小提示**：`.AddFriendlyException()` 預設已經整合在 `AddInject()` 中了，無需再次註冊。
+
+### 7.4.1 註冊友好例外服務
+
+```csharp
+// Furion.Web.Core\FurWebCoreStartup.cs
+using Microsoft.Extensions.DependencyInjection;
+
+namespace Furion.Web.Core
+{
+    [AppStartup(800)]
+    public sealed class FurWebCoreStartup : AppStartup
+    {
+        public void ConfigureServices(IServiceCollection services)
+        {
+            services.AddControllers()
+                    .AddFriendlyException();
+        }
+    }
+}
+```
+
+> ⚠️ `.AddFriendlyException()` 需在 `services.AddControllers()` 之後註冊。
+
+### 7.4.2 兩個例子
+
+**簡單拋個例外：**
+
+```csharp
+using Furion.DynamicApiController;
+using Furion.FriendlyException;
+
+namespace Furion.Application
+{
+    public class FurionAppService : IDynamicApiController
+    {
+        public int Get(int id)
+        {
+            if (id < 3)
+            {
+                throw Oops.Oh($"{id} 不能小於3");
+            }
+            return id;
+        }
+    }
+}
+```
+
+**拋出特定類型例外：**
+
+```csharp
+public int Get(int id)
+{
+    if (id < 3)
+    {
+        throw Oops.Oh($"{id} 不能小於3。", typeof(InvalidOperationException));
+    }
+    return id;
+}
+```
+
+---
+
+## 7.5 關於 Oops.Oh
+
+`Oops.Oh(errorMessage)` 可以結合 `throw` 拋出例外。`Oops.Oh(...)` 方法回傳的正是 `Exception` 實例。
+
+> **為什麼起這個名字？** 來源於英語句子 "Oh, Oops!"，意思是「噢（哎），出錯了！」。
+
+### 7.5.2 Oops.Oh 多載方法
+
+```csharp
+public static class Oops
+{
+    // 拋出字串例外
+    public static Exception Oh(string errorMessage, params object[] args);
+
+    // 拋出字串例外（指定例外類型）
+    public static Exception Oh(string errorMessage, Type exceptionType, params object[] args);
+
+    // 拋出錯誤碼例外
+    public static Exception Oh(object errorCode, params object[] args);
+
+    // 拋出錯誤碼例外（指定例外類型）
+    public static Exception Oh(object errorCode, Type exceptionType, params object[] args);
+}
+```
+
+---
+
+## 7.6 最佳實踐 🤗
+
+### 7.6.1 建立例外資訊類型
+
+實現自訂例外資訊類型必須遵循以下設定：
+
+- 類型必須是公開且是 `Enum` 列舉類型
+- 列舉類型必須貼有 `[ErrorCodeType]` 特性
+- 列舉中每一項必須貼有 `[ErrorCodeItemMetadata]` 特性
+
+```csharp
+using Furion.FriendlyException;
+
+namespace Furion.Application
+{
+    [ErrorCodeType]
+    public enum ErrorCodes
+    {
+        [ErrorCodeItemMetadata("{0} 不能小於 {1}")]
+        z1000,
+
+        [ErrorCodeItemMetadata("資料不存在")]
+        x1000,
+
+        [ErrorCodeItemMetadata("{0} 發現 {1} 個例外", "百小僧", 2)]
+        x1001,
+
+        [ErrorCodeItemMetadata("伺服器執行例外", ErrorCode = "Error")]
+        SERVER_ERROR
+    }
+}
+```
+
+**巢狀錯誤訊息類型定義（Furion 4.9.7.120+）：**
+
+```csharp
+using Furion.FriendlyException;
+
+namespace Furion.Application;
+
+[ErrorCodeType(IncludeNestedTypes = true)]
+public class ErrorCodes
+{
+    public enum User
+    {
+        [ErrorCodeItemMetadata("{0} 不能小於 {1}")]
+        z1000,
+
+        [ErrorCodeItemMetadata("資料不存在")]
+        x1000,
+    }
+
+    public enum System
+    {
+        // ...
+    }
+}
+```
+
+### 7.6.2 關於 [ErrorCodeItemMetadata]
+
+`[ErrorCodeItemMetadata]` 特性用來標識列舉欄位例外中繼資料，支援傳入**訊息內容**和**格式化參數**。最終會使用 `String.Format(訊息內容, 格式化參數)` 進行格式化。
+
+如果訊息內容中包含格式化佔位符但未指定格式化參數，那麼會查找例外所在方法是否貼有 `[IfException]` 特性且含有格式化參數，接著查找 `Oops.Oh` 中指定的格式化參數。
+
+### 7.6.3 靜態例外類別使用
+
+```csharp
+public int Get(int id)
+{
+    if (id < 3)
+    {
+        throw Oops.Oh(ErrorCodes.z1000, id, 3);
+        // throw Oops.Oh(ErrorCodes.User.z1000, id, 3); // Furion 4.9.7.120+ 支援巢狀類型
+    }
+    return id;
+}
+```
+
+### 7.6.4 例外方法重試
+
+> **調整說明**：v2.17.0+ 版本請使用 `Retry.Invoke()` 替代。
+
+```csharp
+Oops.Retry(() => {
+    // Do.....
+}, 3, 1000);
+
+// 帶回傳值
+var value = Oops.Retry<int>(() => {
+    // Do.....
+}, 3, 1000);
+
+// 只有特定例外才監聽
+Oops.Retry(() => {
+    // ...
+}, 3, 1000, typeof(ArgumentNullException));
+```
+
+### 7.6.5 更多例子
+
+```csharp
+throw Oops.Oh(1000);
+throw Oops.Oh(ErrorCodes.x1000);
+throw Oops.Oh("哈哈哈哈");
+throw Oops.Oh(errorCode: "x1001");
+throw Oops.Oh(1000, typeof(Exception));
+throw Oops.Oh(1000).StatusCode(400);           // 設定錯誤碼
+throw Oops.Oh(1000).WithData(new Model {});     // 設定額外資料
+throw Oops.Bah("使用者名稱或密碼錯誤");           // 拋出業務例外，狀態碼為 400
+throw Oops.Bah(1000);
+```
+
+---
+
+## 7.7 多個例外資訊類型
+
+```csharp
+[ErrorCodeType]
+public enum ErrorCodes
+{
+    [ErrorCodeItemMetadata("{0} 不能小於 {1}")]
+    z1000,
+
+    [ErrorCodeItemMetadata("資料不存在")]
+    x1000,
+}
+
+[ErrorCodeType]
+public enum UserErrorCodes
+{
+    [ErrorCodeItemMetadata("使用者資料不存在")]
+    u1000,
+
+    [ErrorCodeItemMetadata("其他例外")]
+    u1001
+}
+```
+
+> ⚠️ 多個例外靜態類別中也必須保證常數值唯一性，不可重複。
+
+---
+
+## 7.8 IErrorCodeTypeProvider 提供器
+
+在不能貼 `[ErrorCodeType]` 特性的情況下使用：
+
+```csharp
+using Furion.FriendlyException;
+using System;
+
+namespace Furion.Application
+{
+    public class CustomErrorCodeTypeProvider : IErrorCodeTypeProvider
+    {
+        public Type[] Definitions => new[] {
+            typeof(ErrorCodes),
+            typeof(ErrorCodes2)
+        };
+    }
+}
+```
+
+啟用：
+
+```csharp
+services.AddControllers()
+        .AddFriendlyException<CustomErrorCodeTypeProvider>();
+```
+
+> **小知識**：只有使用 `IErrorCodeTypeProvider` 方式才需使用泛型方式註冊。透過上面的方式註冊可以同時支援 `IErrorCodeTypeProvider` 和 `[ErrorCodeType]` 方式。
+
+---
+
+## 7.9 appsettings.json 中設定
+
+```json
+{
+  "ErrorCodeMessageSettings": {
+    "Definitions": [
+      ["5000", "{0} 不能小於 {1}"],
+      ["5001", "我叫 {0} 名字", "百小僧"],
+      ["5002", "Oops! 出錯了"]
+    ]
+  }
+}
+```
+
+`Definitions` 類型為二維陣列，每個陣列的第一個參數為 `ErrorCode` 錯誤碼，第二個參數為 `ErrorMessage` 訊息內容，剩餘參數作為 `ErrorMessage` 的格式化參數。
+
+使用示例：
+
+```csharp
+public int Get(int id)
+{
+    if (id < 3)
+    {
+        throw Oops.Oh(5000, id, 3);
+    }
+    return id;
+}
+```
+
+> **小知識**：`[ErrorCodeType]`、`IErrorCodeTypeProvider` 和 `appsettings.json` 可以同時使用。
+
+---
+
+## 7.10 [IfException] 使用
+
+`[IfException]` 特性可以覆蓋預設訊息設定，也就是覆蓋例外訊息類型和 `appsettings.json` 中的設定。
+
+> ⚠️ `[IfException]` 只能貼在方法上，支援多個。
+
+### 7.10.1 使用示例
+
+```csharp
+[IfException(ErrorCodes.z1000, ErrorMessage = "我覆蓋了預設的：{0} 不能小於 {1}")]
+public int Get(int id)
+{
+    if (id < 3)
+    {
+        throw Oops.Oh(ErrorCodes.z1000, id, 3);
+    }
+    return id;
+}
+```
+
+### 7.10.2 更多例子
+
+```csharp
+[IfException(typeof(ExceptionType), ErrorMessage = "特定例外類型全域攔截")]
+[IfException(ErrorMessage = "全域例外攔截")]
+[IfException(ErrorCodes.z1000, ErrorMessage = "我覆蓋了預設的：{0} 不能小於 {1}")]
+[IfException(ErrorCodes.x1001, "格式化參數1", "格式化參數2", ErrorMessage = "我覆蓋了預設的：{0} 不能小於 {1}")]
+[IfException(ErrorCodes.x1000, "格式化參數1", "格式化參數2")]
+[IfException(ErrorCodes.SERVER_ERROR, "格式化參數1", "格式化參數2")]
+public int Get(int id)
+{
+    if (id < 3)
+    {
+        throw Oops.Oh(ErrorCodes.z1000, id, 3);
+    }
+    return id;
+}
+```
+
+> **格式化流程**：如果訊息內容中包含格式化佔位符但未指定格式化參數，那麼會查找例外所在方法是否貼有 `[IfException]` 特性且含有格式化參數，接著查找 `Oops.Oh` 中指定的格式化參數。
+
+---
+
+## 7.11 例外訊息優先順序
+
+```
+[ErrorCodeItemMetadata] → appsettings.json → [IfException]（低 → 高）
+```
+
+- `[IfException]` 會覆蓋 `appsettings.json` 定義的狀態碼訊息
+- `appsettings.json` 會覆蓋 `[ErrorCodeItemMetadata]` 定義的訊息
+
+---
+
+## 7.12 多語言支援
+
+參見【全球化和本地化（多語言）】章節。
+
+---
+
+## 7.13 規範化結果例外處理
+
+如需自訂規範化結果可查閱【6.7 統一回傳值模型】。
+
+---
+
+## 7.14 全域例外處理提供器
+
+通常我們需要在例外捕獲的時候寫日誌，這時候就需要使用到 `IGlobalExceptionHandler`：
+
+```csharp
+using Furion.DependencyInjection;
+using Furion.FriendlyException;
+using Microsoft.AspNetCore.Mvc.Filters;
+using System.Threading.Tasks;
+
+namespace Furion.Application
+{
+    public class LogExceptionHandler : IGlobalExceptionHandler, ISingleton
+    {
+        public Task OnExceptionAsync(ExceptionContext context)
+        {
+            // 寫日誌
+            return Task.CompletedTask;
+        }
+    }
+}
+```
+
+---
+
+## 7.15 FriendlyExceptionSettings 設定
+
+| 設定項 | 類型 | 預設值 | 說明 |
+|--------|------|--------|------|
+| `HideErrorCode` | bool | `false` | 隱藏錯誤碼 |
+| `DefaultErrorCode` | string | — | 預設錯誤碼 |
+| `DefaultErrorMessage` | string | — | 預設錯誤訊息 |
+| `ThrowBah` | bool | `false` | 是否將 `Oops.Oh` 預設拋出為業務例外（設定 `true` 後進入 `OnValidateFailed` 處理） |
+| `LogError` | bool | `true` | 是否輸出例外日誌 |
+
+設定範例：
+
+```json
+{
+  "FriendlyExceptionSettings": {
+    "DefaultErrorMessage": "系統例外，請聯繫管理員"
+  }
+}
+```
+
+---
+
+## 7.16 BadPageResult 錯誤頁
+
+> **版本說明**：僅限 Furion 3.6.1+ 版本使用。
+
+Furion 內建了 `BadPageResult` 錯誤結果類型，該類型衍生自 `IActionResult`：
+
+```csharp
+using Furion.FriendlyException;
+
+public IActionResult Add(Person person)
+{
+    if (!ModelState.IsValid)
+    {
+        return new BadPageResult();
+    }
+}
+```
+
+**BadPageResult 實例屬性和方法：**
+
+| 屬性/方法 | 說明 |
+|-----------|------|
+| 建構函式 `statusCode` | 狀態碼，int 類型，預設 400 |
+| `Title` | 頁面標題 |
+| `Description` | 頁面描述 |
+| `Code` | 詳細錯誤程式碼，支援程式碼 |
+| `CodeLang` | 詳細錯誤程式碼語言，預設 `json` |
+| `Base64Icon` | 頁面圖示，必須是 base64 格式 |
+| `ToString()` | 將物件轉換成 HTML 字串 |
+| `ToByteArray()` | 將物件轉換成 `byte[]` 陣列 |
+
+**BadPageResult 靜態屬性：**
+
+- `Status401Unauthorized`：輸出 401 狀態碼檢視結果
+- `Status403Forbidden`：輸出 403 狀態碼檢視結果
+- `Status404NotFound`：輸出 404 狀態碼檢視結果
+- `Status500InternalServerError`：輸出 500 狀態碼檢視結果
+
+---
+
+## 7.17 取得錯誤碼訊息
+
+> **版本說明**：僅限 Furion 4.9.1.18+ 版本使用。
+
+```csharp
+var errorMessage = Oops.Text(1000);         // => [1000] 錯誤訊息
+
+// 設定第二個參數 hideErrorCode: true 可以隱藏錯誤碼
+var errorMessage = Oops.Text(1000, true);   // => 錯誤訊息
+```