如何設計一個通用的開放平台上-基本需求與總體流程

前言

此開放平台的設計文檔分為上、中、下三篇來說明，分别對應概念與總體流程、關鍵邏輯、資料存儲三部分。

需求簡析

背景

企業之間需要資料交換，需要使用對方的功能時，如果規模較大，對接方比較多則需要有一個統一的對外的平台來完成這些功能。

此平台負責對外提供各種功能，提供标準化的互動規則和文檔來友善多方資料對接。

功能點

一般而言，開放平台需要支援如下功能

• 支援認證與鑒權，主要需要對接入的第三方進行識别，以及不同接入方可以通路的不同接口權限、資料權限做核驗。
• 支援資料隔離，不同接入方産生或通路的資料是隔離的，互相不影響。
• 友善可靠的接入方式、完善規範的接入文檔
• 一般情況下，開放平台需要建立一個對外的 web網站或者app，來向第三方提供基本的應用管理、文檔展示、公告通知等功能。
  • 如果沒有這樣的平台，則接入放需要聯系開放平台從業人員來對接。

總體流程

通路流程

• thirdServer = 第三方服務，即接入方服務
• openServer = 開放平台的服務
• dataSource = 基礎資料來源，可以是資料庫或者微服務； 建議開放平台不直接操作和讀取業務資料(庫)，而是通過原有的資料、業務服務接口通路。

接入流程

一般而言接入分為用戶端與服務端的接入，用戶端類似于應用商店上架或者微信小程式這種上架，在使用對方用戶端的工具或者遵循對應規則開發成品，然後将成品上次到對方平台。而服務端的接入一般指資料和接口通路的鑒權與校驗等，這裡主要說明服務端的接入。

基本概念

• 主體
  • 主體可以了解為是某一個第三方的公司/學校/平台，在一個主體下可以建立多個應用。
• 應用
  • 在開放平台的賬号下可以建立應用，應用之間的資料和權限是獨立的
  • 一個應用隻能屬于一個主體。
• 開發者
  • 在接入期間，需要一群程式員來開發程式，他們可能通路和編輯應用的相關資訊，調試相關的功能，這些程式員就是開發者。
  • 被主體授權的開發者才有權限做和應用相關的操作。
  • 同一個開發者可以被多個主體授權，可以被授權操作多個應用；
    • 一個開發者可能關聯多個應用，一個應用也可能關聯多個開發者。 根據具體情況來設計授權的粒度。
• appKey
  • 唯一代表應用的辨別符，有的平台也叫appId或者其它名稱
• appSecret
  • 和appKey 一 一對應，用來認證鑒定身份，類似于應用的密碼。
  • appSecret原則上不能洩露，如果洩露需要立即在開放平台重新生成，并使用新的值。
• openId
  • 用于唯一确定某 第三方應用下的 使用者.
  • 對于其它實體，也可以映射為各種各樣的openId； 例如使用者所屬的班級 classOpenId ；
• unionId
  • 用于唯一确定某 第三方主體下的 使用者.
  • 對于其它實體，也可以映射為各種各樣的unionId ；classUnionId等。

接入步驟

接入的步驟大同小異，可以根據具體情況調整、增減步驟。主要目标就是使用開放平台規定的方式來順利通路和操作對應的資料。

1. 申請成開發者
2. 完善開發者對應的主體 資訊，或者說建立一個主體，完善主體資訊，聯系開放平台稽核
3. 開放平台稽核主體資訊
   1. 通過稽核後會配置設定主體對應的賬号
   2. 失敗則表示資料有誤，需要開發者重新修改送出
4. 開發者建立應用 , 并獲得對應的 appKey 和 appSecret . appKey将作為此 應用 的唯一辨別 .
5. 配置 ip 白名單, 白名單外的 ip或域名 将禁止通路
   1. 在企業的服務間對接時，從安全考慮，将會做此限定
6. 申請應用 對應的 資料 / 子產品 / 接口 的通路 權限 , 并等待稽核通過
7. 開發者通路預留的測試接口 , 測試功能
   1. 按照通路規則組織好參數 , 通路給定的測試接口 , 測試通路是否成功 . 若成功則表示成功接入.

API 文檔

一般文檔包含如下内容

• 接入指南
• 錯誤碼定義
• api文檔
  • 協定、域名、URL路徑、參數說明、傳回值說明
  • 不同語言的SDK資訊
  • 接口頻率限制說明