作为一个产品经理，要如何轻松搞定接口需求与文档？下面一起来看这篇有笔者整理分享的关于接口需求与文档相关内容的文章吧！推荐值得一看哦！

一、前言

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

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

二、接口的作用

什么是接口？

看下边的例子：

微信获取用户基础信息接口：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. 基于接口的出参如何设计自己的产品？

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

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

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

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

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

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

五、总结

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

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