最近两年一直在和银行、公安、保险、民政等第三方单位之间做接口，写的接口文档不下30份，最初的接口文档漏洞百出，改了又改，丢了不少人，也被批评、埋怨，指责了很多次，久而久之，明白了一个最重要的道理，协作决定接口。双方谈接口时，技术不是最重要的，要兼顾双方技术，成本，工期等等很多因素。但仍有很多技术层面的心得，恰巧上周参与温昱老师的一个性能设计的外训，里面老师讲到了接口设计，正好回来一起整理一下接口设计的经验。主要从3个方面总结一下系统间接口设计：接口定义、接口实现、其他一些注意事项。
一、接口定义
接口是双方（可能是系统、模块、服务等）之间数据交互的一个标准，定制接口方要想让对方没有疑问，接口考虑到的因素一定要全面，一般情况下，主要考虑3个步骤：
交互机制：如同步请求/应答方式、异步请求/应答方式、会话方式、广播通知方式、事件订阅方式、可靠消息传输方式、文件传输等。
接口结束：WebService、Scoket、交易中间件、消息中间件、文件方式、共享数据库等。
接口格式：这个就根据所选技术，实际情况来定义即可。
拿我们（具体行业不便透露）和银行的接口为例（和每个地区银行都不同，以1个为例）
交互机制：异步请求/应答方式，我们有查控请求时调用银行接口，将请求信息发过去，银行查控完毕后，调用我们接口，将查控结果反馈给我们。调用失败后，会有重试，重试每30分钟一次。
接口技术：WebService接口，Java开发，xml格式报文，数据采用3DES加密。
接口定义：具体字段说明，xml格式等略。
有了这些说明，在对方拿到接口文档后，不出意外（比如对方完全不懂技术，无法看懂）对方都能看懂接口，也能描述清楚，如果回答不上这些问题，恐怕就是有漏洞了。
这个接口还有很多不完善的，很多地方有更好的选择，还是前面说的，协作决定接口，合适即可。
二、接口实现
接口定义完成了，开发过程中要考虑的就是非功能层面的了，比如各种约束，像我们这边数据量、并发都较大，需要考虑下面几个情况：
1.高性能，支持高并发，大容量，速度快；
2.健壮性，防止因大量数据，或大量占用资源导致系统不可用；
3.可监控，随时看到接口的运行情况，便于及时发现错误及排除故障；
4.可扩展，两个方面，一是可支持扩展新功能，二是并发增加时支持扩展新硬件。
考虑这些可能会引起接口的改变，比如我们考虑高性能，速度快时，由于我们同时对应30多家银行，每个银行每天大约1000人次查询，单个调用需要3w次，所以改成了支持批量，单次调用最多100人，发送和接收大约5s左右。同时由原来串行改成了并发调用，使用了一个线程池（线程不能太多，可能造成银行接口并发太大导致崩溃）。
有时主动发起的接口可能不如定时轮询的接口，比如上面我们的接口是主动发起，需要做连接池限制并发，免得并发多了给银行造成问题，后来再其他省改成了完全由我们做服务端，银行定时调用获取要查询的请求信息，虽然有几分钟延迟（依据银行轮询时间决定），但是开发简单不少，考虑的情况也少了不少，接口速度也快了不少。
考虑可监控时，有很多开源监控组件，比如我们用的JavaMelody，可以监控某个类执行次数。
考虑可扩展，功能可扩展，比如我们用XML、JSON格式报文，或者其他自定义格式，有一定的规则，千万别用具体含义的参数，一旦增删就会影响接口。
三、注意事项
1.支持批量，这个一定要有，主要是为了性能考虑，后续数据量大了，再修改支持批量就会导致整个接口修改，所以前期一定要支持批量。
2.支持部分拆包，比如报文中最好解析报文头就能知道具体业务或能找到处理的逻辑，避免全部解析后才能知道如何处理，比如我们和一个公司做接口（他们制定接口），有10多个实现类，他们文件加密的，必须整体解密后才能读取到用哪个实现类处理，文件大约200M，每次处理5s左右，有3s都在选择用哪个实现类，并发时及其慢，后来改成了前面32个字节标示哪个实现类，后来处理每个包2s左右，性能提升40%多。
3.安全性，接口的安全控制在逻辑上包括：安全评估、访问控制、入侵检测、口令认证、安全审计、防恶意代码、加密等内容。这个根据实际情况，有些单位要求高，有些无所谓，不涉及互联网的项目，加密为了防止管理员直接看到等，要求不高的Base64就行，或者3DES，高点的通道认证等，再高就根据具体情况来了。
4.实体文件，FTP等方式传实体文件比较容易，我们用WebService较多，文件较小的一般采用转换成文本（Base64），当文本传输，好处是简单，缺点一是慢，二是文件大了或并发大了，内存可能不够；文件大的，我们一般放到FTP上，然后传给对方FTP上的路径，这个配置比较麻烦。
5.日志，这个最最最重要，接口的每个环节都要保留详细的日志，可以设置优先级，上线后单独打印到某个文件或者只保留重要的，因为现场出错后只能根据日志分析，很多情况下对方的接口问题对方不承认时，或者出错后对方把责任扔给咱们时，你会发现最可靠的就是日志。
6.监控，这个也太重要的，但是我们经常忽略，很多时候双方联调测试都没问题，经常一上线就出问题，不外乎数据量大了，并发大了等，此时有一个监控页面，你顿时就会信心倍增。
7.接口文档编写，一般公司都有自己的接口文档模板，当然我们也有，大部分模板都主要定义个一些步骤，如背景、功能描述、交互机制、安全性……我这整理一下我和各各单位讨论时，碰到的一些文件描述不清楚问题，主要是一些格式定义，字段说明等
（1）字段类型，一定要统一标准，比如日期、时间格式，不足补0等，如2015-01-0112:01:02。
（2）实体文件，是Base64之后传递字符串，还是其他规则，或者传递一个FTP上的地址，如果是地址，结束时是否带有斜杠“/”等。
（3）数值，精确小数后几位，小数点前后位数不足时是否补0等。
（4）异常，最好有错误码，或者其他信息，以及错误后处理机制等。
（5）必填项如何校验，代码值是否需要校验等。
（6）最重要的一点，写完了一定要给别人看看，看看别人是否可以看懂，用词准确，是否有遗漏等。
上面只是一些大体的总结，适合一些web项目等，很多其他模式下的接口都不适用，各个点也都没有深入的研究，后续研究后再加进入吧。