定义接口时应注意的问题

(本文最早由我于2018-03-12 22:51在cnblogs上发表：https://www.cnblogs.com/firas/p/8552597.html）

1、 要指明接口输入输出参数使用什么方式传递，是用XML还是JSON还是其他。如果用分隔符分隔不同的字段，则要说明分隔符是什么，字段内容是否需要根据分隔符进行转义，如何转义。
例如CSV文件，分隔符是英文半角逗号","，字段内容若含有英文半角逗号，则需要用双引号括起来；如果字段内容里含有英文半角双引号，则需要转义为两个英文半角双引号。

2、 标明字段的名称、数据类型、最大长度、不足最大长度时是否在数据前/后补空格、是否可为null、是否可不传、描述说明。
name字段可为null的数据示例：{"id":1, "name":null}
name字段可不传的数据示例：{"id":1}

3、 字段的命名风格应该一致。
如果一个接口中，一个字段叫userNo，一个字段叫UserName，一个字段叫user_nick，一个字段叫做idcardno，一个字段叫做GENDER，会让 调用方 容易混淆，解析和处理字段需要的逻辑也会更加复杂。
不同接口中字段的命名风格也应该一致，如果一个接口的字段用驼峰命名法命名，一个接口的字段用下划线命名法，也容易导致混淆出错。

4、 同样意义的字段命名应该一致。
如“用户编号”字段，就不应该在一个接口中叫做userNo，在另一个接口中叫做userCode。

5、 数值字段需要标明可接受的小数位数、最大值、最小值、是否接受千分号（"100,000"）、是否可接受科学记数法表示（"1E6"）、是否可接受省略小数点前/后的0（".1"、"1."）。

6、 与货币有关的数值字段，需要标明单位是“元”还是“分”。

7、 日期、时间字段需要标明格式，如“yyyy-MM-dd”、“HHmmss”。

8、 字符串字段要标明编码，如“UTF-8”、“GBK”。

9、 字符串字段如果有最小长度限制、正则表达式匹配限制或其他限制，也需要标明。

10、 按字符串搜索的接口，需要标明是准确匹配，前缀匹配，还是部分匹配。
例如用户搜索“洗衣机”的时候，是只能搜索出”洗衣机“，还是能搜索到“洗衣机出水管”，还是连“海尔洗衣机”都能搜索到。

11、 最好给出正常的接口调用的输入输出数据的样例，以便 调用方 明确接口的定义和进行初步的调试。

12、 定义好发生异常时返回的数据，以便 调用方 对异常进行处理。
例如用户名密码登录的接口，要定义好数据库访问失败、用户不存在和密码错误等异常的返回。

13、 最好在接口调用的路径或参数中加入接口版本号，以便在接口升级时兼容旧版本接口。

14、 接口升级、修改时，应该在文档中记录好接口修改的地方，以便 调用方 快速知悉要修改的地方。

15、 在提供给手机App或者电脑应用程序的接口中，最好定义一个字段用于显示给用户的异常提示信息。
因为用户不一定会及时更新手机App和电脑应用程序，如果在App中写死异常提示信息，那么如果异常提示信息需要修改，或者接口返回了App没有处理的异常，那么就可能显示给用户错误的或不友好的异常提示信息。如果由接口来返回异常提示信息，则可以更方便地控制显示给用户的异常提示信息。