国外亚洲成av人片在线观看,热99re久久精品这里都是精品,天堂网在线最新版www,国产成人av区一区二区三,51久久成人国产精品麻豆

作為一個產品經理，要如何輕松搞定接口需求與文檔？下面一起來看這篇有筆者整理分享的關于接口需求與文檔相關內容的文章吧！推薦值得一看哦！

一、前言

不懂技術的產品同學，天然的對技術相關的需求犯怵。比如說接口需求，接口是開發(fā)過程中避免不了的東西，作為產品經理，一定要知道。我一直負責集團的公共服務，所有服務都是通過「接口」與各個產品線對接。我也沒有技術背景，當然在過程中遇到了一些問題，所以我總結了關于「接口需求」相關的內容。

說下：接口需求怎么提接口文檔怎么看。

二、接口的作用

什么是接口？

看下邊的例子：

微信獲取用戶基礎信息接口：https://api.weixin.qq.com/cgi-bin/user/info/batchget?access_token=ACCESS_TOKEN

飛書查看全部工單接口：https://open.feishu.cn/open-apis/helpdesk/v1/tickets

這些 url鏈接就是接口地址。通過調用接口地址，獲取到想要的東西。對于接口的作用，我劃分為 3 種：

1. 前端與后端的數據處理

比如列表上有個「新增」的功能。前端開發(fā)出一個表單功能，當填完數據后，點擊確定，前端會調用「新增數據接口」，將頁面中錄入的數據通過接口，傳給后端，后端對傳入的數據進行處理。接口處理完成后，會返回出具體的參數，前端根據返回的參數，給出對應的反饋信息。

比如當接口的校驗沒有通過時，則會通過接口返回出錯誤信息，前端會將錯誤信息在頁面上進行提示。

同樣的，對于刪除數據、修改數據、查詢數據等，都是通過接口的方式對數據進行處理。

2. 跨系統的同步數據

兩個系統之間進行數據同步。

比如我有個需求，需要使用到「系統用戶信息」。對于「用戶信息」，我司只有「賬號系統」有，我需要和賬號系統的產品經理溝通，對方提供給我一個接口文檔，我們按照接口文檔的要求進行數據同步。

同樣的，當有需求要使用到你系統里的數據，也可以通過「接口」將數據同步給需求方。對于數據同步接口，數據同步的方式、數據同步的時機等等都是接口需求需要考慮到的內容。

這幾點我們在下邊詳細說～

3. 提供公共服務

通過接口對外提供服務能力，可以滿足不同的系統或應用程序之間進行功能調用。比如說身份證歸屬地查詢服務，通過輸入身份證號查詢出歸屬地。當需要使用這個功能的時候，都可以調用「身份證歸屬地查詢接口」，來實現這個功能。

另外支付服務、登錄服務、獲取收貨地址等等，能夠對外提供的公共服務，我們都可以做成公共接口對外使用。

三、接口需求怎么提

很多同學認為接口是研發(fā)開發(fā)的，和產品沒有關系，我之前也是這樣想，后來發(fā)現這個并不對。接口是基于需求來開發(fā)的，里邊涉及業(yè)務相關的內容，研發(fā)并不清楚具體的業(yè)務場景，如果產品經理不進行介入，就會導致接口的場景覆蓋程度、擴展性受限。

不會提接口需求沒關系，我們接下來細說：我們根據上邊說的3 種接口用途，看下需求如何提。

1. 前后端數據處理接口

這類接口一般和功能相關，也不涉及到跨系統，可以直接通過功能需求描述，不用特意地對接口進行說明。在研發(fā)開始前，前端與后端根據需求進行功能拆分，后端開發(fā)接口，前端開發(fā)頁面，然后前后端進行接口聯調。

2. 數據同步接口

無非 2 種：

1. 你向別人提供數據：需要你定義接口需求
2. 別人向你提供數據：需要你會看別人的接口文檔

我們先看「你向別人提供數據」

舉個例子：一條產品線有個需求，想使用你系統的「人員信息」數據，在他們系統的頁面中展示出「人員信息列表」

我們先從以下角度思考：

1）數據能否提供？

1. 是否該由自己系統提供，是否其他系統提供更好？
2. 提供的數據能夠滿足對方需求，是否缺字段？
3. 數據是否敏感數據？是否知識產權數據？
4. 其它產品線是否也有這個需求，是否也需要這個接口？
5. 對于這個接口是做成公共接口，每個業(yè)務方都能進行調用，還是只對這一個業(yè)務線提供。

一般情況下，數據同步接口都可以做成公共接口，讓每個業(yè)務方都能使用此接口。

2）支持哪種同步方式？

①業(yè)務方直接使用接口實時搜索，直接列表展示

業(yè)務方通過接口實時查詢數據，并展示出結果，不將數據放到自己的數據庫里。好處是每次查詢都是最新數據。但是這種方式很不建議，當有業(yè)務方需要用到你的數據的時候，也需要提醒對方不要使用這種方式。用他方的數據同步接口去進行實時查詢，如果數據同步接口性能扛不住，接口掛了，那業(yè)務也會掛。

當需要對數據進行二次加工處理，這種方式就不支持了，只能讓數據同步接口加需求。但是一般的數據同步接口都是公共接口，不僅有一個業(yè)務方使用，當這個接口不滿足你的需求的時候，公共接口不會根據你的需求做個性化調整。

②業(yè)務方通過接口將數據存儲到自己的數據庫中，對數據進行二次處理

通過數據同步接口，將數據同步到自己的數據庫中，單獨存一份，與數據提供方做一層隔離。自己業(yè)務使用時，從自己的數據庫中取數據。這樣就算同步接口掛了，也不會影響自己的業(yè)務。同時，可以對獲取的數據進行二次處理，靈活性更強。當業(yè)務方單獨存儲數據后，為了讓兩方數據保持一致，這就涉及到「數據更新」。

3）數據更新機制

分為2種：推、拉

推：有數據更新后，將更新的數據推給下游業(yè)務方。

①「推」有 2 種方式：

1. 當數據有更新時，上游給下游業(yè)務方發(fā)一條「數據更新通知」，讓業(yè)務方判斷是否更新、更新哪些數據。這個時候上游就需要多開發(fā)一個「數據更新通知接口」，用于發(fā)出通知。同時下游方也需要開發(fā)一個接口，用于接收通知。
2. 強制業(yè)務方更新，硬性更新數據。對于主數據、標準字典值都需要使用這種方式。

拉：下游業(yè)務方去主動拉取新的數據。

②「拉取」有 2 種方式：

1. 定時拉?。河沙绦蚨〞r拉取，如每天同步、每 5min 同步、每 1h 同步一次等等，根據數據更新頻次、對數據一致性的嚴謹度進行判斷。
2. 手動拉?。菏謩佑|發(fā)更新。是指當需要使用到最新數據的時候，手動觸發(fā)數據更新，比如頁面上添加個「數據同步」的按鈕，點擊后，調用數據同步接口，拉取最新的數據。當然，也可以「定時拉取+手動拉取」，例如每晚程序自動更新，白天需要更新時，可手動觸發(fā)更新。每次更新數據的時候，又涉及到「數據更新的范圍」。

4）數據更新范圍

分為：全量更新、增量更新。它們的選擇取決于需要同步的數據量以及更新的頻率。

• 全量更新：更新全部數據，無論數據是否有變化，都會對整個數據進行更新。將已有的數據刪除，然后重新獲取新的數據。這種方式比較適合數據量較小或對數據一致性要求較高的情況。
• 增量更新：只更新發(fā)生變化的數據。當把數據全量同步后，之后只更新發(fā)生變化的數據。比如說上游發(fā)出了數據更新通知，告訴哪條數據發(fā)生了更新，此時接入方可以只更新發(fā)生更新的數據。增量更新適用于整體數據量較大、更新頻率低的情況。增量更新比較高效，更新數據用時也比較快。到這，我們把數據同步的同步方式、數據更新機制、數據更新范圍確定好了。接著繼續(xù)明確接入方可以使用哪些字段去獲取數據。

5）通過哪些字段獲取數據能獲取到哪些數據？

用哪個字段獲取數據，意思是向接口傳入哪些字段。能夠獲取到哪些數據，意思是接口會返回出哪些字段。會有2 個名詞：

1. 入參：就是向接口傳入的參數數據，也叫請求參數等。
2. 出參：接口返回數據的參數數據，也叫返參、返回參數、響應參數等。

你可以理解為，接口就是個列表，這個列表的查詢條件有哪些、查詢結果有哪些。查詢條件，就是接口的「入參」查詢出的結果，就是接口的「出參」

①對于「入參」，在提需求時，產品經理需要考慮到：

1. 入參有哪些字段？就是這個列表的查詢條件是什么？比如我們需要對外同步「人員信息」，可以通過「人員 ID」進行獲取數據，也可以通過「性別」，只獲取性別為「男」的數據。人員ID、性別就是這個接口的入參。
2. 入參字段的格式是什么？格式是指字段是字符串、日期格式還是字典值等。比如說「人員性別」，可以定義成 0，1。0 代表女性、1 代表男性。也可以是文字「女性、男性」。對于字段格式，產品經理主要是提供建議，具體的還是以研發(fā)為準。
3. 入參字段能夠支持批量查詢？可以理解為查詢條件的字段是不是支持多選。比如說「人員性別」，是可以通過下拉框多選，還是每次只能選擇一個。
4. 入參字段是不是必填？比如說查詢時，必須輸入「人員 ID」，否則就不支持查詢。

②對于「出參」，產品經理需要考慮到：

1. 出參字段有哪些？也就是查詢結果需要有什么？比如出參有：人員 ID、人員姓名、人員性別、創(chuàng)建時間、創(chuàng)建人、更新時間、更新人、是否啟用、是否刪除。
2. 出參字段的格式是什么？這個和「入參」相同，產品經理給出參考建議。然后，在提需求的時候，我們可以通過表格的形式說明「入參、出參」。

③入參示例如：

④出參示例如：

到這里，我們的數據同步接口需求就可以了，更詳細的可以看我提供的真實接口需求示例，領取方式在文末。

3. 服務用接口

這個接口也比較常見，在很多服務對接時，都是直接使用接口對接。產品經理需要確定的接口中與業(yè)務相關的內容。

主要包括入參、出參、接口處理邏輯。

1. 對于入參：需要把接口中的入參字段有哪些說清楚。不僅要把接口處理必須用到的字段說清楚，對于之后接口用到的字段，也可以寫出來。業(yè)務方在第一次接入的時候，把能傳入的字段都傳過來，下次接口新增其他服務的時候，可以直接用，不需要業(yè)務方在調整接口。
2. 對于出參：需要把接口返參中的字段進行說明。原因是返參的字段，才是要最終用到業(yè)務上的，需要產品經理確定有哪些字段，并把字段進行說明。
3. 接口處理邏輯：就是接口通過「入參」計算出「返參」的具體邏輯，包括校驗邏輯等一系列處理邏輯。

說個簡單的例子：通過「身份證號查詢歸屬地服務」

既然是通過「身份證號」查詢，那「入參」里肯定就是「身份證號」

「返參」里有歸屬地，那「歸屬地」就涉及到省、市、區(qū)。

需求可以這樣提：

1）入參：身份證號、必填、字符串、長度18位

2）出參：省份名稱/直轄市、市/區(qū)、縣

3）處理邏輯：

1. 校驗身份證號格式：長度必須是否18位（等其他邏輯在此不細說）
2. 當校驗不通過時，接口報錯，錯誤原因為「身份證號格式錯誤」
3. 當校驗通過后，截取身份證號「前六位」，在「身份證號與行政區(qū)域表」中查詢對應關系。
4. 當查詢到結果時，接口返回：省份名稱/直轄市code、省份名稱/直轄市名稱、市/區(qū)code、市/區(qū)名稱、縣code、縣名稱。
5. 當未查詢到結果時，接口返回為空

涉及到公共服務接口，就涉及到一個「接口性能需求」，這個不能落下，加上性能說明:

4）接口性能要求

示例如：

1. 平均響應時間：最大50ms
2. 接口并發(fā)數：最少200

性能需求的可以看我之前的文章《5000字詳解性能需求》。

在調用接口時，如果是收費接口，或者是需要調用次數做匯報，這個時候就得有「日志記錄」需求。

5）日志記錄

示例如：調用日志記錄需求：數據庫中存儲入參、出參原始json。json 字段本期暫不進行結構化。記錄字段至少包括：渠道 ID、入參 json、出參 json、創(chuàng)建時間、創(chuàng)建人、更新時間、更新人。其余應用字段研發(fā)自行判斷。

json是一個文件格式，json中包含了字段名稱與字段對應的值，大家可以自己學習下。

另外，如果存在一些報錯情況，產品經理想記錄，用于排查問題，可以加個「記錄錯誤數據」的需求。

6）記錄錯誤數據

示例如：

記錄查詢?yōu)榭諗祿寒斀涌诓樵兘涌跒榭諘r，數據庫存入查詢結果為空的數據，用于補充「身份證號行政區(qū)域表」數據。記錄字段包括：身份證號前6位、查詢時間。

以上內容說完后，這就有一個新的問題：公共接口是誰都能接入嗎？這又涉及到：接口鑒權——只能通過接口權限驗證才能調用接口。接口鑒權需要產品提需求嗎？

我的觀點是不需要，讓產品提還真提不出來。

我們現在采用的方式是：

當有業(yè)務方需要接入我們的公共接口時，我在后臺新增一個渠道，通過渠道ID生成驗簽碼，把渠道ID、驗簽碼提供給業(yè)務方。業(yè)務方把渠道ID、驗簽碼通過接口傳入，具體怎么接口驗簽，研發(fā)自己對。到這，接口需求包含以上內容，我認為就OK了。當然，還有其他的幾個內容。

7）請求方式：

有 GET、POST 等，我認為這個讓研發(fā)去定，只要能滿足需求，這就夠了。我唯一一次遇到過的問題是前端來找我，說 GET 請求字符超長，問我怎么處理。因為 GET 請求是在 url 后邊拼接請求參數，最多支持 2048 個字符。

我們分析后發(fā)現在實際場景里，會有入參很多的情況，就會導致請求 url 超長。我也不知道怎么處理，問后端，后端說改成 POST。因為POST在是使用json傳入參數，不涉及到字符超長的情況。

8）接口分頁：

就是分頁返回數據，可以理解為列表中的分頁，每頁返回10條數據。當數據量過大的時候，響應時間不會過長。一般情況下，返回數據很多時，都可以添加分頁。

9）接口請求頻次

就是對接口加個限制，防止服務過載，避免服務崩潰。具體的限制策略可以根據業(yè)務需求來制定，如 1min 內最多調用 10 次，1天1萬次等。當次數超過限制后，再調用時則報錯。

以上，我們就說完了「接口需求怎么提」，接下來說「接口文檔」。

四、接口文檔怎么寫怎么看？

接口文檔是對外提供的詳細的接口接入說明，主要用于描述可提供的接口信息。

所有開發(fā)人員都將根據這份文檔進行后續(xù)的開發(fā)工作。

接口文檔中內容一般有：

• 修訂歷史：接口文檔每次更新的內容描述
• 接口名稱：清晰地表明該接口的功能。
• 接口描述：簡要說明該接口的作用和業(yè)務邏輯，具體能干什么，能實現什么效果。
• 請求地址：詳細給出接口的URL地址，包括測試環(huán)境、線上環(huán)境等不同環(huán)境中的接口地址。
• 請求方法：常見的有GET、POST、PUT、DELETE、PATCH、UPDATE等。
• 請求頭：通常用于傳遞一些公共參數，如token等。
• 請求參數：就是入參，列出各類請求參數，包括參數名、是否必選、參數類型和具體含義。
• 請求示例：提供傳入接口的參數樣例。
• 響應參數：就是出參，區(qū)分成功和失敗等不同情況的響應內容，包括參數名、類型和具體含義。
• 錯誤代碼：列出可能出現的錯誤代碼及其對應的含義。
• 返回示例：提供成功響應的樣例，幫助使用者更好地理解如何使用該接口。
• 備注及責任人：記錄特殊情況和注意事項，指明接口的負責人。

我們可以看到一份接口文檔中包含了整個接口中的全部信息。產品經理不需要自己寫接口文檔，而是應該由研發(fā)編寫。產品經理在此基礎上填寫與業(yè)務相關的說明

包括：

• 接口名稱、接口描述：產品經理可以補充和業(yè)務相關的內容描述。
• 請求參數、響應參數：產品經理可以確定最終字段有哪些，并對字段的用途進行描述。如當字段不傳入時對業(yè)務會有哪些影響等。
• 返回示例：產品經理可以提供真實的、有參考性的標準示例，讓研發(fā)把參數返回放到文檔中。

同樣的，當我們看接口文檔時，產品經理也需要關注的是和業(yè)務相關的內容即可。

看接口文檔的目的是為了我們自己的需求，要確定接口能夠滿足我們的需求。在接口能夠支持的情況下，更好的去設計需求。

所以我們要關注以下內容：

接口描述：了解接口的作用與能力。

入參：

1. 查看需要給出的字段有哪些？
2. 字段能不能給？
3. 能不能按照接口文檔中要求的格式給？

出參：

1. 查看出參有哪些字段，每個字段的具體含義是什么？
2. 通過什么樣的處理邏輯得出的這個字段？
3. 字段是否有多個值？
4. 字段與字段之間關系是什么？比如上下級關系，有多個值
5. 基于接口的出參如何設計自己的產品？

示例如：有個新需求：后臺中的發(fā)起審核時，要在釘釘群里發(fā)送一條群通知。

這個時候就涉及到釘釘能否支持。

那就去「釘釘開放平臺」看下，釘釘提供了一個「機器人發(fā)送群聊消息」的公共接口。

然后去看這個接口描述，首先可以知道釘釘是可以支持的。

接著繼續(xù)看接口中的入參、返參，里邊說明了可以支持的消息模版，就可以結合我的需求選擇一個消息模板，并確定整體需求設計方案。

至于接口怎么接，讓研發(fā)研究去就行了。

五、總結

接口需求在對于沒有技術背景的同學會有一些迷茫，但是理清楚其實也沒什么。你可以去釘釘開放平臺、飛書開放平臺、微信開發(fā)平臺、抖音開放平臺等很多地方去看看這些大廠的接口文檔，看多了也會知道接口是怎么回事。

我們在做產品的時候，不要只關注原型頁面這些表面的東西，同時也需要考慮接口的設計和使用，尤其是做公共服務、接入三方服務的時候，你無法避免的要關注接口。就算沒有接口需求，我們了解接口后，也能更好的與開發(fā)人員進行有效的溝通和協作。