Furion.Pure 统一结果处理

统一结果处理一、核心功能统一结果处理是 Furion.Pure 框架提供的规范化响应机制确保所有 API 返回统一格式的结果便于前端统一处理。1.1 核心价值统一响应格式所有 API 返回相同结构的数据自动包装无需手动构建响应对象异常处理统一处理异常并返回标准化错误信息可扩展性支持自定义响应格式二、响应格式2.1 RESTful 风格结果集框架默认使用RESTfulResultT作为响应格式publicclassRESTfulResultT{/// summary/// 状态码/// /summarypublicint?StatusCode{get;set;}/// summary/// 数据/// /summarypublicTData{get;set;}/// summary/// 执行成功/// /summarypublicboolSucceeded{get;set;}/// summary/// 错误信息/// /summarypublicobjectErrors{get;set;}/// summary/// 附加数据/// /summarypublicobjectExtras{get;set;}/// summary/// 时间戳/// /summarypubliclongTimestamp{get;set;}}2.2 响应示例成功响应{statusCode:200,data:{id:1,name:张三},succeeded:true,errors:null,extras:null,timestamp:1784192847000}失败响应{statusCode:400,data:null,succeeded:false,errors:参数校验失败,extras:null,timestamp:1784192847000}三、实现流程3.1 服务注册在Startup.cs中调用services.AddControllers().AddUnifyResult();注册逻辑步骤操作说明1添加配置选项注册UnifyResultSettingsOptions2启用统一结果设置UnifyContext.EnabledUnifyHandler true3添加规范化提供器注册RESTfulResultProvider4添加成功筛选器注册SucceededUnifyResultFilter3.2 结果包装机制框架通过 MVC 筛选器自动包装响应结果┌─────────────────────────────────────────────────────────────┐ │ 请求处理流程 │ ├─────────────────────────────────────────────────────────────┤ │ 1. 控制器方法执行 │ │ └── 返回业务数据 │ ├─────────────────────────────────────────────────────────────┤ │ 2. SucceededUnifyResultFilter 执行 │ │ └── 将返回值包装为 RESTfulResultT │ ├─────────────────────────────────────────────────────────────┤ │ 3. 序列化输出 │ │ └── 返回统一格式的 JSON 响应 │ └─────────────────────────────────────────────────────────────┘3.3 异常处理框架通过中间件统一处理异常// UnifyResultStatusCodesMiddlewarepublicasyncTaskInvokeAsync(HttpContextcontext){try{await_next(context);}catch(Exceptionex){// 统一包装异常响应varresultnewRESTfulResultobject{StatusCode500,Succeededfalse,Errorsex.Message,TimestampDateTimeOffset.UtcNow.ToUnixTimeSeconds()};awaitcontext.Response.WriteAsJsonAsync(result);}}四、配置选项UnifyResultSettingsOptions提供了丰富的配置项配置项默认值说明Enabledtrue是否启用统一结果处理WriteRawResultfalse是否直接写入原始结果IgnoreNullValuefalse是否忽略 null 值IgnoreSchemafalse是否忽略 Schema 验证4.1 配置示例在appsettings.json中配置{UnifyResultSettings:{Enabled:true,IgnoreNullValue:true}}五、高级特性5.1 自定义统一结果提供器实现IUnifyResultProvider接口自定义响应格式publicclassCustomResultProvider:IUnifyResultProvider{publicIActionResultOnProvide(ActionExecutedContextcontext){// 自定义响应逻辑}}注册自定义提供器services.AddUnifyResultCustomResultProvider();5.2 局部禁用统一结果使用[UnifyResult(false)]特性禁用特定接口的统一结果处理[UnifyResult(false)]publicclassUserInfoService:IScoped{publicUserInfoOutputGetUserInfo(stringuserId){...}}5.3 自定义响应模型使用[UnifyModel]特性定义自定义响应模型[UnifyModel(typeof(CustomResult))]publicclassCustomResultProvider:IUnifyResultProvider{}publicclassCustomResultT{publicintCode{get;set;}publicTData{get;set;}publicstringMessage{get;set;}}5.4 附加数据在响应中添加附加数据publicclassUserInfoService:IScoped{publicobjectGetUserInfo(stringuserId){vardatanew{IduserId,Name张三};varextrasnew{Total100,PageIndex1};returnnew{data,extras};}}六、核心文件文件说明UnifyResultServiceCollectionExtensions.cs统一结果服务扩展方法IUnifyResultProvider.cs统一结果提供器接口RESTfulResultProvider.cs默认 RESTful 结果提供器RESTfulResult.csRESTful 风格结果集SucceededUnifyResultFilter.cs成功结果筛选器UnifyResultStatusCodesMiddleware.cs统一结果状态码中间件UnifyResultSettingsOptions.cs统一结果配置选项UnifyContext.cs统一结果上下文七、总结统一结果处理通过 MVC 筛选器和中间件机制实现了 API 响应的标准化和规范化。核心设计思想全局统一所有 API 自动返回统一格式的响应自动包装无需手动构建响应对象减少样板代码异常统一处理集中处理异常返回标准化错误信息高度可扩展支持自定义响应格式和提供器这种设计使得前端可以统一处理所有 API 响应提高了前后端协作效率同时也便于日志记录和监控。