Iotgateway技术手册-10. 开发指南

10. 开发指南

本指南将帮助开发者快速上手 IoT Gateway 项目的开发，包括项目结构、开发流程、编码规范和最佳实践。

Iotgateway 网关

10.1 项目结构

10.1.1 目录结构

iotgateway/
├── IoTGateway/              # 主应用程序
│   ├── Areas/               # MVC 区域
│   │   ├── BasicData/       # 基础数据管理
│   │   ├── Config/          # 系统配置
│   │   └── Rpc/             # RPC 管理
│   ├── Controllers/         # 控制器
│   ├── Properties/          # 属性文件
│   ├── Resources/           # 资源文件
│   ├── Views/               # 视图
│   ├── wwwroot/             # 静态资源
│   ├── Program.cs           # 程序入口
│   ├── Startup.cs           # 启动配置
│   └── appsettings.json     # 配置文件
├── IoTGateway.DataAccess/   # 数据访问层
│   ├── Migrations/          # 数据库迁移
│   └── DataContext.cs       # 数据上下文
├── IoTGateway.Model/        # 数据模型层
│   ├── Device.cs            # 设备模型
│   ├── Driver.cs            # 驱动模型
│   └── ...                  # 其他模型
├── IoTGateway.ViewModel/    # 视图模型层
│   ├── BasicData/           # 基础数据视图模型
│   └── HomeVMs/             # 首页视图模型
├── Plugins/                 # 插件目录
│   ├── Plugin/              # 核心插件
│   └── PluginInterface/     # 插件接口
├── technical_details/       # 技术文档
└── IoTGateway.sln           # 解决方案文件

10.1.2 项目依赖关系

┌─────────────────────────────────────────────────────────────────┐
│                        IoTGateway                              │
└─────────────────────────────────────────────────────────────────┘
            │
            ├─ 依赖 ──► ┌─────────────────────────────────────┐
            │           │      IoTGateway.DataAccess          │
            │           └─────────────────────────────────────┘
            │                        │
            │                        └─ 依赖 ──► ┌───────────┐
            │                                      │  IoTGateway.Model  │
            │                                      └───────────┘
            │
            ├─ 依赖 ──► ┌─────────────────────────────────────┐
            │           │       IoTGateway.ViewModel          │
            │           └─────────────────────────────────────┘
            │                        │
            │                        └─ 依赖 ──► ┌───────────┐
            │                                      │  IoTGateway.Model  │
            │                                      └───────────┘
            │
            └─ 依赖 ──► ┌─────────────────────────────────────┐
                        │            Plugins.Plugin          │
                        └─────────────────────────────────────┘
                                      │
                                      └─ 依赖 ──► ┌─────────────────┐
                                                    │  Plugins.PluginInterface  │
                                                    └─────────────────┘

10.2 开发环境设置

10.2.1 安装开发工具

1. Visual Studio 2022

   • 下载地址：https://visualstudio.microsoft.com/vs/

   • 安装工作负载：

     • ASP.NET 和 Web 开发

     • .NET 桌面开发

     • .NET 跨平台开发

2. Visual Studio Code（可选）

   • 下载地址：https://code.visualstudio.com/

   • 安装扩展：

     • C# 扩展

     • .NET Core Test Explorer

     • NuGet Package Manager

     • GitLens

3. .NET 6.0 SDK

   • 下载地址：https://dotnet.microsoft.com/download/dotnet/6.0

   • 验证安装：dotnet --version

10.2.2 克隆代码仓库

git clone <repository-url>
cd iotgateway

10.2.3 还原 NuGet 包

dotnet restore

10.2.4 运行应用

# 运行主应用
dotnet run --project IoTGateway
​
# 或使用 Visual Studio 直接运行

10.3 开发流程

10.3.1 分支管理

1. 主分支 (main)

   • 稳定版本分支

   • 只接受从 develop 分支合并的代码

   • 每次合并后打标签，生成发布版本

2. 开发分支 (develop)

   • 开发主分支

   • 接受从 feature 分支合并的代码

   • 定期合并到 main 分支，生成发布版本

3. 特性分支 (feature/xxx)

   • 用于开发新特性

   • 从 develop 分支检出

   • 开发完成后合并回 develop 分支

4. 修复分支 (hotfix/xxx)

   • 用于修复生产环境的紧急问题

   • 从 main 分支检出

   • 修复完成后合并回 main 和 develop 分支

10.3.2 开发步骤

1. 创建特性分支

   git checkout develop
   git pull
   git checkout -b feature/xxx

2. 编写代码

   • 实现新功能或修复bug

   • 遵循编码规范

   • 编写单元测试

3. 运行测试

   dotnet test

4. 提交代码

   git add .
   git commit -m "feat: 实现xxx功能"
   git push origin feature/xxx

5. 创建 Pull Request

   • 在代码托管平台上创建 Pull Request

   • 等待代码审查

   • 解决审查意见

6. 合并代码

   • 代码审查通过后，合并到 develop 分支

   • 删除特性分支

10.3.3 代码审查

1. 审查内容

   • 代码质量和可读性

   • 功能实现正确性

   • 性能和安全性

   • 测试覆盖率

   • 遵循编码规范

2. 审查流程

   • 至少有一名其他开发者审查代码

   • 所有审查意见必须解决

   • 审查通过后才能合并代码

10.4 编码规范

10.4.1 C# 编码规范

1. 命名规范

   • 类名：PascalCase（如 DeviceService）

   • 方法名：PascalCase（如 CreateDeviceThread）

   • 属性名：PascalCase（如 DeviceName）

   • 变量名：camelCase（如 deviceId）

   • 常量名：UPPER_SNAKE_CASE（如 MAX_RETRY_COUNT）

   • 接口名：I + PascalCase（如 IDriver）

   • 命名空间：PascalCase（如 IoTGateway.Model）

2. 代码格式

   • 缩进：4个空格

   • 行长度：不超过120个字符

   • 方法体：不超过50行

   • 类：不超过500行

3. 注释规范

   • 为公共类、方法和属性添加 XML 注释

   • 为复杂逻辑添加单行注释

   • 避免不必要的注释

   • 使用中文注释

4. 代码结构

   • 类成员顺序：静态字段 → 实例字段 → 属性 → 构造函数 → 方法

   • 方法参数：不超过5个

   • 避免深度嵌套（不超过3层）

10.4.2 前端编码规范

1. HTML 规范

   • 使用语义化标签

   • 缩进：4个空格

   • 属性使用双引号

   • 避免内联样式

2. CSS 规范

   • 使用 BEM 命名规范

   • 缩进：4个空格

   • 选择器：不超过3层

   • 避免 !important

3. JavaScript 规范

   • 变量名：camelCase

   • 函数名：camelCase

   • 缩进：4个空格

   • 避免全局变量

   • 使用箭头函数

   • 优先使用 const 和 let

10.4.3 数据库编码规范

1. 表名 ：使用复数形式，如 Devices

2. 列名 ：camelCase，如 deviceName

3. 主键 ：使用 ID 作为主键名

4. 外键 ：使用 {关联表名}Id 作为外键名，如 DriverId

5. 索引：为频繁查询的字段添加索引

6. 命名一致性：数据库列名与模型属性名保持一致

10.5 最佳实践

10.5.1 架构设计

1. 分层架构

   • 严格遵循分层架构设计

   • 各层之间通过接口通信

   • 避免跨层调用

2. 依赖注入

   • 使用依赖注入容器管理组件依赖

   • 避免直接实例化对象

   • 优先使用构造函数注入

3. 接口设计

   • 接口要小而精

   • 遵循单一职责原则

   • 考虑接口的扩展性

10.5.2 性能优化

1. 异步编程

   • 对于 I/O 操作，使用异步方法

   • 避免阻塞调用

   • 使用 async/await 模式

2. 缓存

   • 对于频繁访问的数据，使用缓存

   • 合理设置缓存过期时间

   • 考虑缓存一致性

3. 数据库优化

   • 使用预加载（Include）减少 N+1 查询

   • 避免在循环中执行数据库操作

   • 使用批量操作

   • 合理设计索引

4. 资源管理

   • 及时释放资源

   • 使用 using 语句管理 IDisposable 对象

   • 避免内存泄漏

10.5.3 安全性

1. 输入验证

   • 对所有输入参数进行验证

   • 使用数据注解或 Fluent Validation

   • 防止注入攻击

2. 认证和授权

   • 使用 JWT 进行身份认证

   • 基于角色的访问控制

   • 最小权限原则

3. 数据保护

   • 敏感数据加密存储

   • 传输过程加密

   • 定期更换密钥

4. 安全日志

   • 记录所有安全相关事件

   • 监控异常访问

   • 定期审计日志

10.5.4 测试

1. 测试类型

   • 单元测试：测试单个组件

   • 集成测试：测试组件之间的交互

   • 端到端测试：测试完整的业务流程

2. 测试覆盖率

   • 核心功能测试覆盖率达到 80% 以上

   • 关键路径必须有测试

   • 定期运行测试

3. 测试框架

   • 单元测试：xUnit 或 NUnit

   • 集成测试：xUnit 或 NUnit + TestServer

   • 端到端测试：Selenium 或 Playwright

10.5.5 日志

1. 日志级别

   • Debug：调试信息

   • Information：普通信息

   • Warning：警告信息

   • Error：错误信息

   • Critical：严重错误信息

2. 日志内容

   • 包含时间戳、日志级别、组件名称

   • 包含关键参数和上下文信息

   • 不记录敏感信息

3. 日志存储

   • 开发环境：控制台日志

   • 生产环境：文件日志 + 集中式日志系统

10.6 开发工具

10.6.1 推荐工具

工具	用途	推荐版本
Visual Studio	集成开发环境	2022 或更高
Visual Studio Code	轻量级代码编辑器	最新版本
ReSharper	代码分析和重构工具	最新版本
LINQPad	LINQ 查询和代码测试	最新版本
Postman	API 测试工具	最新版本
Docker	容器化开发	20.10.0 或更高
Git	版本控制	2.30.0 或更高

10.6.2 扩展推荐

1. Visual Studio 扩展

   • ReSharper

   • CodeMaid

   • SonarLint

   • GitHub Copilot

2. Visual Studio Code 扩展

   • C#

   • C# Extensions

   • .NET Core Test Explorer

   • NuGet Package Manager

   • GitLens

   • Prettier

10.7 常见开发任务

10.7.1 添加新模型

1. 在 IoTGateway.Model 项目中创建模型类

2. 在 DataContext.cs 中添加 DbSet

3. 添加数据库迁移

   dotnet ef migrations add AddNewModel --project IoTGateway.DataAccess --startup-project IoTGateway

4. 更新数据库

   dotnet ef database update --project IoTGateway.DataAccess --startup-project IoTGateway

10.7.2 添加新控制器

1. 在 IoTGateway/Controllers 目录中创建控制器类

2. 继承 Controller 或 BaseController

3. 添加路由属性

4. 实现控制器方法

5. 添加对应的视图

10.7.3 添加新驱动

1. 在 Plugins 目录中创建驱动项目

2. 实现 IDriver 接口

3. 添加驱动属性和方法

4. 编译驱动项目

5. 将驱动 DLL 复制到 drivers/net6.0 目录

6. 在 Web 界面中注册驱动

10.7.4 添加新 API 端点

1. 创建 API 控制器

2. 添加 [ApiController] 和 [Route] 属性

3. 实现 API 方法

4. 添加 Swagger 注释

5. 测试 API 端点

10.8 调试技巧

10.8.1 本地调试

1. 设置断点

   • 在代码中设置断点

   • 运行调试模式

   • 单步执行代码

   • 查看变量值

2. 日志调试

   • 添加日志语句

   • 查看日志输出

   • 分析程序流程

3. 远程调试

   • 配置远程调试

   • 连接到远程进程

   • 进行远程调试

10.8.2 调试驱动

1. 将驱动项目添加到解决方案

2. 设置驱动项目为启动项目

3. 配置调试参数

4. 运行调试模式

10.8.3 调试 MQTT 通信

1. 使用 MQTT 客户端工具（如 MQTTX）

2. 订阅相关主题

3. 发布测试消息

4. 查看应用日志

10.9 文档编写

10.9.1 代码文档

1. XML 注释

   • 为公共类、方法和属性添加 XML 注释

   • 使用标准的 XML 注释标签

   • 包含参数、返回值和异常信息

2. 示例

   /// <summary>
   /// 创建设备线程
   /// </summary>
   /// <param name="Device">设备对象</param>
   /// <returns>设备线程对象</returns>
   /// <exception cref="ArgumentNullException">当设备对象为空时抛出</exception>
   public DeviceThread CreateDeviceThread(Device Device)
   {
       // 实现代码
   }

10.9.2 技术文档

1. 文档结构

   • 清晰的标题和目录

   • 详细的内容

   • 代码示例

   • 图表和流程图

2. 更新频率

   • 代码变更时同步更新文档

   • 定期审查和更新文档

   • 保持文档的准确性

10.10 团队协作

10.10.1 沟通工具

• 使用 Slack 或 Microsoft Teams 进行日常沟通

• 使用 Jira 或 Trello 进行任务管理

• 使用 Confluence 或 Wiki 进行文档协作

10.10.2 协作流程

1. 每日站会：汇报工作进展和遇到的问题

2. 每周评审：评审本周工作和下周计划

3. 代码审查：所有代码必须经过审查才能合并

4. 定期培训：分享技术知识和最佳实践

10.11 持续集成和持续部署

10.11.1 CI/CD 流程

1. 持续集成

   • 代码提交后自动构建

   • 运行单元测试和集成测试

   • 代码质量检查

   • 生成构建报告

2. 持续部署

   • 构建成功后自动部署到测试环境

   • 测试通过后自动部署到生产环境

   • 支持蓝绿部署或金丝雀发布

10.11.2 CI/CD 工具

• GitHub Actions

• Azure DevOps

• Jenkins

• GitLab CI

• Travis CI

10.12 常见问题与解决方案

10.12.1 依赖冲突

问题：项目依赖的 NuGet 包版本冲突

解决方案：

• 使用 dotnet list package --include-transitive 查看依赖树

• 在 Directory.Build.props 中统一管理包版本

• 使用 PackageReference 的 VersionOverride 属性

10.12.2 数据库迁移失败

问题：数据库迁移失败，提示表已存在或字段冲突

解决方案：

• 检查迁移文件是否正确

• 手动修改迁移文件

• 回滚到上一个迁移版本

• 重新生成迁移文件

10.12.3 驱动加载失败

问题：驱动无法加载，提示找不到依赖项

解决方案：

• 检查驱动依赖是否完整

• 将驱动依赖复制到驱动目录

• 使用 dotnet publish 命令发布驱动

• 检查驱动版本是否与网关兼容

---

文档版本 ：1.0 更新日期 ：2025-11-29 编写人员：辉为科技