webservice接口实例_产品经理需要看懂接口文档吗？

最近在帮研发小gg 检查外部三方对接的接口文档，想到那些年因不懂接口而踩的那些坑儿，感触略多，于是催生了这篇文章。看完的 PM 们技能值都会 Upupup❕

互联网产品的研发过程中，一旦涉及前后端数据交互，往往都离不开接口调用。“了解接口设计” 也逐渐成为了产品经理面试时的加分项。

确实，会看接口文档能给 PM 注入更多的开发者思维、拓展自身产品思维，也能帮助刚入职的 PM 快速了解技术开发能力和现有产品功能。另外，会拆解需求中的接口设计要求，还能帮助 PM 合理地评估开发工作量、合理排期，设计出更好的产品。

今天就从这两个方面着手，分享经验：

• 如何查看接口文档

• 如何剥丝抽茧，拆解产品需求，参与接口设计

接口是什么

应用程序的编程接口(Application Programming Interface，简称 API) ，本质是一种已经定义好的函数逻辑。我们可以把它想象成黑匣子，使用者无需知道接口具体的实现原理，却可以通过它实现一些既定功能。

接口的用途

接口的主要用途是供其他方请求，然后返回对应的结果，以实现某一具体功能。

举例：某接口的函数可以用 y = 2x 来表示，当我们输入 x = 2 时，接口通过自己的逻辑运算后告诉我们：y = 4。

当产品研发涉足其他领域，考虑到研发的投入产出比，降低研发成本，企业往往会优先选择购买、调用其他公司提供的成熟接口。

举例：公司A要开发一款新的理财 app，用户在注册时需要进行人脸识别。但对A而言，开发一套人脸识别程序的成本较高，而且技术复用可能性小，如果自主研发，投入产出比低；于是A可以选择去旷视、商汤等成熟的人脸识别厂商所提供的开放平台，购买、调用人脸识别应用的接口，这样就能在 app 的注册页实现人脸识别的功能了。

接口文档

详细描述如何调用接口的文档就叫 “接口文档”，一般由后端(web产品)或前后端(app产品)共同定义。一份规范的接口文档是前、后端开发工程师和谐相处的基础，在项目之后的维护和迭代时，也方便其他人员查看。

前后端交互逻辑示例：

图中的浏览器、服务器就相当于我们常说的前端、后端，他们之间的交互需要遵循接口文档。如果前端想把“姓名”、“手机号”、“校区” 这三个值传给后端，就必须符合接口文档的规范，否则将得不到预期效果。

接口文档的框架

接口文档一般分为以下 7 个部分：

• 接口描述

包含接口的介绍、适用场景、使用说明和使用限制等相关规则。

• 接口地址

接口正式的url地址，需求方通过调用url，获取响应内容。

• 请求方法

一般来说，接口最常见的请求方法为 GET 和 POST 两种方式，即读接口和写接口。通过这两种方式，实现对数据的增删改(POST)查(GET)。

注：

GET请求提交的数据显示在地址栏里，不安全且数据量有限制，慎用。

POST请求采用隐式提交，安全且没有数据量限制，推荐。

• 请求参数

请求该接口时需提供的参数，常见的参数属性：字段名称、字段、字段类型、是否必填、示例值、说明等。

• 返回参数

接口正常响应后，返回的字段名称和规则。

注： 

研发小gg 一般只会列出重要字段，当你发现接口文档中没有需要的字段时，可以在最后的实例部分中寻找。

• 错误代码

接口请求失败后，返回的错误代码、对应释义及排查策略。

• 实例

实际调用时响应的内容示例。

详细的接口文档案例，可参考高德开放平台Web服务API：

https://lbs.amap.com/api/webservice/summary/

接口设计

当 PM 产出详细的产品方案时，可以通过参与接口设计，详细地梳理、拆解设计细节：在梳理需求对应的接口时，先将功能细化，按照所设计的操作一步步拆解需求，想象每一步操作之后，前后端的交互以及后端逻辑分别是怎样的，然后再思考：

• 用哪一种接口比较好；

• 请求参数中应设置哪些字段、是否必填、有无字段格式要求等 -> 页面展示字段；

• 返回参数中应设置哪些字段、是否必填、有无字段格式要求等 -> 页面提示或跳转；

• 可能遇到哪些非理想情况、对应前端如何提示用户等 -> 提示文案；

举例：

用户登录：用户输入登录信息后，后台根据所填手机号或用户名、密码等校验用户是否存在，如果存在，登录密码是否正确等，最终返回登录结果。

1)这一步虽然只涉及查询，不涉及写入操作，但考虑到安全性 -> 采用POST接口；

2)需要输入哪些信息? -> 请求参数字段有哪些，手机号、userID？

     是否都必填？有无格式要求？-> 输入后前端校验规则：手机号必填，需为字符串，且长度有限制；

3)返回的登录结果 -> 返回参数字段有哪些？

4)非理想情况，例如网络不好 -> 对应前端提示文案，如 “不好! 网络崩溃啦”；

另外，PM 参与接口设计时，也可以站在需求或产品设计的角度，提供关于接口“扩展性”、“性能”、“稳定性” 等相关的建议：

• 扩展性：新开发的接口将来能否用于其他功能？能否将现有的订单查询接口复用于新增页面的订单查询功能？

• 性能：接口响应时间要保持在*s内；

• 稳定性：支持多大量级的秒/分钟并发。

注：

1. 并发数：指同时访问服务器站点的连接数。如果需求方对此有严格要求，最好在上线前做好压力测试，验证接口能支持的最大并发数到底是多少。

2. 接口响应时间：指从请求端发送一个请求开始，到接收到响应结果所经历的时间，响应时间越短，多线程并发数越高，接口性能越好。

公众号 : 雪菜Rose

各位PM小伙伴

● 欢迎扫码关注我哦~

点击写评论