1. 功能库视角下的 RFID 上位机:串口代码塞进窗体,换模块时整片返工
前年接手一个 C# RFID 读写器上位机,窗体里直接 new SerialPort,DataReceived 里拼字节,按钮回调里发指令再 Sleep 等回包。第一版在现场跑得挺顺,直到客户换了一款读写器:帧头变了、校验算法也变了,MainForm 里三十多处硬编码全要改,改完还漏了两处,现场调了一下午。那次之后我把整个工程按功能库重新划了一遍:通信、卡片业务、界面、共享工具四个项目,每个功能库只做一件事,依赖方向只允许单向。这篇就把这套拆法、每一层的代码和调试时踩过的坑摊开讲,适合正在写串口上位机、或者准备接第二款读卡器的人。
需要模型API调用? 免费领10W Token,多模型网关一键接入 Claude、DeepSeek 等主流模型。
2. 功能库的边界怎么划:四个项目、一条单向依赖
功能库这件事,很多人理解成“多建几个 csproj 就算解耦”。我一开始也这么干过,结果项目是分开了,业务层里照样 new SerialPortManager(),换读卡器时照样整片改。真正的分界不在目录,而在依赖方向:谁可以认识谁、谁绝对不能认识谁,这个规则写下来并且能被编译检查,功能库才算立住。
2.1 目录结构和每层的职责
工程目录按下面这样落,四个项目各管一段,跨层契约集中在 Shared 里:
text复制RFIDSolution/
├── Rfid.Communication/ // 通信层:只管字节怎么进出、怎么成帧
│ ├── SerialPortManager.cs // 串口开关、接收、缓冲
│ ├── SerialTransport.cs // IRfidTransport 的串口实现
│ ├── RfidFrameHelper.cs // 指令帧组包
│ └── RfidFrameParser.cs // 回包拆帧与事件触发
├── Rfid.Card/ // 业务层:字节含义、卡片操作
│ ├── CardOperator.cs // 寻卡、认证、读写块
│ └── CardModels.cs // 卡号、扇区、卡型参数
├── Rfid.App/ // 界面层:WinForms,最薄的一层
│ ├── MainForm.cs // 串口配置与功能按钮
│ └── CardDetailForm.cs // 卡片明细与扇区内容展示
└── Rfid.Shared/ // 共享库:契约、校验、字节工具
├── IRfidTransport.cs // 通信层对外的唯一接口
├── RfidFrame.cs // 完整帧模型
├── Crc16.cs // CRC16 校验
└── ByteHelper.cs // 字节转换、Hex 显示
每层的职责用一张表定死,后面所有代码争议都拿这张表裁决:
| 项目 | 只做 | 允许引用 | 明确禁止 |
|---|---|---|---|
| Rfid.Communication | 串口开关、字节收发、组帧拆帧 | System.IO.Ports、Rfid.Shared | 引用业务层、界面层,出现卡片、扇区这类词 |
| Rfid.Card | 把完整帧翻译成卡片操作 | Rfid.Shared(接口与模型) | 引用 System.IO.Ports,出现 SerialPort |
| Rfid.App | 收集参数、调用业务方法、展示结果 | Rfid.Card、Rfid.Shared | 碰串口、拼帧、写 CRC |
| Rfid.Shared | 放契约与纯工具 | 无 | 反向引用上面任何一个 |
这张表最关键的一行是 Rfid.Card 禁止引用 System.IO.Ports。只要这条守住,以后换蓝牙、换网口、换 USB 转接,业务层一行代码都不用动;反过来,业务层只要出现一个 SerialPort,这个功能库就白拆了。
2.2 依赖方向用接口锁住
光靠自觉守不住,得有编译层面的约束。我在 Shared 里放一个通信接口,所有上层只认这个接口,不认具体实现:
csharp复制namespace Rfid.Shared
{
// 通信层对外的唯一契约:发一条命令,收一帧完整数据
public interface IRfidTransport : IDisposable
{
// 由通信层拆好帧后触发,上层不接触原始字节
event Action<RfidFrame> FrameReady;
void Open();
void Close();
// 只传命令字与数据区,帧头、长度、CRC 由通信层自己拼
void Send(byte command, byte[] payload);
}
}
接口签名里有两个刻意设计。Send 只接收命令字和数据区,不接收整帧字节,是因为业务层不该知道帧头多长、长度字段是大端还是小端;FrameReady 直接给 RfidFrame 而不是 byte[],是因为拆帧属于通信层的活,半包、粘包、校验失败这些事不能漏到业务层去处理。这两个决定看着只是方法签名,实际上决定了后面换模块的工作量落在哪一层。
依赖检查也不需要额外工具,一条命令就能扫出来:
bash复制# 在解决方案根目录执行:业务层和界面层只要出现串口库,就说明依赖漏了
grep -rn "System.IO.Ports" Rfid.Card Rfid.App || echo "依赖方向干净"
这条命令我一般挂在提交前的手动检查里。有输出就是有泄漏,先把它挪回通信层再继续写功能,别等到换读卡器那天才发现业务层里藏着一堆串口代码。
3. 通信功能库:从串口字节流到可校验的完整帧
通信层只干两件事:让字节可靠地进出,把进来的字节拼成完整帧。听起来简单,翻车基本都翻在第二件事上——串口一次给你的可能是一个半帧,也可能是两帧粘在一起,甚至前面还带几个上电时的脏字节。这一层写不扎实,业务层就会收到缺角的卡号,表现出来就是“偶尔读不到卡”这种玄学问题。
3.1 SerialPortManager:开关、接收与缓冲
先看串口管理器。它不解析任何含义,只负责打开端口、把 DataReceived 里读到的字节累积起来,再抛给下一级:
csharp复制using System;
using System.IO.Ports;
namespace Rfid.Communication
{
public class SerialPortManager : IDisposable
{
private readonly SerialPort _port;
private readonly object _sync = new object();
private byte[] _buffer = new byte[4096];
private int _count;
// 原始字节到达事件,交给拆帧器消费,不要在订阅方直接碰 UI
public event Action<byte[], int> BytesReceived;
public SerialPortManager(string portName, int baudRate, Parity parity,
int dataBits, StopBits stopBits)
{
_port = new SerialPort(portName, baudRate, parity, dataBits, stopBits);
_port.ReadTimeout = 500; // 同步读的兜底,防止线程永久挂住
_port.WriteTimeout = 500;
_port.DataReceived += OnDataReceived;
}
public void Open()
{
if (!_port.IsOpen) _port.Open();
}
private void OnDataReceived(object sender, SerialDataReceivedEventArgs e)
{
lock (_sync)
{
int n = _port.BytesToRead;
if (n <= 0) return;
if (_count + n > _buffer.Length)
Array.Resize(ref _buffer, Math.Max(_buffer.Length * 2, _count + n));
_port.Read(_buffer, _count, n); // 追加,不覆盖上一批没消费完的数据
_count += n;
BytesReceived?.Invoke(_buffer, _count);
}
}
public void Write(byte[] frame)
{
lock (_sync) _port.Write(frame, 0, frame.Length);
}
public void Close()
{
if (_port.IsOpen) _port.Close();
}
public void Dispose()
{
_port.DataReceived -= OnDataReceived; // 先退订,再关端口
if (_port.IsOpen) _port.Close();
_port.Dispose();
}
}
}
构造参数里 portName、baudRate、parity、dataBits、stopBits 一律从设备手册或配置文件来,不写死在代码里。现场最常见的“打开串口没反应”,十有八九是波特率或者校验位和读卡器对不上,而不是代码问题。ReadTimeout、WriteTimeout 我给了 500 毫秒兜底,是因为 USB 转串口拔插之后,同步读可能一直不返回,没有超时会把线程挂死。
lock 这把锁同时保护读和写:DataReceived 在后台线程触发,业务层的 Send 在调用线程执行,两者共用一个 SerialPort 的缓冲区,不加锁的话写出去的字节可能交错,读回来的数据也可能被覆盖。另外注意 BytesReceived 是在后台线程触发的,谁订阅谁自己负责切线程,这一点后面避坑会专门讲。
3.2 RfidFrameHelper 与 RfidFrameParser:组帧、拆帧、半包处理
组帧没什么花样,按设备协议把帧头、长度、命令、数据、校验依次拼起来:
csharp复制namespace Rfid.Communication
{
public static class RfidFrameHelper
{
// head 由设备协议配置;payload 允许为空
public static byte[] Build(byte[] head, byte command, byte[] payload, ICrc16 crc)
{
int len = payload?.Length ?? 0;
var frame = new byte[head.Length + 2 + 1 + len + 2];
Buffer.BlockCopy(head, 0, frame, 0, head.Length);
int p = head.Length;
frame[p++] = (byte)(len & 0xFF); // 长度低字节
frame[p++] = (byte)(len >> 8); // 长度高字节
frame[p++] = command;
if (len > 0) Buffer.BlockCopy(payload, 0, frame, p, len);
p += len;
// 校验覆盖范围:长度 + 命令 + 数据,不含帧头,具体按手册
ushort c = crc.Compute(frame, head.Length, p - head.Length);
frame[p++] = (byte)(c & 0xFF);
frame[p++] = (byte)(c >> 8);
return frame;
}
}
}
这里有两个容易埋雷的参数:长度字段的字节序和 CRC 的覆盖范围。上面按小端、覆盖长度到数据区来写,如果你的手册写的是大端,或者 CRC 从帧头开始算,改的就是这两行,不要在下游业务里做补偿。payload 为空时长度写 0,帧结构仍然完整,读卡器那边才不会把后续字节错认成数据。
拆帧才是通信层最容易出错的地方。核心是一个能处理半包的缓冲区:
csharp复制namespace Rfid.Communication
{
public class RfidFrameParser
{
private readonly byte[] _head; // 帧头字节,按设备手册配置
private readonly bool _lengthLittleEndian;
private readonly int _maxPayload; // 数据区上限,防止异常长度耗尽内存
private readonly ICrc16 _crc;
private byte[] _buf = new byte[1024];
private int _len;
public event Action<RfidFrame> FrameReady;
public event Action<byte[], int> CrcFailed; // 校验失败也抛出来,方便记日志
public RfidFrameParser(byte[] head, bool lengthLittleEndian, int maxPayload, ICrc16 crc)
{
_head = head;
_lengthLittleEndian = lengthLittleEndian;
_maxPayload = maxPayload;
_crc = crc;
}
public void Feed(byte[] data, int count)
{
if (_len + count > _buf.Length)
Array.Resize(ref _buf, Math.Max(_buf.Length * 2, _len + count));
Buffer.BlockCopy(data, 0, _buf, _len, count);
_len += count;
while (TryParse(out var frame))
FrameReady?.Invoke(frame); // 一次 Feed 可能拆出多帧
}
private bool TryParse(out RfidFrame frame)
{
frame = null;
int start = IndexOfHead();
if (start < 0) { _len = 0; return false; } // 没有帧头,全是脏字节
if (start > 0) // 丢掉帧头之前的垃圾
{
Buffer.BlockCopy(_buf, start, _buf, 0, _len - start);
_len -= start;
}
int headLen = _head.Length;
if (_len < headLen + 2) return false; // 长度字段还没到,等下一批
int payloadLen = _lengthLittleEndian
? _buf[headLen] | (_buf[headLen + 1] << 8)
: (_buf[headLen] << 8) | _buf[headLen + 1];
if (payloadLen < 0 || payloadLen > _maxPayload) // 长度离谱,跳过一个字节重找帧头
{
Buffer.BlockCopy(_buf, 1, _buf, 0, _len - 1);
_len -= 1;
return true;
}
int total = headLen + 2 + 1 + payloadLen + 2; // 帧头+长度+命令+数据+CRC
if (_len < total) return false; // 半包,保留缓冲等下一批
ushort crcCalc = _crc.Compute(_buf, headLen, total - headLen - 2);
ushort crcIn = _lengthLittleEndian
? (ushort)(_buf[total - 2] | (_buf[total - 1] << 8))
: (ushort)((_buf[total - 2] << 8) | _buf[total - 1]);
if (crcCalc != crcIn)
{
CrcFailed?.Invoke(_buf, total);
Buffer.BlockCopy(_buf, 1, _buf, 0, _len - 1);
_len -= 1;
return true; // 跳一个字节继续找,别整段丢弃
}
var payload = new byte[payloadLen];
Buffer.BlockCopy(_buf, headLen + 3, payload, 0, payloadLen);
frame = new RfidFrame(_buf[headLen + 2],
