定义接口时应注意的问题

定义接口时应注意的问题
0
  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.”)。
    最好还要说明,如果小数位数有限或有效数字有限而遇到有舍入的情况,是如何舍入的,是四舍五入(满 5 向上取整),还是向正负无穷大取整,还是向上 / 向下取整。

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

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

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

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

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

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

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

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

  14. 接口升级、修改时,应该在文档中记录好接口修改的地方,以便 调用方 快速知悉要修改的地方。可以在文档中记录一个变更日志。

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