1. 引言

由于工作的关系，会较多接触一些系统间交互的接口文档，这里既有互联网大厂、小厂、东厂、西厂的，也有国有、商业银行的，当然还有一些是支付、清算、监管等行业或机构的，可以说是方方面面都涉猎到了一些。
虽然这块儿不是由我的团队直接负责，但是也稍微地多留意了一下。可以说，没有对比，就没有伤害。这些接口设计及文档还是基本能满足需求的，但也是参差不齐，有些让人赏心悦目，由衷赞叹，有些则惨不忍睹，暗暗唾弃。
当然，本文的目的不是来批判和恶心谁的，主要还是想借这个机会，对系统交互设计和接口文档编写方面稍微做一下总结。

2. 接口文档

首先来看一下接口文档的编写。

2.1 编写原则

我们知道，文档是信息的载体，是用来沟通的工具，沟通效果越好的文档质量就越高。好的沟通效果就是把信息清晰、完整、有效地传达到沟通对象。所以，写文档时，也要学会换位思考，要清楚文档的使用者，要考虑他们的需求有哪些，他们在阅读或应用文档过程中会遇到哪些问题，要站在沟通对象的角度，来安排文档的内容和形式，方便对方阅读和使用，这应该是沟通之道，也是文档之道。

2.2 内容设计

接口文档的目标受众应该主要是交互双方的开发和运维人员，所以接口文档的内容也应该围绕他们来提供。下面来依次列举一下接口文档的各项内容。

• 封面
  封面即文档的脸面，内容可以包括：密级、标题、版本号、版本性质、发布方和发布日期等，简明扼要地说明文档的关键信息，方便读者决策。
• 版本
  为方便文档追溯和管理，此处可以使用表格形式，按照修订时间从前到后、版本号从小到大的顺序，列出每次修订的版本号、原因、主要内容、日期、修订者等，甚至审批人和审批日期。
  对于版本修订内容较多的或较为重要的，可以下方单独一个表格进行详细列举。
• 目录
  为便于阅读，提供树形文档目录索引，支持通过目录项快速定位到对应章节内容。
  当然，能从章节能方便地再跳转回目录更好。
• 引言
• 目标
  可以说明文档编写的目的、范围等。
• 对象
  可以列举文档阅读对象。
• 前提
  可以列举阅读文档所需背景知识等前置条件，如前置关联文档、相关业务或技术知识等。
• 术语
  列举解释文档涉及的专业术语，方便读者查阅理解。
• 约定
  说明文档编写原理、规范、阅读方法等。
• 交互总览
  使用简要图形画出接口涉及各方各类交互，表达出调用方向、调用时序、交互内容、交互形式、各方职责等信息。
  也可以在图形下发以表格形式按一定顺序展示各方各类交互的要素，方便读者了解交互的全貌。
  如可能，为各交互增加链接，点击后直接跳转到下发接口详细说明处。
• 通讯模式
  列举说明共有几类通讯模式，如请求应答模式、单向通知模式等，可辅助UML图说明交互过程，文字说明各方职责等。
• 报文规范
• 数据规范
  说明报文中所涉各类数据类型的定义方式，如字符串类型用C或char表示，数字类型用N或num表示等，以及数据长度、精度的表示方法，还有集合等数据的表示和处理方法，最好举例说明。
• 字段规范
  说明字段必填项、可选项、有条件可选项的表示方法及各方处理规则。
• 实时接口
  说明实时通讯接口的通讯协议、字符编码、消息头内容、消息体格式、加密算法、签名规范等，并提供报文示例。
• 文件接口
  说明文件传输接口的通信协议、字符编码、内容格式、加密方式、目录规范、文件名称规范等。
• 实时类接口
  按照业务发生时序分别依次说明各接口具体的业务意义、交互模式、访问地址、请求报文、响应报文、双方处理规则等，详细说明各字段使用方法、处理规则等。
  报文中的字段可以引用附录中的字段，以便统一管理。
• 文件类接口
  按照业务发生时序依次说明各文件接口具体的业务意义、交互模式、请求报文、响应报文、双方处理规则、目录规范、名称规范等，详细说明各字段使用方法、处理规则等。
  报文中的字段可以引用附录中的字段，以便统一管理。
  提供文件接口的示例报文。
• 附录
• 字段
  对各类接口中使用的字段列表进行说明，内容包括编号、中文名称、英文名称、类型、长度、备注等。
• 响应码
  使用表格列举各接口可能的响应码、含义、处理方式。
• 字典
  对各字段涉及的列表值使用表格进行枚举，主要包括代码、含义两项内容。

2.3 文件格式

文档文件的格式应当使用便于对方打开和使用的格式，如PDF、Word等。当然，在编写阶段，为方便编写和版本管理等，可以使用Markdown、Wiki等标记语言和相关工具。

2.4 注意事项

• 内聚性
  写接口文档也如同写代码，要注意“复用”、“内聚性”和“单一职责”，要避免重复“代码”，防止出现到处修改、前后不一致的问题。具体可以从本文前面的文档内容部分窥得一斑。比如，涉及各接口公共的信息，如数据规范、通信规范、字段定义、响应码、字典表等，都在单独的章节专门进行了说明，避免分散到各接口，导致不便阅读或不便修改。
• 版本号
  接口字段中注意设置版本号，以便沟通或做兼容性处理。
• 请求编号
  接口字段中注意设置全局唯一请求编号，可以区别于业务请求编号，方便对调用跟踪和处理。
• 扩展字段
  有些接口会预设一些扩展字段，方便在特定情况下使用，这种做法似乎很少能看到好处。
• 接口编号
  可以对各接口按照一定规则进行编号，如R001、F001等，方便沟通。

3 交互设计

说完了接口文档，我们再来看一下系统交互的设计需要注意哪些事项。

3.1 通讯设计

在通讯方面，根据交互系统实际情况，可能需要考虑以下几个问题。

• 通讯协议
  通讯协议可能是首要需要考虑的问题。
  系统交互方面，一般都会有实时通讯和文件批量两种方式。
  目前远程通信的方式和协议有很多，对于跨机构的实时交互，常见的还是使用HTTP，而文件传输接口一般会使用SFTP协议。传输的文件较大时，还要考虑压缩传输。
• 信息安全
  机构间一般通过专线通信。如果通过互联网通信，一般都要对报文信息进行加密和验签，防止信息泄露和恶意篡改。
• 报文格式
  实时交互常用的报文格式有key=value、Json、Xml等。
  签名验签注意约定字段的顺序、字符大小写、空白字符等的处理。
  Xml有自己的一套验签机制。
  文件交互时，一般使用换行符区分多条数据，使用分隔符或定长两种机制区分不同字段的数据。注意明确地约定换行符，避免受操作系统影响。
  一般都需要注意将日期时间类型数据的格式、货币型数值的单位、字符型的编码约定清楚。

3.2 一致性保障

由于网络等原因，调用可能会因异常而失败，为此就需要一些机制来处理双方业务状态的一致性。
一种方式是采用幂等设计，被调用方需要幂等地处理每次调用，并对并发调用进行协调，尽可能地最终处理成功。这样，调用方在调用异常或未确认最终结果的情况下，可以再次发起调用，以获得明确结果。
另一种方式是提供查询接口、通知接口，调用方可以按需使用查询接口查询每笔业务请求的最新状态，被调用方可以使用通知接口及时通知每笔交易最新状态。
当然，有些情况下，一般还会设计批量对账接口，由某一方提供一段时间内每笔业务的状态及关键数据，供另一方核对和处理，必要时返回对账结果。这里涉及到以谁为准的问题，以及不一致后如何处理的问题，需要具体业务具体确定。
一般来说，有幂等或查询机制即可以满足一致性要求，除非被调用方后期存在修改业务状态或数据的可能性，才提供对账机制。

3.3 性能问题

实时接口一般对系统的性能和可用性等方面要求比较高。如果可能的话，建议尽量采用文件批量交互的方式，或者实时异步通信方式。

到这里，本篇文章就结束了，如果后面有想到的，还会随时更新，希望能够抛砖引玉，对大家能有所启发和帮助。