本文首发于个人微信公众号《andyqian》, 期待你的关注!
前言
接口是目前:前后端交互(Rest),系统交互(RPC)最普遍的一种方式。一个好的接口,应该清晰易懂,职责明确,易于维护。反之,则会造成很多困扰。特别是Open API,谁做谁知道。基于这样的前提以及自己之前踩过的坑,就成了这篇文章的由来。
编写文档
文档与程序员之间有着一种非常奇妙的关系。一句话概括就是:”写之,痛之。用之,悔之”。怎么解释呢?就是:写的时候觉得很痛苦,不愿意写!用的时候呢,又后悔当初没有留下文档! 可见文档是多么重要。以Rest接口为例,文档需要详细的记录请求参数,返回参数,每个字段的意思,是否必填,请求方法等。随着代码的更新,文档也应该及时更新。在很多开发者眼里(包括我自己),觉得写文档是一件浪费时间的事情,写代码才是正经事。随着工作经验的积累,愈发觉得文档的重要性,不但没浪费时间,反而还在节省时间。
符合最小原则
这个原则其实是有点像设计模式中的迪米特法则(也称为:最小知识原则),不过我认为这其中包含了两层意思:
其一:在接口设计中,请求参数在保证功能的前提下:尽可能的减少参数,更不允许添加无用的参数。以Rest接口为例:一旦添加了无用的参数,在后续迭代过程中,就会遇到:<