如何轻松搞定接口需求与文档？

一、前言

不懂技术的产品同学，天然的对技术相关的需求犯怵。比如说接口需求，接口是开发过程中避免不了的东西，作为产品经理，一定要知道。我一直负责集团的公共服务，所有服务都是通过「接口」与各个产品线对接。我也没有技术背景，当然在过程中遇到了一些问题，所以我总结了关于「接口需求」相关的内容。

说下：接口需求怎么提接口文档怎么看。

二、接口的作用

什么是接口？

看下边的例子：

微信获取用户基础信息接口：https://api.weixin.qq.com/cgi-bin/user/info/batchget?access_token=ACCESS_TOKEN

飞书查看全部工单接口：https://open.feishu.cn/open-apis/helpdesk/v1/tickets

这些 url链接就是接口地址。通过调用接口地址，获取到想要的东西。对于接口的作用，我划分为 3 种：

1. 前端与后端的数据处理

比如列表上有个「新增」的功能。前端开发出一个表单功能，当填完数据后，点击确定，前端会调用「新增数据接口」，将页面中录入的数据通过接口，传给后端，后端对传入的数据进行处理。接口处理完成后，会返回出具体的参数，前端根据返回的参数，给出对应的反馈信息。

比如当接口的校验没有通过时，则会通过接口返回出错误信息，前端会将错误信息在页面上进行提示。

同样的，对于删除数据、修改数据、查询数据等，都是通过接口的方式对数据进行处理。

2. 跨系统的同步数据

两个系统之间进行数据同步。

比如我有个需求，需要使用到「系统用户信息」。对于「用户信息」，我司只有「账号系统」有，我需要和账号系统的产品经理沟通，对方提供给我一个接口文档，我们按照接口文档的要求进行数据同步。

同样的，当有需求要使用到你系统里的数据，也可以通过「接口」将数据同步给需求方。对于数据同步接口，数据同步的方式、数据同步的时机等等都是接口需求需要考虑到的内容。

这几点我们在下边详细说～

3. 提供公共服务

通过接口对外提供服务能力，可以满足不同的系统或应用程序之间进行功能调用。比如说身份证归属地查询服务，通过输入身份证号查询出归属地。当需要使用这个功能的时候，都可以调用「身份证归属地查询接口」，来实现这个功能。

另外支付服务、登录服务、获取收货地址等等，能够对外提供的公共服务，我们都可以做成公共接口对外使用。

三、接口需求怎么提

很多同学认为接口是研发开发的，和产品没有关系，我之前也是这样想，后来发现这个并不对。接口是基于需求来开发的，里边涉及业务相关的内容，研发并不清楚具体的业务场景，如果产品经理不进行介入，就会导致接口的场景覆盖程度、扩展性受限。

不会提接口需求没关系，我们接下来细说：我们根据上边说的3 种接口用途，看下需求如何提。

1. 前后端数据处理接口

这类接口一般和功能相关，也不涉及到跨系统，可以直接通过功能需求描述，不用特意地对接口进行说明。在研发开始前，前端与后端根据需求进行功能拆分，后端开发接口，前端开发页面，然后前后端进行接口联调。

2. 数据同步接口

无非 2 种：

1. 你向别人提供数据：需要你定义接口需求
2. 别人向你提供数据：需要你会看别人的接口文档

我们先看「你向别人提供数据」

举个例子：一条产品线有个需求，想使用你系统的「人员信息」数据，在他们系统的页面中展示出「人员信息列表」

我们先从以下角度思考：

1）数据能否提供？

1. 是否该由自己系统提供，是否其他系统提供更好？
2. 提供的数据能够满足对方需求，是否缺字段？
3. 数据是否敏感数据？是否知识产权数据？
4. 其它产品线是否也有这个需求，是否也需要这个接口？
5. 对于这个接口是做成公共接口，每个业务方都能进行调用，还是只对这一个业务线提供。

一般情况下，数据同步接口都可以做成公共接口，让每个业务方都能使用此接口。

2）支持哪种同步方式？

①业务方直接使用接口实时搜索，直接列表展示

业务方通过接口实时查询数据，并展示出结果，不将数据放到自己的数据库里。好处是每次查询都是最新数据。但是这种方式很不建议，当有业务方需要用到你的数据的时候，也需要提醒对方不要使用这种方式。用他方的数据同步接口去进行实时查询，如果数据同步接口性能扛不住，接口挂了，那业务也会挂。

当需要对数据进行二次加工处理，这种方式就不支持了，只能让数据同步接口加需求。但是一般的数据同步接口都是公共接口，不仅有一个业务方使用，当这个接口不满足你的需求的时候，公共接口不会根据你的需求做个性化调整。

②业务方通过接口将数据存储到自己的数据库中，对数据进行二次处理

通过数据同步接口，将数据同步到自己的数据库中，单独存一份，与数据提供方做一层隔离。自己业务使用时，从自己的数据库中取数据。这样就算同步接口挂了，也不会影响自己的业务。同时，可以对获取的数据进行二次处理，灵活性更强。当业务方单独存储数据后，为了让两方数据保持一致，这就涉及到「数据更新」。

3）数据更新机制

分为2种：推、拉

推：有数据更新后，将更新的数据推给下游业务方。

①「推」有 2 种方式：

1. 当数据有更新时，上游给下游业务方发一条「数据更新通知」，让业务方判断是否更新、更新哪些数据。这个时候上游就需要多开发一个「数据更新通知接口」，用于发出通知。同时下游方也需要开发一个接口，用于接收通知。
2. 强制业务方更新，硬性更新数据。对于主数据、标准字典值都需要使用这种方式。

拉：下游业务方去主动拉取新的数据。

②「拉取」有 2 种方式：

1. 定时拉取：由程序定时拉取，如每天同步、每 5min 同步、每 1h 同步一次等等，根据数据更新频次、对数据一致性的严谨度进行判断。
2. 手动拉取：手动触发更新。是指当需要使用到最新数据的时候，手动触发数据更新，比如页面上添加个「数据同步」的按钮，点击后，调用数据同步接口，拉取最新的数据。当然，也可以「定时拉取+手动拉取」，例如每晚程序自动更新，白天需要更新时，可手动触发更新。每次更新数据的时候，又涉及到「数据更新的范围」。

4）数据更新范围

分为：全量更新、增量更新。它们的选择取决于需要同步的数据量以及更新的频率。

• 全量更新：更新全部数据，无论数据是否有变化，都会对整个数据进行更新。将已有的数据删除，然后重新获取新的数据。这种方式比较适合数据量较小或对数据一致性要求较高的情况。
• 增量更新：只更新发生变化的数据。当把数据全量同步后，之后只更新发生变化的数据。比如说上游发出了数据更新通知，告诉哪条数据发生了更新，此时接入方可以只更新发生更新的数据。增量更新适用于整体数据量较大、更新频率低的情况。增量更新比较高效，更新数据用时也比较快。到这，我们把数据同步的同步方式、数据更新机制、数据更新范围确定好了。接着继续明确接入方可以使用哪些字段去获取数据。

5）通过哪些字段获取数据能获取到哪些数据？

用哪个字段获取数据，意思是向接口传入哪些字段。能够获取到哪些数据，意思是接口会返回出哪些字段。会有2 个名词：

1. 入参：就是向接口传入的参数数据，也叫请求参数等。
2. 出参：接口返回数据的参数数据，也叫返参、返回参数、响应参数等。

你可以理解为，接口就是个列表，这个列表的查询条件有哪些、查询结果有哪些。查询条件，就是接口的「入参」查询出的结果，就是接口的「出参」

①对于「入参」，在提需求时，产品经理需要考虑到：

1. 入参有哪些字段？就是这个列表的查询条件是什么？比如我们需要对外同步「人员信息」，可以通过「人员 ID」进行获取数据，也可以通过「性别」，只获取性别为「男」的数据。人员ID、性别就是这个接口的入参。
2. 入参字段的格式是什么？格式是指字段是字符串、日期格式还是字典值等。比如说「人员性别」，可以定义成 0，1。0 代表女性、1 代表男性。也可以是文字「女性、男性」。对于字段格式，产品经理主要是提供建议，具体的还是以研发为准。
3. 入参字段能够支持批量查询？可以理解为查询条件的字段是不是支持多选。比如说「人员性别」，是可以通过下拉框多选，还是每次只能选择一个。
4. 入参字段是不是必填？比如说查询时，必须输入「人员 ID」，否则就不支持查询。

②对于「出参」，产品经理需要考虑到：

1. 出参字段有哪些？也就是查询结果需要有什么？比如出参有：人员 ID、人员姓名、人员性别、创建时间、创建人、更新时间、更新人、是否启用、是否删除。
2. 出参字段的格式是什么？这个和「入参」相同，产品经理给出参考建议。然后，在提需求的时候，我们可以通过表格的形式说明「入参、出参」。

③入参示例如：

④出参示例如：

到这里，我们的数据同步接口需求就可以了，更详细的可以看我提供的真实接口需求示例，领取方式在文末。

3. 服务用接口

这个接口也比较常见，在很多服务对接时，都是直接使用接口对接。产品经理需要确定的接口中与业务相关的内容。

主要包括入参、出参、接口处理逻辑。

1. 对于入参：需要把接口中的入参字段有哪些说清楚。不仅要把接口处理必须用到的字段说清楚，对于之后接口用到的字段，也可以写出来。业务方在第一次接入的时候，把能传入的字段都传过来，下次接口新增其他服务的时候，可以直接用，不需要业务方在调整接口。
2. 对于出参：需要把接口返参中的字段进行说明。原因是返参的字段，才是要最终用到业务上的，需要产品经理确定有哪些字段，并把字段进行说明。
3. 接口处理逻辑：就是接口通过「入参」计算出「返参」的具体逻辑，包括校验逻辑等一系列处理逻辑。

说个简单的例子：通过「身份证号查询归属地服务」

既然是通过「身份证号」查询，那「入参」里肯定就是「身份证号」

「返参」里有归属地，那「归属地」就涉及到省、市、区。

需求可以这样提：

1）入参：身份证号、必填、字符串、长度18位

2）出参：省份名称/直辖市、市/区、县

3）处理逻辑：

1. 校验身份证号格式：长度必须是否18位（等其他逻辑在此不细说）
2. 当校验不通过时，接口报错，错误原因为「身份证号格式错误」
3. 当校验通过后，截取身份证号「前六位」，在「身份证号与行政区域表」中查询对应关系。
4. 当查询到结果时，接口返回：省份名称/直辖市code、省份名称/直辖市名称、市/区code、市/区名称、县code、县名称。
5. 当未查询到结果时，接口返回为空

涉及到公共服务接口，就涉及到一个「接口性能需求」，这个不能落下，加上性能说明:

4）接口性能要求

示例如：

1. 平均响应时间：最大50ms
2. 接口并发数：最少200

性能需求的可以看我之前的文章《5000字详解性能需求》。

在调用接口时，如果是收费接口，或者是需要调用次数做汇报，这个时候就得有「日志记录」需求。

5）日志记录

示例如：调用日志记录需求：数据库中存储入参、出参原始json。json 字段本期暂不进行结构化。记录字段至少包括：渠道 ID、入参 json、出参 json、创建时间、创建人、更新时间、更新人。其余应用字段研发自行判断。

json是一个文件格式，json中包含了字段名称与字段对应的值，大家可以自己学习下。

另外，如果存在一些报错情况，产品经理想记录，用于排查问题，可以加个「记录错误数据」的需求。

6）记录错误数据

示例如：

记录查询为空数据：当接口查询接口为空时，数据库存入查询结果为空的数据，用于补充「身份证号行政区域表」数据。记录字段包括：身份证号前6位、查询时间。

以上内容说完后，这就有一个新的问题：公共接口是谁都能接入吗？这又涉及到：接口鉴权——只能通过接口权限验证才能调用接口。接口鉴权需要产品提需求吗？

我的观点是不需要，让产品提还真提不出来。

我们现在采用的方式是：

当有业务方需要接入我们的公共接口时，我在后台新增一个渠道，通过渠道ID生成验签码，把渠道ID、验签码提供给业务方。业务方把渠道ID、验签码通过接口传入，具体怎么接口验签，研发自己对。到这，接口需求包含以上内容，我认为就OK了。当然，还有其他的几个内容。

7）请求方式：

有 GET、POST 等，我认为这个让研发去定，只要能满足需求，这就够了。我唯一一次遇到过的问题是前端来找我，说 GET 请求字符超长，问我怎么处理。因为 GET 请求是在 url 后边拼接请求参数，最多支持 2048 个字符。

我们分析后发现在实际场景里，会有入参很多的情况，就会导致请求 url 超长。我也不知道怎么处理，问后端，后端说改成 POST。因为POST在是使用json传入参数，不涉及到字符超长的情况。

8）接口分页：

就是分页返回数据，可以理解为列表中的分页，每页返回10条数据。当数据量过大的时候，响应时间不会过长。一般情况下，返回数据很多时，都可以添加分页。

9）接口请求频次

就是对接口加个限制，防止服务过载，避免服务崩溃。具体的限制策略可以根据业务需求来制定，如 1min 内最多调用 10 次，1天1万次等。当次数超过限制后，再调用时则报错。

以上，我们就说完了「接口需求怎么提」，接下来说「接口文档」。

四、接口文档怎么写怎么看？

接口文档是对外提供的详细的接口接入说明，主要用于描述可提供的接口信息。

所有开发人员都将根据这份文档进行后续的开发工作。

接口文档中内容一般有：

• 修订历史：接口文档每次更新的内容描述
• 接口名称：清晰地表明该接口的功能。
• 接口描述：简要说明该接口的作用和业务逻辑，具体能干什么，能实现什么效果。
• 请求地址：详细给出接口的URL地址，包括测试环境、线上环境等不同环境中的接口地址。
• 请求方法：常见的有GET、POST、PUT、DELETE、PATCH、UPDATE等。
• 请求头：通常用于传递一些公共参数，如token等。
• 请求参数：就是入参，列出各类请求参数，包括参数名、是否必选、参数类型和具体含义。
• 请求示例：提供传入接口的参数样例。
• 响应参数：就是出参，区分成功和失败等不同情况的响应内容，包括参数名、类型和具体含义。
• 错误代码：列出可能出现的错误代码及其对应的含义。
• 返回示例：提供成功响应的样例，帮助使用者更好地理解如何使用该接口。
• 备注及责任人：记录特殊情况和注意事项，指明接口的负责人。

我们可以看到一份接口文档中包含了整个接口中的全部信息。产品经理不需要自己写接口文档，而是应该由研发编写。产品经理在此基础上填写与业务相关的说明

包括：

• 接口名称、接口描述：产品经理可以补充和业务相关的内容描述。
• 请求参数、响应参数：产品经理可以确定最终字段有哪些，并对字段的用途进行描述。如当字段不传入时对业务会有哪些影响等。
• 返回示例：产品经理可以提供真实的、有参考性的标准示例，让研发把参数返回放到文档中。

同样的，当我们看接口文档时，产品经理也需要关注的是和业务相关的内容即可。

看接口文档的目的是为了我们自己的需求，要确定接口能够满足我们的需求。在接口能够支持的情况下，更好的去设计需求。

所以我们要关注以下内容：

接口描述：了解接口的作用与能力。

入参：

1. 查看需要给出的字段有哪些？
2. 字段能不能给？
3. 能不能按照接口文档中要求的格式给？

出参：

1. 查看出参有哪些字段，每个字段的具体含义是什么？
2. 通过什么样的处理逻辑得出的这个字段？
3. 字段是否有多个值？
4. 字段与字段之间关系是什么？比如上下级关系，有多个值
5. 基于接口的出参如何设计自己的产品？

示例如：有个新需求：后台中的发起审核时，要在钉钉群里发送一条群通知。

这个时候就涉及到钉钉能否支持。

那就去「钉钉开放平台」看下，钉钉提供了一个「机器人发送群聊消息」的公共接口。

然后去看这个接口描述，首先可以知道钉钉是可以支持的。

接着继续看接口中的入参、返参，里边说明了可以支持的消息模版，就可以结合我的需求选择一个消息模板，并确定整体需求设计方案。

至于接口怎么接，让研发研究去就行了。

五、总结

接口需求在对于没有技术背景的同学会有一些迷茫，但是理清楚其实也没什么。你可以去钉钉开放平台、飞书开放平台、微信开发平台、抖音开放平台等很多地方去看看这些大厂的接口文档，看多了也会知道接口是怎么回事。

我们在做产品的时候，不要只关注原型页面这些表面的东西，同时也需要考虑接口的设计和使用，尤其是做公共服务、接入三方服务的时候，你无法避免的要关注接口。就算没有接口需求，我们了解接口后，也能更好的与开发人员进行有效的沟通和协作。

作者

王大鹿，公众号：产品大鹿。关注医疗领域，擅长原型设计、需求分析和方案设计，分享能落地的工作技能~

本文

版权声明

本文来自互联网用户投稿，文章观点仅代表作者本人，不代表本站立场。本站仅提供信息存储空间服务，不拥有所有权，不承担相关法律责任。如若转载，请注明出处。如若内容有涉嫌抄袭侵权/违法违规/事实不符，请点击 举报 进行投诉反馈！