diff --git a/README.md b/README.md index 11eb2ea53a06693a4a4f04312c6133528ef9db25..2ee7a1c6313147dcb5183f9eaaa0ef89bdf2c9c5 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,15 +13,14 @@ DeviceCommons 是一个现代化的设备消息处理库,专门为物联网设备开发者、嵌入式系统工程师和后端数据处理开发者设计。它提供了高效、安全、可扩展的消息序列化和反序列化功能,支持跨平台部署和多种编程语言。 ### 核心优势 -- 🏎️ **极致性能**:最小化内存分配,优化的序列化算法,快速解析支持 -- 🔒 **数据安全**:线程安全的AES加密、CRC校验机制、密码管理 -- 📦 **智能压缩**:GZip压缩减少传输体积,支持多种压缩级别 +- 🏎️ **极致性能**:最小化内存分配,优化的序列化算法,支持快速AES模式 +- 🔒 **数据安全**:内置AES加密(快速/安全双模式)和CRC校验机制 +- 📦 **智能压缩**:Gzip压缩减少传输体积 - 🔄 **平滑升级**:V1/V2协议共存,无缝迁移 - 🌐 **跨平台支持**:C#/.NET与C++双语言实现 - 🧩 **高度可扩展**:支持自定义序列化器和协议扩展 -- ⚡ **现代化设计**:依赖注入、链式调用、完整的XML文档 -- 🎯 **简化API**:DeviceMessageProcessor提供高级简化接口 -- 🔍 **全面验证**:完整的消息验证框架和错误处理 +- ⚡ **现代化设计**:异步API、依赖注入、链式调用 +- 🏭 **工厂模式**:设备状态配置注册和快速解析 ## 🏗️ 项目架构 @@ -28,8 +28,8 @@ DeviceCommons 采用**多项目解决方案**架构,每个项目专注于特 ``` DeviceCommons/ -├── 📚 DeviceCommons/ # 核心库 (.NET) -├── 🧪 TestProject1/ # 单元测试套件 +├── 📚 DeviceCommons/ # 核心库 (.NET 8.0) +├── 🧪 TestProject1/ # 单元测试套件 (xUnit) ├── 🔧 DeviceCommons(C++)/ # C++ 版本库 ├── 🎯 ConsoleTestApp/ # 演示应用 ├── 📖 docs/ # 项目文档 @@ -41,26 +41,39 @@ DeviceCommons/ ### 1. [DeviceCommons](DeviceCommons/README.md) - 核心库 **项目类型**: .NET 8.0 类库 +**版本**: 2.1.0-rc **主要功能**: 设备消息处理、状态管理、加密压缩、验证框架 **核心特性**: - 🔧 **设备消息处理**:消息构建器模式、多协议版本支持、快速解析 - 🏭 **状态工厂系统**:可配置状态工厂、状态类型管理、验证规则引擎 -- 🔐 **安全功能**:线程安全AES加密、CRC校验、密码管理 +- 🔐 **安全功能**:AES加密(快速/安全双模式)、CRC校验、密码管理 - 📦 **数据处理**:GZip压缩、消息池管理、序列化优化 - 🎯 **依赖注入**:完整的DI集成、服务生命周期管理 -- 🔍 **验证框架**:全面的消息验证、错误分类、异常处理 -- 📖 **完整文档**:所有接口和类都有详细的XML文档注释 +- 🏭 **工厂模式**:设备状态配置注册、快速解析支持 **技术架构**: ``` DeviceMessages/ # 设备消息核心 -├── Abstractions/ # 抽象接口 (IDeviceMessage, IDeviceMessageBuilder等) -├── Builders/ # 构建器模式 (DeviceMessageBuilder, EnhancedDeviceMessageBuilder) -├── Enums/ # 枚举定义 (StateValueTypeEnum, CRCTypeEnum等) -├── Factories/ # 工厂模式 (DeviceMessageProcessor, FastReadingStateFactory) -├── Models/ # 数据模型 (V1/V2协议模型) -└── Serialization/ # 序列化处理 (解析器、序列化器) +├── Abstractions/ # 抽象接口 +├── Builders/ # 构建器模式 +├── Enums/ # 枚举定义 +├── Factories/ # 工厂模式 +├── Models/ # 数据模型 +└── Serialization/ # 序列化处理 + +Security/ # 安全功能 +├── AesEncryptor.cs # AES加密器(双模式) +└── ... + +Validation/ # 验证框架 +├── DeviceMessageValidator.cs +└── ... + +DataHandling/ # 数据处理 +├── DeviceMessageUtilities.cs +├── Compression/ # 压缩功能 +└── ... ``` **新增核心组件**: @@ -72,17 +85,17 @@ DeviceMessages/ # 设备消息核心 ### 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**: 单元测试基类 @@ -117,8 +130,7 @@ DeviceMessages/ # 设备消息核心 - 🏭 **状态配置演示**: 设备类型注册、状态定义、验证规则 - 🔐 **安全功能演示**: AES模式对比、加密配置、密码管理 - 📊 **性能测试演示**: 序列化性能、加密性能、内存监控 -- ⚡ **快速解析演示**: 快速解析与传统解析对比 -- 🎯 **简化API演示**: DeviceMessageProcessor使用示例 +- 🏭 **工厂模式演示**: 快速解析、设备状态配置 **命令行参数**: ```bash @@ -128,8 +140,10 @@ dotnet run -- performance # 性能测试 dotnet run -- builder # 构建器演示 dotnet run -- table # 表格显示演示 dotnet run -- record # 测试记录演示 -dotnet run -- simple # 简化API演示 -dotnet run -- fast # 快速解析演示 +dotnet run -- config # AES模式配置演示 +dotnet run -- demo # 分段统计演示 +dotnet run -- verify # 表格对齐验证 +dotnet run -- fix # 性能修复验证 ``` ## 🚀 快速开始 @@ -159,6 +173,10 @@ dotnet test # 运行特定测试项目 dotnet test TestProject1/ dotnet test ConsoleTestApp/ + +# 运行特定测试类别 +dotnet test TestProject1/ --filter "Category=Security" +dotnet test TestProject1/ --filter "Category=Performance" ``` #### 3. 运行演示 @@ -171,6 +189,9 @@ dotnet run --project ConsoleTestApp -- fast # 运行AES性能测试 dotnet run --project ConsoleTestApp -- performance + +# 运行工厂模式演示 +dotnet run --project ConsoleTestApp -- builder ``` #### 4. 构建C++版本 @@ -190,22 +211,27 @@ cd "DeviceCommons(C++)" - **消息构建器模式**:流畅的API设计,支持链式调用 - **多协议版本支持**:兼容不同版本的设备通信协议 - **灵活的设备结构**:支持主设备和子设备的层次结构 -- **快速解析支持**:预注册设备类型,跳过传统解析步骤 +- **工厂模式支持**:设备状态配置注册和快速解析 ### 状态工厂系统 - **可配置状态工厂**:支持运行时状态配置注册 - **状态类型管理**:完整的 StateValueTypeEnum 支持(Float32, Int32, String, Bool, UInt16, Int16, Timestamp, Binary, Double) - **验证规则引擎**:自定义状态验证逻辑 +- **快速解析**:基于注册配置的直接状态值提取 ### 安全功能 -- **线程安全AES加密**:支持快速模式(1000次PBKDF2)和安全模式(60000次PBKDF2) -- **CRC校验**:支持CRC16和CRC32数据完整性验证 -- **密码管理**:灵活的加密密码配置,支持默认密码和自定义密码 +- **AES加密双模式**: + - **快速模式**:1000次PBKDF2迭代,启用密钥缓存,适合开发测试 + - **安全模式**:60000次PBKDF2迭代,适合生产环境 +- **CRC校验**:数据完整性验证 +- **密码管理**:灵活的加密密码配置 +- **线程安全**:ThreadLocal确保并发安全 ### 数据处理 - **GZip压缩**:高效的数据压缩,支持多种压缩级别 - **消息池管理**:内存优化的消息对象池 - **序列化优化**:高性能的消息序列化 +- **内存优化**:使用ArrayPool减少内存分配 ### 验证框架 - **全面验证**:消息结构、数据类型、格式验证 @@ -252,8 +278,8 @@ var (deviceTypes, totalStates) = processor.GetStatistics(); ### 服务注册 ```csharp services.AddDeviceCommons() - .WithAesEncryption() - .WithGZipCompression() + .WithDefaultAesEncryption("password", AesMode.Fast) + .WithDefaultGZipCompression() .AddStateFactory(deviceType: 0x10); ``` @@ -268,6 +294,17 @@ Console.WriteLine($"启用加密: {options.EnableDefaultAesEncryption}"); Console.WriteLine($"启用压缩: {options.EnableDefaultGZipCompression}"); ``` +### 工厂模式集成 +```csharp +// 注册设备状态配置 +services.AddDeviceCommons() + .AddStateFactory(deviceType: 0x01); + +// 使用工厂模式进行快速解析 +var factory = serviceProvider.GetRequiredService(); +var stateFactory = factory.GetFactory(0x01); +``` + ## 📊 性能基准 ### 序列化性能 @@ -310,8 +347,8 @@ Console.WriteLine($"启用压缩: {options.EnableDefaultGZipCompression}"); dotnet test # 运行特定测试 -dotnet test TestProject1/Core/MessageBuilderTests.cs dotnet test TestProject1/Security/EncryptionTests.cs +dotnet test TestProject1/Builders/BuilderAesModeConfigurationTests.cs # 性能测试 dotnet run --project ConsoleTestApp -- performance @@ -327,6 +364,9 @@ dotnet run --project ConsoleTestApp -- verify # 性能修复验证 dotnet run --project ConsoleTestApp -- fix + +# AES性能对比 +dotnet run --project ConsoleTestApp -- aes ``` ## 📚 API参考 @@ -337,18 +377,16 @@ dotnet run --project ConsoleTestApp -- fix - `IDeviceMessageParser` - 解析器接口 - `IDeviceCommonsConfigurationService` - 配置服务接口 - `IStateFactory` - 状态工厂接口 -- `IFastReadingStateFactory` - 快速解析工厂接口 -- `IDeviceStateConfiguration` - 设备状态配置接口 +- `IStateFactoryRegistry` - 状态工厂注册表接口 ### 主要类 - `DeviceMessageProcessor` - 简化的消息处理器 - `DeviceMessageBuilder` - 消息构建器实现 - `DeviceMessage` - 设备消息模型 -- `AesEncryptor` - 线程安全AES加密器 +- `AesEncryptor` - AES加密器(双模式支持) - `DeviceCommonsOptions` - 配置选项 +- `PerformanceStats` - 性能统计 - `DeviceMessageValidator` - 消息验证器 -- `Compressor` - GZip压缩器 -- `CrcCalculator` - CRC计算器 ### 枚举类型 - `AesMode` - AES加密模式(Fast/Secure) @@ -361,6 +399,11 @@ dotnet run --project ConsoleTestApp -- fix - `DeviceMessageValidationException` - 消息验证异常 - `InvalidMessageException` - 无效消息异常 +### 工厂模式 +- `DeviceStateConfigurationRegistry` - 设备状态配置注册表 +- `FastReadingStateFactory` - 快速读取状态工厂 +- `IDeviceStateConfiguration` - 设备状态配置接口 + ## 🤝 贡献指南 ### 开发环境设置 @@ -374,6 +417,7 @@ dotnet run --project ConsoleTestApp -- fix - 使用有意义的变量和方法名 - 添加完整的XML文档注释 - 编写单元测试 +- 支持中文注释 ### 提交流程 1. Fork项目 @@ -397,10 +441,10 @@ A: 开发和测试环境建议使用快速模式,生产环境使用安全模 A: 支持字符串、二进制、整数、浮点数、布尔值、时间戳等多种类型。 **Q: 如何优化序列化性能?** -A: 使用快速AES模式、启用压缩、合理设计数据结构、使用快速解析。 +A: 使用快速AES模式、启用压缩、合理设计数据结构、使用工厂模式进行快速解析。 -**Q: 什么是快速解析?** -A: 快速解析允许预注册设备类型,跳过传统解析步骤,大幅提升解析性能。 +**Q: 工厂模式有什么优势?** +A: 工厂模式支持设备状态配置注册,可以实现基于配置的直接状态值提取,避免逐层解析,大幅提升性能。 ### 获取帮助 - 查看各子项目的专用文档 @@ -409,7 +453,7 @@ A: 快速解析允许预注册设备类型,跳过传统解析步骤,大幅 - 参与社区讨论 ### 版本历史 -- **v2.1** - 添加DeviceMessageProcessor、快速解析、完整XML文档、线程安全AES +- **v2.1.0-rc** - 添加工厂模式、AES双模式优化、性能提升 - **v2.0** - 添加依赖注入支持、AES双模式、性能优化 - **v1.0** - 基础序列化功能、V1/V2协议支持