教你写接口需求文档

作者:果果  转载已取得作者授权

一、什么是接口

百科上对接口的定义:API(Application Programming Interface,应用程序编程接口)是一些预先定义的函数,目的是提供应用程序与开发人员基于某软件或硬件得以访问一组例程的能力,而又无需访问源码,或理解内部工作机制的细节。

要理解接口是什么,首先理解一下为什么要用接口?

两个独立的系统,它们的数据或程序是独立的,这就使得它们无法直接访问对方的数据库或程序(两个独立的数据相当于两个独立的家庭,每个家庭肯定是不允许外人随便进入的,否则会发生偷窃等后果严重的事件)。但是某些业务场景下,独立的系统之间又必须相互共享数据或共用一套程序逻辑,如统一业务流程上的不同业务操作系统,下游系统的业务依赖于上游系统的数据。

既然如此为什么不把它们设计成一个系统,这样不就没有上面的问题了吗?

这是因为有的业务流程很长很复杂,如果设计成一个系统,整个系统变得很庞杂,不论是功能设计、开发维护都很难。因此一般都会把虽然有上下游业务关系但又有清晰边界的业务划分成独立的系统实现,如采购系统和仓储系统。此外,很多时候我们需要获取的数据是我们外部其他公司拥有的数据,更不可能设计成同一个系统了。

基于以上两点:接口就是两个独立系统之间同步数据或访问对方程序的途径。

二、如何设计接口

1. 搞清楚是主动访问还是被动请求:

a. 若是主动访问,有两种情况:

一是我方是数据的使用方,需要主动从对方获取数据;二是我方是数据的提供方,需要主动将数据同步给对方。

主动访问时无需做接口,而是访问对方的接口,要搞清楚的问题是:我们需要在什么节点访问对方的接口?是用户触发某个操作的时候实时去访问?还是没有实时性要求,只是周期性地访问?

若我方是数据的使用方且需要的数据是用户使用某个功能必须的数据,因此必须在用户操作时实时去访问对方的接口获取数据并展示给用户,典型的有我们注册某网站时获取验证码的功能。

若我方是数据的使用方且需要的数据是一些跟用户实时操作无关的基础数据,如客服系统需要从其他业务系统获取用户的基础数据,以在系统中的某些功能下展示用户的信息(如客服在处理客诉等问题时,需要知道客户的一些详细信息,这些信息只有业务系统有)。这种情况下,一般会新增一个脚本定时(如两小时一次)访问对方的接口将数据获取过来存储到自己的数据库,在用到的时候直接从自己数据库获取并展示。

若我方是数据的提供方且提供的数据是下游系统需要的实时要求高的数据则更多地用实时同步;若是基础数据,则选择周期性同步的方式。

b. 若是被动请求,有两种情况:

一是我方是数据提供方,需要对方来获取数据;二是我方是数据使用方,需要对方主动将数据同步过来。

被动请求需要提供接口供对方访问,此时要搞清楚:让对方来访问的时候,需要提供什么样的参数?根据他提供的参数我们需要返回什么数据?这些数据从哪里取值?

若有一些数据的来源是本系统,其他系统需要使用这些数据,则可提供接口让其他系统通过访问接口获取这些数据。

若我方是数据使用方且让对方将数据主动同步过来,此种场景典型如——我们是业务的下游,上游系统产生数据后,需要将数据同步到下游系统让流程继续进行,并且流程的及时性要求高,不能有延迟。这种情况下,只有上游系统知道什么节点产生了数据,因此只有等他产生数据后主动推送给下游系统,因为下游系统因无法知道数据生成的时间,也就无法及时去获取数据,这时最好的方式是让对方主动将数据同步过来。

2. 搞清楚数据交互的实时性要求

a. 对于我方是数据使用方的情况,要根据业务的需要决定获取数据的实时性。

如上文所说,如果是用户使用功能时需要的数据就是即时性访问。如果是定期获取基础数据,根据我们对数据准确性的要求和对方数据变更的频率决定获取的周期。如我们对数据的准确性要求不是100%的要求,且对方的数据变更频率也不是很高,则周期可设计得长一些,如每天一次,每几个小时一次等。

b. 对于我方是数据提供方的情况,则以对方的业务需要为准,但是对于获取数据的访问量大等特殊情况,应在需求中或评审中做好说明和交代,以帮助开发设计更满足需要的接口。

3. 选择合适的接口方式

结合接口的不同类型和实时性要求两方面,可以选择合适的接口实现方式:

a. mq消息队列

是一个中间件,数据提供方将数据放到中间件,数据获取方从中间件中获取数据。针对向多个系统同步基础数据的需要,消息队列是最适合的方式。

若选择这种同步方式,要注意的一点是:增量同步还是全量同步,若是增量同步,对方是增量获取还是全量获取?若是全量同步,在什么情况下,对方应该更新数据,什么情况下应该更新数据?

b. otter同步

数据同步方直接访问数据获取方的数据表将数据写入对应的表中,这种方式实时性最高,若对数据的准确性要求很高,此方式是很好的数据同步方式。

c. http

一般在功能设计中常用的接口是此种方式,双方通过http地址保持数据同步和通信。

在设计具体的数据同步接口时,具体的方式产品经理不用关注,由开发根据需求设计合理的方式,然后产品可帮助开发一起确定所选方式是否满足业务需要。除非业务上有特殊要求,则在需求中可指定具体的方式。

三、如何编写接口文档

不同的接口使用场景,需要关注的点和交代清楚的规则不一样,以主动/被动+数据使用方/数据获取方的维度,有以下四种情况:

1. 如果是向对方系统主动推送数据,则可按以下方式整理接口需求

2. 如果是对方主动来获取数据,则可按以下方式整理接口需求

3. 如果是被动接收对方推送的数据,则可按以下方式整理接口需求

4. 如果主动从对方获取数据,则可按以下方式整理接口需求

欢迎小伙伴加微信:chanpin628  沟通交流。

此外我们的官方网站也上线了,每日分享高质量的文章、原型素材和行业报告,小伙伴可自行前往索取,支持搜索,需要的小伙伴可前往 www.dadaghp.com 查看(直接复制网址打开)。

更多干货可关注微信公众号:产品刘

想学习更多关于产品、职场、心理、认知等干货,可长按右边二维码,关注我们。

往期精彩文章

不知道自己适合做什么,迷茫!怎么办?

用户激励体系搭建指南

公司变相裁员的那些肮脏手段

线下实战

产品经理七宗罪

点击“阅读原文”

即可进行报名

本文来自互联网用户投稿,该文观点仅代表作者本人,不代表本站立场。本站仅提供信息存储空间服务,不拥有所有权,不承担相关法律责任。如若转载,请注明出处:http://www.rhkb.cn/news/9632.html

如若内容造成侵权/违法违规/事实不符,请联系长河编程网进行投诉反馈email:809451989@qq.com,一经查实,立即删除!

相关文章

什么是反向代理,开放的反向代理软件使用方法

什么是反向代理呢?其实,反向代理也就是通常所说的WEB服务器加速,它是一种通过在繁忙的WEB服务器和Internet之间增加一个高速的WEB缓冲服务器(即:WEB反向代理服务器)来降低实际的WEB服务器的负载。 Web服务器…

反向正向代理

https://www.zhihu.com/question/36412304

宝塔反代教程

近期有网友问宝塔如何设置反向代理,小编这里介绍一种简单的操作方法,就是使用宝塔官方软件面板自带的反向代理功能来实现。首先您要先安装宝塔面板,当Nginx或LNMP环境配置完成后,便可开始设置反向代理了,下面来看下操作…

[转发]图示说明正向代理和反向代理

关于代理 说到代理,首先我们要明确一个概念,所谓代理就是一个代表、一个渠道; 此时就设计到两个角色,一个是被代理角色,一个是目标角色,被代理角色通过这个代理访问目标角色完成一些任务的过程称为代理操…

Linux宝塔面板反向代理设置教程

此方法最简单快捷,没有复杂步骤,不容易出错,即最简单,零代码、零部署的方法。 实现准备 一台服务器安装宝塔面板OpenAI官方的API_KEYChatGPT网站系统源码 ChatGPT网站系统源码,大家可以看看另一篇文章介绍&#xff…

网关V.S反向代理

简介 网关主要服务于微服务/API,偏向研发人员反向代理主要面向传统静态web应用,偏向运维而未来趋势是DevOps网关和反向代理再次融合 发展趋势 WEB1.0/2.0时代,使用前置反向代理,由运维负责 nginx,进行反向代理和负载…

反向代理

先看这张图 反向代理(Reverse Proxy)方式是指以代理服务器来接受internet上的连接请求,然后将请求转发给内部网络上的服务器,并将从服务器上得到的结果返回给internet上请求连接的客户端,此时代理服务器对外就表现为一…

图解正向代理和反向代理

套用古龙武侠小说套路来说,代理服务技术是一门很古老的技术,是在互联网早期出现就使用的技术。一般实现代理技术的方式就是在服务器上安装代理服务软件,让其成为一个代理服务器,从而实现代理技术。常用的代理技术分为正向代理、反…

代理,正向代理和反向代理

1. 代理 代理也被叫做网络代理,是一种比较特殊的网络服务,允许一个终端(通常指客户端)通过这个服务与另一个终端(通常指服务器端)进行非直接的连接。 例如:一些网关、路由器等网络设备都具备网…

反向代理,正向代理,网关

反向代理,正向代理,网关 正向代理与反向代理,正向与反向是如何区分的?反向代理在系统架构中的应用场景: 正向代理与反向代理,正向与反向是如何区分的? 正向与反向的目标是客户端,是…

2、正向代理和反向代理(正向代理(客户端),反向代理(服务器))

正向代理和反向代理(正向代理(客户端),反向代理(服务器)) 1、正向代理:(代理客户端) 说个例子(访问外网):我们的客户端先…

正向代理 / 反向代理

1. 正向代理 正向代理是一个位于客户端和原始服务器(origin server)之间的服务器,为了从原始服务器取得内容,客户端向代理发送一个请求并指定目标(原始服务器),然后代理向原始服务器转交请求并将获得的内容返回给客户端。客户端必须设置正向代理服务器,当然前提是要知道正…

chatgpt赋能python:Python中的JWT解码(Decode)

Python中的JWT解码(Decode) 什么是JWT(JSON Web Token)? JSON Web Token(JWT)是目前最流行的 Web 身份验证方案之一。JWT 是基于 JSON 的开放标准,它可以让客户端和服务器之间传递…

对接支付宝php版easysdk接口分享

在网上没有找到支付宝easysdk接口的对接详细说明,自己一步一步的摸索,其中使用chatgpt的帮助作用不少。 根据官方给的文档 需要执行composer require alipaysdk/easysdk:^2.0安装sdk。如果你的项目已经安装过其它扩展,可以先把vendor文件夹备…

记录第一次利用chatgpt 实现RSA加密解密编程

1,下载Cursor软件 2,左侧文件栏目新建一个first.java 3,在编辑区输入“//使用RSA公私钥实现JWT令牌的签名和验签”,并且连续输入两个回车(相当于调用CtrlK) AI会自动生成代码,点击“Accept al…

ChatGPT | Word文档如何更好地提取表格内容给ChatGPT

本文来自http://blog.csdn.net/hellogv/ ,引用必须注明出处! Word文档如何更好地提取表格内容给ChatGPT做知识库,这属于文本预处理工作。 本文只讲思路、测试结果,技术实现用Python和Java都能完成,下一篇文章再贴源码…

分享一个淘宝/天猫/京东/阿里 图片抓取工具

链接:https://pan.baidu.com/s/1lbTL8UNQr4o45Z30J_YGLA提取码:xr3z 复制这段内容后打开百度网盘手机App,操作更方便哦 转载于:https://www.cnblogs.com/ForStudyAlways/p/11212591.html

利用python爬取淘宝的商品图片

代码 from selenium import webdriver from selenium.webdriver.common import keys import time import requests import random# 创建浏览器 def functions():browser webdriver.Chrome(rG:\taobao\chromedriver.exe)# 让浏览器打开淘宝browser.get("https://www.taob…

JavaScript实现淘宝商品展示(鼠标放在小图片上,上面会出现相应的大图片)

最终效果&#xff1a; 代码部分&#xff1a; <!DOCTYPE html> <html><head><meta charset"utf-8" /><meta name"viewport" content"widthdevice-width, initial-scale1"><title>图片放大效果</title&…

html转化成图片,相当于生成海报,长按保存到手机

html <div class"tab-con" id"erweima"><div class"erweima-box"><div class"erweima"><div class"top"><span>扫码支付</span><span>排队免单</span></div><di…