# DeviceCommons

**Repository Path**: ruan-yong/device-commons

## Basic Information

- **Project Name**: DeviceCommons
- **Description**: 这是一个用于高效序列化/反序列化 IoT 设备消息的高性能 .NET 工具库，支持压缩、加密、CRC 校验及灵活的扩展结构。
- **Primary Language**: C#
- **License**: Apache-2.0
- **Default Branch**: master
- **Homepage**: None
- **GVP Project**: No

## Statistics

- **Stars**: 1
- **Forks**: 1
- **Created**: 2025-08-25
- **Last Updated**: 2025-09-10

## Categories & Tags

**Categories**: Uncategorized

**Tags**: 军工级AES加密, 高性能IoT通信框架, 零分配内存优化, 工业级协议, CleanArchitecture

## README

# DeviceCommons - 设备通信通用库

[![.NET](https://img.shields.io/badge/.NET-8.0+-blue.svg)](https://dotnet.microsoft.com/)
[![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.3.0-blue.svg)]()

> 专为物联网（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](DeviceCommons/README.md) - 核心库

**项目类型**: .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](TestProject1/README.md) - 单元测试套件

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

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

**测试工具**:
- **BaseUnitTest**: 单元测试基类
- **BaseTestClass**: 测试基类
- **TestDataBuilder**: 测试数据生成器

### 3. [DeviceCommons(C++)](DeviceCommons(C++)/README.md) - 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](ConsoleTestApp/README.md) - 演示应用

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

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

**命令行参数**:
```bash
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文档中心](wiki/README.md)** - 完整的文档导航
- **🚀 [入门指南](wiki/md/01-入门指南/README.md)** - 快速上手教程
- **💡 [最佳实践](wiki/md/05-最佳实践/README.md)** - 性能优化、安全配置、错误处理、代码规范
- **🔧 [故障排除](wiki/md/06-故障排除/README.md)** - 常见问题、调试技巧、性能诊断、兼容性
- **📋 [API参考](wiki/md/07-API参考/README.md)** - 完整的API文档
- **💻 [示例代码](wiki/md/08-示例代码/README.md)** - 基础、高级、集成示例

### 基本使用

#### 1. 安装依赖
```bash
# 克隆仓库
git clone https://gitee.com/ruan-yong/device-commons.git
cd device-commons

# 还原依赖
dotnet restore
```

#### 2. 运行测试
```bash
# 运行所有测试
dotnet test

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

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

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

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

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

#### 4. 构建C++版本
```bash
# 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减少内存分配

## 🏗️ 依赖注入支持

### 服务注册
```csharp
services.AddDeviceCommons()
    .WithDefaultAesEncryption("password", AesMode.Fast)
    .WithDefaultGZipCompression()
    .AddStateFactory<CustomStateFactory>(deviceType: 0x10);
```

### 配置选项
```csharp
// 获取配置
var options = serviceProvider
    .GetRequiredService<IOptions<DeviceCommonsOptions>>().Value;

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

### 工厂模式集成
```csharp
// 注册设备状态配置
services.AddDeviceCommons()
    .AddStateFactory<CustomStateFactory>(deviceType: 0x01);

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

## 📊 性能基准

### 序列化性能
| 操作类型 | 平均耗时 | 吞吐量 | 内存使用 |
|---------|---------|--------|---------|
| 构建消息 | ~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加密性能
| 加密模式 | 首次加密 | 缓存加密 | 性能提升 |
|---------|---------|---------|---------|
| 快速模式 | ~2ms | ~0.1ms | 20x |
| 安全模式 | ~120ms | ~120ms | 1x |

### 压缩效果
| 数据类型 | 原始大小 | 压缩后 | 压缩比 |
|---------|---------|--------|--------|
| 文本数据 | 1KB | ~300B | 70% |
| 重复数据 | 5KB | ~200B | 96% |
| 随机数据 | 10KB | ~9.8KB | 2% |

## 🌐 跨平台支持

### 支持平台
- **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

## 🧪 测试和调试

### 运行测试
```bash
# 运行所有单元测试
dotnet test

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

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

### 调试工具
```bash
# 生成测试报告
dotnet run --project ConsoleTestApp -- record

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

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

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

## 📚 API参考

详细的API文档请参考：[📋 API参考文档](wiki/md/07-API参考/README.md)

### 核心接口
- `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 许可证](LICENSE)。

## 🆘 支持和帮助

### 常见问题

**Q: 如何选择AES加密模式？**  
A: 开发和测试环境建议使用快速模式，生产环境使用安全模式。详细说明请参考：[安全配置最佳实践](wiki/md/05-最佳实践/02-安全配置.md)

**Q: 支持哪些数据类型？**  
A: 支持字符串、二进制、整数、浮点数、布尔值、时间戳等多种类型。完整列表请参考：[消息模型文档](wiki/md/02-核心概念/02-消息模型.md)

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

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

### 获取帮助
- **📖 [完整文档中心](wiki/README.md)** - 32个详细文档
- **🔧 [故障排除指南](wiki/md/06-故障排除/README.md)** - 常见问题和解决方案
- **💻 [示例代码](wiki/md/08-示例代码/README.md)** - 可直接运行的代码示例
- 运行内置的演示程序
- 提交Issue反馈问题
- 参与社区讨论

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

## 📞 项目导航

| 项目 | 类型 | 描述 | 文档 |
|------|------|------|------|
| [DeviceCommons](DeviceCommons/README.md) | .NET 库 | 核心功能库 | [📖 详细文档](DeviceCommons/README.md) |
| [TestProject1](TestProject1/README.md) | 测试项目 | 单元测试套件 | [🧪 测试文档](TestProject1/README.md) |
| [DeviceCommons(C++)](DeviceCommons(C++)/README.md) | C++ 库 | C++版本实现 | [🔧 C++文档](DeviceCommons(C++)/README.md) |
| [ConsoleTestApp](ConsoleTestApp/README.md) | 演示应用 | 功能演示和测试 | [🎯 演示文档](ConsoleTestApp/README.md) |
| [📚 Wiki文档中心](wiki/README.md) | 文档 | 完整文档体系 | [📖 32个详细文档](wiki/README.md) |

---

<div align="center">

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

[快速开始](#-快速开始) • [文档中心](wiki/README.md) • [API文档](wiki/md/07-API参考/README.md) • [贡献指南](#-贡献指南)

</div>