Acme.ReturnOh：让.NET API返回值处理更优雅，统一响应格式一步到位

在.NET API开发中你是否也曾为这些问题头疼接口返回格式不统一、异常处理代码重复、参数验证错误提示杂乱、Swagger配置繁琐...今天给大家推荐一款专为解决这些痛点而生的工具库——Acme.ReturnOh一站式搞定API返回值标准化、异常处理、参数验证和Swagger配置让接口开发更规范、更高效。一、Acme.ReturnOh 是什么Acme.ReturnOh 是面向.NET 8.0 框架的通用返回参数处理库核心目标是标准化API响应格式同时内置全局异常处理、参数验证和Swagger配置能力让开发者告别重复的返回值处理代码专注业务逻辑开发。核心特性 统一响应格式定义标准化的API返回结构前后端对接更顺畅️ 全局异常处理自动捕获并格式化异常响应减少try-catch冗余代码✅ 参数验证自动处理模型验证错误返回统一格式的提示信息 一键Swagger简化Swagger配置支持多版本、多XML注释文件 轻量易用NuGet一键安装几行代码完成集成无侵入式设计支持框架.NET 8.0 / 9.0 / 10.0二、5分钟快速上手1. 安装依赖dotnet add package Acme.ReturnOh2. 基础配置Program.csusing Acme.ReturnOh; var builder WebApplication.CreateBuilder(args); // 1. 配置Swagger可选推荐配置 builder.Services.ConfigureSwaggerOptions(我的API文档); // 2. 配置参数验证自动处理 builder.Services.ConfigureApiBehaviorOptions(); // 3. 配置全局异常过滤器 builder.Services.AddExceptionFilterService(); // 4. 添加MVC核心功能 builder.Services.AddControllers(); var app builder.Build(); // 开发环境启用Swagger if (app.Environment.IsDevelopment()) { app.UseSwagger(); app.UseSwaggerUI(); } app.UseAuthorization(); app.MapControllers(); app.Run();3. 第一个标准化接口using Acme.ReturnOh; using Microsoft.AspNetCore.Mvc; [ApiController] [Route([controller])] public class WeatherForecastController : ControllerBase { private static readonly string[] Summaries new[] { Freezing, Bracing, Chilly, Cool, Mild, Warm, Balmy, Hot, Sweltering, Scorching }; [HttpGet(Name GetWeatherForecast)] public Oh Get() { var forecasts Enumerable.Range(1, 5).Select(index new WeatherForecast { Date DateOnly.FromDateTime(DateTime.Now.AddDays(index)), TemperatureC Random.Shared.Next(-20, 55), Summary Summaries[Random.Shared.Next(Summaries.Length)] }).ToArray(); // 标准化成功响应 return forecasts.Success(天气数据获取成功); } }此时接口会返回标准化格式{ Code: 200, Msg: 天气数据获取成功, Data: [/* 天气数据数组 */] }三、核心功能详解1. 标准化响应格式基础结构Acme.ReturnOh 定义了两种核心返回类型满足不同场景需求// 通用返回类型 public record Oh(int Code, string Msg, object? Data null); // 泛型返回类型强类型 public record OhTEntity(int Code, string Msg, TEntity? Data) where TEntity : class, new();常用响应方法无需手动new对象通过扩展方法快速生成响应// 成功响应默认200状态码 return data.Success(); // 默认消息成功 return data.Success(用户查询成功); // 自定义消息 // 失败响应默认500状态码 return data.Fail(); // 默认消息服务器错误请联系管理员 return data.Fail(用户名已存在); // 自定义失败消息 // 自定义状态码和消息 return data.Custom(403, 权限不足无法访问); // 布尔值快速转换 bool isSuccess _userService.Create(user); return isSuccess.IsSuccess(创建成功, 创建失败);泛型强类型返回推荐[HttpGet({id})] public OhUserDto GetUserById(int id) { var user _userService.GetById(id); if (user null) { return new OhUserDto(404, 用户不存在, null); } return user.SuccessUserDto(用户查询成功); }2. 全局异常处理无需手动try-catch框架自动捕获并格式化异常响应异常类型返回状态码响应示例ArgumentException400{Code:400,Msg:参数错误用户名不能为空,Data:null}SystemException500{Code:500,Msg:系统错误数据库连接失败,Data:null}其他异常500{Code:500,Msg:服务器错误请联系管理员,Data:null}手动抛出标准化异常// 业务逻辑中手动抛出异常 if (string.IsNullOrEmpty(userDto.Username)) { OhUser.ArgumentException(用户名不能为空); } if (dbConnection.State ! ConnectionState.Open) { OhUser.SystemException(数据库连接失败); }3. 自动参数验证结合ASP.NET Core的模型验证特性自动处理验证错误// 定义验证规则 public class UserDto { [Required(ErrorMessage 用户名不能为空)] public string Username { get; set; } [Required(ErrorMessage 密码不能为空)] [MinLength(6, ErrorMessage 密码长度不能少于6位)] public string Password { get; set; } } // 控制器接口 [HttpPost] public Oh Create([FromBody] UserDto user) { // 无需手动验证验证失败会自动返回标准化响应 return _userService.Create(user).Success(创建成功); }验证失败时自动返回{ Code: 400, Msg: 用户名不能为空密码长度不能少于6位, Data: null }4. 一键Swagger配置简化Swagger的繁琐配置支持自定义标题、版本、多XML注释文件// 基础配置 builder.Services.ConfigureSwaggerOptions(电商API文档); // 自定义版本 builder.Services.ConfigureSwaggerOptions(电商API文档, v2); // 包含多个XML注释文件显示实体类、服务层注释 var xmlFiles new Liststring { MyProject.Model, MyProject.Service }; builder.Services.ConfigureSwaggerOptions(电商API文档, v1, xmlFiles);四、高级用法1. 自定义异常过滤器如果默认异常处理逻辑不满足需求可自定义过滤器// 自定义异常过滤器 public class CustomExceptionFilter : Attribute, IAsyncExceptionFilter { public async Task OnExceptionAsync(ExceptionContext context) { if (context.ExceptionHandled) return; // 自定义异常处理逻辑 Oh result context.Exception switch { BusinessException ex // 业务异常 new Oh(400, $业务异常{ex.Message}), AuthException ex // 认证异常 new Oh(401, $认证失败{ex.Message}), _ // 其他异常 Oh.Fail($系统错误{context.Exception.Message}), }; context.ExceptionHandled true; context.Result new ObjectResult(result); await Task.CompletedTask; } } // 注册自定义过滤器 builder.Services.AddExceptionFilterServiceCustomExceptionFilter();2. 内置常量复用库中内置了常用的响应消息和状态码常量避免硬编码// 常用成功/失败消息 return user.Success(CV.GetYes); // 获取成功 return result.IsSuccess(CV.InsertYes, CV.InsertNo); // 新增成功/新增失败 // 常用状态码 return data.Custom(CV.YesCode, 操作成功); // 200 return data.Fail(CV.NoCode, 操作失败); // 500完整常量列表常量名值用途CV.Yes成功通用成功消息CV.GetYes获取成功查询成功消息CV.InsertYes新增成功新增成功消息CV.UpdateYes更新成功更新成功消息CV.DeleteYes删除成功删除成功消息CV.YesCode200成功状态码CV.NoCode500失败状态码五、完整实战示例控制器层完整示例using Acme.ReturnOh; using Microsoft.AspNetCore.Mvc; namespace MyProject.Controllers { [ApiController] [Route(api/[controller])] public class UserController : ControllerBase { private readonly IUserService _userService; public UserController(IUserService userService) { _userService userService; } // 查询所有用户 [HttpGet] public Oh GetAll() { var users _userService.GetAll(); return users.Success(CV.GetYes); } // 根据ID查询用户 [HttpGet({id})] public OhUserDto GetById(int id) { var user _userService.GetById(id); if (user null) { return new OhUserDto(404, 用户不存在, null); } return user.SuccessUserDto(CV.GetYes); } // 新增用户 [HttpPost] public Oh Create([FromBody] UserDto userDto) { var result _userService.Create(userDto); return result.IsSuccess(CV.InsertYes, CV.InsertNo); } // 更新用户 [HttpPut({id})] public Oh Update(int id, [FromBody] UserDto userDto) { var result _userService.Update(id, userDto); return result.IsSuccess(CV.UpdateYes, CV.UpdateNo); } // 删除用户 [HttpDelete({id})] public Oh Delete(int id) { var result _userService.Delete(id); return result.IsSuccess(CV.DeleteYes, CV.DeleteNo); } } }服务层示例using Acme.ReturnOh; public class UserService : IUserService { private readonly ListUser _users new(); public ListUserDto GetAll() { return _users.Select(u new UserDto { Id u.Id, Username u.Username, Email u.Email }).ToList(); } public UserDto GetById(int id) { var user _users.FirstOrDefault(u u.Id id); return user null ? null : new UserDto { Id user.Id, Username user.Username, Email user.Email }; } public bool Create(UserDto userDto) { // 业务验证失败则抛出标准化异常 if (string.IsNullOrEmpty(userDto.Username)) { OhUser.ArgumentException(用户名不能为空); } if (_users.Any(u u.Username userDto.Username)) { OhUser.ArgumentException(用户名已存在); } _users.Add(new User { Id _users.Count 1, Username userDto.Username, Email userDto.Email }); return true; } // 其他方法省略... }六、常见问题解答1. 如何修改默认的成功/失败消息直接在调用Success/Fail方法时传入自定义消息即可// 自定义成功消息 return data.Success(数据查询完成); // 自定义失败消息 return data.Fail(该记录已被删除无法操作);2. 如何添加自定义状态码使用Custom方法自定义状态码和消息// 403权限不足 return data.Custom(403, 您没有该操作权限); // 401未认证 return data.Custom(401, 请先登录);3. Swagger不显示XML注释怎么办右键项目 → 属性 → 生成 → 勾选生成XML文档文件在ConfigureSwaggerOptions中指定XML文件var xmlFiles new Liststring { MyProject.Controllers, MyProject.Models }; builder.Services.ConfigureSwaggerOptions(API文档, v1, xmlFiles);4. 如何禁用全局异常处理如果需要自定义异常处理逻辑可不注册默认过滤器// 注释掉默认异常过滤器注册 // builder.Services.AddExceptionFilterService(); // 注册自定义过滤器 builder.Services.AddExceptionFilterServiceCustomExceptionFilter();七、总结Acme.ReturnOh 作为一款轻量级的.NET API返回值处理库核心价值在于标准化和提效 标准化统一API响应格式降低前后端对接成本️ 提效内置异常处理、参数验证、Swagger配置减少重复代码 灵活支持自定义异常处理、自定义状态码满足个性化需求 易用几行代码集成学习成本低开箱即用无论是小型项目快速开发还是中大型项目的接口规范化建设Acme.ReturnOh 都能显著提升开发效率让开发者从繁琐的返回值处理中解放出来专注于核心业务逻辑。版本历史1.7.3 - 当前稳定版本1.7.2 - 修复小问题优化参数验证提示1.7.1 - 优化异常处理逻辑增加泛型返回支持1.7.0 - 新增泛型返回类型1.5.0 - 初始版本核心功能上线如果你的.NET API项目还在为返回值格式不统一、异常处理繁琐而烦恼不妨试试Acme.ReturnOh让接口开发更规范、更高效