怎么看懂接⼝⽂档
本⽂转载⾃CSDN博主「陪学」的原创⽂章
原⽂链接：blog.csdn/weixin_42058609/article/details/105147681
-------------------
⽇常产品开发过程中，涉及前后端数据交互的时候，往往会离不开接⼝调⽤，尽管产品经理⼀般不需要写接⼝⽂档（负责接⼝中间层产品经理除外），但对接⼝了解，对于需求沟通、需求传达还是很有帮助的。
接⼝是什么？
API（ApplicationProgramming Interface）即应⽤程序接⼝。
可以认为 API 是⼀个软件组件或是⼀个Web 服务与外界进⾏的交互的接⼝。从另⼀个⾓度说，API是⼀套协议，规定了我们与外界的沟通⽅式：如何发送请求和接收响应。
API的本质是根据调⽤者的输⼊内容来返回⼀些其他内容。
举个栗⼦，这和我们⽣活中接触的USB接⼝的原理是类似的，我们知道接⼊某个接⼝就能实现某种功能，
例如：U盘插⼊电脑USB接⼝就可以相互传输⽂件。
产品经理看懂接⼝⽂档的意义
1）了解技术开放能⼒，产品设计更合理
例如，我们公司是做⽣态相关的产品的，开放了许多的接⼝，如果不了解的接⼝⽂档，往往就不知道如何应⽤到⾃⼰的产品。
2）通过接⼝构建产品功能。
通过现有接⼝来搭建产品，通过对接⼝、技术的理解，能够更深⼊地衡量产品的数据边界，对针对性的进⾏产品特⾊功能设计。
接⼝组成
接⼝分为四部分:
1、⽅法:
新增(post) 修改(put) 删除(delete) 获取(get)
2、格式：
以/a开头，如果需要登录才能调⽤的接⼝后⾯需要加/u(如新增、修改；前台的⽤户个⼈信息，资⾦信息等)，即：/a/u；中间⼀般放表名或者能表达这个接⼝的单词；
get⽅法，如果是后台通过搜索查询列表，那么以/search结尾，如果是前台的查询列表，以/list结尾。
3、请求参数和返回参数，
都分为5列：字段、说明、类型、备注、是否必填
字段：类的属性
说明：中⽂释义；
类型：属性类型；
备注：⼀些解释，或者可以写⼀下例⼦，⽐如负责json结构的情况，最好写上例⼦（这⾥不是产品写），好让前端能更好理解；
是否必填：字段的是否必填。
4、返回参数结构的⼏种情况
如果只返回接⼝调⽤成功还是失败（如新增、删除、修改等），则只有⼀个结构体：code和message两个参数；
如果要返回某些参数，则有两个结构体：1是code/mesage/data，2是data⾥写返回的参数,data是object类型；
如果要返回列表，那么有三个结构体，1是code/mesage/data,data是object，⾥⾯放置page/size/total/totalPage/list 5个参数，其中list是Arrary类型，list⾥放object，object⾥是具体的参数。
接⼝请求⽅式
基于http协议的常⽤请求⽅式是post和get；两者的主要区别如下：
（1）get请求⽅式是将请求参数放到url中，post是将参数放到requstbody中，
直接影响是get的请求参数存在长度限制，post⽆限制；其次是get将参数放到url中安全性弱于post；
（2）get请求⽅式⽤户端和服务端只产⽣⼀次交互，post请求⽅式⽤户端会和服务端产⽣两次交互，
例：快递⼩哥是⽤户端，你是服务端，get就像常来你们⼩区和你认识的快递员直接将快件送到你家，你跟他说声谢谢；post就像新来的快递员先打个电话问下你在家吗？你告诉他你在家呢，过了5分钟他将快递送到你家了，你跟他说声谢谢；
接⼝响应机制
接⼝的响应机制包括：
同步接⼝
异步接⼝
同步接⼝即实时返回消息给调⽤⽅，异步接⼝就是可以延迟返回消息给调⽤⽅；实时性要求⾼的且只能线性⼯作的需要采⽤同步接⼝，其他可以优先使⽤异步接⼝；
不同的场景，同样的服务接⼝会被要求同步或异步，以⼈脸识别中的⼈脸注册为例：
（1）刷脸⽀付：
以⽀付宝为例，使⽤之前需要按照步骤采集⼈脸，后台调⽤⼈脸注册将当前⼈脸注册进⼈脸库并和该⽀
付宝账号信息绑定，这⼀步⼈脸注册通常是同步接⼝，因为不会要求⽤户在APP前等待太久，需要及时返回注册成功信息；
（2）客流系统：
商超使⽤的客流系统⼀般已经采⽤⼈脸识别取代头肩模型，这样不仅可以统计⼈数还可以统计⼈次，其中对于⾸次识别的陌⽣⼈脸通常需要注册进陌⽣⼈脸库，这⾥的⼈脸注册⼀般为异步接⼝，因为⼤型商超每天数⼗万客流且对于陌⽣⼈⽆会员信息，所以不需要实时注册，只要进⼊队列能在当⽇24⼩时内注册完即可；
关于API的接⼝在设计时，开发⼀般会要求产品确定接⼝的响应机制；其他的开发都会⾃⼰完成；
很多产品经理刚接触API接⼝⼯作时，脑⼦⼀⽚空⽩，不理解接⼝（API）是什么，更看不懂接⼝开发⽂档。那么，作为⼀个不懂技术的产品经理，该如何看懂接⼝⽂档。
API⽂档结构
API接⼝⽂档⼀般分为接⼝描述、接⼝地址、请求⽅法、请求参数、相应内容、错误代码、实例⼏个部分。
1、接⼝描述
简单描述接⼝的逻辑和作⽤
2、接⼝地址
接口文档怎么看接⼝的正式url和接⼝测试的url，需求⽅通过调⽤接⼝url，获取响应内容
3、请求⽅法
⼀般来说，接⼝最常见的请求⽅法为GET和POST两种⽅式，即读接⼝和写接⼝。通过这两种⽅式，实现对数据的增删查改。增删改本质都是写的动作。
4、请求参数
即需要请求的字段名的名称和规则：都是哪些字段，字段的类型是什么，是否必填字段等等
5、响应内容
接⼝返回的字段名称和规则。
注意：⼤部分开发往往不会把所有的字段罗列，只会列出⽐较重要的字段。当你发现，接⼝⽂档中没有你需求的字段，别着急开发，可以看下实例中，有没有需求的字段。
6、错误代码
对接⼝的错误⽤代码进⾏归类，以便能快速到错误原因，解决问题。
7、实例
实际调⽤时的响应的内容。
核⼼业务字段&接⼝约束
产品经理虽然不需要定义API⽂档⾥所有的字段信息，但是跟业务需求有关的字段产品经理需要明确清晰。
下⾯就来看看API⽂档中的核⼼业务字段与接⼝约束。
1. ⼊参
（1）鉴权字段信息
调⽤第三⽅平台接⼝通常需要进⾏接⼝鉴权，服务端判断⽤户端是否有调⽤接⼝的权限；产品经理设计应⽤管理时，要了解：应⽤列表、应⽤创建、应⽤详情、应⽤配置、应⽤删除等操作；
以百度AI平台为例，应⽤列表如下：
AppID、API Key和Secret Key为创建应⽤时⾃动⽣成，接⼝鉴权所需要的access_token必须通过API key和Secret key请求服务端获取。（2）核⼼业务字段
产品经理要根据业务需求明确接⼝⼊参中需要哪些字段信息以及字段⽀持的类型，
以百度AI平台的菜品识别为例：

版权声明：本站内容均来自互联网，仅供演示用，请勿用于商业和其他非法用途。如果侵犯了您的权益请与我们联系QQ:729038198，我们将在24小时内删除。