需求文檔是典型的說明文，力求邏輯清楚、言簡(jiǎn)意賅。對(duì)語序、用詞要求嚴(yán)格。寧可枯燥也不能模棱兩可，這就暗示需求文檔有它的語法。

本文繼“后端產(chǎn)品經(jīng)理筆記：數(shù)據(jù)傳輸和寫入”之后，梳理了需求文檔的語法，有興趣的朋友可以一起交流，歡迎指正。

一、需求文檔概述

（1）一些移動(dòng)端產(chǎn)品不寫文檔，直接在原型上備注，但遇到邏輯復(fù)雜的時(shí)候還是要寫文檔。

建議大家寫文檔，因?yàn)閷懙倪^程會(huì)發(fā)現(xiàn)更多。

（2）文檔內(nèi)容涵蓋：背景、目標(biāo)、需求范圍、需求用例（正文）、備注、參考資料。

不管是用誰的模板，這都是要有的。

• 背景：業(yè)務(wù)的習(xí)慣是xxxx，現(xiàn)在的是xxxx這么處理的，問題是xxxx，因此需要xxxx。
• 目標(biāo)：本需求要實(shí)現(xiàn)1、xxxx。2、xxxx。3、xxxx。
• 需求范圍：可以用一個(gè)腦圖或者用例圖表示。
• 備注：開發(fā)注意xxxx，測(cè)試提醒xxxx。
• 參考資料：本需求涉及的數(shù)據(jù)表/字段為xxxx。涉及的腳本是xxxx，接口xxxx，歷史文檔是xxxx，流程圖xxxx，原型xxxx。

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

比如：要在已有接口增加獲取一個(gè)字段，并在頁面展示，可以這樣：

1. 在xx接口增加獲取xx字段，存入后臺(tái)表xx——接口邏輯調(diào)整為xx。舊數(shù)據(jù)初始化方案是xx。
2. 在xx頁面列表，新增xx列，對(duì)應(yīng)取值是xx后臺(tái)表中的字段的xx。

（4）正文只寫要開發(fā)做的事情。因?yàn)殚_發(fā)就是照著你的地圖去打怪完成任務(wù)的。

把開發(fā)當(dāng)直男，告訴他兩點(diǎn)：在哪里，做什么。避免前面巴拉巴拉一堆，后面又接著一個(gè)“即xxxxx”、“也就是說xxxxx”。

（5）避免詞語失準(zhǔn)，如果用詞拿不準(zhǔn)的話，建議不要用。

在文檔中很常見的比如：“維度”、“顆粒度”、“參數(shù)”、“字段”、“項(xiàng)”、“列”、“表”。

可以這樣用：

• 以‘訂單號(hào)+產(chǎn)品編碼’維度進(jìn)行唯一性判斷。
• 列表數(shù)據(jù)細(xì)到‘訂單’顆粒度。
• 以‘時(shí)間’作為請(qǐng)求參數(shù)。
• 后臺(tái)表的字段為number。
• 頁面搜索欄的‘姓名’搜索項(xiàng)，
• 頁面列表的‘年齡’列。

（6）如果需要開發(fā)參考舊功能的，比如做優(yōu)化，可以這樣的結(jié)構(gòu)：

修改前：xxxx

修改后：xxxx

也可以寫完需求點(diǎn)，然后在后面跟上（已有，詳見參考資料1）

（7）如果熟悉數(shù)據(jù)庫，可以直接寫數(shù)據(jù)表的字段。比寫頁面的更準(zhǔn)確，前提是你要準(zhǔn)確。

（8）避免模棱兩可

比如：你寫‘該字段默認(rèn)取空’，就不如說是‘空字符串’。因?yàn)槲覀兛春笈_(tái)是這樣：NOT NULL DEFAULT ”——表示不能為空 ，默認(rèn)為空字符串。

（9）寫接口的時(shí)候記得加上數(shù)據(jù)量級(jí)和接口響應(yīng)要求

比如：預(yù)計(jì)半年內(nèi)數(shù)據(jù)100萬/天，要求接口響應(yīng)3s內(nèi)，因?yàn)殚_發(fā)的實(shí)現(xiàn)方式多種，他要做評(píng)估。

（10）通用規(guī)范統(tǒng)一，?這些是早期文檔要建立起來的規(guī)范。

比如：

• 刪除/禁用/關(guān)閉/封存、開啟/啟用/生效、配置/設(shè)置、編輯時(shí)間/修改時(shí)間/更新時(shí)間。
• 是否寫入用is_use/is_write？
• 已寫入/未寫入用1/0，還是用1/2？
• 空字符串時(shí)，前端展示什么，是‘/’還是空白？

每個(gè)開發(fā)習(xí)慣不同，所以要固定用哪一種，避免千人千面。比如：有個(gè)開發(fā)比葫蘆畫瓢，把goods_sn寫成good_sn，就尷尬了。

二、條件反射出邏輯規(guī)則

（1）遇到輸入框，就要限定輸入的范圍，且做輸入校驗(yàn)。

比如：輸入框下方紅色字體提示：請(qǐng)?zhí)顚懠臉有畔?！最省事的辦法是，輸入的不負(fù)荷就不予寫入。

比如：年齡欄位寫‘張三11.2’則能寫進(jìn)去的只有‘11’。

這種也不用考慮校驗(yàn)的時(shí)間是輸入時(shí)還是最后保存時(shí)。

（2）遇到下拉搜索框，考慮下拉的同時(shí)是否支持輸入搜索，是否支持多選？

（3）導(dǎo)入文檔要校驗(yàn)文檔內(nèi)容，最安全的辦法是一旦校驗(yàn)到一處重復(fù)或者不合規(guī)格，則全部不予導(dǎo)入。

（4）已有功能的邏輯規(guī)則變更，則要考慮舊數(shù)據(jù)。

（5）基礎(chǔ)數(shù)據(jù)刪除，則要考慮基礎(chǔ)數(shù)據(jù)被調(diào)用的地方，刪除和編輯怎么處理。?比如：產(chǎn)品分類中維護(hù)的類型刪除，那么歷史生產(chǎn)出的該分類下的數(shù)據(jù)再編輯和刪除時(shí)候就可能報(bào)錯(cuò)，所以記得基礎(chǔ)數(shù)據(jù)維護(hù)時(shí)候校驗(yàn)調(diào)用情況。

（6）設(shè)置規(guī)則時(shí)，考慮規(guī)則去重、規(guī)則優(yōu)先級(jí)。嚴(yán)格說，沒有優(yōu)先級(jí)的情況下，規(guī)則的校驗(yàn)比較累。比如參數(shù)A選項(xiàng)有n個(gè)，參數(shù)B的選項(xiàng)m個(gè)，那么可以搭配出至少n*m種規(guī)則條件（如果加上多選、全選、全不選就更多），就要確保這些規(guī)則之間不重復(fù)。

（7）列表的數(shù)據(jù)一般按照修改時(shí)間的倒敘排列，最新的序號(hào)為1。也可以用id代替序號(hào)，好處是用戶自己就可以用規(guī)則與產(chǎn)生的數(shù)據(jù)對(duì)應(yīng)，方便追溯。

（8）異常機(jī)制：每時(shí)每刻都要有異常思維，告訴開發(fā)怎么算異常？異常了怎么標(biāo)示出來。?比如：表1字段A，匹配表2字段B，將匹配成功的數(shù)據(jù)寫入表3。就要考慮表1無該字段A的情況。

（9）頁面長(zhǎng)期不登錄，則給自動(dòng)退出。主要考慮到后端系統(tǒng)的保密性。

（10）凡是帶操作的一般都要設(shè)置頁面權(quán)限。最簡(jiǎn)單的方式是所有系統(tǒng)的權(quán)限都分三個(gè)等級(jí)：不能查看、只能查看、可以編輯。

（文檔的模式和注意事項(xiàng)遠(yuǎn)不止上述，后續(xù)整理再補(bǔ)充）

本文由 @ 環(huán)滁皆山也 原創(chuàng)發(fā)布于人人都是產(chǎn)品經(jīng)理。未經(jīng)許可，禁止轉(zhuǎn)載

題圖來自 Pexels，基于 CC0 協(xié)議