如何设计优雅的API接口？API接口设计方案怎么做？

核心思路叫“依赖倒置”；实现时要尽量“完整且最小”。

高层模块不应该依赖低层模块，两者都应该依赖其抽象；抽象不应该依赖细节，细节应该依赖抽象
High level modules shouldnot depend upon low level modules.Both should depend upon abstractions.Abstractions should not depend upon details. Details should depend upon abstractions.

依赖倒置这个概念比较难理解。我们最好借助一些经典例子来认识它。

举例来说吧，网络编程时我们经常要用到——让我们暂时忘记socket的接口设计方案，自己从头分析一番。

首先，我们要支持用户拿它编写各种各样的网络应用。比如跑网页的apache/nginx，比如即时通讯的QQ和WeChat，比如被炒的火热的区块链，比如早年名噪一时的分布式下载应用bt，比如加密通讯协议tls，比如zookeeper，比如流媒体，比如远程桌面，比如网络中的网络VPN……比如淘宝，比如bilibili，比如知乎，比如王者荣耀比如明日方舟比如我画你猜等等等等……

这还是已经存在的应用。未来，还不知道会有多少应用依赖于它呢。

请问，这个东西该如何设计？

你看，如果你从这个错误的角度开始思考，那你必定傻了。这压根就是个不可能完成的任务嘛。

要不，我们换一个方向？

为了实现socket通讯，我们的数据可能通过UDP传输，也可能通过TCP传输；而TCP拥塞控制算法的核心是滑窗算法，但具体的算法嘛……起码十几二十种是有的，最新一个叫BBR。

不仅如此TCP两端的控制算法可能不同，另一端可能无法支持最新的BBR（甚至某些老爷机连五年、十年前的某个改进都还没有应用）；同时，IP报文的承载协议可能是以太协议也可能是光纤；上网方式可能是56k猫拨号上网也可能是ADSL，甚至可能是某种自定义的无线电协议……

那么，这里就可以看出“依赖倒置”思想的精辟之处了。

高层模块不应该依赖低层模块，两者都应该依赖其抽象；抽象不应该依赖细节，细节应该依赖抽象。

这句话是什么意思？

意思是：别管用户怎么用你的socket（高层不应该依赖底层模块）；也别管socket将来要如何实现（抽象不应该依赖细节）——先问问自己，我，应该把socket做成什么样子？

仍然很简单：对于socket的设计者来说，为了方便用户应用，我们把socket抽象为“网线插头”；而为了方便我们实现socket，我们把底层通讯协议抽象为一根根看不见的“虚拟网线”。

那么，当用户想要和别人通讯时，他应该先捏住插头扯来一根能够和对方联通的网线——嗯嗯，为了不同目的，这根网线应该分别表现的好像有缓冲/无缓冲文件一样：前者是TCP，后者是UDP……

所以，这个接口应该是socket(协议域，协议类型，报文类型)——这三者就决定了这根虚拟网线上将要传输什么样的数据、走什么样的协议。

然后，这根网线的一头肯定在咱自己的机器上，这就不用管了；另一头要“插”到远端机器上。

怎么插呢？

当然，这个是面向对象写法。传统的过程式写法是connect(文件描述符，对方网络地址)

其中，文件描述符就是之前建立的socket文件——但事实上，它也完全可以是一个磁盘文件或别的什么东西（不妨看一看Linux socket怎么玩），方便用户本机调试或者做一些骚应用。

好了，两头都连上了，那就write往远端写东西、或者read从远端读入数据吧。

写完了，拔掉插头: close(文件描述符)

嗯，泛文件抽象。方便你直接用echo之类命令向网络灌数据、或者拿socket当文件丢给log之类程序让它记录下来——甚至它们玩链式传输都没关系。

这是客户端抽象。

服务端呢，也差不多：socket创建好之后，bind到本地一个地址上——意思是你不是插头，你是墙上的插座。

在墙上装好（bind）插座之后，开始监听（listen）；如果远端有人试图连接，可以接受这个连接（accept）——然后，仍然和客户端一样，当成文件读写吧。

你看，这个抽象简单、清晰，恰到好处的完成了任务，没有做丝毫多余的事——然而却又有不可思议的兼容性、以至于从老掉牙的telnet直到现在奇怪的区块链应用，它都能轻易支持。

但是，请注意：别管用户会怎么使用它、或者将来你以及你的同事以及接手维护它的其它人该怎么实现它。这些你都不要考虑。

你要考虑的是，我的这个抽象给出的功能集是不是完整、接口集合有没有冗余（最小）。

完整，意思是这个接口设计完整的模拟了“通讯线缆”这个应用场景，允许你拿它当一根真正的电缆来使用，电缆该支持的功能它都有、不会出现“我需要什么功能却被你封装的看不见了搞的我多费九牛二虎之力最终还是只能放弃、或者不得不窥探你的内部实现、搞的你不能随便改否则我们一大票程序都要崩”；最小，意思是这个接口每个功能都必不可少、没有重叠的部分，从而降低了使用者的思维负担也降低了实现者的心智负担——不需要我考虑究竟是用iQQServer建立类QQ服务器呢、还是用iWeChatServer建立类微信服务器（以及两者究竟有什么微妙的差别）；也不需要你琢磨什么“我这个iMSNServer究竟该从QQ还是WeChat继承”。

当然，有时候完整且最小会和效率产生矛盾、有时候为了方便用户（比如某些流程的自动化）我们也不得不提供一些冗余接口；但完整且最小的接口一定要找出来——它代表着你有没有真正抓住设计要领、是不是真的想通了来龙去脉。

恰恰是接口设计的“我行我素”、上不理你QQ多流行也不理你马云有多富，下不管你是用BBR做拥塞控还是拿先进的不得了的WiFi6借光纤进了机房、然后又走了卫星信道——这些统统不管。反正我看见的，只是一根虚拟电缆和它两端的插头；怎么用这玩意儿是你的事，怎么用你的通讯方案模拟出这玩意儿也是你的事，我不该对你指手画脚——这才给了它无与伦比的兼容性和稳定度，才让高层用户用着舒服、底层开发者实现起来也能随心所欲；这才使得自几十年前设计出来之后，它基本就没变过。

正所谓“少即是多”。举重若轻、化繁为简，这才是真正的优雅。

最后，再强调一次：接口稳定靠的不是拍胸脯不是兢兢业业任劳任怨，而是高屋建瓴。

类似的，找出这个简洁有效的socket抽象，靠的也不是傲娇——你要说网络啊……那就是一根管子，push一些数据过去，pull一些东西过来，所以得区分使动和被动、使动端不先push一个请求被动端就pull不到东西……不管你们信不信，反正我信了。

这个抽象似乎也简单形象，但无论用起来的方便程度还是响应速度，那都没法看了——很多人之所以设计不好接口，原因就是其实他并不是很清楚自己面对的是什么情况，只能照着一些清规戒律碰运气。

你必须从根本上搞清楚网络是怎么一回事、是拿来做什么的；然后站在一个很高的位置俯视它、概括它，这才能一把抓住根本：任网络底层百家争鸣、上层千变万化，但网络这玩意儿，就是可以拿它当一根虚拟电线看。

API接口设计方案

{
    "code": 0}

{
    "code": 1,
    "message": "参数错误"}{
    "code": 1001,
    "message": "未登录"}

{
    "code": 0,
    "data": {}}

{
    "code": 0,
    "data": [],
    "pageSize":10,
    "currentPage":1,
    "totalPage":5,
    "totalCount":49}

data: { token: 123456 }

data: 123456