三、怎么写接口需求在我之前的发布的内容《需求文档遗漏问题的良方：认识它并干掉它》当中，有提到过，仅从功能的角度去看产品，无论是C端产品还是B端产品，其实都是在为用户提供增、删、改、查、显服务，因此接口需求怎么写，我们可以分别从增、删、改、查、显的场景去思考。
1. 查询
文章插图
以顺丰的运费失效查询为例：客户在寄件前，需要预先运费时，可以通过在运费时效查询中输入原寄地、目的地，货物信息（重量、长、宽、高、件数）寄件时间 等信息，可以得出从深圳寄件到武汉的预估运费和预计时效。

文章插图
上图是通过F12（浏览器检查工具），查看到的具体请求参数和返回参数。
从请求参数中我们可以发现，用户使用运费时效查询工具时，在用户界面用户需要输入寄件地址的省市区和收件地址的省市区，但实际在执行查询动作的时候是将寄件省市区和收件省市区解析为区号，然后通过区号去查询并得到结果。由此我们可以倒推出，顺丰-运费时效查询的接口应该如下：

文章插图
由上面模板可以得知，我们提供给开发的接口需求文档，主要需要描述以下内容：

• 应用场景：描述接口的应用场景接口描述：描述接口的逻辑，例如运费单价查询逻辑，运费计算逻辑等性能：接口的性能要求说明，包括调用量、并发量等，可以根据过去发生的业务量来评估；
• 调用方：接口的调用方
• 接口CODE：在旧接口中进行逻辑调整，需要把接口CODE附上；新开发的接口，接口CODE可以不写；
• 入参/出参：接口需求中最重要的组成部分之一，在查询的场景中，可以将入参理解为查询条件；出参理解为期望得到的查询结果；如接口需求支持批量查询，接口的出参需以list的形式返回，并需求说明数据分页规则

2. 新增
文章插图
以顺丰的运单下单业务为例：当用户有寄件需求时，顺丰用户可以在顺丰官网、顺丰APP、顺丰公众号、顺丰小程序等多个渠道中任一渠道下单，但从实现层面来看，不同渠道的下单业务其实共用的一个下单接口。
例如，用户去顺丰官网立即下单页面， 在寄件表单中分别填写寄方信息、收方信息、快件信息、快递产品等信息，用户填写完信息点击”立即下单”时调用下单接口完成下单。
在用户眼里，填写完寄件信息表单并点击立即下单，是完成了下单。从系统的角度去理解，实际是系统基于用户的行为新增了一条运单数据。

文章插图
基于上面的用户界面截图可以知道，系统新增一笔运单，系统需要用户填写的寄方信息、收方信息、快件信息、快递产品等信息，由此可以倒推出顺丰新增运单的接口为：

文章插图
3. 修改（更新）
文章插图
修改（更新）场景的接口，与上面的新增接口类似，以用户修改账号密码的案例为例：用户在修改密码时，需要在表单中填写账号信息和密码信息，然后点击【确定】按钮，提交表单信息并更新账号信息。通过以上的描述，可以倒推出修改账号密码的接口应为：

文章插图

• 苹果|苹果最巅峰产品就是8，之后的产品，多少都有出现问题
• 元宇宙持续发酵，或迎“终极形态”？马斯克为何力挺脑机接口技术
• |OPPOK11x，精准的满足用户对于强续航，大存储、拍摄的需求
• 业务|传统企业里，产品经理失去了话语权
• 这回库克要头疼了！工信部正式答复，手机将统一充电接口
• 上海尊宝音响多款产品获《影音极品》器材大赏奖项
• 噪音|聊聊社交产品中的信号与暗示
• 雷曼巨幕LEDPLAY获IT影响中国2021年度创新产品奖
• 华为逐渐逼近工薪党的需求，中端手机发挥有声有色，期待恢复
• iPad|一样是苹果的电子产品，为什么iPhone比iPad贵几千元呢