DeviceCommons 2.3.0

DeviceCommons - 设备通信通用库

专为物联网（IoT）场景设计的高性能设备消息处理库，提供完整的序列化/反序列化解决方案，支持 C# 和 C++ 双语言实现。

🚀 项目简介

DeviceCommons 是一个现代化的设备消息处理库，专门为物联网设备开发者、嵌入式系统工程师和后端数据处理开发者设计。它提供了高效、安全、可扩展的消息序列化和反序列化功能，支持跨平台部署和多种编程语言。

核心优势

• 🏎️ 极致性能：最小化内存分配，优化的序列化算法，支持快速AES模式
• 🔒 数据安全：内置AES加密（快速/安全双模式）和CRC校验机制
• 📦 智能压缩：Gzip压缩减少传输体积
• 🔄 平滑升级：V1/V2协议共存，无缝迁移
• 🌐 跨平台支持：C#/.NET与C++双语言实现
• 🧩 高度可扩展：支持自定义序列化器和协议扩展
• ⚡ 现代化设计：异步API、依赖注入、链式调用
• 🏭 工厂模式：设备状态配置注册和快速解析
• 📚 完整文档：32个wiki文档，涵盖入门指南、最佳实践、故障排除、API参考和示例代码

🏗️ 项目架构

DeviceCommons 采用多项目解决方案架构，每个项目专注于特定的功能领域：

DeviceCommons/
├── 📚 DeviceCommons/           # 核心库 (.NET 8.0)
├── 🧪 TestProject1/            # 单元测试套件 (xUnit)
├── 🔧 DeviceCommons(C++)/      # C++ 版本库
├── 🎯 ConsoleTestApp/          # 演示应用
├── 📖 docs/                    # 项目文档
├── 📚 wiki/                    # 完整文档中心 (32个文档)
└── 📄 配置文件                 # 解决方案和许可证

📚 子项目详情

1. DeviceCommons - 核心库

项目类型: .NET 8.0 类库
版本: 2.3.0
主要功能: 设备消息处理、状态管理、加密压缩、验证框架

核心特性:

• 🔧 设备消息处理：消息构建器模式、多协议版本支持
• 🏭 状态工厂系统：可配置状态工厂、状态类型管理、验证规则引擎
• 🔐 安全功能：AES加密（快速/安全双模式）、CRC校验、密码管理
• 📦 数据处理：GZip压缩、消息池管理、序列化优化
• 🎯 依赖注入：完整的DI集成、服务生命周期管理
• 🏭 工厂模式：设备状态配置注册、快速解析支持

技术架构:

DeviceMessages/           # 设备消息核心
├── Abstractions/        # 抽象接口
├── Builders/            # 构建器模式
├── Enums/               # 枚举定义
├── Factories/           # 工厂模式
├── Models/              # 数据模型
└── Serialization/       # 序列化处理

Security/                # 安全功能
├── AesEncryptor.cs      # AES加密器（双模式）
└── ...

Validation/              # 验证框架
├── DeviceMessageValidator.cs
└── ...

DataHandling/            # 数据处理
├── DeviceMessageUtilities.cs
├── Compression/         # 压缩功能
└── ...

2. TestProject1 - 单元测试套件

项目类型: xUnit 测试项目 (.NET 8.0)
测试覆盖: 100% 核心功能覆盖

测试分类:

• 🔧 核心功能测试 (Core/): 消息构建器、解析器、序列化器
• 🏭 构建器测试 (Builders/): AES模式配置、状态配置
• ⚙️ 配置测试 (Configuration/): AES模式、依赖注入配置
• 🔐 安全功能测试 (Security/): 加密、压缩、CRC验证
• 📊 性能测试 (Performance/): 序列化性能、并发测试、异步操作
• 🔗 集成测试 (Integration/): 边界条件、异常处理、依赖注入
• ✅ 验证测试 (Validation/): 数据验证、错误处理

测试工具:

• BaseUnitTest: 单元测试基类
• BaseTestClass: 测试基类
• TestDataBuilder: 测试数据生成器

3. DeviceCommons(C++) - C++ 版本库

项目类型: C++17 库项目
跨平台支持: Windows、Linux、macOS

核心特性:

• 🔧 设备消息处理: 与C#版本完全一致的API设计
• 🏭 状态管理: 状态工厂系统、类型安全、验证支持
• 🔐 安全功能: AES加密、CRC校验、密码管理
• 📦 数据处理: 序列化优化、内存管理、错误处理

性能优势: | 操作类型 | C# 版本 | C++ 版本 | 性能提升 | |---------|---------|---------|---------| | 消息构建 | ~0.1ms | ~0.05ms | 2x | | 序列化 | ~0.5ms | ~0.2ms | 2.5x | | 解析 | ~0.8ms | ~0.3ms | 2.7x |

4. ConsoleTestApp - 演示应用

项目类型: .NET 8.0 控制台应用
主要用途: 功能演示、性能测试、配置示例

演示功能:

• 🔧 核心功能演示: 消息构建器、状态配置系统
• 🏭 状态配置演示: 设备类型注册、状态定义、验证规则
• 🔐 安全功能演示: AES模式对比、加密配置、密码管理
• 📊 性能测试演示: 序列化性能、加密性能、内存监控
• 🏭 工厂模式演示: 快速解析、设备状态配置

命令行参数:

dotnet run -- state          # 设备状态配置演示
dotnet run -- aes            # AES模式配置演示
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            # 性能修复验证

🚀 快速开始

环境要求

• .NET 8.0+ SDK
• C++17 编译器（可选，用于C++版本）
• CMake 3.15+（可选，用于C++构建）

📚 文档导航

项目提供完整的文档体系，包含32个详细文档：

• 📖 Wiki文档中心 - 完整的文档导航
• 🚀 入门指南 - 快速上手教程
• 💡 最佳实践 - 性能优化、安全配置、错误处理、代码规范
• 🔧 故障排除 - 常见问题、调试技巧、性能诊断、兼容性
• 📋 API参考 - 完整的API文档
• 💻 示例代码 - 基础、高级、集成示例

基本使用

1. 安装依赖

# 克隆仓库
git clone https://gitee.com/ruan-yong/device-commons.git
cd device-commons

# 还原依赖
dotnet restore

2. 运行测试

# 运行所有测试
dotnet test

# 运行特定测试项目
dotnet test TestProject1/
dotnet test ConsoleTestApp/

# 运行特定测试类别
dotnet test TestProject1/ --filter "Category=Security"
dotnet test TestProject1/ --filter "Category=Performance"

3. 运行演示

# 运行设备状态配置演示
dotnet run --project ConsoleTestApp -- state

# 运行AES性能测试
dotnet run --project ConsoleTestApp -- performance

# 运行工厂模式演示
dotnet run --project ConsoleTestApp -- builder

4. 构建C++版本

# Windows
cd "DeviceCommons(C++)"
build.bat

# Linux/macOS
cd "DeviceCommons(C++)"
./build.sh

🔐 核心功能特性

设备消息处理

• 消息构建器模式：流畅的API设计，支持链式调用
• 多协议版本支持：兼容不同版本的设备通信协议
• 灵活的设备结构：支持主设备和子设备的层次结构
• 工厂模式支持：设备状态配置注册和快速解析

状态工厂系统

• 可配置状态工厂：支持运行时状态配置注册
• 状态类型管理：完整的 StateValueTypeEnum 支持
• 验证规则引擎：自定义状态验证逻辑
• 快速解析：基于注册配置的直接状态值提取

安全功能

• AES加密双模式：
  • 快速模式：1000次PBKDF2迭代，启用密钥缓存，适合开发测试
  • 安全模式：60000次PBKDF2迭代，适合生产环境
• CRC校验：数据完整性验证
• 密码管理：灵活的加密密码配置
• 线程安全：ThreadLocal<T>确保并发安全

数据处理

• GZip压缩：高效的数据压缩
• 消息池管理：内存优化的消息对象池
• 序列化优化：高性能的消息序列化
• 内存优化：使用ArrayPool减少内存分配

🏗️ 依赖注入支持

服务注册

services.AddDeviceCommons()
    .WithDefaultAesEncryption("password", AesMode.Fast)
    .WithDefaultGZipCompression()
    .AddStateFactory<CustomStateFactory>(deviceType: 0x10);

配置选项

// 获取配置
var options = serviceProvider
    .GetRequiredService<IOptions<DeviceCommonsOptions>>().Value;

Console.WriteLine($"加密模式: {options.AesEncryptionMode}");
Console.WriteLine($"启用加密: {options.EnableDefaultAesEncryption}");
Console.WriteLine($"启用压缩: {options.EnableDefaultGZipCompression}");

工厂模式集成

// 注册设备状态配置
services.AddDeviceCommons()
    .AddStateFactory<CustomStateFactory>(deviceType: 0x01);

// 使用工厂模式进行快速解析
var factory = serviceProvider.GetRequiredService<IStateFactoryRegistry>();
var stateFactory = factory.GetFactory(0x01);

📊 性能基准

序列化性能

AES加密性能

压缩效果

🌐 跨平台支持

支持平台

• Windows: .NET 8.0+, C++17 (MSVC/MinGW)
• Linux: .NET 8.0+, C++17 (GCC/Clang)
• macOS: .NET 8.0+, C++17 (Clang)

构建系统

• .NET: MSBuild, dotnet CLI
• C++: CMake, Visual Studio, Make

🧪 测试和调试

运行测试

# 运行所有单元测试
dotnet test

# 运行特定测试
dotnet test TestProject1/Security/EncryptionTests.cs
dotnet test TestProject1/Builders/BuilderAesModeConfigurationTests.cs

# 性能测试
dotnet run --project ConsoleTestApp -- performance

调试工具

# 生成测试报告
dotnet run --project ConsoleTestApp -- record

# 验证表格对齐
dotnet run --project ConsoleTestApp -- verify

# 性能修复验证
dotnet run --project ConsoleTestApp -- fix

# AES性能对比
dotnet run --project ConsoleTestApp -- aes

📚 API参考

详细的API文档请参考：📋 API参考文档

核心接口

• IDeviceMessageBuilder - 消息构建器接口
• IDeviceMessageSerializer - 序列化器接口
• IDeviceMessageParser - 解析器接口
• IDeviceCommonsConfigurationService - 配置服务接口
• IStateFactory - 状态工厂接口
• IStateFactoryRegistry - 状态工厂注册表接口

主要类

• DeviceMessageBuilder - 消息构建器实现
• DeviceMessage - 设备消息模型
• AesEncryptor - AES加密器（双模式支持）
• DeviceCommonsOptions - 配置选项
• PerformanceStats - 性能统计
• DeviceMessageValidator - 消息验证器

枚举类型

• AesMode - AES加密模式（Fast/Secure）
• CRCTypeEnum - CRC校验类型
• StateValueTypeEnum - 状态值类型
• TimeStampFormatEnum - 时间戳格式

工厂模式

• DeviceStateConfigurationRegistry - 设备状态配置注册表
• FastReadingStateFactory - 快速读取状态工厂
• IDeviceStateConfiguration - 设备状态配置接口

🤝 贡献指南

开发环境设置

1. 克隆仓库：git clone https://gitee.com/ruan-yong/device-commons.git
2. 安装.NET 8.0+ SDK
3. 安装C++17编译器（可选）
4. 运行测试：dotnet test

代码规范

• 遵循.NET编码标准
• 使用有意义的变量和方法名
• 添加XML文档注释
• 编写单元测试
• 支持中文注释

提交流程

1. Fork项目
2. 创建功能分支：git checkout -b feature/new-feature
3. 提交更改：git commit -am 'Add new feature'
4. 推送分支：git push origin feature/new-feature
5. 创建Pull Request

📄 许可证

本项目采用 MIT 许可证。

🆘 支持和帮助

常见问题

Q: 如何选择AES加密模式？
A: 开发和测试环境建议使用快速模式，生产环境使用安全模式。详细说明请参考：安全配置最佳实践

Q: 支持哪些数据类型？
A: 支持字符串、二进制、整数、浮点数、布尔值、时间戳等多种类型。完整列表请参考：消息模型文档

Q: 如何优化序列化性能？
A: 使用快速AES模式、启用压缩、合理设计数据结构、使用工厂模式进行快速解析。详细指南请参考：性能优化最佳实践

Q: 工厂模式有什么优势？
A: 工厂模式支持设备状态配置注册，可以实现基于配置的直接状态值提取，避免逐层解析，大幅提升性能。

获取帮助

• 📖 完整文档中心 - 32个详细文档
• 🔧 故障排除指南 - 常见问题和解决方案
• 💻 示例代码 - 可直接运行的代码示例
• 运行内置的演示程序
• 提交Issue反馈问题
• 参与社区讨论

版本历史

• v2.3.0 - 添加工厂模式、AES双模式优化、性能提升、完整文档体系（32个文档）
• v2.0 - 添加依赖注入支持、AES双模式、性能优化
• v1.0 - 基础序列化功能、V1/V2协议支持

📞 项目导航

<div align="center">

DeviceCommons - 让IoT设备通信更简单、更安全、更高效

快速开始 • 文档中心 • API文档 • 贡献指南

</div>