Acme .NET 工具类库：一站式解决.NET开发高频场景问题

作为.NET开发者，日常开发中总会遇到各种重复的基础功能开发------JSON序列化、数据类型转换、HTTP请求封装、Excel处理...这些功能看似简单，但要做到稳定、高效、易用却需要不少精力。今天给大家推荐一款功能丰富的.NET工具类库「Acme」，覆盖11大核心模块，让你告别重复造轮子，专注业务逻辑开发。

一、Acme 工具库简介

Acme 是一款面向.NET 8.0+ 框架的通用工具类库，当前版本5.6.4，支持.NET 8.0/9.0/10.0全版本，旨在封装日常开发中高频使用的功能模块，提供简洁、易用、高性能的API，降低开发成本。

核心特点：

📦 开箱即用：NuGet一键安装，几行代码完成集成
🎯 场景全覆盖：JSON、类型转换、HTTP、加密、Excel等11大核心模块
🚀 性能优化：内置异步支持、缓存策略等性能优化方案
🔒 安全可靠：内置输入验证、安全加密等最佳实践
📋 完善文档：每个功能都有详细示例和最佳实践指导

二、快速上手：5分钟集成使用

1. 安装方式

NuGet安装（推荐）

复制代码

dotnet add package Acme

手动集成 将Acme项目添加到解决方案，在目标项目中添加项目引用即可。

2. 服务注册

在Program.cs中完成服务注册（ASP.NET Core项目）：

cs 复制代码

using Acme;

var builder = WebApplication.CreateBuilder(args);

// 注册Acme核心服务
builder.Services.AddAcmeBuilderServer();

var app = builder.Build();

3. 极简使用示例

cs 复制代码

using Acme.Tools;

public class HomeController : Controller
{
    public IActionResult Index()
    {
        // JSON序列化
        var user = new { Name = "张三", Age = 25 };
        string json = user.ToJson();
        
        // 安全类型转换
        int number = "123".ToInt();
        
        // MD5加密
        string hashedPassword = MD5Encryption.Encrypt("password123");
        
        return View();
    }
}

三、核心功能模块详解

1. JSON处理（Json.cs）

基于Newtonsoft.Json封装，提供简洁的序列化/反序列化API：

cs 复制代码

// 对象转JSON
var user = new { Name = "张三", Age = 25 };
string json = user.ToJson();

// JSON转实体
string jsonStr = "{\"Name\":\"李四\",\"Age\":30}";
User user = jsonStr.ToEntity<User>();

// 动态类型解析
dynamic dynamicUser = jsonStr.ToEntity<dynamic>();
Console.WriteLine(dynamicUser.Name); // 输出：李四

2. 数据类型转换（ConvHelper.cs）

解决.NET原生类型转换繁琐、易出错的问题：

cs 复制代码

// 安全类型转换（带默认值）
int safeNum = "abc".ToInt(0); // 转换失败返回默认值0
double price = "99.9".ToDouble();
bool isTrue = "true".ToBool();

// 路径处理
string webPath = @"C:\files\image.jpg".ToUrlPath(); // 输出：/files/image.jpg

// 时间戳处理
long timestamp = ConvHelper.GetTimeStamp(); // 13位时间戳
DateTime date = ConvHelper.GetDateTimeFromTimestamp(timestamp);

// 随机码生成
string verifyCode = "0-9".ToRandomCode(6); // 6位数字验证码

3. HTTP请求封装（HttpHelper.cs）

简化HttpClient使用，内置JSON支持和错误处理：

cs 复制代码

// GET请求
string response = HttpHelper.HttpClientGet("https://api.example.com/users?id=1");

// POST请求（自动序列化JSON）
var postData = new { UserId = 1, Name = "新名称" };
string postResp = HttpHelper.HttpClientPost("https://api.example.com/update", postData);

// 带请求头的请求
var headers = new Dictionary<string, string>
{
    { "Authorization", "Bearer your-token" },
    { "Content-Type", "application/json" }
};
string authResp = HttpHelper.HttpClientGet("https://api.example.com/protected", headers);

4. 加密工具（MD5Encryption.cs）

适用于非敏感数据的MD5加密，支持大小写输出：

cs 复制代码

// 基础加密
string password = "123456";
string md5Lower = MD5Encryption.Encrypt(password); // 小写
string md5Upper = MD5Encryption.Encrypt(password, true); // 大写

// 密码验证
bool isValid = MD5Encryption.Compare(inputPwd, storedHash);

⚠️ 注意：MD5适用于非敏感数据，用户密码等敏感信息建议使用BCrypt/Argon2算法

5. Session/Cookie管理

提供统一的Session/Cookie操作接口，支持对象存储：

cs 复制代码

// Session操作
public class AccountController : Controller
{
    private readonly IHttpSessionService _sessionService;
    
    public AccountController(IHttpSessionService sessionService)
    {
        _sessionService = sessionService;
    }
    
    public IActionResult Login(string username)
    {
        // 存储字符串
        _sessionService.SetSession("CurrentUser", username);
        
        // 存储对象
        var userInfo = new { Name = username, Role = "Admin" };
        _sessionService.SetObjectAsJson("UserInfo", userInfo);
        
        return RedirectToAction("Index");
    }
}

// Cookie操作
_cookieService.SetCookies("AuthToken", "abc123", 60); // 60分钟过期
string token = _cookieService.GetCookies("AuthToken");
_cookieService.DeleteCookies("AuthToken");

6. 拼音处理（Pinyin.cs）

中文转拼音首字母，适用于搜索、排序场景：

cs 复制代码

// 中文转拼音首字母
string initials = Pinyin.GetInitials("中文拼音处理"); // 输出：ZWPYCL

// 搜索场景示例
public List<User> SearchUsers(string keyword)
{
    string pinyinKey = Pinyin.GetInitials(keyword).ToLower();
    return _userRepo.SearchByPinyinKey(pinyinKey);
}

7. Excel处理（基于NPOI）

支持Excel导入导出，自动映射实体类：

cs 复制代码

// 定义数据模型
public class Product
{
    public string Name { get; set; }
    public decimal Price { get; set; }
    public int Stock { get; set; }
}

// 导出Excel
public void ExportProducts(List<Product> products)
{
    var excelService = new NpolExcelService<Product>();
    // 自定义表头映射
    var headers = new Dictionary<string, string>
    {
        { "Name", "产品名称" },
        { "Price", "价格" },
        { "Stock", "库存" }
    };
    excelService.ExportToExcel(products, "products.xlsx", "产品列表", headers);
}

// 导入Excel
public List<Product> ImportProducts(string filePath)
{
    var excelService = new NpolExcelService<Product>();
    return excelService.ImportFromExcel(filePath);
}

8. 其他核心模块

模块	功能亮点	适用场景
验证码生成（VerCode.cs）	生成指定长度数字验证码	手机/邮箱验证码、交易验证
验证工具（VerificationHelper.cs）	Guid验证、正则验证（邮箱/手机号/身份证）	输入验证、数据校验
配置管理	统一读取appsettings.json、自定义JSON配置	配置集中管理、多环境配置

四、最佳实践指南

1. 依赖注入最佳实践

合理设置服务生命周期，避免内存泄漏：

cs 复制代码

// Scoped：每个请求一个实例（用户服务、业务服务）
builder.Services.AddScoped<IUserService, UserService>();

// Transient：每次注入新实例（工具类、临时服务）
builder.Services.AddTransient<IExcelService, ExcelService>();

// Singleton：全局单例（缓存服务、配置服务）
builder.Services.AddSingleton<ICacheService, CacheService>();

2. 错误处理策略

cs 复制代码

// 安全数据处理封装
public class SafeDataProcessor
{
    public int? SafeConvertToInt(string input)
    {
        try { return input.ToInt(); }
        catch { return null; }
    }
    
    public T SafeJsonDeserialize<T>(string json) where T : new()
    {
        try { return json.ToEntity<T>(); }
        catch { return new T(); }
    }
}

// 全局异常处理
app.UseExceptionHandler(options =>
{
    options.Run(async context =>
    {
        var exception = context.Features.Get<IExceptionHandlerFeature>();
        if (exception != null)
        {
            // 记录日志
            Console.WriteLine($"全局异常：{exception.Error.Message}");
            
            // 返回友好响应
            context.Response.StatusCode = 500;
            await context.Response.WriteAsJsonAsync(new
            {
                success = false,
                message = "服务器处理失败，请稍后重试"
            });
        }
    });
});

3. 性能优化建议

缓存策略

复制代码

public class CachedUserService : IUserService
{
    private readonly IUserService _userService;
    private readonly ICacheService _cacheService;
    
    public async Task<User> GetUserById(int id)
    {
        string cacheKey = $"User:{id}";
        
        // 优先从缓存获取
        var cachedUser = _cacheService.Get<User>(cacheKey);
        if (cachedUser != null) return cachedUser;
        
        // 缓存未命中，从数据库获取
        var user = await _userService.GetUserById(id);
        
        // 存入缓存（10分钟过期）
        _cacheService.Set(cacheKey, user, TimeSpan.FromMinutes(10));
        
        return user;
    }
}

异步操作

复制代码

// 控制器异步示例
[HttpGet("{id}")]
public async Task<IActionResult> GetUser(int id)
{
    try
    {
        var user = await _userService.GetUserById(id);
        return Ok(user);
    }
    catch (Exception ex)
    {
        return BadRequest(new { message = ex.Message });
    }
}

4. 安全最佳实践

密码安全处理（加盐MD5）

复制代码

public string HashPassword(string password)
{
    // 生成8位盐值
    string salt = Guid.NewGuid().ToString().Substring(0, 8);
    // 密码+盐值加密
    return MD5Encryption.Encrypt(password + salt) + ":" + salt;
}

// 密码验证
public bool VerifyPassword(string inputPwd, string storedHash)
{
    var parts = storedHash.Split(':');
    if (parts.Length != 2) return false;
    
    string hash = parts[0];
    string salt = parts[1];
    
    return MD5Encryption.Encrypt(inputPwd + salt) == hash;
}

输入验证

复制代码

// 常用验证正则
public static class ValidationPatterns
{
    public const string Email = @"^[\w-]+(\.[\w-]+)*@[\w-]+(\.[\w-]+)+$";
    public const string Phone = @"^1[3-9]\d{9}$";
    public const string IdCard = @"^[1-9]\d{5}(18|19|20)\d{2}(0[1-9]|1[0-2])(0[1-9]|[12]\d|3[01])\d{3}[\dXx]$";
}

// 验证逻辑
public bool ValidateUser(User user)
{
    if (user.Id.IsDefault()) return false;
    if (!user.Email.RegexVerification(ValidationPatterns.Email)) return false;
    if (!user.Phone.RegexVerification(ValidationPatterns.Phone)) return false;
    
    return true;
}

五、依赖与兼容性

核心依赖包

依赖包	用途	推荐版本
Newtonsoft.Json	JSON序列化	13.0.4+
NPOI	Excel操作	2.7.5+
Microsoft.Extensions.DependencyInjection	依赖注入	9.0.11+（.NET8/9）、10.0.3+（.NET10）
Microsoft.Extensions.Caching.Abstractions	缓存抽象	9.0.11+（.NET8/9）、10.0.3+（.NET10）

版本兼容性

✅ .NET 8.0：完全支持
✅ .NET 9.0：完全支持
✅ .NET 10.0：完全支持

六、常见问题排查

1. 配置文件读取失败

检查appsettings.json是否存在于项目根目录
确认配置项路径正确（如ConnectionStrings:DefaultConnection）
验证JSON格式是否合法

2. Excel导入失败

确认安装NPOI包：dotnet add package NPOI
检查Excel文件格式是否正确（.xlsx/.xls）
验证实体类属性与Excel列名映射是否一致
确保应用程序有文件读取权限

3. 依赖注入报错

确认已调用builder.Services.AddAcmeBuilderServer()
检查服务生命周期是否正确（避免Singleton注入Scoped）
验证接口与实现类是否正确注册

七、总结

Acme .NET工具类库通过封装日常开发中的高频功能，帮助开发者减少重复代码，提升开发效率。无论是小型项目快速开发，还是大型项目的基础组件建设，Acme都能提供可靠的支持。

核心优势回顾：

📦 开箱即用：NuGet一键安装，快速集成
🎯 功能全面：11大核心模块覆盖绝大部分开发场景
🚀 性能优异：内置异步、缓存等性能优化方案
🔒 安全可靠：遵循安全开发最佳实践
📋 易于维护：完善的文档和示例，降低维护成本

如果你正在寻找一款能解决.NET开发中各种琐碎问题的工具库，Acme绝对值得一试。无论是新手入门还是资深开发者提升效率，都能从中受益。

技术支持

📧 邮箱支持：yzxs949@163.com
📖 文档地址：Acme官方文档
💡 问题反馈：发邮件提供截图和详细报错以及Acme版本、.NET版本、完整错误信息和重现步骤

最后：技术的价值在于解决问题，Acme工具库的设计理念就是让开发者把更多精力放在业务逻辑上，而非重复的基础功能开发。希望这款工具库能成为你.NET开发路上的好帮手！