基于设计模式的Winform软件框架-03MySQL数据库(Repository 模式+单例模式+工厂模式+策略模式+生产者-消费者模式)

目录

1. 项目概述
2. 架构设计
3. 核心设计模式原理
4. 核心概念与实现
5. 详细API文档
6. 移植指南
7. 性能优化
8. 常见问题FAQ
9. 附录

---

一、项目概述

1.1 什么是 Related_MySQL？

Related_MySQL 是一个专为工业自动化场景设计的数据库持久化类库，基于 SqlSugar ORM 框架封装，提供统一的数据访问接口。

核心功能：

功能模块	说明	典型用途
业务驱动写入	事件触发的立即写入	报警记录、用户操作、审计日志
持续数据写入	高频数据的缓冲批量写入	轴数据、IO数据、传感器数据
泛型仓储模式	统一的数据访问接口	所有实体表的增删改查
连接管理	数据库连接的单例和独立连接	多线程安全的数据库操作

1.2 解决的核心问题

问题	传统方案	Related_MySQL 方案
高频数据写入性能差	逐条插入，每条 5ms	缓冲队列批量插入，100 条仅需 10ms
代码重复，每个表都要写服务	每个表一个 Service 类	泛型仓储，一个类处理所有表
业务数据和持续数据混在一起	统一处理，无法优化	分类处理，不同策略不同优化
多线程数据库操作冲突	共享连接，并发错误	独立连接，线程安全
数据库连接管理混乱	到处 new 连接	单例 + 工厂，统一管理

1.3 核心特性

• ✅ 高性能批量写入：缓冲队列 + 定时刷新，性能提升 50 倍
• ✅ 泛型仓储模式：统一的增删改查接口，减少 90% 重复代码
• ✅ 双模式写入策略：业务驱动立即写入，持续数据批量写入
• ✅ 线程安全设计：独立连接 + 线程安全队列，支持多线程并发
• ✅ 异步操作支持：完整的异步 API，高并发场景性能更佳
• ✅ 零业务侵入：基于接口和标记接口，业务代码无需修改
• ✅ 灵活配置：预设配置 + 自定义配置，适应不同场景

1.4 适用场景

场景类型	推荐方案	原因
报警信息、用户操作	BusinessServiceManager	事件驱动，需要立即写入
轴数据、IO数据	ContinuousServiceManager	高频采集，需要批量写入优化
配置表、字典表	SqlSugarRepository	低频查询，直接使用仓储
报表统计	SqlSugarRepository	复杂查询，仓储提供的 Query 方法

---

二、架构设计

2.1 整体架构图

┌─────────────────────────────────────────────────────────────────────┐
│                        Related_MySQL 架构                            │
├─────────────────────────────────────────────────────────────────────┤
│                                                                     │
│  ┌─────────────────────────────────────────────────────────────┐    │
│  │                   业务层（调用方）                             │    │
│  │  - PLC采集线程                                                │    │
│  │  - 报警处理线程                                               │    │
│  │  - 用户操作事件                                               │    │
│  └──────────────────────┬──────────────────────────────────────┘    │
│                         │                                           │
│                         ▼                                           │
│  ┌─────────────────────────────────────────────────────────────┐    │
│  │                   服务管理层                                  │    │
│  │  ┌────────────────────────┐  ┌─────────────────────────┐    │    │
│  │  │ BusinessServiceManager │  │ ContinuousServiceManager │    │    │
│  │  │ (单例)                  │  │ (单例)                  │    │    │
│  │  │ - 报警信息              │  │ - 轴数据                │    │    │
│  │  │ - 用户操作              │  │ - IO数据                │    │    │
│  │  │ - 审计日志              │  │ - 传感器数据            │    │    │
│  │  └───────────┬────────────┘  └───────────┬─────────────┘    │    │
│  │              │                          │                    │    │
│  │              └──────────┬───────────────┘                    │    │
│  │                         ▼                                    │    │
│  │              ┌───────────────────────┐                       │    │
│  │              │ SqlSugarRepository<T> │                       │    │
│  │              │ (泛型仓储)             │                       │    │
│  │              └───────────┬───────────┘                       │    │
│  └──────────────────────────┼───────────────────────────────────┘    │
│                             │                                          │
│  ┌──────────────────────────┼───────────────────────────────────┐    │
│  │         持续写入层          │                                   │    │
│  │  ┌───────────────────────────────────────────────────────┐   │    │
│  │  │         ContinuousDataWriter<T>                        │   │    │
│  │  │         缓冲队列 + 定时刷新                              │   │    │
│  │  │  ┌─────────────────┐    ┌──────────────────────────┐  │   │    │
│  │  │  │ ConcurrentQueue │    │  Timer (定时刷新)         │  │   │    │
│  │  │  │ (线程安全队列)   │    │  - 500ms/1000ms/3000ms   │  │   │    │
│  │  │  └─────────────────┘    └──────────────────────────┘  │   │    │
│  │  └───────────────────────────────────────────────────────┘   │    │
│  └──────────────────────────┼───────────────────────────────────┘    │
│                             │                                          │
│  ┌──────────────────────────┼───────────────────────────────────┐    │
│  │        数据访问层          │                                   │    │
│  │  ┌───────────────────────────────────────────────────────┐   │    │
│  │  │              SqlSugarHelper                            │   │    │
│  │  │  ┌─────────────────────┐  ┌─────────────────────────┐ │   │    │
│  │  │  │ SqlSugarClient      │  │ GetScopedClient()        │ │   │    │
│  │  │  │ (主连接，单例)       │  │ (独立连接，工厂)          │ │   │    │
│  │  │  │ - 用于简单操作       │  │ - 用于多线程操作          │ │   │    │
│  │  │  │ - 串行执行           │  │ - 并发执行，线程安全      │ │   │    │
│  │  │  └─────────────────────┘  └─────────────────────────┘ │   │    │
│  │  └───────────────────────────────────────────────────────┘   │    │
│  └──────────────────────────┼───────────────────────────────────┘    │
│                             │                                          │
│                             ▼                                          │
│  ┌─────────────────────────────────────────────────────────────┐    │
│ │                    MySQL 数据库                                  │    │
│  │  - 业务驱动表（报警信息、用户操作）                            │    │
│  │  - 持续写入表（轴数据、IO数据）                                │    │
│  │  - 配置表、字典表                                              │    │
│  └─────────────────────────────────────────────────────────────┘    │
│                                                                     │
└─────────────────────────────────────────────────────────────────────┘

2.2 设计模式总览

设计模式	应用位置	作用
Repository 模式	IRepository<T> + SqlSugarRepository<T>	封装数据访问逻辑，与业务逻辑分离
单例模式	SqlSugarHelper, BusinessServiceManager, ContinuousServiceManager	全局唯一实例，统一管理资源
工厂模式	SqlSugarHelper.GetScopedClient()	创建独立连接对象
策略模式	IBusinessEntity vs IContinuousEntity	不同数据类型使用不同写入策略
生产者-消费者模式	ContinuousDataWriter<T>	缓冲队列批量写入，解耦生产和消费
泛型编程	所有核心类	一个类处理所有实体类型

2.3 类图

┌─────────────────────────────────────────────────────────────────────────┐
│                           业务层（调用方）                                 │
└──────────────────────────────────────┬────────────────────────────────────┘
                                       │
                ┌──────────────────────┴──────────────────────┐
                ▼                                              ▼
┌─────────────────────────────────────────┐  ┌───────────────────────────────────┐
│   BusinessServiceManager (单例)        │  │  ContinuousServiceManager (单例)  │
│  ┌─────────────────────────────────┐   │  │  ┌─────────────────────────────┐ │
│  │ Dictionary<Type, IRepository>  │   │  │  │ Dictionary<string, Writer>  │ │
│  │ (仓储缓存，按类型索引)           │   │  │  │ (写入器字典，按名称索引)     │ │
│  └──────────────┬──────────────────┘   │  │  └──────────────┬──────────────┘ │
└─────────────────┼──────────────────────┘  └─────────────────┼────────────────┘
                  │                                          │
                  ▼                                          ▼
┌─────────────────────────────────────────┐  ┌───────────────────────────────────┐
│      IRepository<T> (接口)              │  │  ContinuousDataWriter<T>           │
│  ┌───────────────────────────────────┐ │  │  ┌─────────────────────────────┐  │
│  │ Insert/Update/Delete/Query        │ │  │  │ ConcurrentQueue<T>           │  │
│  │ (增删改查方法声明)                 │ │  │  │ Timer (定时刷新)             │  │
│  └──────────────┬────────────────────┘ │  │  │ Enqueue/Flush                │  │
└─────────────────┼──────────────────────┘  │  └──────────────┬──────────────┘  │
                  │                         └─────────────────┼────────────────┘
                  ▼                                          │
┌─────────────────────────────────────────┐                  │
│  SqlSugarRepository<T> (实现类)         │                  │
│  ┌───────────────────────────────────┐ │                  │
│  │ using (db = GetScopedClient())     │ │                  │
│  │ db.Insertable().ExecuteCommand()  │ │                  │
│  └──────────────┬────────────────────┘ │                  │
└─────────────────┼──────────────────────┘                  │
                  │                                          │
                  └──────────────────┬───────────────────────┘
                                     ▼
                  ┌────────────────────────────────────────┐
                  │         SqlSugarHelper (单例)          │
                  │  ┌──────────────────────────────────┐   │
                  │  │ SqlSugarClient (主连接)          │   │
                  │  │ - 单例，全局唯一                  │   │
                  │  │ - 用于简单操作                   │   │
                  │  └──────────────────────────────────┘   │
                  │  ┌──────────────────────────────────┐   │
                  │  │ GetScopedClient() (工厂)         │   │
                  │  │ - 每次创建新连接                 │   │
                  │  │ - 用于多线程操作                 │   │
                  │  └──────────────────────────────────┘   │
                  └────────────────────────────────────────┘
                                     │
                                     ▼
                  ┌────────────────────────────────────────┐
                  │            MySQL 数据库                 │
                  └────────────────────────────────────────┘

2.4 数据流转图

2.4.1 业务驱动数据流

┌─────────────────────────────────────────────────────────────────┐
│                         报警触发事件                              │
└────────────────────────────┬────────────────────────────────────┘
                             │
                             ▼
┌─────────────────────────────────────────────────────────────────┐
│               BusinessServiceManager.Instance                   │
│  .Insert(new AlarmInfoEntity { ... })                           │
└────────────────────────────┬────────────────────────────────────┘
                             │
                             ▼
┌─────────────────────────────────────────────────────────────────┐
│              GetOrCreateRepository<AlarmInfoEntity>()            │
│  (从缓存获取或创建仓储实例)                                       │
└────────────────────────────┬────────────────────────────────────┘
                             │
                             ▼
┌─────────────────────────────────────────────────────────────────┐
│                SqlSugarRepository<AlarmInfoEntity>              │
│  .Insert(entity)                                                 │
└────────────────────────────┬────────────────────────────────────┘
                             │
                             ▼
┌─────────────────────────────────────────────────────────────────┐
│              SqlSugarHelper.GetScopedClient()                    │
│  (创建独立数据库连接)                                             │
└────────────────────────────┬────────────────────────────────────┘
                             │
                             ▼
┌─────────────────────────────────────────────────────────────────┐
│              db.Insertable(entity).ExecuteCommand()              │
│  (执行 SQL: INSERT INTO AlarmInfo ...)                          │
└────────────────────────────┬────────────────────────────────────┘
                             │
                             ▼
┌─────────────────────────────────────────────────────────────────┐
│                    MySQL 数据库                                   │
│  表：AlarmInfo                                                   │
└─────────────────────────────────────────────────────────────────┘

2.4.2 持续数据流

┌─────────────────────────────────────────────────────────────────┐
│                    PLC 采集线程（100Hz）                         │
└────────────────────────────┬────────────────────────────────────┘
                             │
                             │ 每 10ms 采集一次
                             │
                             ▼
┌─────────────────────────────────────────────────────────────────┐
│         ContinuousServiceManager.Instance                      │
│  .Enqueue(new AxisDataEntity { ... })                            │
└────────────────────────────┬────────────────────────────────────┘
                             │ 入队（<0.01ms，非阻塞）
                             ▼
┌─────────────────────────────────────────────────────────────────┐
│              ContinuousDataWriter<AxisDataEntity>                │
│  ┌─────────────────────────────────────────────────────────┐   │
│  │         ConcurrentQueue<AxisDataEntity>                  │   │
│  │  [数据1] [数据2] [数据3] ... [数据N]                      │   │
│  │         ↑                                                 │   │
│  │         │ 入队                                            │   │
│  └─────────────────────────────────────────────────────────┘   │
└────────────────────────────┬────────────────────────────────────┘
                             │
                             │ Timer: 每 500ms 触发一次
                             │
                             ▼
┌─────────────────────────────────────────────────────────────────┐
│                      FlushBuffer()                                │
│  (后台消费者线程)                                                 │
│  1. 从队列取出最多 200 条数据                                     │
│  2. db.Insertable().ExecuteCommand()                            │
│  3. 批量写入数据库                                                │
└────────────────────────────┬────────────────────────────────────┘
                             │
                             ▼
┌─────────────────────────────────────────────────────────────────┐
│                    MySQL 数据库                                   │
│  表：AxisData                                                     │
│  (一次批量写入 200 条，耗时约 10ms)                               │
└─────────────────────────────────────────────────────────────────┘

2.5 文件结构

Related_MySQL/
├── Core/
│   ├── Entities/
│   │   ├── IBusinessEntity.cs          ← 业务写入实体标记接口
│   │   └── IContinuousEntity.cs        ← 持续写入实体标记接口
│   └── Interfaces/
│       └── IRepository.cs              ← 泛型仓储接口
├── Infrastructure/
│   ├── SqlSugar/
│   │   ├── SqlSugarHelper.cs           ← 数据库连接管理（单例 + 工厂）
│   │   └── SqlSugarRepository.cs       ← 泛型仓储实现
│   └── Continuous/
│       ├── ContinuousDataWriter.cs     ← 持续数据写入器
│       └── WriterConfig.cs             ← 写入器配置
├── Services/
│   ├── Business/
│   │   └── BusinessServiceManager.cs  ← 业务服务管理器（单例）
│   └── Continuous/
│       └── ContinuousServiceManager.cs ← 持续服务管理器（单例）
├── Models/
│   ├── Business/
│   │   ├── AlarmInfoEntity.cs          ← 报警信息实体（示例）
│   │   ├── UserInfoEntity.cs           ← 用户信息实体（示例）
│   │   └── AuthInfoEntity.cs           ← 认证信息实体（示例）
│   └── Continuous/
│       └── SystemStatusEntity.cs       ← 系统状态实体（示例）
└── Related_MySQL_技术文档_V2.0.md       ← 本文档

---

三、核心设计模式原理

本章目标：深入理解类库使用的核心设计模式，掌握其原理并能够应用到自己的项目中。

3.1 Repository（仓储）模式原理详解

3.1.1 什么是 Repository 模式？

Repository 模式是一种数据访问设计模式，它将数据库访问逻辑封装起来，与业务逻辑分离。

生活中的类比：

• 仓库管理员：你去仓库取货，不需要知道货物具体放在哪个货架，只需要告诉管理员你要什么，管理员会帮你找到。
• 图书馆：你借书时不需要知道书在哪个书架，只需要告诉图书管理员书名或ISBN，管理员会帮你找到。

3.1.2 为什么需要 Repository 模式？

没有 Repository 模式的痛点：

// ❌ 传统方式：业务逻辑和数据访问逻辑混在一起
public void ProcessAlarm()
{
    // 业务逻辑
    if (temperature > 100)
    {
        // 数据访问逻辑直接写在业务中
        using (var conn = new MySqlConnection(connectionString))
        {
            conn.Open();
            string sql = "INSERT INTO AlarmInfo ...";
            var cmd = new MySqlCommand(sql, conn);
            cmd.ExecuteNonQuery();
        }
    }
}

// 问题：
// 1. 每个方法都要重复写连接、打开、执行的代码
// 2. 业务逻辑和数据访问逻辑混在一起，难以维护
// 3. 更换数据库需要修改所有方法
// 4. 难以进行单元测试（无法 Mock 数据库访问）

使用 Repository 模式：

// ✅ Repository 模式：业务逻辑和数据访问逻辑分离
public void ProcessAlarm()
{
    // 业务逻辑
    if (temperature > 100)
    {
        // 数据访问通过接口
        _alarmRepository.Insert(new AlarmInfoEntity { ... });
    }
}

// 优势：
// 1. 业务逻辑清晰，不包含数据访问细节
// 2. 更换数据库只需修改 Repository 实现
// 3. 可以 Mock 接口进行单元测试
// 4. 代码复用性高，所有表共用同一个仓储

3.1.3 Repository 模式的实现

接口定义（抽象层）

/// <summary>
/// 泛型仓储接口
/// </summary>
/// <typeparam name="T">实体类型</typeparam>
public interface IRepository<T> where T : class, new()
{
    // 增删改查方法
    OperateResult Insert(T entity);
    OperateResult Update(T entity);
    OperateResult Delete(Expression<Func<T, bool>> where);
    IEnumerable<T> Query(Expression<Func<T, bool>> where);
    T GetById(object id);
    IEnumerable<T> GetAll();
    int Count(Expression<Func<T, bool>> where);
}

实现类（具体层）

/// <summary>
/// SqlSugar 仓储实现
/// </summary>
public class SqlSugarRepository<T> : IRepository<T> where T : class, new()
{
    public OperateResult Insert(T entity)
    {
        using (var db = SqlSugarHelper.GetScopedClient())
        {
            int result = db.Insertable(entity).ExecuteCommand();
            return result == 1 
                ? OperateResult.CreateSuccessResult() 
                : OperateResult.CreateFailResult("插入失败");
        }
    }

    // 其他方法实现...
}

使用方式

// 创建报警仓储
IRepository<AlarmInfoEntity> alarmRepo = new SqlSugarRepository<AlarmInfoEntity>();

// 插入数据
alarmRepo.Insert(new AlarmInfoEntity { ... });

// 查询数据
var alarms = alarmRepo.Query(x => x.CreateTime > DateTime.Today);

3.1.4 为什么使用泛型？

不使用泛型的问题：

// ❌ 每个表都要写一个仓储
public interface IAlarmRepository
{
    bool Insert(AlarmInfoEntity entity);
    IEnumerable<AlarmInfoEntity> Query(...);
}

public interface IUserRepository
{
    bool Insert(UserInfoEntity entity);
    IEnumerable<UserInfoEntity> Query(...);
}

public class AlarmRepository : IAlarmRepository { ... }
public class UserRepository : IUserRepository { ... }

// 问题：
// - 代码重复：每个仓储的代码结构几乎一样
// - 维护成本高：修改一个功能需要修改所有仓储
// - 表数量增加时，代码量线性增长

使用泛型的优势：

// ✅ 一个仓储处理所有表
public interface IRepository<T> where T : class, new()
{
    OperateResult Insert(T entity);
    IEnumerable<T> Query(Expression<Func<T, bool>> where);
}

public class SqlSugarRepository<T> : IRepository<T> where T : class, new()
{
    // 一个实现处理所有表
}

// 使用：
var alarmRepo = new SqlSugarRepository<AlarmInfoEntity>();
var userRepo = new SqlSugarRepository<UserInfoEntity>();

// 优势：
// - 代码复用：一个类处理所有表
// - 维护成本低：修改一处，所有表生效
// - 表数量增加时，代码量不增长

3.1.5 Repository 模式的 UML 图

┌─────────────────────────────────────────────────────────────────┐
│                        IRepository<T>                              │
│                      (接口，抽象层)                                │
├─────────────────────────────────────────────────────────────────┤
│ + Insert(entity): OperateResult                                   │
│ + Update(entity): OperateResult                                   │
│ + Delete(where): OperateResult                                    │
│ + Query(where): IEnumerable<T>                                    │
│ + GetById(id): T                                                  │
│ + GetAll(): IEnumerable<T>                                        │
│ + Count(where): int                                               │
└────────────────────────────────▲──────────────────────────────────┘
                                  │ 实现
                                  │
┌──────────────────────────────────────────────────────────────────┐
│                     SqlSugarRepository<T>                          │
│                    (实现类，具体层)                                 │
├─────────────────────────────────────────────────────────────────┤
│ + Insert(entity): OperateResult                                   │
│ + Update(entity): OperateResult                                   │
│ + Delete(where): OperateResult                                    │
│ + Query(where): IEnumerable<T>                                    │
│ + GetById(id): T                                                  │
│ + GetAll(): IEnumerable<T>                                        │
│ + Count(where): int                                               │
├─────────────────────────────────────────────────────────────────┤
│ - 使用 SqlSugar ORM 实现具体的数据库操作                            │
│ - 每个操作使用 using 语句管理连接                                   │
└──────────────────────────────────────────────────────────────────┘

---

3.2 单例模式原理详解

3.2.1 什么是单例模式？

单例模式 是一种创建型设计模式，它确保一个类在整个应用程序生命周期中只能有一个实例，并提供一个全局访问点来获取该实例。

生活中的类比：

• 打印机管理器：办公室里可能有多台电脑，但只有一台打印机管理器软件。
• Windows任务管理器：无论你打开多少次任务管理器，系统只允许一个窗口存在。
• 美国总统：同一时间只能有一个现任总统。

3.2.2 为什么在数据访问中使用单例模式？

场景对比：

对比项	多实例（错误做法）	单例（正确做法）
连接管理	每个实例创建自己的连接，连接数失控	全局统一管理，连接数可控
配置管理	每个实例都要读取配置，浪费资源	一次读取，全局共享
资源消耗	内存占用高，GC 压力大	内存占用低，GC 压力小
线程安全	多线程访问多个实例，难以同步	统一锁机制，易于保证线程安全

3.2.3 单例模式的实现方式

方式1：简单单例（非线程安全）

public class SimpleSingleton
{
    private static SimpleSingleton _instance;

    private SimpleSingleton()  // 私有构造函数
    {
    }

    public static SimpleSingleton Instance
    {
        get
        {
            if (_instance == null)
                _instance = new SimpleSingleton();
            return _instance;
        }
    }
}

问题 ：多线程环境下，两个线程可能同时通过 if (_instance == null) 检查，导致创建多个实例！

方式2：线程安全的单例（双重检查锁定）

public class ThreadSafeSingleton
{
    private static ThreadSafeSingleton _instance;
    private static readonly object _lock = new object();

    private ThreadSafeSingleton()
    {
    }

    public static ThreadSafeSingleton Instance
    {
        get
        {
            // 第一次检查：如果实例已存在，直接返回
            if (_instance == null)
            {
                // 加锁，保证只有一个线程能进入
                lock (_lock)
                {
                    // 第二次检查：其他线程可能已经创建了
                    if (_instance == null)
                        _instance = new ThreadSafeSingleton();
                }
            }
            return _instance;
        }
    }
}

工作流程：

线程1和线程2同时调用 Instance
         │
         ▼
    _instance == null? 
         │
    是/Yes ──────────→ 获取锁 _lock
         │                │
         │                │ 等待获取锁
         │                │
         │                ▼
         │         线程1获得锁        线程2等待
         │                │                │
         │                ▼                │
         │         第二次检查:          │
         │         _instance == null?   │
         │                │                │
         │         是/Yes → 创建实例     │
         │                │                │
         │                ▼                │
         │         释放锁 ──────────────→ 线程2获得锁
         │                                  │
         │                                  ▼
         │                         第二次检查:
         │                         _instance == null?
         │                                  │
         │                         否/No → 返回已存在的实例
         │                                  │
         └──────────────────────────────────┘

方式3：本类库使用的写法（BusinessServiceManager）

public class BusinessServiceManager
{
    private static BusinessServiceManager _instance;
    private static readonly object _instanceLock = new object();

    private BusinessServiceManager()  // 私有构造函数
    {
        _repositoryCache = new Dictionary<Type, object>();
    }

    public static BusinessServiceManager Instance
    {
        get
        {
            if (_instance == null)
            {
                lock (_instanceLock)
                {
                    if (_instance == null)
                    {
                        _instance = new BusinessServiceManager();
                    }
                }
            }
            return _instance;
        }
    }
}

3.2.4 单例模式在类库中的应用

// ========== 任何地方都可以这样调用 ==========
// 不需要 new，不需要传递引用
BusinessServiceManager.Instance.Insert(new AlarmInfoEntity { ... });

// ========== 在不同类中使用 ==========
public class AlarmService
{
    public void TriggerAlarm()
    {
        // 直接使用，无需传递
        BusinessServiceManager.Instance.Insert(new AlarmInfoEntity { ... });
    }
}

public class UserService
{
    public void LogLogin()
    {
        // 同一个实例，共享状态（仓储缓存）
        BusinessServiceManager.Instance.Insert(new UserInfoEntity { ... });
    }
}

3.2.5 单例模式的优缺点

优点	缺点
✅ 全局唯一访问点	❌ 难以单元测试（全局状态）
✅ 节省内存资源	❌ 违反单一职责原则（管理自身+创建）
✅ 延迟初始化（用到时才创建）	❌ 隐藏依赖关系（类之间的耦合不明显）
✅ 线程安全（正确实现时）	❌ 可能被滥用（全局变量替代品）

3.2.6 何时使用单例模式？

适用场景：

• ✅ 数据库连接管理
• ✅ 配置管理器
• ✅ 日志服务
• ✅ 线程池
• ✅ 缓存管理器

不适用场景：

• ❌ 普通的业务对象（如用户、订单）
• ❌ 需要多实例的对象（如网络连接）
• ❌ 有状态且需要隔离的对象

---

3.3 生产者-消费者模式原理详解

3.3.1 什么是生产者-消费者模式？

生产者-消费者模式是一种并发设计模式，它解耦了"生产数据"和"处理数据"两个过程，通过一个**缓冲区（队列）**来连接它们。

生活中的类比：

• 餐厅后厨 ：
  • 生产者：厨师（不断炒菜）
  • 队列：出餐口（放菜的地方）
  • 消费者：服务员（取菜送给客人）
• 快递中转站 ：
  • 生产者：快递员（不断送来包裹）
  • 队列：分拣传送带
  • 消费者：派送员（取走包裹派送）

3.3.2 为什么需要消息队列？

场景对比：

对比项	直接写入数据库（传统方式）	消息队列（本类库方式）
写入方式	每次调用立即写数据库	先放入队列，后台批量写
主线程阻塞	每次写入可能耗时 5-50ms	入队耗时 <0.01ms
100条数据总耗时	500-5000ms	入队 <10ms，后台异步处理
用户体验	界面可能卡顿	界面流畅无感
数据库I/O次数	100次（每条1次）	1-2次（批量）

核心优势：

1. 解耦：生产者和消费者互不依赖，可以独立变化
2. 削峰：处理突发大量请求时，队列起到缓冲作用
3. 异步：主线程快速返回，耗时操作在后台执行
4. 批量处理：合并多次写入为一次，减少磁盘I/O

3.3.3 消息队列的工作原理

核心组件

┌──────────────────────────────────────────────────────────────────┐
│                   生产者-消费者模式                                  │
├──────────────────────────────────────────────────────────────────┤
│                                                                  │
│  ┌──────────┐         ┌──────────────┐         ┌──────────┐     │
│  │ 生产者    │  入队   │  消息队列     │  出队   │  消费者   │     │
│  │(多个线程)│ ───────→│ (缓冲区)     │ ───────→│(后台线程)│     │
│  └──────────┘         └──────────────┘         └──────────┘     │
│       │                     │                    │              │
│       │                     │                    │              │
│   PLC采集线程           ConcurrentQueue      Timer触发          │
│  (100Hz, 每10ms)        (线程安全队列)       (每500ms)          │
│                                                                  │
└──────────────────────────────────────────────────────────────────┘

时序图

时间线 ──────────────────────────────────────────────────────────→

PLC采集线程（生产者）:               后台线程（消费者）:
     │                                      │
     │ 采集数据1                            │
     ├─→ Enqueue(数据1) ────────→ [数据1]   │
     ├─→ 立即返回 <0.01ms                   │
     │                                      │
     │ 采集数据2                            │
     ├─→ Enqueue(数据2) ────────→ [数据1, 数据2] │
     ├─→ 立即返回                           │
     │                                      │
     │ 采集数据3                            │
     ├─→ Enqueue(数据3) ────────→ [数据1, 数据2, 数据3, ...] │
     │ ...（继续采集）                       │
     │                                      │ 500ms 后，Timer 触发
     │                                      │
     │                                      ├─→ 从队列取出200条
     │                                      ├─→ 批量写入数据库（一次性）
     │                                      ├─→ 写入完成（约10ms）
     │                                      └─→ 继续等待下一个500ms

3.3.4 本类库中的队列实现

核心代码结构

public class ContinuousDataWriter<T> : IDisposable where T : class, IContinuousEntity, new()
{
    // 线程安全的队列
    private readonly ConcurrentQueue<T> _buffer;

    // 定时器
    private readonly Timer _flushTimer;

    // 写入器配置
    private readonly WriterConfig _config;

    // 构造函数
    public ContinuousDataWriter(WriterConfig config)
    {
        _buffer = new ConcurrentQueue<T>();
        _config = config ?? new WriterConfig();

        // 创建定时器
        _flushTimer = new Timer(
            callback: FlushBuffer,      // 定时触发的回调
            state: null,
            dueTime: _config.FlushInterval,  // 首次触发时间
            period: _config.FlushInterval     // 触发间隔
        );
    }

    // ========== 生产者方法（PLC线程调用） ==========

    public void Enqueue(T data)
    {
        _buffer.Enqueue(data);  // 入队（线程安全，<0.01ms）
    }

    // ========== 消费者方法（后台线程执行） ==========

    private void FlushBuffer(object state)
    {
        // 1. 从队列取出数据（最多 BatchSize 条）
        var batch = new List<T>(_config.BatchSize);
        while (batch.Count < _config.BatchSize && _buffer.TryDequeue(out var item))
        {
            batch.Add(item);
        }

        // 2. 批量写入数据库
        if (batch.Count > 0)
        {
            using (var db = SqlSugarHelper.GetScopedClient())
            {
                db.Insertable(batch).ExecuteCommand();
            }
        }
    }
}

关键技术点解析

1. ConcurrentQueue - 线程安全队列

// 普通队列（非线程安全）
Queue<T> queue = new Queue<T>();
queue.Enqueue(item);     // 多线程同时调用会出错
var item = queue.Dequeue();

// 线程安全队列
ConcurrentQueue<T> queue = new ConcurrentQueue<T>();
queue.Enqueue(item);     // 多线程同时调用安全 ✓
queue.TryDequeue(out item);  // 尝试取出，失败返回false

为什么需要线程安全？

• PLC采集线程（生产者）在入队
• 后台线程（消费者）在出队
• 两个线程同时操作同一个队列，必须使用线程安全的队列

2. Timer - 定时器

// 创建定时器
var timer = new Timer(
    callback: FlushBuffer,      // 定时触发的回调方法
    state: null,                // 传递给回调的参数
    dueTime: 1000,              // 首次触发前延迟1000ms
    period: 1000                // 之后每1000ms触发一次
);

// 停止定时器
timer.Dispose();

与 Thread.Sleep 的区别：

特性	Timer	Thread.Sleep
资源占用	不占用线程	占用一个线程
精确度	高（基于系统定时器）	低（基于线程调度）
灵活性	可随时停止	需要等待结束
性能	高	低

3. 批量处理 - 性能优化的关键

// ❌ 效率低：每次写一条
foreach (var data in dataList)
{
    db.Insertable(data).ExecuteCommand();  // 100次数据库I/O
}

// ✅ 效率高：批量写入
db.Insertable(dataList).ExecuteCommand();  // 1次数据库I/O

性能对比（100条数据）：

• 逐条插入：约 500ms（100次网络往返）
• 批量插入：约 10ms（1次网络往返）
• 性能提升：50倍

3.3.5 完整数据流程图

┌──────────────────────────────────────────────────────────────────┐
│                         PLC采集线程                                │
│  while (true)                                                     │
│  {                                                                 │
│      var axisData = PlcClient.ReadAxisData();                     │
│      ContinuousServiceManager.Instance.Enqueue(axisData);        │
│      Thread.Sleep(10);  // 每10ms采集一次                          │
│  }                                                                 │
└────────────────────────────┬─────────────────────────────────────┘
                             │ Enqueue
                             ▼
┌──────────────────────────────────────────────────────────────────┐
│               ContinuousDataWriter<AxisDataEntity>                 │
│  ┌────────────────────────────────────────────────────────────┐   │
│  │          ConcurrentQueue<AxisDataEntity>                    │   │
│  │  ┌─────┐ ┌─────┐ ┌─────┐ ┌─────┐ ┌─────┐ ┌─────┐           │   │
│  │  │Data1│ │Data2│ │Data3│ │Data4│ │Data5│ │ ... │   ...    │   │
│  │  └─────┘ └─────┘ └─────┘ └─────┘ └─────┘ └─────┘           │   │
│  └────────────────────────────────────────────────────────────┘   │
└────────────────────────────┬─────────────────────────────────────┘
                             │ Timer触发（每500ms）
                             ▼
┌──────────────────────────────────────────────────────────────────┐
│                      FlushBuffer()                                │
│  1. 从队列取出最多200条数据                                        │
│  2. db.Insertable(batch).ExecuteCommand()                        │
│  3. 批量写入数据库（约10ms）                                       │
└────────────────────────────┬─────────────────────────────────────┘
                             │ 写入
                             ▼
┌──────────────────────────────────────────────────────────────────┐
│                       MySQL 数据库                                 │
│  表：AxisData                                                     │
│  (一次批量写入200条)                                               │
└──────────────────────────────────────────────────────────────────┘

3.3.6 队列的优缺点与权衡

优点	缺点	权衡方案
✅ 生产者线程不被阻塞	❌ 程序崩溃可能丢失队列中的数据	程序退出时调用 Flush()
✅ 批量写入，减少I/O	❌ 增加内存消耗	限制队列最大长度
✅ 处理突发流量	❌ 数据有延迟（最多一个刷新间隔）	设置合理的刷新间隔
✅ 线程安全	❌ 调试难度增加	添加队列大小监控

3.3.7 何时使用消息队列？

适用场景：

• ✅ 高频数据写入（如100Hz的轴数据）
• ✅ 大量数据批量写入（如IO数据、传感器数据）
• ✅ 生产速度快、消费速度慢的场景
• ✅ 需要解耦生产和消费的场景

不适用场景：

• ❌ 需要立即确认的操作（如报警信息、用户操作）
• ❌ 数据量极小，直接处理更简单
• ❌ 消息不能丢失且无法容忍延迟

---

3.4 策略模式：业务驱动 vs 持续写入

3.4.1 为什么需要区分两种写入策略？

问题背景：

工业自动化场景中，有两种截然不同的数据类型：

数据类型	业务驱动数据（报警）	持续数据（轴数据）
触发方式	事件触发（温度过高）	周期采集（100Hz）
数据量	小（每天几十条）	大（每秒几百条）
实时性要求	高（必须立即写入）	中（可延迟1-2秒）
性能要求	低（单条插入够用）	高（必须批量优化）

如果用统一策略的问题：

// ❌ 统一策略：都用批量写入
// 问题：报警信息可能被缓冲，延迟2秒才写入
//      用户可能看不到最新的报警

// ❌ 统一策略：都用立即写入
// 问题：轴数据每次采集都立即写入
//      每秒100次写入 × 5ms = 500ms/秒
//      占用大量CPU和数据库资源

解决方案：策略模式

// ✅ 策略模式：不同数据类型使用不同策略
// 报警信息 → 立即写入（BusinessServiceManager）
// 轴数据   → 批量写入（ContinuousServiceManager）

3.4.2 策略模式的实现

标记接口（策略标识）

/// <summary>
/// 业务写入实体标记接口
/// </summary>
public interface IBusinessEntity
{
    DateTime CreateTime { get; set; }
}

/// <summary>
/// 持续写入实体标记接口
/// </summary>
public interface IContinuousEntity
{
    DateTime DataTimestamp { get; set; }
}

实体类（选择策略）

// 报警信息：选择"业务驱动"策略
public class AlarmInfoEntity : IBusinessEntity
{
    public DateTime CreateTime { get; set; }
    public string AlarmMessage { get; set; }
    // ...
}

// 轴数据：选择"持续写入"策略
public class AxisDataEntity : IContinuousEntity
{
    public DateTime DataTimestamp { get; set; }
    public double Position { get; set; }
    // ...
}

服务管理器（策略执行）

// 业务驱动服务：立即写入策略
public class BusinessServiceManager
{
    public OperateResult Insert<T>(T entity) where T : IBusinessEntity
    {
        var repository = GetOrCreateRepository<T>();
        return repository.Insert(entity);  // 立即写入
    }
}

// 持续写入服务：批量写入策略
public class ContinuousServiceManager
{
    public void Enqueue<T>(T data) where T : IContinuousEntity
    {
        var writer = GetWriter<T>();
        writer.Enqueue(data);  // 入队，后台批量写入
    }
}

使用方式

// 报警信息：使用业务驱动服务
BusinessServiceManager.Instance.Insert(
    new AlarmInfoEntity { CreateTime = DateTime.Now, ... }
);

// 轴数据：使用持续写入服务
ContinuousServiceManager.Instance.Enqueue(
    new AxisDataEntity { DataTimestamp = DateTime.Now, ... }
);

3.4.3 策略对比

特性	业务驱动策略	持续写入策略
接口	IBusinessEntity	IContinuousEntity
服务	BusinessServiceManager	ContinuousServiceManager
写入方式	立即写入	缓冲队列批量写入
数据延迟	无延迟	有延迟（可配置）
性能	中（单条插入）	高（批量插入）
适用场景	报警、用户操作、审计日志	轴数据、IO数据、传感器数据

---

四、核心概念与实现

4.1 SqlSugar ORM 框架

4.1.1 什么是 ORM？

**ORM（Object-Relational Mapping）**对象关系映射，是一种将面向对象的语言中的对象与关系数据库中的表进行映射的技术。

传统方式 vs ORM：

// ❌ 传统方式：手写 SQL
using (var conn = new MySqlConnection(connectionString))
{
    conn.Open();
    string sql = "INSERT INTO AlarmInfo (CreateTime, Message) VALUES (@time, @msg)";
    var cmd = new MySqlCommand(sql, conn);
    cmd.Parameters.AddWithValue("@time", DateTime.Now);
    cmd.Parameters.AddWithValue("@msg", "温度过高");
    cmd.ExecuteNonQuery();
}

// ✅ ORM 方式：操作对象
BusinessServiceManager.Instance.Insert(
    new AlarmInfoEntity { CreateTime = DateTime.Now, AlarmMessage = "温度过高" }
);

4.1.2 为什么选择 SqlSugar？

特性	SqlSugar	Entity Framework	Dapper
性能	高（接近原生SQL）	中	最高
易用性	高（中文文档）	中	低（手写SQL）
学习曲线	低	中	中
跨数据库	支持	支持	支持
中文支持	优秀	一般	差
工业场景	推荐	可用	不推荐

4.1.3 SqlSugar 基础

实体定义

[SugarTable("AlarmInfo")]  // 指定表名
public class AlarmInfoEntity
{
    [SugarColumn(IsPrimaryKey = true, Length = 15)]
    public string TimeKey { get; set; }

    [SugarColumn(ColumnDataType = "datetime")]
    public DateTime CreateTime { get; set; }

    [SugarColumn(ColumnDataType = "nvarchar", Length = 200)]
    public string AlarmMessage { get; set; }
}

基本操作

using (var db = SqlSugarHelper.GetScopedClient())
{
    // 插入
    db.Insertable(new AlarmInfoEntity { ... }).ExecuteCommand();

    // 查询
    var list = db.Queryable<AlarmInfoEntity>().Where(x => x.CreateTime > DateTime.Today).ToList();

    // 更新
    db.Updateable(new AlarmInfoEntity { ... }).ExecuteCommand();

    // 删除
    db.Deleteable<AlarmInfoEntity>().Where(x => x.Id == 1).ExecuteCommand();
}

CodeFirst 建表

var manager = new SqlSugarManager();
manager.SetConnectionString("Server=localhost;DataBase=mydb;...");
manager.CreateTable<AlarmInfoEntity>();  // 自动根据实体类创建表

---

4.2 连接管理：单例 vs 独立连接

4.2.1 主连接（单例）

public static SqlSugarClient SqlSugarClient
{
    get
    {
        if (_sqlSugarClient == null)
            RebuildClient();
        return _sqlSugarClient;
    }
}

使用场景：

• 单线程或顺序执行的操作
• 不需要事务的操作
• 简单的查询操作

注意事项：

• 多线程使用会有并发问题
• 不适合多线程环境

4.2.2 独立连接（工厂）

public static SqlSugarClient GetScopedClient()
{
    lock (_dbLock)
    {
        var client = new SqlSugarClient(new ConnectionConfig()
        {
            ConnectionString = _connectionString,
            DbType = DbType.MySql,
            IsAutoCloseConnection = false,  // 手动管理
            InitKeyType = InitKeyType.Attribute
        });
        return client;
    }
}

使用场景：

• 多线程并发操作
• 需要事务的操作
• Repository 操作（推荐）

注意事项：

• 必须使用 using 语句
• 避免连接泄漏

4.2.3 对比总结

特性	主连接	独立连接
数量	全局唯一一个	每次创建新的
生命周期	程序运行期间	用完即释放
线程安全	不安全	安全
性能	高（复用连接）	中（创建开销）
使用方式	SqlSugarHelper.SqlSugarClient	using (var db = GetScopedClient())

---

4.3 两种实体类型

4.3.1 IBusinessEntity - 业务驱动实体

public interface IBusinessEntity
{
    DateTime CreateTime { get; set; }
}

特点：

• 必须实现 CreateTime 属性
• 用于事件驱动的数据（报警、用户操作）
• 使用 BusinessServiceManager 管理
• 立即写入，无延迟

示例：

[SugarTable("AlarmInfo")]
public class AlarmInfoEntity : IBusinessEntity
{
    [SugarColumn(IsPrimaryKey = true, Length = 15)]
    public string TimeKey { get; set; }

    public DateTime CreateTime { get; set; }  // 必须实现
    public string AlarmMessage { get; set; }
}

// 使用
BusinessServiceManager.Instance.Insert(
    new AlarmInfoEntity
    {
        TimeKey = DateTime.Now.ToString("yyyyMMddHHmmssfff"),
        CreateTime = DateTime.Now,
        AlarmMessage = "温度过高"
    }
);

4.3.2 IContinuousEntity - 持续写入实体

public interface IContinuousEntity
{
    DateTime DataTimestamp { get; set; }
}

特点：

• 必须实现 DataTimestamp 属性
• 用于持续采集的数据（轴数据、IO数据）
• 使用 ContinuousServiceManager 管理
• 缓冲队列批量写入，有延迟

示例：

[SugarTable("AxisData")]
public class AxisDataEntity : IContinuousEntity
{
    [SugarColumn(IsPrimaryKey = true, Length = 15)]
    public string TimeKey { get; set; }

    public DateTime DataTimestamp { get; set; }  // 必须实现
    public double Position { get; set; }
    public int Status { get; set; }
}

// 使用
ContinuousServiceManager.Instance.Enqueue(
    new AxisDataEntity
    {
        TimeKey = DateTime.Now.ToString("yyyyMMddHHmmssfff"),
        DataTimestamp = DateTime.Now,
        Position = 123.45,
        Status = 1
    }
);

---

4.4 WriterConfig - 写入器配置

4.4.1 配置参数

public class WriterConfig
{
    /// <summary>
    /// 刷新间隔（毫秒）
    /// </summary>
    public int FlushInterval { get; set; } = 1000;

    /// <summary>
    /// 批量大小（每次写入的最大记录数）
    /// </summary>
    public int BatchSize { get; set; } = 100;

    /// <summary>
    /// 是否启用调试日志
    /// </summary>
    public bool EnableDebugLog { get; set; } = false;
}

4.4.2 预设配置

// 高频配置：轴数据（100Hz采集）
public static WriterConfig HighFrequency => new WriterConfig(500, 200);
// 刷新间隔：500ms（0.5秒）
// 批量大小：200条

// 中频配置：IO数据（10Hz采集）
public static WriterConfig MediumFrequency => new WriterConfig(1000, 500);
// 刷新间隔：1000ms（1秒）
// 批量大小：500条

// 低频配置：系统状态（1Hz采集）
public static WriterConfig LowFrequency => new WriterConfig(3000, 50);
// 刷新间隔：3000ms（3秒）
// 批量大小：50条

4.4.3 选择指南

数据类型	采集频率	推荐配置	刷新间隔	批量大小	说明
轴数据	100Hz	HighFrequency	500ms	200	高频采集，快速刷新
IO数据	10Hz	MediumFrequency	1000ms	500	中频采集，平衡延迟
传感器数据	10Hz	MediumFrequency	1000ms	500	同IO数据
系统状态	1Hz	LowFrequency	3000ms	50	低频采集，延迟可接受

---

五、详细API文档

5.1 SqlSugarManager - 数据库管理器

5.1.1 设置连接字符串

var manager = new SqlSugarManager();
manager.SetConnectionString("Server=localhost;DataBase=mydb;Port=3306;User Id=root;Password=123456;");

连接字符串格式：

Server=地址;DataBase=数据库名;Port=端口;User Id=用户名;Password=密码;

5.1.2 创建表（CodeFirst）

// 创建单个表
var result = manager.CreateTable<AlarmInfoEntity>();
if (result.IsSuccess)
    Console.WriteLine("表创建成功");

// 创建多个表
manager.CreateTable<AlarmInfoEntity>();
manager.CreateTable<UserInfoEntity>();
manager.CreateTable<AxisDataEntity>();

5.1.3 测试连接

bool isConnected = manager.TestConnection();
if (isConnected)
    Console.WriteLine("数据库连接正常");
else
    Console.WriteLine("数据库连接失败");

---

5.2 BusinessServiceManager - 业务服务管理器

5.2.1 插入数据

// 插入单条
var result = BusinessServiceManager.Instance.Insert(
    new AlarmInfoEntity
    {
        TimeKey = DateTime.Now.ToString("yyyyMMddHHmmssfff"),
        CreateTime = DateTime.Now,
        AlarmMessage = "温度过高",
        AlarmIndex = 1
    }
);

// 批量插入
var list = new List<AlarmInfoEntity>
{
    new AlarmInfoEntity { ... },
    new AlarmInfoEntity { ... }
};
BusinessServiceManager.Instance.InsertRange(list);

5.2.2 查询数据

// 根据ID查询
var alarm = BusinessServiceManager.Instance.GetById<AlarmInfoEntity>("20260624143025123");

// 条件查询
var todayAlarms = BusinessServiceManager.Instance.Query<AlarmInfoEntity>(
    x => x.CreateTime >= DateTime.Today
);

// 查询所有
var allAlarms = BusinessServiceManager.Instance.GetAll<AlarmInfoEntity>();

// 统计
int count = BusinessServiceManager.Instance.Count<AlarmInfoEntity>(
    x => x.AlarmStatus == 0
);

5.2.3 更新数据

var alarm = BusinessServiceManager.Instance.GetById<AlarmInfoEntity>("20260624143025123");
alarm.AlarmStatus = 1;  // 更新状态
alarm.ConfirmTime = DateTime.Now;
BusinessServiceManager.Instance.Update(alarm);

5.2.4 删除数据

// 根据条件删除
BusinessServiceManager.Instance.Delete<AlarmInfoEntity>(
    x => x.CreateTime < DateTime.Today.AddDays(-30)  // 删除30天前的数据
);

5.2.5 异步操作

// 异步插入
await BusinessServiceManager.Instance.InsertAsync(
    new AlarmInfoEntity { ... }
);

// 异步查询
var alarms = await BusinessServiceManager.Instance.QueryAsync<AlarmInfoEntity>(
    x => x.CreateTime >= DateTime.Today
);

---

5.3 ContinuousServiceManager - 持续服务管理器

5.3.1 注册写入器

// 注册轴数据写入器（高频配置）
ContinuousServiceManager.Instance.RegisterWriter<AxisDataEntity>(
    "AxisData",
    WriterConfig.HighFrequency
);

// 注册IO数据写入器（中频配置）
ContinuousServiceManager.Instance.RegisterWriter<IODataEntity>(
    "IOData",
    WriterConfig.MediumFrequency
);

// 注册系统状态写入器（低频配置）
ContinuousServiceManager.Instance.RegisterWriter<SystemStatusEntity>(
    "SystemStatus",
    WriterConfig.LowFrequency
);

5.3.2 入队数据

// PLC采集线程
while (true)
{
    // 采集轴数据
    var axisData = new AxisDataEntity
    {
        TimeKey = DateTime.Now.ToString("yyyyMMddHHmmssfff"),
        DataTimestamp = DateTime.Now,
        Position = plc.ReadReal("Axis.Position"),
        Status = plc.ReadInt("Axis.Status")
    };

    // 入队（非阻塞）
    ContinuousServiceManager.Instance.Enqueue(axisData);

    // 继续采集
    Thread.Sleep(10);
}

5.3.3 手动刷新

// 立即将指定写入器的缓冲数据写入数据库
ContinuousServiceManager.Instance.Flush("AxisData");

// 立即将所有写入器的缓冲数据写入数据库
ContinuousServiceManager.Instance.FlushAll();

5.3.4 获取统计信息

// 获取单个写入器的统计信息
string stats = ContinuousServiceManager.Instance.GetStatistics("AxisData");
Console.WriteLine(stats);
// 输出：入队次数：15000，写入次数：75，写入记录数：15000，当前缓冲区大小：50

// 获取所有写入器的统计信息
var allStats = ContinuousServiceManager.Instance.GetAllStatistics();
foreach (var kvp in allStats)
{
    Console.WriteLine($"{kvp.Key}: {kvp.Value}");
}

5.3.5 注销写入器

// 注销写入器（程序关闭时）
ContinuousServiceManager.Instance.UnregisterWriter("AxisData");

---

5.4 SqlSugarRepository - 泛型仓储

5.4.1 直接使用仓储

// 创建仓储
var alarmRepo = new SqlSugarRepository<AlarmInfoEntity>();

// 插入
alarmRepo.Insert(new AlarmInfoEntity { ... });

// 查询
var alarms = alarmRepo.Query(x => x.CreateTime >= DateTime.Today);

// 更新
var alarm = alarmRepo.GetById("20260624143025123");
alarm.AlarmStatus = 1;
alarmRepo.Update(alarm);

// 删除
alarmRepo.Delete(x => x.CreateTime < DateTime.Today.AddDays(-30));

---

六、移植指南

6.1 文件依赖

6.1.1 NuGet 包

SqlSugar 5.x                    ← MySQL ORM 核心（必须）
MySql.Data 8.0.33               ← MySQL 数据库驱动（必须）
Related_DataConvertLib          ← 操作结果类（必须）

6.1.2 项目引用

主工程需引用：

• Related_MySQL.dll
• Related_DataConvertLib.dll

6.2 数据库准备

6.2.1 安装 MySQL

-- 1. 下载并安装 MySQL 5.7+
-- https://dev.mysql.com/downloads/mysql/

-- 2. 创建数据库
CREATE DATABASE semi_equip_db CHARACTER SET utf8mb4 COLLATE utf8mb4_unicode_ci;

-- 3. 创建用户（可选）
CREATE USER 'semi_user'@'%' IDENTIFIED BY 'your_password';
GRANT ALL PRIVILEGES ON semi_equip_db.* TO 'semi_user'@'%';
FLUSH PRIVILEGES;

6.2.2 配置连接字符串

// 方式1：代码设置
SqlSugarHelper.ConnectionString = "Server=localhost;DataBase=semi_equip_db;Port=3306;User Id=root;Password=123456;";

// 方式2：配置文件（App.config）
<?xml version="1.0" encoding="utf-8" ?>
<configuration>
  <connectionStrings>
    <add name="MySqlConnection" 
         connectionString="Server=localhost;DataBase=semi_equip_db;Port=3306;User Id=root;Password=123456;"/>
  </connectionStrings>
</configuration>

// 读取配置文件
var connStr = ConfigurationManager.ConnectionStrings["MySqlConnection"].ConnectionString;
SqlSugarHelper.ConnectionString = connStr;

6.3 实体类定义

6.3.1 业务驱动实体

using SqlSugar;

[SugarTable("AlarmInfo")]
public class AlarmInfoEntity : IBusinessEntity
{
    [SugarColumn(IsPrimaryKey = true, Length = 15)]
    public string TimeKey { get; set; }

    public DateTime CreateTime { get; set; }

    [SugarColumn(ColumnDataType = "int")]
    public int AlarmIndex { get; set; }

    [SugarColumn(ColumnDataType = "nvarchar", Length = 200)]
    public string AlarmMessage { get; set; }

    [SugarColumn(ColumnDataType = "int")]
    public int AlarmStatus { get; set; }

    [SugarColumn(IsNullable = true, ColumnDataType = "datetime")]
    public DateTime? ConfirmTime { get; set; }
}

6.3.2 持续写入实体

using SqlSugar;

[SugarTable("AxisData")]
public class AxisDataEntity : IContinuousEntity
{
    [SugarColumn(IsPrimaryKey = true, Length = 15)]
    public string TimeKey { get; set; }

    public DateTime DataTimestamp { get; set; }

    [SugarColumn(ColumnDataType = "double")]
    public double Position { get; set; }

    [SugarColumn(ColumnDataType = "int")]
    public int Status { get; set; }

    [SugarColumn(ColumnDataType = "double")]
    public double Velocity { get; set; }
}

6.4 初始化流程

6.4.1 完整初始化代码

using Related_MySQL;

public class Program
{
    public static void Main()
    {
        // ========== 第1步：设置连接字符串 ==========
        SqlSugarHelper.ConnectionString = 
            "Server=localhost;DataBase=semi_equip_db;Port=3306;User Id=root;Password=123456;";

        // ========== 第2步：测试连接 ==========
        var manager = new SqlSugarManager();
        if (!manager.TestConnection())
        {
            Console.WriteLine("数据库连接失败，请检查连接字符串");
            return;
        }

        // ========== 第3步：创建表结构（首次运行） ==========
        try
        {
            // 创建业务驱动表
            manager.CreateTable<AlarmInfoEntity>();
            manager.CreateTable<UserInfoEntity>();
            manager.CreateTable<AuthInfoEntity>();

            // 创建持续写入表
            manager.CreateTable<AxisDataEntity>();
            manager.CreateTable<IODataEntity>();
            manager.CreateTable<SystemStatusEntity>();

            Console.WriteLine("表结构创建成功");
        }
        catch (Exception ex)
        {
            Console.WriteLine($"表结构创建失败：{ex.Message}");
        }

        // ========== 第4步：注册持续写入器 ==========
        try
        {
            // 轴数据：高频配置
            ContinuousServiceManager.Instance.RegisterWriter<AxisDataEntity>(
                "AxisData",
                WriterConfig.HighFrequency
            );

            // IO数据：中频配置
            ContinuousServiceManager.Instance.RegisterWriter<IODataEntity>(
                "IOData",
                WriterConfig.MediumFrequency
            );

            Console.WriteLine("持续写入器注册成功");
        }
        catch (Exception ex)
        {
            Console.WriteLine($"持续写入器注册失败：{ex.Message}");
        }

        // ========== 第5步：开始运行 ==========
        Console.WriteLine("系统初始化完成，开始运行...");
        
        // 启动PLC采集线程
        StartPLCCollection();

        // 阻塞主线程
        Console.ReadLine();
    }

    static void StartPLCCollection()
    {
        // PLC采集线程示例
        Task.Run(() =>
        {
            while (true)
            {
                try
                {
                    // 采集轴数据
                    var axisData = new AxisDataEntity
                    {
                        TimeKey = DateTime.Now.ToString("yyyyMMddHHmmssfff"),
                        DataTimestamp = DateTime.Now,
                        Position = ReadAxisPosition(),
                        Status = ReadAxisStatus()
                    };

                    // 入队（非阻塞）
                    ContinuousServiceManager.Instance.Enqueue(axisData);
                }
                catch (Exception ex)
                {
                    Console.WriteLine($"采集失败：{ex.Message}");
                }

                Thread.Sleep(10);  // 100Hz采集
            }
        });
    }

    static double ReadAxisPosition()
    {
        // 实际项目中这里调用PLC通讯库读取数据
        return 123.45;
    }

    static int ReadAxisStatus()
    {
        // 实际项目中这里调用PLC通讯库读取数据
        return 1;
    }
}

6.5 使用示例

6.5.1 报警处理

public class AlarmService
{
    public void OnAlarmTriggered(int alarmIndex, string message)
    {
        // 立即写入报警信息（业务驱动）
        var result = BusinessServiceManager.Instance.Insert(
            new AlarmInfoEntity
            {
                TimeKey = DateTime.Now.ToString("yyyyMMddHHmmssfff"),
                CreateTime = DateTime.Now,
                AlarmIndex = alarmIndex,
                AlarmMessage = message,
                AlarmStatus = 0  // 未处理
            }
        );

        if (!result.IsSuccess)
        {
            Console.WriteLine($"报警信息写入失败：{result.Message}");
        }
    }

    public void ConfirmAlarm(string timeKey, string userName)
    {
        // 查询报警
        var alarm = BusinessServiceManager.Instance.GetById<AlarmInfoEntity>(timeKey);
        if (alarm == null)
        {
            Console.WriteLine("报警不存在");
            return;
        }

        // 更新报警状态
        alarm.AlarmStatus = 1;
        alarm.ConfirmTime = DateTime.Now;
        alarm.ConfirmUserName = userName;

        // 写入数据库
        var result = BusinessServiceManager.Instance.Update(alarm);
        if (!result.IsSuccess)
        {
            Console.WriteLine($"报警确认失败：{result.Message}");
        }
    }
}

6.5.2 PLC数据采集

public class PLCCollectionService
{
    private Thread _axisCollectionThread;
    private Thread _ioCollectionThread;
    private bool _isRunning = false;

    public void Start()
    {
        _isRunning = true;

        // 启动轴数据采集线程（100Hz）
        _axisCollectionThread = new Thread(CollectAxisData)
        {
            IsBackground = true
        };
        _axisCollectionThread.Start();

        // 启动IO数据采集线程（10Hz）
        _ioCollectionThread = new Thread(CollectIOData)
        {
            IsBackground = true
        };
        _ioCollectionThread.Start();
    }

    public void Stop()
    {
        _isRunning = false;

        // 等待线程结束
        _axisCollectionThread?.Join(1000);
        _ioCollectionThread?.Join(1000);

        // 刷新缓冲区，确保数据写入
        ContinuousServiceManager.Instance.FlushAll();
    }

    private void CollectAxisData()
    {
        while (_isRunning)
        {
            try
            {
                // 采集轴数据（示例：采集3个轴）
                for (int i = 1; i <= 3; i++)
                {
                    var axisData = new AxisDataEntity
                    {
                        TimeKey = DateTime.Now.ToString("yyyyMMddHHmmssfff"),
                        DataTimestamp = DateTime.Now,
                        AxisIndex = i,
                        Position = PLCDriver.ReadReal($"Axis{i}.Position"),
                        Velocity = PLCDriver.ReadReal($"Axis{i}.Velocity"),
                        Status = PLCDriver.ReadInt($"Axis{i}.Status")
                    };

                    // 入队（非阻塞，<0.01ms）
                    ContinuousServiceManager.Instance.Enqueue(axisData);
                }
            }
            catch (Exception ex)
            {
                Console.WriteLine($"轴数据采集失败：{ex.Message}");
            }

            Thread.Sleep(10);  // 100Hz采集，每10ms一次
        }
    }

    private void CollectIOData()
    {
        while (_isRunning)
        {
            try
            {
                // 采集IO数据（示例：采集100个点位）
                var ioData = new IODataEntity
                {
                    TimeKey = DateTime.Now.ToString("yyyyMMddHHmmssfff"),
                    DataTimestamp = DateTime.Now,
                    IOValues = ReadIOValues()  // 读取100个IO点位
                };

                // 入队
                ContinuousServiceManager.Instance.Enqueue(ioData);
            }
            catch (Exception ex)
            {
                Console.WriteLine($"IO数据采集失败：{ex.Message}");
            }

            Thread.Sleep(100);  // 10Hz采集，每100ms一次
        }
    }

    private byte[] ReadIOValues()
    {
        // 实际项目中这里调用PLC通讯库读取IO数据
        var values = new byte[100];
        for (int i = 0; i < 100; i++)
        {
            values[i] = PLCDriver.ReadBit($"IO.{i}") ? (byte)1 : (byte)0;
        }
        return values;
    }
}

6.5.3 查询和统计

public class ReportService
{
    public void ShowTodayAlarms()
    {
        // 查询今天的所有报警
        var todayAlarms = BusinessServiceManager.Instance.Query<AlarmInfoEntity>(
            x => x.CreateTime >= DateTime.Today
        );

        Console.WriteLine($"今天的报警数量：{todayAlarms.Count()}");

        foreach (var alarm in todayAlarms)
        {
            Console.WriteLine($"[{alarm.CreateTime:HH:mm:ss}] {alarm.AlarmMessage}");
        }
    }

    public void ShowUnconfirmedAlarms()
    {
        // 查询未确认的报警
        var unconfirmed = BusinessServiceManager.Instance.Query<AlarmInfoEntity>(
            x => x.AlarmStatus == 0
        );

        Console.WriteLine($"未确认报警数量：{unconfirmed.Count()}");
    }

    public void ShowStatistics()
    {
        // 统计各类报警数量
        var tempAlarms = BusinessServiceManager.Instance.Count<AlarmInfoEntity>(
            x => x.AlarmIndex == 1  // 温度报警
        );
        var pressAlarms = BusinessServiceManager.Instance.Count<AlarmInfoEntity>(
            x => x.AlarmIndex == 2  // 压力报警
        );

        Console.WriteLine($"温度报警：{tempAlarms}次");
        Console.WriteLine($"压力报警：{pressAlarms}次");
    }

    public void ShowWriterStatistics()
    {
        // 显示持续写入器统计信息
        var allStats = ContinuousServiceManager.Instance.GetAllStatistics();

        Console.WriteLine("=== 持续写入器统计 ===");
        foreach (var kvp in allStats)
        {
            Console.WriteLine($"{kvp.Key}: {kvp.Value}");
        }
    }
}

6.6 程序退出

public class MainForm : Form
{
    protected override void OnFormClosing(FormClosingEventArgs e)
    {
        // ========== 第1步：停止PLC采集 ==========
        _plcService?.Stop();

        // ========== 第2步：刷新缓冲区 ==========
        ContinuousServiceManager.Instance.FlushAll();

        // ========== 第3步：释放资源 ==========
        ContinuousServiceManager.Instance.Dispose();

        // ========== 第4步：可选：清理旧数据 ==========
        // CleanOldData();

        base.OnFormClosing(e);
    }

    private void CleanOldData()
    {
        try
        {
            // 删除30天前的报警信息
            BusinessServiceManager.Instance.Delete<AlarmInfoEntity>(
                x => x.CreateTime < DateTime.Today.AddDays(-30)
            );

            // 删除90天前的轴数据
            var axisRepo = new SqlSugarRepository<AxisDataEntity>();
            axisRepo.Delete(x => x.DataTimestamp < DateTime.Today.AddDays(-90));

            Console.WriteLine("旧数据清理完成");
        }
        catch (Exception ex)
        {
            Console.WriteLine($"旧数据清理失败：{ex.Message}");
        }
    }
}

---

七、性能优化

7.1 批量写入性能对比

7.1.1 测试代码

// 准备测试数据
var testData = new List<AxisDataEntity>();
for (int i = 0; i < 1000; i++)
{
    testData.Add(new AxisDataEntity
    {
        TimeKey = DateTime.Now.AddMilliseconds(i).ToString("yyyyMMddHHmmssfff"),
        DataTimestamp = DateTime.Now.AddMilliseconds(i),
        Position = i * 1.0,
        Status = 1
    });
}

// ========== 测试1：逐条插入 ==========
var repo1 = new SqlSugarRepository<AxisDataEntity>();
var sw1 = Stopwatch.StartNew();
foreach (var data in testData)
{
    repo1.Insert(data);
}
sw1.Stop();
Console.WriteLine($"逐条插入1000条耗时：{sw1.ElapsedMilliseconds}ms");

// ========== 测试2：批量插入 ==========
var repo2 = new SqlSugarRepository<AxisDataEntity>();
var sw2 = Stopwatch.StartNew();
repo2.InsertRange(testData);
sw2.Stop();
Console.WriteLine($"批量插入1000条耗时：{sw2.ElapsedMilliseconds}ms");

// ========== 测试3：缓冲队列批量插入 ==========
ContinuousServiceManager.Instance.RegisterWriter<AxisDataEntity>(
    "PerformanceTest",
    new WriterConfig(flushInterval: 1000, batchSize: 200)
);
var sw3 = Stopwatch.StartNew();
foreach (var data in testData)
{
    ContinuousServiceManager.Instance.Enqueue(data);  // 入队
}
ContinuousServiceManager.Instance.Flush("PerformanceTest");  // 刷新
sw3.Stop();
Console.WriteLine($"缓冲队列批量插入1000条耗时：{sw3.ElapsedMilliseconds}ms");

7.1.2 性能测试结果

方法	100条	500条	1000条	5000条
逐条插入	500ms	2500ms	5000ms	25000ms
批量插入	10ms	30ms	50ms	200ms
缓冲队列	5ms	15ms	25ms	100ms

结论：

• 批量插入比逐条插入快 50-100倍
• 缓冲队列比直接批量插入快 2倍（因为异步，不阻塞主线程）

7.2 优化建议

7.2.1 选择合适的刷新间隔

刷新间隔	数据延迟	数据库压力	适用场景
500ms	低（<0.5秒）	高	轴数据（高频）
1000ms	中（<1秒）	中	IO数据（中频）
3000ms	高（<3秒）	低	系统状态（低频）

7.2.2 选择合适的批量大小

批量大小	单次写入耗时	内存占用	适用场景
50-100	短（<5ms）	低	系统状态
200-500	中（5-20ms）	中	轴数据
500-1000	长（20-50ms）	高	IO数据

7.2.3 数据库优化

-- 1. 添加索引（常用查询字段）
CREATE INDEX idx_createtime ON AlarmInfo(CreateTime);
CREATE INDEX idx_datatimestamp ON AxisData(DataTimestamp);

-- 2. 分区表（大数据量时）
ALTER TABLE AxisData PARTITION BY RANGE (TO_DAYS(DataTimestamp)) (
    PARTITION p202606 VALUES LESS THAN (TO_DAYS('2026-07-01')),
    PARTITION p202607 VALUES LESS THAN (TO_DAYS('2026-08-01')),
    PARTITION pmax VALUES LESS THAN MAXVALUE
);

-- 3. 定期清理旧数据
DELETE FROM AxisData WHERE DataTimestamp < DATE_SUB(NOW(), INTERVAL 90 DAY);
DELETE FROM AlarmInfo WHERE CreateTime < DATE_SUB(NOW(), INTERVAL 30 DAY);

-- 4. 优化表
OPTIMIZE TABLE AxisData;
OPTIMIZE TABLE AlarmInfo;

---

八、常见问题FAQ

Q1: 如何选择使用 BusinessServiceManager 还是 ContinuousServiceManager？

A: 根据数据类型选择：

数据类型	使用服务	原因
报警信息、用户操作、审计日志	BusinessServiceManager	事件驱动，必须立即写入
轴数据、IO数据、传感器数据	ContinuousServiceManager	高频采集，需要批量优化

Q2: 程序崩溃时，缓冲队列中的数据会丢失吗？

A: 是的，会丢失。解决方案：

1. 在程序退出时调用 ContinuousServiceManager.Instance.FlushAll()
2. 在关键位置手动调用 Flush()
3. 对于绝对不能丢失的数据，使用 BusinessServiceManager

Q3: 如何查看当前缓冲队列中有多少数据？

A: 调用统计方法：

var stats = ContinuousServiceManager.Instance.GetStatistics("AxisData");
Console.WriteLine(stats);
// 输出：入队次数：15000，写入次数：75，写入记录数：15000，当前缓冲区大小：50

Q4: 多个线程同时写入同一个表会冲突吗？

A: 不会冲突。本类库设计为线程安全：

• BusinessServiceManager：每个操作创建独立连接
• ContinuousServiceManager：使用线程安全队列

Q5: 如何处理写入失败？

A: 查看操作结果：

var result = BusinessServiceManager.Instance.Insert(new AlarmInfoEntity { ... });
if (!result.IsSuccess)
{
    Console.WriteLine($"写入失败：{result.Message}");
    // 可以在这里重试或记录错误日志
}

Q6: 可以在运行时更改写入器配置吗？

A: 不能直接更改。需要：

1. 注销旧的写入器：UnregisterWriter("AxisData")
2. 重新注册新配置：RegisterWriter<AxisDataEntity>("AxisData", newConfig)

Q7: 如何清理旧数据？

A: 使用 Repository 或 Service：

// 删除30天前的报警信息
BusinessServiceManager.Instance.Delete<AlarmInfoEntity>(
    x => x.CreateTime < DateTime.Today.AddDays(-30)
);

// 删除90天前的轴数据
var axisRepo = new SqlSugarRepository<AxisDataEntity>();
axisRepo.Delete(x => x.DataTimestamp < DateTime.Today.AddDays(-90));

Q8: 支持事务吗？

A: 当前版本不直接支持，但可以通过 SqlSugar 实现：

using (var db = SqlSugarHelper.GetScopedClient())
{
    try
    {
        db.BeginTran();

        db.Insertable(new AlarmInfoEntity { ... }).ExecuteCommand();
        db.Insertable(new UserInfoEntity { ... }).ExecuteCommand();

        db.CommitTran();
    }
    catch
    {
        db.RollbackTran();
        throw;
    }
}

Q9: 如何备份和恢复数据库？

A: 使用 MySQL 命令：

# 备份
mysqldump -u root -p semi_equip_db > backup.sql

# 恢复
mysql -u root -p semi_equip_db < backup.sql

Q10: 支持其他数据库吗？

A: SqlSugar 支持多种数据库，只需修改连接字符串和 DbType：

// MySQL
DbType = DbType.MySql
ConnectionString = "Server=localhost;DataBase=mydb;..."

// SQL Server
DbType = DbType.SqlServer
ConnectionString = "Server=.;DataBase=mydb;User Id=sa;Password=123;"

// PostgreSQL
DbType = DbType.PostgreSQL
ConnectionString = "Host=localhost;DataBase=mydb;Username=postgres;Password=123;"

---

九、附录

9.1 命名空间汇总

命名空间	说明
Related_MySQL	主命名空间
Related_MySQL.Infrastructure.SqlSugar	SqlSugar 连接管理和仓储
Related_MySQL.Infrastructure.Continuous	持续写入器和配置
Related_MySQL.Core.Interfaces	仓储接口
Related_MySQL.Core.Entities	实体标记接口
Related_MySQL.Services.Business	业务服务管理器
Related_MySQL.Services.Continuous	持续服务管理器
Related_MySQL.Models.Business	业务实体示例
Related_MySQL.Models.Continuous	持续实体示例

9.2 类型汇总

类型	说明
SqlSugarHelper	数据库连接管理器（单例）
SqlSugarRepository<T>	泛型仓储实现
IRepository<T>	泛型仓储接口
BusinessServiceManager	业务服务管理器（单例）
ContinuousServiceManager	持续服务管理器（单例）
ContinuousDataWriter<T>	持续数据写入器
WriterConfig	写入器配置类
IBusinessEntity	业务实体标记接口
IContinuousEntity	持续实体标记接口

9.3 快速参考卡片

╔═══════════════════════════════════════════════════════════════╗
║                    Related_MySQL 快速参考                        ║
╠═══════════════════════════════════════════════════════════════╣
║                                                                ║
║  🔹 初始化                                                      ║
║     SqlSugarHelper.ConnectionString = "...";                   ║
║     new SqlSugarManager().CreateTable<T>();                     ║
║                                                                ║
║  🔹 业务驱动写入（报警、用户操作）                                ║
║     BusinessServiceManager.Instance.Insert(entity);            ║
║     .Query<T>(where)                                           ║
║     .Update(entity)                                            ║
║     .Delete(where)                                             ║
║                                                                ║
║  🔹 持续写入（轴数据、IO数据）                                   ║
║     ContinuousServiceManager.Instance.RegisterWriter<T>(      ║
║         "WriterName", WriterConfig.HighFrequency               ║
║     );                                                         ║
║     .Enqueue(data)  // PLC采集线程调用                           ║
║     .FlushAll()  // 程序退出时调用                               ║
║                                                                ║
║  🔹 直接使用仓储                                                 ║
║     var repo = new SqlSugarRepository<T>();                     ║
║     repo.Insert(entity)                                        ║
║     repo.Query(where)                                          ║
║                                                                ║
╚═══════════════════════════════════════════════════════════════╝