計到測試文檔編寫指南)
這周在處理一個很典型的需求單編號 10001標題寫著“需求管理新增字段【ADB 模塊】、【YUNTI 模塊】需求文檔測試文檔”。先給結(jié)論這類“就是加幾個字段”的需求寫起來遠比看上去復雜。加字段不只是數(shù)據(jù)庫里多一列它牽扯到前端表單、列表展示、詳情頁、導出模板、接口出入?yún)ⅰ?shù)據(jù)字典、歷史數(shù)據(jù)回填、權(quán)限控制還要配一套能驗證這些鏈路的測試用例。這篇文章把我處理這個需求的全過程拆開講從需求澄清、字段設(shè)計到測試文檔編寫、評審應對和上線自檢適合正在做需求管理、配置管理和測試設(shè)計的朋友參考。1. 接到需求單先別急著寫字段表三個問題問清楚1.1 ADB 模塊和 YUNTI 模塊到底在解決什么場景我拿到這個單子的時候第一反應不是去畫字段而是先把兩個模塊在現(xiàn)有系統(tǒng)里的位置徹底弄清楚。ADB 模塊在我們這套需求管理平臺里承擔業(yè)務(wù)接入申請記錄的流轉(zhuǎn)YUNTI 模塊負責資源變更記錄的登記和追蹤。為了不把原始業(yè)務(wù)細節(jié)鋪得太開下面統(tǒng)一用這套代稱來講。這兩個模塊有一個共性現(xiàn)有的核心字段只覆蓋了“記錄本身是什么”卻沒有覆蓋“這條記錄當前處于什么狀態(tài)、由誰負責、預計什么時候處理完”。比如 ADB 模塊的列表能看出申請內(nèi)容但看不出渠道來源和優(yōu)先級業(yè)務(wù)方每天打開列表只能再點進詳情看流水日志去猜哪一個該先處理。YUNTI 模塊也是類似的別扭變更單能看出來改了什么但看不出負責人是誰、這個變更來自人工提交還是接口觸發(fā)導致出問題的時候找不到人。所以新增字段在設(shè)計層面本質(zhì)上不是“拍腦袋加幾列”而是在補業(yè)務(wù)流程里的信息斷點。需求澄清的第一步就是把這種“不好用”的痛點和字段缺口對齊。1.2 “測試文檔”四個字意味著什么需求文檔后面掛著“測試文檔”四個字這不是可有可無的后綴。結(jié)合需求管理平臺的分類習慣這種文檔要同時承擔兩個職責第一是把需求本身描述清楚第二是讓測試同事能直接照著設(shè)計用例。也就是說文檔里的每一條字段描述都要能翻譯成一句“如果怎么操作應該看到什么結(jié)果”的預期。這也解釋了為什么同樣一份文檔有人覺得寫得夠詳細有人卻覺得沒法下手。問題通常出在字段描述只寫了“新增什么”沒寫“在哪里展示、能不能為空、對歷史數(shù)據(jù)有沒有影響、錯誤時怎么提示”。把這些問題補上需求文檔才真正具備測試屬性也才對得起“測試文檔”這個類型。1.3 需求澄清會怎么開才不會白開需求澄清會不要開成“大家一起看文檔”。我一般把問題按下面幾個維度列成清單逐條過字段來源字段由誰新增、誰修改、誰查看操作權(quán)限分別落在哪些角色上。界面位置字段出現(xiàn)在列表、詳情、表單哪幾個地方新增、編輯、查看時是否一致。約束條件是否必填、是否唯一、是否參與排序、是否允許為空。字典范圍可選值的來源是固定枚舉、動態(tài)字典還是外部接口。數(shù)據(jù)影響歷史數(shù)據(jù)要不要回填老數(shù)據(jù)不適用新字段時怎么兜底。導出需求導出模板是否增加列列名和列寬怎么定導出格式與頁面展示是否一致。我會把這些問題在會前發(fā)給相關(guān)角色會上不是問“有沒有問題”而是問“每個字段在這六個維度分別選什么”。這樣開會效率會高很多開完就能形成一頁需求澄清記錄作為后期字段設(shè)計的輸入而不是開完會腦子里還是糊的。2. ADB 與 YUNTI 的字段清單從業(yè)務(wù)規(guī)則到字段屬性的一次推演2.1 字段命名、類型、取值范圍怎么定字段設(shè)計一定要先定規(guī)范再填內(nèi)容。我們這里的約定是內(nèi)部字段名統(tǒng)一用英文駝峰必須帶模塊前綴避免將來和其他模塊的同名字段在接口層撞車。下面這張表是我這次沉淀出來的第一版字段清單字段名和枚舉值都做了脫敏但設(shè)計思路可以直接復用模塊字段名中文含義數(shù)據(jù)類型是否必填默認值字典/說明ADBadb_channel渠道來源varchar(32)是無枚舉self、partner、otherADBadb_priority優(yōu)先級tinyint是11低、2中、3高參與列表排序ADBadb_estimated_time預計完成時間datetime否無精確到分鐘詳情頁展示ADBadb_remark備注varchar(500)否空串詳情頁展示不參與篩選YUNTIyunti_owner負責人varchar(64)是空串存人員工號展示時翻譯為姓名YUNTIyunti_source_type來源類型varchar(32)是manual枚舉manual、api、migrateYUNTIyunti_status狀態(tài)varchar(20)是pending枚舉pending、processing、done、rejectedYUNTIyunti_effective_date生效日期date否無只精確到天不參與時間計算字段表誰都會列難點在確定每一項背后的理由。我挑三個容易出問題的字段展開說。第一個是 adb_priority。業(yè)務(wù)方最開始提的是“優(yōu)先級用一個文本備注就行”但后來發(fā)現(xiàn)列表要按照優(yōu)先級排序文本字段排序會出來字典序3會排在10前面而且“高”“中”“低”這種中文文本在不同終端上的排序規(guī)則還容易不一致。最后改成 tinyint配合映射關(guān)系展示“低中高”排序和展示徹底解耦。第二個是 yunti_owner。字段如果直接存姓名會面臨人員離職、改名、重復名的問題。我們權(quán)限體系里本來就有統(tǒng)一的人員接口所以最終落庫存工號前端展示時再翻譯成姓名。這樣權(quán)限過濾、待辦推送、后續(xù)統(tǒng)計都能用同一個標識不會出現(xiàn)“張三”和“zhangsan”對不上的尷尬。第三個是 yunti_effective_date。日期和時間是兩個概念很多人會順手用 datetime但這里的業(yè)務(wù)語義只到“哪一天生效”用 datetime 反而會引入時區(qū)、跨天這些沒必要的復雜度。所以我明確用 date存儲、查詢、展示都不需要額外轉(zhuǎn)換。字段長度也一樣。比如 adb_channel 設(shè) varchar(32)不是因為渠道名最多 32 個字符而是因為字典里的枚舉值最長是 16預留一倍是為了以后增加枚舉項時不用馬上改表結(jié)構(gòu)。長度不是拍腦袋寫的要有余地。2.2 歷史數(shù)據(jù)與兼容性最容易忽略的“半路出家”問題新增字段時大家都盯著新數(shù)據(jù)卻很容易忽略老數(shù)據(jù)。兩個模塊在線上已經(jīng)跑了大半年存量記錄不會自動帶上新字段。處理原則是這樣的字段允許為空存量記錄留空即可但前端展示要定義“空值顯示什么”一般顯示短橫線。字段不允許為空必須提供一個回填方案。比如 adb_priority 存量統(tǒng)一回填為 1yunti_status 按流程節(jié)點反推當前狀態(tài)。字段要參與統(tǒng)計回填值必須經(jīng)過業(yè)務(wù)確認不能技術(shù)團隊自己拍板。數(shù)據(jù)庫變更我一般會寫成可重復執(zhí)行的遷移腳本核心部分長這樣ALTER TABLE adb_record ADD COLUMN adb_channel varchar(32) NOT NULL DEFAULT self COMMENT 渠道來源; ALTER TABLE adb_record ADD COLUMN adb_priority tinyint NOT NULL DEFAULT 1 COMMENT 優(yōu)先級 1低 2中 3高; ALTER TABLE adb_record ADD COLUMN adb_estimated_time datetime NULL COMMENT 預計完成時間; ALTER TABLE yunti_record ADD COLUMN yunti_owner varchar(64) NOT NULL DEFAULT COMMENT 負責人工號;注意這里用了 NOT NULL 和 DEFAULT是為了保證存量行讀取時不會出現(xiàn) NULL。類似的做法在測試文檔里也要體現(xiàn)一條歷史數(shù)據(jù)回填后列表頁、詳情頁、導出文件三個地方展示的結(jié)果要一致。否則很容易出現(xiàn)數(shù)據(jù)庫有值導出卻還是空的情況。3. 測試文檔怎么寫字段需求轉(zhuǎn)成驗收用例的完整拆解3.1 每條需求必須能對應到測試點需求文檔要變成測試文檔最有效的方法是在文檔里同時維護一張“需求-用例映射表”。我習慣用一個編號體系需求條目是 REQ-001、REQ-002 這種測試用例是 TC-001、TC-002 這種兩者一一掛鉤。對應關(guān)系如下需求條目需求內(nèi)容對應用例范圍關(guān)鍵預期REQ-001ADB模塊新增 adb_channel 字段TC-001~TC-004必填校驗、字典值、非法值、保存后展示REQ-002ADB模塊新增 adb_priority 字段TC-005~TC-008默認值、排序、范圍校驗、導出展示REQ-003YUNTI模塊新增 yunti_status 狀態(tài)字段TC-009~TC-012狀態(tài)流轉(zhuǎn)、權(quán)限可見、歷史數(shù)據(jù)回填這樣做的好處是評審的時候不用爭論“這里該測不該測”而是直接對著表說這條用例的預期對不對。文檔掛了“測試文檔”這個屬性就該早一點把測試視角拉進需求階段而不是等研發(fā)做完再補測試用例那樣既被動又容易漏。3.2 字段測試的邊界值和異常場景字段級用例最容易寫漏的是邊界和異常。拿 adb_priority 舉例正常用例只覆蓋 1、2、3但真正上線前我會補這么幾個提交 0 和 4驗證是否被校驗攔截。提交空字符串和 null驗證必填提示是否準確。提交小數(shù)、負數(shù)、超長字符串驗證接口是否返回明確的錯誤碼。列表按優(yōu)先級排序時3 優(yōu)先于 22 優(yōu)先于 1而不是按創(chuàng)建時間排。導出模板里優(yōu)先級顯示為“低中高”不是數(shù)字 1、2、3。yunti_owner 這類人員字段也要測輸入不存在的工號、輸入離職人員工號、批量導入時負責人字段為空以及負責人顯示時是否和人員接口的姓名一致。這些在平時回歸里屬于高頻問題提前寫進用例能省掉很多線上工單。3.3 頁面、接口、數(shù)據(jù)庫三層驗證字段改動很少只落在一層。前端表單、后端接口、數(shù)據(jù)庫表三處都要能對上否則就會出現(xiàn)“頁面能填接口不存數(shù)據(jù)庫為空”這種問題。聯(lián)調(diào)時我通常按三層分別確認前端層表單校驗規(guī)則、提示文案、詳情展示、列表列頭與寬度、篩選條件里是否增加了新字段以及空值狀態(tài)下頁面的展示是否符合預期。接口層創(chuàng)建接口、更新接口、詳情接口、列表接口的出入?yún)⑹欠癜伦侄巫侄蚊笮懯欠裾_老客戶端不傳新字段時能不能正常兼容。字段變更導致的接口報錯錯誤信息里要能看出是哪個字段出了問題。數(shù)據(jù)層新增記錄后數(shù)據(jù)庫字段是否正確落庫歷史數(shù)據(jù)回填是否執(zhí)行成功字段值是否符合字典約束是否存在超長截斷。3.4 測試數(shù)據(jù)準備與回歸范圍圈定準備測試數(shù)據(jù)時不能只準備一條“完美數(shù)據(jù)”。我一般至少準備三批一批新數(shù)據(jù)、一批舊數(shù)據(jù)、一批邊界數(shù)據(jù)。舊數(shù)據(jù)用于驗證回填邏輯邊界數(shù)據(jù)用于驗證校驗邏輯新數(shù)據(jù)用于覆蓋正常主流程。回歸范圍也不是只跑新增字段相關(guān)頁面而是要帶上列表頁、詳情頁、導出、權(quán)限過濾、排序這幾條鏈路因為它們都可能在同一個查詢里用到新字段。尤其是導出很多線上問題都出在導出模板漏加列或者列頭錯位這類問題用自動化用例不容易發(fā)現(xiàn)測試文檔里必須顯式寫出來。4. 評審會上最容易被挑戰(zhàn)的四個點以及怎么回應4.1 “這個字段為什么要叫這個名字”這個問題幾乎每次都會有人問。應對的核心不是臨場解釋而是提前把命名規(guī)范寫進文檔。我們這邊的規(guī)矩是內(nèi)部字段名用英文駝峰帶模塊前綴展示名稱單獨配置。比如 adb_priority 展示為“優(yōu)先級”如果業(yè)務(wù)方堅持要叫“重要程度”那是字典值的調(diào)整不影響字段名。剛開始帶需求評審的時候我也被問住過后來明白一個道理字段名不是給某一個人看的是給所有上下游系統(tǒng)看的。一旦定了接口、數(shù)據(jù)庫、報表、權(quán)限配置都要沿用改名成本極高。所以評審會上看到命名分歧不要急著爭論“好不好看”而是先確認這套命名會不會影響已確定的接口協(xié)議和數(shù)據(jù)字典。4.2 “那個字段以后可能改成多選”評審會里經(jīng)常聽到“現(xiàn)在單選用著以后可能會變成多選”。我的處理方式是先問清楚變化周期。如果三個月內(nèi)確實要改我會在字段設(shè)計上預留空間比如 yunti_source_type 直接用逗號分隔存字符串或者提前用 JSON 數(shù)組避免后面做結(jié)構(gòu)遷移如果只是“未來可能”就不要為不確定的需求增加復雜度。凡是臨時改類型的需求一定要評估歷史數(shù)據(jù)和新老版本兼容并在文檔里注明變更影響。單改多最大的坑在于存量數(shù)據(jù)存量值是單個字符串改成多選后歷史數(shù)據(jù)顯示成什么需要提前定義清楚否則上線后詳情頁會展示出很難看的格式。4.3 “為什么新增字段要動權(quán)限”yunti_owner 和狀態(tài)這類字段天然涉及數(shù)據(jù)敏感度不是所有角色都能看。需求文檔里要單獨畫一個權(quán)限矩陣哪些角色可讀、哪些角色可寫、哪些字段列表頁可見、哪些字段詳情頁才顯示。不寫這個上線后很容易被安全同事打回。權(quán)限矩陣示例字段管理員業(yè)務(wù)操作員只讀人員yunti_owner讀寫讀寫只讀yunti_status讀寫讀寫只讀adb_priority讀寫讀只讀還可以進一步定義字段是否進入列表查詢條件。比如 adb_estimated_time 只有詳情頁可見不進列表不參與篩選這樣權(quán)限、性能、展示三個問題的邊界都清楚了。4.4 評審記錄與變更控制評審會上被挑戰(zhàn)是好事說明大家認真看了。但文檔不能在評審后七改八改尤其是字段類型這種一旦落庫就很難回頭的決定。我會準備一個版本記錄表記錄版本號、修改人、修改內(nèi)容、修改原因和確認人。任何字段名、類型、字典值的變更都要重新走一次相關(guān)角色確認不能私下在群里說一句“改一下吧”就直接改。關(guān)于“測試文檔”這個類型評審記錄里還要專門寫清楚測試范圍。哪些字段納入本次測試哪些字段只是預留接口不落庫哪些字段會影響歷史數(shù)據(jù)展示這三類事件在評審表里分開列后面測試執(zhí)行時才不會有人拿著預留字段當 bug 提。5. 從評審到上線需求文檔的修改、確認和變更控制5.1 文檔狀態(tài)怎么流轉(zhuǎn)需求管理平臺里新增字段的需求文檔一般會有草稿、評審中、已確認、開發(fā)中、待測試、已完成這幾個狀態(tài)。10001 這個單子目前是測試文檔階段我理解為字段需求已經(jīng)評審通過進入驗證環(huán)節(jié)。但這個“已確認”并不意味著所有細節(jié)都定了接口聯(lián)調(diào)時發(fā)現(xiàn)的字段參數(shù)問題仍然要走變更記錄不能背地里改完不吭聲。我習慣在文檔狀態(tài)變更時同步更新一版“變更說明”哪怕只是改了一個默認值也要寫清楚改前是什么、改后是什么、為什么改。這個動作看起來繁瑣但遇上兩三個月后有人問“這個字段當初為什么這么設(shè)計”翻文檔比翻聊天記錄靠譜得多。5.2 多模塊并發(fā)時如何避免互相影響ADB 和 YUNTI 模塊同在一個需求管理平臺里如果同期還有其他需求在動同一張表字段新增就可能產(chǎn)生沖突。我這次處理時先把兩個模塊涉及的數(shù)據(jù)庫表、接口路徑、頁面路由都拉出來做了一份影響范圍清單并在文檔里標注。如果后續(xù)有人要改同一張表我會提醒對方先看我的字段定義避免重復字段或者類型不一致。另一個容易被忽略的是索引。新字段如果作為列表篩選條件很可能需要加普通索引但如果與其他需求并發(fā)兩個人同時加索引可能造成表鎖等待。所以數(shù)據(jù)庫變更要排好順序盡量放在低峰期執(zhí)行并且提前把變更腳本發(fā)給 DBA 確認。5.3 文檔歸檔與知識沉淀需求文檔和測試文檔最終要歸檔到系統(tǒng)里不只是為了流程合規(guī)更是為了以后做同類需求時有現(xiàn)成可參考的模板。我每次做完這類“新增字段”需求都會把字段設(shè)計、回填方案、測試用例這套方法沉淀成一個通用模板。下次再有一個模塊要加字段直接復用至少能省半天評審時間。歸檔時不要只傳一份終版文檔最好把需求澄清記錄、評審會議紀要和變更記錄三個附件一起掛上去。這樣項目結(jié)束三個月后誰來看都能還原當時的決策鏈路不需要拉著當時的經(jīng)辦人重新講一遍。6. 一份可以直接抄作業(yè)的字段需求自檢清單6.1 需求文檔內(nèi)容自檢我給自己定了一個發(fā)布前的檢查清單每次都覺得檢查完肯定沒問題結(jié)果一對照還能翻出來幾個遺漏整理成下面這版每個字段是否說明了中文名、英文名、類型、長度、必填性、默認值、字典項。是否說明字段在哪些頁面出現(xiàn)列表、表單、詳情、篩選、導出有沒有遺漏。是否說明新字段和現(xiàn)有舊字段的關(guān)系有沒有重復或可以復用。是否說明歷史數(shù)據(jù)回填方案存量數(shù)據(jù)不滿足新規(guī)則時如何兜底。是否定義接口出入?yún)⒑湾e誤碼新增字段在異常情況下怎么返回。是否畫出權(quán)限矩陣敏感字段有沒有設(shè)置可見范圍。是否把需求條目和測試用例關(guān)聯(lián)起來評審時能逐條核對。6.2 測試文檔內(nèi)容自檢測試文檔這邊我也有一個清單正常用例、邊界用例、異常用例是否齊全。是否覆蓋前端、接口、數(shù)據(jù)庫三層。導出、排序、篩選、權(quán)限、歷史數(shù)據(jù)這些跨功能鏈路是否都設(shè)計到了。測試數(shù)據(jù)是否同時包含新數(shù)據(jù)和存量數(shù)據(jù)。用例預期是否具體到可見的界面表現(xiàn)而不是“系統(tǒng)正?！边@類空話。是否預留了回歸執(zhí)行人和執(zhí)行時間方便追蹤測試進度。6.3 上線前后的時間節(jié)奏參考字段需求雖然小節(jié)奏不能亂。我的建議是需求澄清至少留半天字段設(shè)計加歷史數(shù)據(jù)方案留一天評審會留一小時研發(fā)開發(fā)一到兩天測試用例設(shè)計半天到一天接口聯(lián)調(diào)半天全量回歸一天。如果每個環(huán)節(jié)都壓縮得很緊最大的風險不是開發(fā)寫不出代碼而是測試遺漏了邊界場景后面線上補數(shù)據(jù)可比開發(fā)的時候補麻煩得多。最后再說一個自己的小習慣每次上線前我會把所有新字段的字典項、默認值、回填規(guī)則單獨拉一個 Excel 給業(yè)務(wù)和測試各發(fā)一份讓大家在上線前哪怕不打開系統(tǒng)也有一個統(tǒng)一的對表。這個動作成本極低卻能避免很多“我以為你改了你以為我改了”的誤會。需求管理和字段設(shè)計這件事說到底不是替系統(tǒng)做決定而是替團隊把每個決定說清楚。 需求管理新增字段全流程：從設(shè)計到測試文檔編寫指南
這周在處理一個很典型的需求單編號 10001標題寫著“需求管理新增字段【ADB 模塊】、【YUNTI 模塊】需求文檔測試文檔”。先給結(jié)論這類“就是加幾個字段”的需求寫起來遠比看上去復雜。加字段不只是數(shù)據(jù)庫里多一列它牽扯到前端表單、列表展示、詳情頁、導出模板、接口出入?yún)ⅰ?shù)據(jù)字典、歷史數(shù)據(jù)回填、權(quán)限控制還要配一套能驗證這些鏈路的測試用例。這篇文章把我處理這個需求的全過程拆開講從需求澄清、字段設(shè)計到測試文檔編寫、評審應對和上線自檢適合正在做需求管理、配置管理和測試設(shè)計的朋友參考。1. 接到需求單先別急著寫字段表三個問題問清楚1.1 ADB 模塊和 YUNTI 模塊到底在解決什么場景我拿到這個單子的時候第一反應不是去畫字段而是先把兩個模塊在現(xiàn)有系統(tǒng)里的位置徹底弄清楚。ADB 模塊在我們這套需求管理平臺里承擔業(yè)務(wù)接入申請記錄的流轉(zhuǎn)YUNTI 模塊負責資源變更記錄的登記和追蹤。為了不把原始業(yè)務(wù)細節(jié)鋪得太開下面統(tǒng)一用這套代稱來講。這兩個模塊有一個共性現(xiàn)有的核心字段只覆蓋了“記錄本身是什么”卻沒有覆蓋“這條記錄當前處于什么狀態(tài)、由誰負責、預計什么時候處理完”。比如 ADB 模塊的列表能看出申請內(nèi)容但看不出渠道來源和優(yōu)先級業(yè)務(wù)方每天打開列表只能再點進詳情看流水日志去猜哪一個該先處理。YUNTI 模塊也是類似的別扭變更單能看出來改了什么但看不出負責人是誰、這個變更來自人工提交還是接口觸發(fā)導致出問題的時候找不到人。所以新增字段在設(shè)計層面本質(zhì)上不是“拍腦袋加幾列”而是在補業(yè)務(wù)流程里的信息斷點。需求澄清的第一步就是把這種“不好用”的痛點和字段缺口對齊。1.2 “測試文檔”四個字意味著什么需求文檔后面掛著“測試文檔”四個字這不是可有可無的后綴。結(jié)合需求管理平臺的分類習慣這種文檔要同時承擔兩個職責第一是把需求本身描述清楚第二是讓測試同事能直接照著設(shè)計用例。也就是說文檔里的每一條字段描述都要能翻譯成一句“如果怎么操作應該看到什么結(jié)果”的預期。這也解釋了為什么同樣一份文檔有人覺得寫得夠詳細有人卻覺得沒法下手。問題通常出在字段描述只寫了“新增什么”沒寫“在哪里展示、能不能為空、對歷史數(shù)據(jù)有沒有影響、錯誤時怎么提示”。把這些問題補上需求文檔才真正具備測試屬性也才對得起“測試文檔”這個類型。1.3 需求澄清會怎么開才不會白開需求澄清會不要開成“大家一起看文檔”。我一般把問題按下面幾個維度列成清單逐條過字段來源字段由誰新增、誰修改、誰查看操作權(quán)限分別落在哪些角色上。界面位置字段出現(xiàn)在列表、詳情、表單哪幾個地方新增、編輯、查看時是否一致。約束條件是否必填、是否唯一、是否參與排序、是否允許為空。字典范圍可選值的來源是固定枚舉、動態(tài)字典還是外部接口。數(shù)據(jù)影響歷史數(shù)據(jù)要不要回填老數(shù)據(jù)不適用新字段時怎么兜底。導出需求導出模板是否增加列列名和列寬怎么定導出格式與頁面展示是否一致。我會把這些問題在會前發(fā)給相關(guān)角色會上不是問“有沒有問題”而是問“每個字段在這六個維度分別選什么”。這樣開會效率會高很多開完就能形成一頁需求澄清記錄作為后期字段設(shè)計的輸入而不是開完會腦子里還是糊的。2. ADB 與 YUNTI 的字段清單從業(yè)務(wù)規(guī)則到字段屬性的一次推演2.1 字段命名、類型、取值范圍怎么定字段設(shè)計一定要先定規(guī)范再填內(nèi)容。我們這里的約定是內(nèi)部字段名統(tǒng)一用英文駝峰必須帶模塊前綴避免將來和其他模塊的同名字段在接口層撞車。下面這張表是我這次沉淀出來的第一版字段清單字段名和枚舉值都做了脫敏但設(shè)計思路可以直接復用模塊字段名中文含義數(shù)據(jù)類型是否必填默認值字典/說明ADBadb_channel渠道來源varchar(32)是無枚舉self、partner、otherADBadb_priority優(yōu)先級tinyint是11低、2中、3高參與列表排序ADBadb_estimated_time預計完成時間datetime否無精確到分鐘詳情頁展示ADBadb_remark備注varchar(500)否空串詳情頁展示不參與篩選YUNTIyunti_owner負責人varchar(64)是空串存人員工號展示時翻譯為姓名YUNTIyunti_source_type來源類型varchar(32)是manual枚舉manual、api、migrateYUNTIyunti_status狀態(tài)varchar(20)是pending枚舉pending、processing、done、rejectedYUNTIyunti_effective_date生效日期date否無只精確到天不參與時間計算字段表誰都會列難點在確定每一項背后的理由。我挑三個容易出問題的字段展開說。第一個是 adb_priority。業(yè)務(wù)方最開始提的是“優(yōu)先級用一個文本備注就行”但后來發(fā)現(xiàn)列表要按照優(yōu)先級排序文本字段排序會出來字典序3會排在10前面而且“高”“中”“低”這種中文文本在不同終端上的排序規(guī)則還容易不一致。最后改成 tinyint配合映射關(guān)系展示“低中高”排序和展示徹底解耦。第二個是 yunti_owner。字段如果直接存姓名會面臨人員離職、改名、重復名的問題。我們權(quán)限體系里本來就有統(tǒng)一的人員接口所以最終落庫存工號前端展示時再翻譯成姓名。這樣權(quán)限過濾、待辦推送、后續(xù)統(tǒng)計都能用同一個標識不會出現(xiàn)“張三”和“zhangsan”對不上的尷尬。第三個是 yunti_effective_date。日期和時間是兩個概念很多人會順手用 datetime但這里的業(yè)務(wù)語義只到“哪一天生效”用 datetime 反而會引入時區(qū)、跨天這些沒必要的復雜度。所以我明確用 date存儲、查詢、展示都不需要額外轉(zhuǎn)換。字段長度也一樣。比如 adb_channel 設(shè) varchar(32)不是因為渠道名最多 32 個字符而是因為字典里的枚舉值最長是 16預留一倍是為了以后增加枚舉項時不用馬上改表結(jié)構(gòu)。長度不是拍腦袋寫的要有余地。2.2 歷史數(shù)據(jù)與兼容性最容易忽略的“半路出家”問題新增字段時大家都盯著新數(shù)據(jù)卻很容易忽略老數(shù)據(jù)。兩個模塊在線上已經(jīng)跑了大半年存量記錄不會自動帶上新字段。處理原則是這樣的字段允許為空存量記錄留空即可但前端展示要定義“空值顯示什么”一般顯示短橫線。字段不允許為空必須提供一個回填方案。比如 adb_priority 存量統(tǒng)一回填為 1yunti_status 按流程節(jié)點反推當前狀態(tài)。字段要參與統(tǒng)計回填值必須經(jīng)過業(yè)務(wù)確認不能技術(shù)團隊自己拍板。數(shù)據(jù)庫變更我一般會寫成可重復執(zhí)行的遷移腳本核心部分長這樣ALTER TABLE adb_record ADD COLUMN adb_channel varchar(32) NOT NULL DEFAULT self COMMENT 渠道來源; ALTER TABLE adb_record ADD COLUMN adb_priority tinyint NOT NULL DEFAULT 1 COMMENT 優(yōu)先級 1低 2中 3高; ALTER TABLE adb_record ADD COLUMN adb_estimated_time datetime NULL COMMENT 預計完成時間; ALTER TABLE yunti_record ADD COLUMN yunti_owner varchar(64) NOT NULL DEFAULT COMMENT 負責人工號;注意這里用了 NOT NULL 和 DEFAULT是為了保證存量行讀取時不會出現(xiàn) NULL。類似的做法在測試文檔里也要體現(xiàn)一條歷史數(shù)據(jù)回填后列表頁、詳情頁、導出文件三個地方展示的結(jié)果要一致。否則很容易出現(xiàn)數(shù)據(jù)庫有值導出卻還是空的情況。3. 測試文檔怎么寫字段需求轉(zhuǎn)成驗收用例的完整拆解3.1 每條需求必須能對應到測試點需求文檔要變成測試文檔最有效的方法是在文檔里同時維護一張“需求-用例映射表”。我習慣用一個編號體系需求條目是 REQ-001、REQ-002 這種測試用例是 TC-001、TC-002 這種兩者一一掛鉤。對應關(guān)系如下需求條目需求內(nèi)容對應用例范圍關(guān)鍵預期REQ-001ADB模塊新增 adb_channel 字段TC-001~TC-004必填校驗、字典值、非法值、保存后展示REQ-002ADB模塊新增 adb_priority 字段TC-005~TC-008默認值、排序、范圍校驗、導出展示REQ-003YUNTI模塊新增 yunti_status 狀態(tài)字段TC-009~TC-012狀態(tài)流轉(zhuǎn)、權(quán)限可見、歷史數(shù)據(jù)回填這樣做的好處是評審的時候不用爭論“這里該測不該測”而是直接對著表說這條用例的預期對不對。文檔掛了“測試文檔”這個屬性就該早一點把測試視角拉進需求階段而不是等研發(fā)做完再補測試用例那樣既被動又容易漏。3.2 字段測試的邊界值和異常場景字段級用例最容易寫漏的是邊界和異常。拿 adb_priority 舉例正常用例只覆蓋 1、2、3但真正上線前我會補這么幾個提交 0 和 4驗證是否被校驗攔截。提交空字符串和 null驗證必填提示是否準確。提交小數(shù)、負數(shù)、超長字符串驗證接口是否返回明確的錯誤碼。列表按優(yōu)先級排序時3 優(yōu)先于 22 優(yōu)先于 1而不是按創(chuàng)建時間排。導出模板里優(yōu)先級顯示為“低中高”不是數(shù)字 1、2、3。yunti_owner 這類人員字段也要測輸入不存在的工號、輸入離職人員工號、批量導入時負責人字段為空以及負責人顯示時是否和人員接口的姓名一致。這些在平時回歸里屬于高頻問題提前寫進用例能省掉很多線上工單。3.3 頁面、接口、數(shù)據(jù)庫三層驗證字段改動很少只落在一層。前端表單、后端接口、數(shù)據(jù)庫表三處都要能對上否則就會出現(xiàn)“頁面能填接口不存數(shù)據(jù)庫為空”這種問題。聯(lián)調(diào)時我通常按三層分別確認前端層表單校驗規(guī)則、提示文案、詳情展示、列表列頭與寬度、篩選條件里是否增加了新字段以及空值狀態(tài)下頁面的展示是否符合預期。接口層創(chuàng)建接口、更新接口、詳情接口、列表接口的出入?yún)⑹欠癜伦侄巫侄蚊笮懯欠裾_老客戶端不傳新字段時能不能正常兼容。字段變更導致的接口報錯錯誤信息里要能看出是哪個字段出了問題。數(shù)據(jù)層新增記錄后數(shù)據(jù)庫字段是否正確落庫歷史數(shù)據(jù)回填是否執(zhí)行成功字段值是否符合字典約束是否存在超長截斷。3.4 測試數(shù)據(jù)準備與回歸范圍圈定準備測試數(shù)據(jù)時不能只準備一條“完美數(shù)據(jù)”。我一般至少準備三批一批新數(shù)據(jù)、一批舊數(shù)據(jù)、一批邊界數(shù)據(jù)。舊數(shù)據(jù)用于驗證回填邏輯邊界數(shù)據(jù)用于驗證校驗邏輯新數(shù)據(jù)用于覆蓋正常主流程。回歸范圍也不是只跑新增字段相關(guān)頁面而是要帶上列表頁、詳情頁、導出、權(quán)限過濾、排序這幾條鏈路因為它們都可能在同一個查詢里用到新字段。尤其是導出很多線上問題都出在導出模板漏加列或者列頭錯位這類問題用自動化用例不容易發(fā)現(xiàn)測試文檔里必須顯式寫出來。4. 評審會上最容易被挑戰(zhàn)的四個點以及怎么回應4.1 “這個字段為什么要叫這個名字”這個問題幾乎每次都會有人問。應對的核心不是臨場解釋而是提前把命名規(guī)范寫進文檔。我們這邊的規(guī)矩是內(nèi)部字段名用英文駝峰帶模塊前綴展示名稱單獨配置。比如 adb_priority 展示為“優(yōu)先級”如果業(yè)務(wù)方堅持要叫“重要程度”那是字典值的調(diào)整不影響字段名。剛開始帶需求評審的時候我也被問住過后來明白一個道理字段名不是給某一個人看的是給所有上下游系統(tǒng)看的。一旦定了接口、數(shù)據(jù)庫、報表、權(quán)限配置都要沿用改名成本極高。所以評審會上看到命名分歧不要急著爭論“好不好看”而是先確認這套命名會不會影響已確定的接口協(xié)議和數(shù)據(jù)字典。4.2 “那個字段以后可能改成多選”評審會里經(jīng)常聽到“現(xiàn)在單選用著以后可能會變成多選”。我的處理方式是先問清楚變化周期。如果三個月內(nèi)確實要改我會在字段設(shè)計上預留空間比如 yunti_source_type 直接用逗號分隔存字符串或者提前用 JSON 數(shù)組避免后面做結(jié)構(gòu)遷移如果只是“未來可能”就不要為不確定的需求增加復雜度。凡是臨時改類型的需求一定要評估歷史數(shù)據(jù)和新老版本兼容并在文檔里注明變更影響。單改多最大的坑在于存量數(shù)據(jù)存量值是單個字符串改成多選后歷史數(shù)據(jù)顯示成什么需要提前定義清楚否則上線后詳情頁會展示出很難看的格式。4.3 “為什么新增字段要動權(quán)限”yunti_owner 和狀態(tài)這類字段天然涉及數(shù)據(jù)敏感度不是所有角色都能看。需求文檔里要單獨畫一個權(quán)限矩陣哪些角色可讀、哪些角色可寫、哪些字段列表頁可見、哪些字段詳情頁才顯示。不寫這個上線后很容易被安全同事打回。權(quán)限矩陣示例字段管理員業(yè)務(wù)操作員只讀人員yunti_owner讀寫讀寫只讀yunti_status讀寫讀寫只讀adb_priority讀寫讀只讀還可以進一步定義字段是否進入列表查詢條件。比如 adb_estimated_time 只有詳情頁可見不進列表不參與篩選這樣權(quán)限、性能、展示三個問題的邊界都清楚了。4.4 評審記錄與變更控制評審會上被挑戰(zhàn)是好事說明大家認真看了。但文檔不能在評審后七改八改尤其是字段類型這種一旦落庫就很難回頭的決定。我會準備一個版本記錄表記錄版本號、修改人、修改內(nèi)容、修改原因和確認人。任何字段名、類型、字典值的變更都要重新走一次相關(guān)角色確認不能私下在群里說一句“改一下吧”就直接改。關(guān)于“測試文檔”這個類型評審記錄里還要專門寫清楚測試范圍。哪些字段納入本次測試哪些字段只是預留接口不落庫哪些字段會影響歷史數(shù)據(jù)展示這三類事件在評審表里分開列后面測試執(zhí)行時才不會有人拿著預留字段當 bug 提。5. 從評審到上線需求文檔的修改、確認和變更控制5.1 文檔狀態(tài)怎么流轉(zhuǎn)需求管理平臺里新增字段的需求文檔一般會有草稿、評審中、已確認、開發(fā)中、待測試、已完成這幾個狀態(tài)。10001 這個單子目前是測試文檔階段我理解為字段需求已經(jīng)評審通過進入驗證環(huán)節(jié)。但這個“已確認”并不意味著所有細節(jié)都定了接口聯(lián)調(diào)時發(fā)現(xiàn)的字段參數(shù)問題仍然要走變更記錄不能背地里改完不吭聲。我習慣在文檔狀態(tài)變更時同步更新一版“變更說明”哪怕只是改了一個默認值也要寫清楚改前是什么、改后是什么、為什么改。這個動作看起來繁瑣但遇上兩三個月后有人問“這個字段當初為什么這么設(shè)計”翻文檔比翻聊天記錄靠譜得多。5.2 多模塊并發(fā)時如何避免互相影響ADB 和 YUNTI 模塊同在一個需求管理平臺里如果同期還有其他需求在動同一張表字段新增就可能產(chǎn)生沖突。我這次處理時先把兩個模塊涉及的數(shù)據(jù)庫表、接口路徑、頁面路由都拉出來做了一份影響范圍清單并在文檔里標注。如果后續(xù)有人要改同一張表我會提醒對方先看我的字段定義避免重復字段或者類型不一致。另一個容易被忽略的是索引。新字段如果作為列表篩選條件很可能需要加普通索引但如果與其他需求并發(fā)兩個人同時加索引可能造成表鎖等待。所以數(shù)據(jù)庫變更要排好順序盡量放在低峰期執(zhí)行并且提前把變更腳本發(fā)給 DBA 確認。5.3 文檔歸檔與知識沉淀需求文檔和測試文檔最終要歸檔到系統(tǒng)里不只是為了流程合規(guī)更是為了以后做同類需求時有現(xiàn)成可參考的模板。我每次做完這類“新增字段”需求都會把字段設(shè)計、回填方案、測試用例這套方法沉淀成一個通用模板。下次再有一個模塊要加字段直接復用至少能省半天評審時間。歸檔時不要只傳一份終版文檔最好把需求澄清記錄、評審會議紀要和變更記錄三個附件一起掛上去。這樣項目結(jié)束三個月后誰來看都能還原當時的決策鏈路不需要拉著當時的經(jīng)辦人重新講一遍。6. 一份可以直接抄作業(yè)的字段需求自檢清單6.1 需求文檔內(nèi)容自檢我給自己定了一個發(fā)布前的檢查清單每次都覺得檢查完肯定沒問題結(jié)果一對照還能翻出來幾個遺漏整理成下面這版每個字段是否說明了中文名、英文名、類型、長度、必填性、默認值、字典項。是否說明字段在哪些頁面出現(xiàn)列表、表單、詳情、篩選、導出有沒有遺漏。是否說明新字段和現(xiàn)有舊字段的關(guān)系有沒有重復或可以復用。是否說明歷史數(shù)據(jù)回填方案存量數(shù)據(jù)不滿足新規(guī)則時如何兜底。是否定義接口出入?yún)⒑湾e誤碼新增字段在異常情況下怎么返回。是否畫出權(quán)限矩陣敏感字段有沒有設(shè)置可見范圍。是否把需求條目和測試用例關(guān)聯(lián)起來評審時能逐條核對。6.2 測試文檔內(nèi)容自檢測試文檔這邊我也有一個清單正常用例、邊界用例、異常用例是否齊全。是否覆蓋前端、接口、數(shù)據(jù)庫三層。導出、排序、篩選、權(quán)限、歷史數(shù)據(jù)這些跨功能鏈路是否都設(shè)計到了。測試數(shù)據(jù)是否同時包含新數(shù)據(jù)和存量數(shù)據(jù)。用例預期是否具體到可見的界面表現(xiàn)而不是“系統(tǒng)正?！边@類空話。是否預留了回歸執(zhí)行人和執(zhí)行時間方便追蹤測試進度。6.3 上線前后的時間節(jié)奏參考字段需求雖然小節(jié)奏不能亂。我的建議是需求澄清至少留半天字段設(shè)計加歷史數(shù)據(jù)方案留一天評審會留一小時研發(fā)開發(fā)一到兩天測試用例設(shè)計半天到一天接口聯(lián)調(diào)半天全量回歸一天。如果每個環(huán)節(jié)都壓縮得很緊最大的風險不是開發(fā)寫不出代碼而是測試遺漏了邊界場景后面線上補數(shù)據(jù)可比開發(fā)的時候補麻煩得多。最后再說一個自己的小習慣每次上線前我會把所有新字段的字典項、默認值、回填規(guī)則單獨拉一個 Excel 給業(yè)務(wù)和測試各發(fā)一份讓大家在上線前哪怕不打開系統(tǒng)也有一個統(tǒng)一的對表。這個動作成本極低卻能避免很多“我以為你改了你以為我改了”的誤會。需求管理和字段設(shè)計這件事說到底不是替系統(tǒng)做決定而是替團隊把每個決定說清楚。