From c977f1106507dc8e2ea4b8806af05622917a2c17 Mon Sep 17 00:00:00 2001 From: "erol_ruan@163.com" Date: Sun, 31 Aug 2025 17:32:08 +0800 Subject: [PATCH] =?UTF-8?q?=E6=9B=B4=E6=96=B0=20README=20=E6=96=87?= =?UTF-8?q?=E6=A1=A3=EF=BC=8C=E6=B7=BB=E5=8A=A0=E7=89=88=E6=9C=AC=E4=BF=A1?= =?UTF-8?q?=E6=81=AF=E5=92=8C=E5=B7=A5=E5=8E=82=E6=A8=A1=E5=BC=8F=E6=94=AF?= =?UTF-8?q?=E6=8C=81?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit - 增加版本徽章，标识当前版本为 2.1.0-rc - 优化核心优势部分，增加快速 AES 模式支持和工厂模式描述 - 更新项目架构，明确 .NET 版本为 8.0，并详细说明单元测试套件 - 增强安全功能描述，明确 AES 加密的双模式支持 - 更新命令行参数示例，增加对 AES 模式配置和工厂模式演示的支持 --- README.md | 99 +++++++++++++++++++++++++++++++++++++++++++++---------- 1 file changed, 81 insertions(+), 18 deletions(-) diff --git a/README.md b/README.md index 9a70108..defb654 100644 --- a/README.md +++ b/README.md @@ -4,6 +4,7 @@ [![C++](https://img.shields.io/badge/C++-17-blue.svg)](https://isocpp.org/) [![License](https://img.shields.io/badge/license-MIT-green.svg)](LICENSE) [![Build Status](https://img.shields.io/badge/build-passing-brightgreen.svg)]() +[![Version](https://img.shields.io/badge/version-2.1.0--rc-blue.svg)]() > 专为物联网（IoT）场景设计的高性能设备消息处理库，提供完整的序列化/反序列化解决方案，支持 C# 和 C++ 双语言实现。 @@ -12,13 +13,14 @@ DeviceCommons 是一个现代化的设备消息处理库，专门为物联网设备开发者、嵌入式系统工程师和后端数据处理开发者设计。它提供了高效、安全、可扩展的消息序列化和反序列化功能，支持跨平台部署和多种编程语言。 ### 核心优势 -- 🏎️ **极致性能**：最小化内存分配，优化的序列化算法 -- 🔒 **数据安全**：内置AES加密和CRC校验机制 +- 🏎️ **极致性能**：最小化内存分配，优化的序列化算法，支持快速AES模式 +- 🔒 **数据安全**：内置AES加密（快速/安全双模式）和CRC校验机制 - 📦 **智能压缩**：Gzip压缩减少传输体积 - 🔄 **平滑升级**：V1/V2协议共存，无缝迁移 - 🌐 **跨平台支持**：C#/.NET与C++双语言实现 - 🧩 **高度可扩展**：支持自定义序列化器和协议扩展 - ⚡ **现代化设计**：异步API、依赖注入、链式调用 +- 🏭 **工厂模式**：设备状态配置注册和快速解析 ## 🏗️ 项目架构 @@ -26,8 +28,8 @@ DeviceCommons 采用**多项目解决方案**架构，每个项目专注于特 ``` DeviceCommons/ -├── 📚 DeviceCommons/ # 核心库 (.NET) -├── 🧪 TestProject1/ # 单元测试套件 +├── 📚 DeviceCommons/ # 核心库 (.NET 8.0) +├── 🧪 TestProject1/ # 单元测试套件 (xUnit) ├── 🔧 DeviceCommons(C++)/ # C++ 版本库 ├── 🎯 ConsoleTestApp/ # 演示应用 ├── 📖 docs/ # 项目文档 @@ -39,14 +41,16 @@ DeviceCommons/ ### 1. [DeviceCommons](DeviceCommons/README.md) - 核心库 **项目类型**: .NET 8.0 类库 +**版本**: 2.1.0-rc **主要功能**: 设备消息处理、状态管理、加密压缩、验证框架 **核心特性**: - 🔧 **设备消息处理**：消息构建器模式、多协议版本支持 - 🏭 **状态工厂系统**：可配置状态工厂、状态类型管理、验证规则引擎 -- 🔐 **安全功能**：AES加密、CRC校验、密码管理 +- 🔐 **安全功能**：AES加密（快速/安全双模式）、CRC校验、密码管理 - 📦 **数据处理**：GZip压缩、消息池管理、序列化优化 - 🎯 **依赖注入**：完整的DI集成、服务生命周期管理 +- 🏭 **工厂模式**：设备状态配置注册、快速解析支持 **技术架构**: ``` @@ -57,20 +61,34 @@ DeviceMessages/ # 设备消息核心 ├── Factories/ # 工厂模式 ├── Models/ # 数据模型 └── Serialization/ # 序列化处理 + +Security/ # 安全功能 +├── AesEncryptor.cs # AES加密器（双模式） +└── ... + +Validation/ # 验证框架 +├── DeviceMessageValidator.cs +└── ... + +DataHandling/ # 数据处理 +├── DeviceMessageUtilities.cs +├── Compression/ # 压缩功能 +└── ... ``` ### 2. [TestProject1](TestProject1/README.md) - 单元测试套件 -**项目类型**: xUnit 测试项目 +**项目类型**: xUnit 测试项目 (.NET 8.0) **测试覆盖**: 100% 核心功能覆盖 **测试分类**: -- 🔧 **核心功能测试**: 消息构建器、解析器、序列化器 -- 🏭 **构建器测试**: AES模式配置、状态配置 -- ⚙️ **配置测试**: AES模式、依赖注入配置 -- 🔐 **安全功能测试**: 加密、压缩、CRC验证 -- 📊 **性能测试**: 序列化性能、并发测试、异步操作 -- 🔗 **集成测试**: 边界条件、异常处理、依赖注入 +- 🔧 **核心功能测试** (`Core/`): 消息构建器、解析器、序列化器 +- 🏭 **构建器测试** (`Builders/`): AES模式配置、状态配置 +- ⚙️ **配置测试** (`Configuration/`): AES模式、依赖注入配置 +- 🔐 **安全功能测试** (`Security/`): 加密、压缩、CRC验证 +- 📊 **性能测试** (`Performance/`): 序列化性能、并发测试、异步操作 +- 🔗 **集成测试** (`Integration/`): 边界条件、异常处理、依赖注入 +- ✅ **验证测试** (`Validation/`): 数据验证、错误处理 **测试工具**: - **BaseUnitTest**: 单元测试基类 @@ -105,6 +123,7 @@ DeviceMessages/ # 设备消息核心 - 🏭 **状态配置演示**: 设备类型注册、状态定义、验证规则 - 🔐 **安全功能演示**: AES模式对比、加密配置、密码管理 - 📊 **性能测试演示**: 序列化性能、加密性能、内存监控 +- 🏭 **工厂模式演示**: 快速解析、设备状态配置 **命令行参数**: ```bash @@ -114,6 +133,10 @@ dotnet run -- performance # 性能测试 dotnet run -- builder # 构建器演示 dotnet run -- table # 表格显示演示 dotnet run -- record # 测试记录演示 +dotnet run -- config # AES模式配置演示 +dotnet run -- demo # 分段统计演示 +dotnet run -- verify # 表格对齐验证 +dotnet run -- fix # 性能修复验证 ``` ## 🚀 快速开始 @@ -143,6 +166,10 @@ dotnet test # 运行特定测试项目 dotnet test TestProject1/ dotnet test ConsoleTestApp/ + +# 运行特定测试类别 +dotnet test TestProject1/ --filter "Category=Security" +dotnet test TestProject1/ --filter "Category=Performance" ``` #### 3. 运行演示 @@ -152,6 +179,9 @@ dotnet run --project ConsoleTestApp -- state # 运行AES性能测试 dotnet run --project ConsoleTestApp -- performance + +# 运行工厂模式演示 +dotnet run --project ConsoleTestApp -- builder ``` #### 4. 构建C++版本 @@ -171,29 +201,35 @@ cd "DeviceCommons(C++)" - **消息构建器模式**：流畅的API设计，支持链式调用 - **多协议版本支持**：兼容不同版本的设备通信协议 - **灵活的设备结构**：支持主设备和子设备的层次结构 +- **工厂模式支持**：设备状态配置注册和快速解析 ### 状态工厂系统 - **可配置状态工厂**：支持运行时状态配置注册 - **状态类型管理**：完整的 StateValueTypeEnum 支持 - **验证规则引擎**：自定义状态验证逻辑 +- **快速解析**：基于注册配置的直接状态值提取 ### 安全功能 -- **AES加密**：支持多种AES模式（快速、安全、自定义） +- **AES加密双模式**： + - **快速模式**：1000次PBKDF2迭代，启用密钥缓存，适合开发测试 + - **安全模式**：60000次PBKDF2迭代，适合生产环境 - **CRC校验**：数据完整性验证 - **密码管理**：灵活的加密密码配置 +- **线程安全**：ThreadLocal确保并发安全 ### 数据处理 - **GZip压缩**：高效的数据压缩 - **消息池管理**：内存优化的消息对象池 - **序列化优化**：高性能的消息序列化 +- **内存优化**：使用ArrayPool减少内存分配 ## 🏗️ 依赖注入支持 ### 服务注册 ```csharp services.AddDeviceCommons() - .WithAesEncryption() - .WithGZipCompression() + .WithDefaultAesEncryption("password", AesMode.Fast) + .WithDefaultGZipCompression() .AddStateFactory(deviceType: 0x10); ``` @@ -208,6 +244,17 @@ Console.WriteLine($"启用加密: {options.EnableDefaultAesEncryption}"); Console.WriteLine($"启用压缩: {options.EnableDefaultGZipCompression}"); ``` +### 工厂模式集成 +```csharp +// 注册设备状态配置 +services.AddDeviceCommons() + .AddStateFactory(deviceType: 0x01); + +// 使用工厂模式进行快速解析 +var factory = serviceProvider.GetRequiredService(); +var stateFactory = factory.GetFactory(0x01); +``` + ## 📊 性能基准 ### 序列化性能 @@ -216,6 +263,7 @@ Console.WriteLine($"启用压缩: {options.EnableDefaultGZipCompression}"); | 构建消息 | ~0.1ms | 10,000 ops/sec | <1KB | | 序列化 | ~0.5ms | 2,000 ops/sec | <2KB | | 解析消息 | ~0.8ms | 1,250 ops/sec | <2KB | +| 快速解析 | ~0.2ms | 5,000 ops/sec | <1KB | ### AES加密性能 | 加密模式 | 首次加密 | 缓存加密 | 性能提升 | @@ -249,7 +297,7 @@ Console.WriteLine($"启用压缩: {options.EnableDefaultGZipCompression}"); dotnet test # 运行特定测试 -dotnet test TestProject1/Configuration/AesModeConfigurationTests.cs +dotnet test TestProject1/Security/EncryptionTests.cs dotnet test TestProject1/Builders/BuilderAesModeConfigurationTests.cs # 性能测试 @@ -266,6 +314,9 @@ dotnet run --project ConsoleTestApp -- verify # 性能修复验证 dotnet run --project ConsoleTestApp -- fix + +# AES性能对比 +dotnet run --project ConsoleTestApp -- aes ``` ## 📚 API参考 @@ -276,13 +327,15 @@ dotnet run --project ConsoleTestApp -- fix - `IDeviceMessageParser` - 解析器接口 - `IDeviceCommonsConfigurationService` - 配置服务接口 - `IStateFactory` - 状态工厂接口 +- `IStateFactoryRegistry` - 状态工厂注册表接口 ### 主要类 - `DeviceMessageBuilder` - 消息构建器实现 - `DeviceMessage` - 设备消息模型 -- `AesEncryptor` - AES加密器 +- `AesEncryptor` - AES加密器（双模式支持） - `DeviceCommonsOptions` - 配置选项 - `PerformanceStats` - 性能统计 +- `DeviceMessageValidator` - 消息验证器 ### 枚举类型 - `AesMode` - AES加密模式（Fast/Secure） @@ -290,6 +343,11 @@ dotnet run --project ConsoleTestApp -- fix - `StateValueTypeEnum` - 状态值类型 - `TimeStampFormatEnum` - 时间戳格式 +### 工厂模式 +- `DeviceStateConfigurationRegistry` - 设备状态配置注册表 +- `FastReadingStateFactory` - 快速读取状态工厂 +- `IDeviceStateConfiguration` - 设备状态配置接口 + ## 🤝 贡献指南 ### 开发环境设置 @@ -303,6 +361,7 @@ dotnet run --project ConsoleTestApp -- fix - 使用有意义的变量和方法名 - 添加XML文档注释 - 编写单元测试 +- 支持中文注释 ### 提交流程 1. Fork项目 @@ -326,7 +385,10 @@ A: 开发和测试环境建议使用快速模式，生产环境使用安全模 A: 支持字符串、二进制、整数、浮点数、布尔值、时间戳等多种类型。 **Q: 如何优化序列化性能？** -A: 使用快速AES模式、启用压缩、合理设计数据结构。 +A: 使用快速AES模式、启用压缩、合理设计数据结构、使用工厂模式进行快速解析。 + +**Q: 工厂模式有什么优势？** +A: 工厂模式支持设备状态配置注册，可以实现基于配置的直接状态值提取，避免逐层解析，大幅提升性能。 ### 获取帮助 - 查看各子项目的专用文档 @@ -335,6 +397,7 @@ A: 使用快速AES模式、启用压缩、合理设计数据结构。 - 参与社区讨论 ### 版本历史 +- **v2.1.0-rc** - 添加工厂模式、AES双模式优化、性能提升 - **v2.0** - 添加依赖注入支持、AES双模式、性能优化 - **v1.0** - 基础序列化功能、V1/V2协议支持 -- Gitee