产品必修课：接口文档怎么用？

阿宅的产品笔记 2023-08-02 17:14:54

又到了周末，快乐开黑开始！阿宅兴冲冲得找小伙伴上号，结果小伙伴尔康摆手：“等一下，我先开电脑喷下开发。”

阿宅一局酣战之后，又来找到小伙伴：“好了没？”“没好，我被开发喷了，是我的需求bug，老板还骂我了，你看。”

为了让小伙伴尽快上号，我们开始一起复盘：“这是关于基金购买流程的需求，我在这个地方需要先明确基金的委托类型，我问爷爷找爸爸终于把这个理清楚了，可以分为购买、赎回、定投。结果上线后才发现分类没定义完整。”“这玩意不是接口里写得明明白白吗？”

“！！！！接口文档是个啥！我怎么从来没看过！”

“你啊你，都做了半年理财产品了，竟然连这个都不知道。那本宅就大发慈悲教教你吧，记住明天给我一根冰糖葫芦。”

一、什么是接口文档？

首先，什么是接口？你可以把它简单理解为一个函数，你输入x，它就会告诉你y。你无需知道这个函数的逻辑，只需要知道输入什么样的问题，会得到什么样的答案就可以了。

但x怎么输，会出现什么样的y，就需要通过接口文档来了解。就比如下图的表格，当你按照“输入参数”输入“委托方式”、“分支机构”等参数时，这个接口就会告诉你“资产账户”是什么。

恒生统一接入平台_周边接口规范(期货,期权_20210812).xls

接口一般来讲分为两种：

程序内部的接口：方法与方法、模块与模块之间的交互，如登录发帖，发帖就必须要登录，如果不登录不能发帖，发帖和登录这两个模块之间就要有交互，就会抛出一个接口，进行内部系统调用。
系统对外的接口：从别人的网站或服务器上获取资源或信息，对方不会提供数据库，只能提供一个写好的方法来获取数据，如购物网站和第三方支付，购物网站支付时可选择第三方支付方法，但第三方不会提供自己的数据库给购物网站，只会提供一个接口，供购物网站进行调用。

这便意味着开发的人甚至团队都不一样，为了便于沟通，便有了接口文档。从这里可以看出，接口文档大多时候是给开发看的，那么产品为什么要会看这玩意呢？

首先，在迭代或依赖其他系统时，你能明确知道有哪些资源。例如下面这个关于微信菜单创建的接口，从这个接口的参数“type”的说明，我们就能清楚的知道，微信菜单能实现3种交互：一是直接点击打开网页；二是消息推送；三是跳转小程序。

其次，业务很复杂的时候可以通过接口反推，例如我们在做期货需求时，不清楚期货产品分为哪些，这时我们便可以找到恒生的接口查查它的数据字典，结果就发现答案竟如此清晰：

再次，在写需求文档或和开发沟通发现说不明白时，也可以通过文档来澄清。例如做内容排序时可能有多个时间：创建时间、更新时间、操作时间等等。而你想调用的时间和开发理解的可能会存在差异，这时你便可拉出接口文档告诉他我要的就是CreateTime。

当然啦，接口文档还有很多妙用，比如作为撕逼利器、装逼神器等等，欢迎大家在留言区写下你的文档故事~

接口文档有这么多好处，那我们怎么去读懂它呢？在这里我们用微信订阅通知的接口文档作为学习材料。

如上图所示，接口通常分为四部分：请求方法、url、请求参数、返回参数：

1）请求方法：常用的方法就是下面的四种——GET、PUT、POST、DELETE。

GET请求会向数据库发索取数据的请求，从而来获取信息。该请求就像数据库的select操作一样，只是用来查询一下数据，不会修改、增加数据，不会影响资源的内容，即该请求不会产生副作用。
与GET不同的是，PUT请求是向服务器端发送数据的，从而改变信息。该请求就像数据库的update操作一样，用来修改数据的内容，但是不会增加数据的种类等。
POST请求同PUT请求类似，都是向服务器端发送数据的，但是该请求会改变数据的种类等资源，就像数据库的insert操作一样，会创建新的内容。目前所有的提交操作几乎都是用POST请求。
DELETE请求顾名思义，就是用来删除某一个资源的，该请求就像数据库的delete操作。

这个概念产品经理简单了解即可，一般不考

2）url：以微信微信订阅通知接口的url为例https://api.weixin.qq.com/wxaapi/newtmpl/addtemplate?access_token=ACCESS_TOKEN

我们可以把这个 URL 分解成 5部分：

协议部分：指访问服务器获取资源时，需要使用哪种协议。常用的有http、https、ftp协议等。本例中的为https。
域名部分：指资源宿主服务器的主机名或IP地址。本例中的域名部分为：api.weixin.qq.com。URL中也可以使用IP作为域名。
端口部分：域名和端口之间使用“:“作为分隔符，端口不是一个URL必须的部分。http服务的默认端口是80，这种情况下端口号可以省略，如果使用了其他端口必须知名，例如：http://www.azhai.com:90/。
虚拟目录部分：该部分说明了资源位于服务器的什么地方。从域名后的第一个“/“开始到最后一个“/“为止，是虚拟目录部分。本例中的虚拟目录是“/wxaapi/newtmpl/”。
文件名部分：从域名的最后一个”/“开始到”?“为止，是文件名部分。如果没有”?“，则是从域名后的最后一个“/”开始到“#”为止；如果没有“？”和“#”，那么从域名后的最后一个“/”开始到结束，都是文件名部分。文件名部分也不是一个URL必须的部分，如果省略该部分，则使用默认的文件名。本例中的文件名是“addtemplate”。

同样，产品经理不需要非常明白。

3）请求参数和返回参数：请求参数和返回参数都分为：字段、说明、类型、默认值、是否必填这5列。