"面向对象式"开发串口协议的SDK

背景

用户在访问我们的网站时，可以选择使用线下POS机进行支付，因此我们需要集成并控制POS机完成刷卡操作和返回数据。
然而，POS机提供方邮件发送过来的并不是我们预想的Http接口或是SDK，而是150多页的一份串口集成文档...

（文中涉及的代码、编号、枚举值都已经过模糊处理）

令人头晕的二进制

不同于我们日常所使用的HTTP协议：具有标准结构和完备的SDK；可以很容易的构建起Server-Client进行数据传输；无需关注应用层（ISO七层）以下的实现。而串口更像是物理层，通过指定频率的高低电平（0/1）来传输数据。

因此在使用串口通信时，通常需要设计一套自有协议表达复杂的数据结构。例如：

image-20211127144504102.png

• 主要部分为消息头（Header）和消息数据（Data），消息数据可以有多个
• 通过Field Code可区别不同的数据，是一个变长的数据
• 数据的主要类型为Hex（十六进制）、BCD（二进制化整数）、ASC（asiic码）

对照着上述结构来构造一个消息并不是一件困难的事，然而不同的类型的功能指令（Function）会包含大量不同的消息数据（Field Data）。如果我们面向一个一个功能指令开发，效率低且代码难以维护 —— 从我们拿到的一份Legacy的代码中，也能看出这点：

code-demo1.png

在一个类中，既有对业务字段的赋值，又有对底层数据格式的序列化。再加上大量的魔法字符，让我抄都不知道从何抄起...

于是在“修改这份代码使其适应新版本协议”和“重写，重写，重写！”中，我毅然选择了后者...

“封装，他使用了封装！”

那如何开发一个适配底层协议的SDK呢？

遇事不决，量子力学（不是） / 遇事不决，面向对象（还行）

面向对象的一大优势是利用封装，使逻辑高内聚低耦合。

首先，我将三个字段类型进行了封装：BCD、ASC、Hex，使其实现Attribute接口以实现toBytes()方法。此时业务所会用到的数据类型都和Bytes没有了直接关系，BCD、ASC、Hex成为了实质上的的基本类型。

同理，Token、分隔符、长度这些和功能指令（业务侧）没有直接关联的数据类型也被我抽取了出来。

此时的Message和0101已完全解耦，变成了只含三个字段类型的POJO类。

image-20211127150158827.png

一层一层又一层

但是直接使用Message时还是有一些困难

• ASC对于上层业务指令来说还是太细节，而且无法很好的表达业务含义
  • 对于指令功能（Function），他们不关心下层如何序列化我的数据，只关心业务数据是否正确的被设置和接收
  • 对于消息数据（Message & Message Data），他们不关心上层数据有什么业务含义，也不关心下层这些数据如何被发送

多重施法！ —— 就像Attribute一样，使用Field接口将上层的业务字段进行了隔离。此后，当你想要发起一个指令，你只需要用富含业务信息的Field组建你的数据，接口会帮你完成剩下所有的事。

val request = MakePaymentRequest(ID = "000001", amount = 200.00)
val response = client.send(request)
val isSuccess = response.responseCode == ResponseCode.APPROVED

image-20211127160249771.png

当然还得加上串口连接的部分，里面会使用Blocking队列来将异步操作同步化

各个组件通过接口Request/Response, Message, Field, Attribute进行协作，大大增加了灵活性和可扩展性

也使用了注解、反射来统一实现对象的序列化操作

image-20211127160401744.png

测试...

Of cause，为了避免破坏已经构建好的功能，测试也是开发过程中需要慎重对待的环节（前面错一个bit，后面读出来的消息能跟鬼画符一样...）。对于协议（protocol）层来说，TDD用起来是非常爽的且高效的，但是到了数据传输部分就难搞起来了。

• 串口的读写操作是异步的，读操作是通过注册监听器实现的
• 因为类似长链接，在传输过程中遇到错误会发送ACK/NACK的握手信息，并且会触发重试

Option 1：构造多线程测试环境

• 创建Stub Server：使用了PipedInputStream,PipedOutputStream将Client的读写流给包装起来，通过另一个线程来模拟Server操作里面的数据，实现接收请求、返回数据。

  val serverInputStream = PipedInputStream()
  val serverOutputStream = PipedOutputStream()
  val clientInputStream = PipedInputStream(serverOutputStream)  // server output -> client input
  val clientOutputStream = PipedOutputStream(serverInputStream) // client output -> server input
  val connection = StreamSerialChannel(clientInputStream, clientOutputStream)
  
  val mockServer = Thread {
      Thread.sleep(50)                                                                  // 1.  wait for client
      serverInputStream.read(ByteArray(requestLength))  // 2. read request in server side
      serverOutputStream.write(ACK.getBytes())                  // 3. send ack to client
      connection.onDataAvailable()                                          // 4. notify client - simulate comm listener
      
      serverOutputStream.write(responseBytes)                       // 5. send response to client
      connection.onDataAvailable()                                          // 6. notify client - simulate comm listener
      
      Thread.sleep(50)                                                                  // 7.  wait for client
      serverInputStream.read(ByteArray(1))                          // 8. read ack in server side
  }
  val client = Client(connection)
  ....
  

Option 2：使用Fake的外部程序

• 虚拟串口：Windows和Linux上都有现成的串口调试工具，Win上的有界面更方便

  我使用的是Windows Virtual Serial Port Driver，因为虚拟串口不好操作写数据（或者是我太菜），我创建了2个虚拟串口A - B，将他们Pair起来；

  还是如上起2个线程，这时候Client通过串口A写入的数据，会被正在监听串口B的Server捕获；

  Server如期返回数据后，Client又能够从串口A接收到Response；

  而且所有数据操作和控制都在Test代码里，一键操作还是不错的；

• USB转串口芯片（稍微硬核）

  从某宝网购一块USB转TTL的串口芯片，装上驱动就能用；

  把read和write引脚短接，可以验证串口连接和数据传输是否正确；

  但是想要走通整个流程，还得控制write的数据 —— write/read接上树莓派，然后（一顿操作）就可以了；

Option 3：连接测试机

• （主要是我们的测试机器到的太晚，而且还是远程调试，所以才想了上面的办法先保证基本功能没问题）

  （不过由于前期的良好测试，拿到测试机后直接run test case没太大问题）

后记（脑补）

此文仅以笔者经验，阐述使用面向对象手法封装串口协议的一种方式。

虽然分析实现过程以“面向对象”为主，封装、基础、多态均有，但都是抽象的一种手法 —— 抽象，即是编程的本质，对问题域和解决方案域的提炼。选择合适的角度和层级分析问题、找寻共性、得出答案，将过程抽象为模型、方法论、原则，最后用何种代码、何种工具进行实现就不再是问题了。这也是架构师的职责所在 —— 将混沌、繁杂的问题通过分析变为复杂、简单的知识（Cynefin）。

虽然此处只是对串口协议做了一层封装，但相关的分析方式、分层模型一样可以套用到其他领域：

• 高级语言对汇编指令的抽象封装
• kubctl对K8S组件的抽象封装
• 云服务对软硬件服务的抽象抽象
• ...

Learning：在如今的云原生时代，抽象的层级又被拔高了一些，但软件工程的核心理论（短期）不会改变。如何将既有的分析模式、架构设计扩展到云原生领域...