From 6b15dbf0f50822b92fb325f8cdfcc7f646233047 Mon Sep 17 00:00:00 2001 From: feijie Date: Tue, 10 Dec 2024 20:57:08 +0800 Subject: [PATCH] =?UTF-8?q?feat(docs):=20=E6=B7=BB=E5=8A=A0Wrapper?= =?UTF-8?q?=E6=A8=A1=E5=9D=97=E6=96=87=E6=A1=A3?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit --- .../common/LINGYUN.Abp.Wrapper/README.EN.md | 105 ++++++++++++++++++ .../common/LINGYUN.Abp.Wrapper/README.md | 84 ++++++++++++-- 2 files changed, 180 insertions(+), 9 deletions(-) create mode 100644 aspnet-core/framework/common/LINGYUN.Abp.Wrapper/README.EN.md diff --git a/aspnet-core/framework/common/LINGYUN.Abp.Wrapper/README.EN.md b/aspnet-core/framework/common/LINGYUN.Abp.Wrapper/README.EN.md new file mode 100644 index 000000000..1196d1bf1 --- /dev/null +++ b/aspnet-core/framework/common/LINGYUN.Abp.Wrapper/README.EN.md @@ -0,0 +1,105 @@ +# LINGYUN.Abp.Wrapper + +A wrapper module for unifying API response results and exception handling. + +## Features + +* Unified response result wrapping +* Flexible exception handling mechanism +* Support for multiple ignore strategies +* Configurable empty result handling +* Custom exception handlers + +## Installation + +```bash +dotnet add package LINGYUN.Abp.Wrapper +``` + +## Configuration + +```csharp +[DependsOn(typeof(AbpWrapperModule))] +public class YouProjectModule : AbpModule +{ + public override void ConfigureServices(ServiceConfigurationContext context) + { + Configure(options => + { + // Enable wrapper + options.IsEnabled = true; + + // Custom error code for unhandled exceptions + options.CodeWithUnhandled = "500"; + + // Ignore specific URL prefixes + options.IgnorePrefixUrls.Add("/api/health"); + + // Add custom exception handler + options.AddHandler(new CustomExceptionHandler()); + }); + } +} +``` + +## Configuration Options + +* `AbpWrapperOptions.IsEnabled` - Whether to wrap return results, default: false +* `AbpWrapperOptions.CodeWithUnhandled` - Error code for unhandled exceptions, default: 500 +* `AbpWrapperOptions.CodeWithSuccess` - Success code for successful operations, default: 0 +* `AbpWrapperOptions.ErrorWithEmptyResult` - Whether to return error message when resource is empty, default: false +* `AbpWrapperOptions.HttpStatusCode` - Http response code after wrapping, default: 200 +* `AbpWrapperOptions.CodeWithEmptyResult` - Error code when returning empty object, default: 404 +* `AbpWrapperOptions.MessageWithEmptyResult` - Error message when returning empty object, default: Not Found + +* `AbpWrapperOptions.IgnorePrefixUrls` - Specify which URL prefixes to ignore +* `AbpWrapperOptions.IgnoreNamespaces` - Specify which namespaces to ignore +* `AbpWrapperOptions.IgnoreControllers` - Specify which controllers to ignore +* `AbpWrapperOptions.IgnoreReturnTypes` - Specify which return types to ignore +* `AbpWrapperOptions.IgnoreExceptions` - Specify which exception types to ignore +* `AbpWrapperOptions.IgnoredInterfaces` - Specify which interfaces to ignore (by default, implements **IWrapDisabled** interface will not be processed) + +## Usage Examples + +### 1. Basic Usage + +```csharp +public class TestController : AbpController +{ + public async Task> GetAsync() + { + return new WrapResult("0", "Hello World"); + } +} +``` + +### 2. Ignore Wrapping + +```csharp +[IgnoreWrapResult] +public class HealthController : AbpController +{ + public async Task GetAsync() + { + return "OK"; + } +} +``` + +### 3. Custom Exception Handler + +```csharp +public class CustomExceptionHandler : IExceptionWrapHandler +{ + public void Wrap(ExceptionWrapContext context) + { + context.WithCode("CUSTOM_ERROR") + .WithMessage("Custom exception occurred") + .WithDetails(context.Exception.Message); + } +} +``` + +## Links + +* [中文文档](./README.md) diff --git a/aspnet-core/framework/common/LINGYUN.Abp.Wrapper/README.md b/aspnet-core/framework/common/LINGYUN.Abp.Wrapper/README.md index 98c0e2aae..f90816cfd 100644 --- a/aspnet-core/framework/common/LINGYUN.Abp.Wrapper/README.md +++ b/aspnet-core/framework/common/LINGYUN.Abp.Wrapper/README.md @@ -1,6 +1,20 @@ # LINGYUN.Abp.Wrapper -包装器模块 +包装器模块，用于统一包装API返回结果和异常处理。 + +## 功能 + +* 统一的返回结果包装 +* 灵活的异常处理机制 +* 支持多种忽略策略 +* 可配置的空结果处理 +* 自定义异常处理器 + +## 安装 + +```bash +dotnet add package LINGYUN.Abp.Wrapper +``` ## 配置使用 @@ -8,16 +22,26 @@ [DependsOn(typeof(AbpWrapperModule))] public class YouProjectModule : AbpModule { - public override void ConfigureServices(ServiceConfigurationContext context) - { - Configure(options => - { - // 启用包装器 - options.IsEnabled = true; + public override void ConfigureServices(ServiceConfigurationContext context) + { + Configure(options => + { + // 启用包装器 + options.IsEnabled = true; + + // 自定义未处理异常的错误代码 + options.CodeWithUnhandled = "500"; + + // 忽略特定前缀的URL + options.IgnorePrefixUrls.Add("/api/health"); + + // 添加自定义异常处理器 + options.AddHandler(new CustomExceptionHandler()); }); - } + } } ``` + ## 配置项说明 * AbpWrapperOptions.IsEnabled 是否包装返回结果,默认: false @@ -36,5 +60,47 @@ public class YouProjectModule : AbpModule * AbpWrapperOptions.IgnoredInterfaces 指定哪些接口不需要处理（默认实现**IWrapDisabled**接口不进行处理） -## 其他 +## 使用示例 + +### 1. 基本使用 + +```csharp +public class TestController : AbpController +{ + public async Task> GetAsync() + { + return new WrapResult("0", "Hello World"); + } +} +``` + +### 2. 忽略包装 + +```csharp +[IgnoreWrapResult] +public class HealthController : AbpController +{ + public async Task GetAsync() + { + return "OK"; + } +} +``` + +### 3. 自定义异常处理 + +```csharp +public class CustomExceptionHandler : IExceptionWrapHandler +{ + public void Wrap(ExceptionWrapContext context) + { + context.WithCode("CUSTOM_ERROR") + .WithMessage("发生自定义异常") + .WithDetails(context.Exception.Message); + } +} +``` + +## 链接 +* [English document](./README.EN.md)