产品经理接口文档怎么写 后端产品经理笔记

需求文档是典型的说明文，力求逻辑清楚、言简意赅。对语序、用词要求严格。宁可枯燥也不能模棱两可，这就暗示需求文档有它的语法。

本文继“后端产品经理笔记：数据传输和写入”之后，梳理了需求文档的语法，有兴趣的朋友可以一起交流，欢迎指正。

一、需求文档概述

（1）一些移动端产品不写文档，直接在原型上备注，但遇到逻辑复杂的时候还是要写文档。

建议大家写文档，因为写的过程会发现更多。

（2）文档内容涵盖：背景、目标、需求范围、需求用例（正文）、备注、参考资料。

不管是用谁的模板，这都是要有的。

• 背景：业务的习惯是xxxx，现在的是xxxx这么处理的，问题是xxxx，因此需要xxxx。
• 目标：本需求要实现1、xxxx。2、xxxx。3、xxxx。
• 需求范围：可以用一个脑图或者用例图表示。
• 备注：开发注意xxxx，测试提醒xxxx。
• 参考资料：本需求涉及的数据表/字段为xxxx。涉及的脚本是xxxx，接口xxxx，历史文档是xxxx，流程图xxxx，原型xxxx。

（3）需求用例（正文）：避免散文化思维，要按正常的顺序去描述。

比如：要在已有接口增加获取一个字段，并在页面展示，可以这样：

1. 在xx接口增加获取xx字段，存入后台表xx——接口逻辑调整为xx。旧数据初始化方案是xx。
2. 在xx页面列表，新增xx列，对应取值是xx后台表中的字段的xx。

（4）正文只写要开发做的事情。因为开发就是照着你的地图去打怪完成任务的。

把开发当直男，告诉他两点：在哪里，做什么。避免前面巴拉巴拉一堆，后面又接着一个“即xxxxx”、“也就是说xxxxx”。

（5）避免词语失准，如果用词拿不准的话，建议不要用。

在文档中很常见的比如：“维度”、“颗粒度”、“参数”、“字段”、“项”、“列”、“表”。

可以这样用：

• 以‘订单号 产品编码’维度进行唯一性判断。
• 列表数据细到‘订单’颗粒度。
• 以‘时间’作为请求参数。
• 后台表的字段为number。
• 页面搜索栏的‘姓名’搜索项，
• 页面列表的‘年龄’列。

（6）如果需要开发参考旧功能的，比如做优化，可以这样的结构：

修改前：xxxx

修改后：xxxx

也可以写完需求点，然后在后面跟上（已有，详见参考资料1）

（7）如果熟悉数据库，可以直接写数据表的字段。比写页面的更准确，前提是你要准确。

（8）避免模棱两可

比如：你写‘该字段默认取空’，就不如说是‘空字符串’。因为我们看后台是这样：NOT NULL DEFAULT ”——表示不能为空 ，默认为空字符串。

（9）写接口的时候记得加上数据量级和接口响应要求

比如：预计半年内数据100万/天，要求接口响应3s内，因为开发的实现方式多种，他要做评估。

（10）通用规范统一， 这些是早期文档要建立起来的规范。

比如：

• 删除/禁用/关闭/封存、开启/启用/生效、配置/设置、编辑时间/修改时间/更新时间。
• 是否写入用is_use/is_write？
• 已写入/未写入用1/0，还是用1/2？
• 空字符串时，前端展示什么，是‘/’还是空白？

每个开发习惯不同，所以要固定用哪一种，避免千人千面。比如：有个开发比葫芦画瓢，把goods_sn写成good_sn，就尴尬了。

二、条件反射出逻辑规则

（1）遇到输入框，就要限定输入的范围，且做输入校验。

比如：输入框下方红色字体提示：请填写寄样信息！最省事的办法是，输入的不负荷就不予写入。

比如：年龄栏位写‘张三11.2’则能写进去的只有‘11’。

这种也不用考虑校验的时间是输入时还是最后保存时。

（2）遇到下拉搜索框，考虑下拉的同时是否支持输入搜索，是否支持多选？

（3）导入文档要校验文档内容，最安全的办法是一旦校验到一处重复或者不合规格，则全部不予导入。

（4）已有功能的逻辑规则变更，则要考虑旧数据。

（5）基础数据删除，则要考虑基础数据被调用的地方，删除和编辑怎么处理。 比如：产品分类中维护的类型删除，那么历史生产出的该分类下的数据再编辑和删除时候就可能报错，所以记得基础数据维护时候校验调用情况。

（6）设置规则时，考虑规则去重、规则优先级。严格说，没有优先级的情况下，规则的校验比较累。比如参数A选项有n个，参数B的选项m个，那么可以搭配出至少n*m种规则条件（如果加上多选、全选、全不选就更多），就要确保这些规则之间不重复。

（7）列表的数据一般按照修改时间的倒叙排列，最新的序号为1。也可以用id代替序号，好处是用户自己就可以用规则与产生的数据对应，方便追溯。

（8）异常机制：每时每刻都要有异常思维，告诉开发怎么算异常？异常了怎么标示出来。 比如：表1字段A，匹配表2字段B，将匹配成功的数据写入表3。就要考虑表1无该字段A的情况。

（9）页面长期不登录，则给自动退出。主要考虑到后端系统的保密性。

（10）凡是带操作的一般都要设置页面权限。最简单的方式是所有系统的权限都分三个等级：不能查看、只能查看、可以编辑。

（文档的模式和注意事项远不止上述，后续整理再补充）

本文由 @ 环滁皆山也 原创发布于人人都是产品经理。未经许可，禁止转载

题图来自 Pexels，基于 CC0 协议

,