Browse Source

feat(docs): 添加Wrapper模块文档

pull/1049/head
feijie 1 year ago
parent
commit
6b15dbf0f5
  1. 105
      aspnet-core/framework/common/LINGYUN.Abp.Wrapper/README.EN.md
  2. 70
      aspnet-core/framework/common/LINGYUN.Abp.Wrapper/README.md

105
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<AbpWrapperOptions>(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<CustomException>(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<WrapResult<string>> GetAsync()
{
return new WrapResult<string>("0", "Hello World");
}
}
```
### 2. Ignore Wrapping
```csharp
[IgnoreWrapResult]
public class HealthController : AbpController
{
public async Task<string> 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)

70
aspnet-core/framework/common/LINGYUN.Abp.Wrapper/README.md

@ -1,6 +1,20 @@
# LINGYUN.Abp.Wrapper
包装器模块
包装器模块,用于统一包装API返回结果和异常处理。
## 功能
* 统一的返回结果包装
* 灵活的异常处理机制
* 支持多种忽略策略
* 可配置的空结果处理
* 自定义异常处理器
## 安装
```bash
dotnet add package LINGYUN.Abp.Wrapper
```
## 配置使用
@ -14,10 +28,20 @@ public class YouProjectModule : AbpModule
{
// 启用包装器
options.IsEnabled = true;
// 自定义未处理异常的错误代码
options.CodeWithUnhandled = "500";
// 忽略特定前缀的URL
options.IgnorePrefixUrls.Add("/api/health");
// 添加自定义异常处理器
options.AddHandler<CustomException>(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<WrapResult<string>> GetAsync()
{
return new WrapResult<string>("0", "Hello World");
}
}
```
### 2. 忽略包装
```csharp
[IgnoreWrapResult]
public class HealthController : AbpController
{
public async Task<string> 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)

Loading…
Cancel
Save