1. 契約精神
什麼是契約?
百度百科:https://baike.baidu.com/item/%E5%A5%91%E7%BA%A6/2874688
維基百科:https://zh.wikipedia.org/zh/%E5%A5%91%E7%BA%A6
相關概念:
- Design by Contract (契約式設計)
- Contract-First (契約先行)
2. 版本號
3. 一方庫版本設計
一方庫:本工程中的各模塊的相互依賴
推薦方案:
- 版本統一
- 頂層 pom 定義版本
- 子隨父:child module 沿用 parent module 版本
版本管理:
Maven 項目,建議採用 Maven Version Plugin 統一管理升級。
發佈:
無需發佈,項目內引用。
4. 二方庫版本設計
二方庫:公司內部的依賴庫,一般指公司內部的其他項目發佈的 jar 包
推薦方案:
- 基於版本號,多版本發佈
- 高版本向下兼容
發佈:
Maven 私服發佈,多版本代碼發佈。
4.1. 理解“高版本向下兼容”
- 對“修改、刪除”關閉,對“新增”開放
舊版本:
{
"name":"Bob",
"age":20
}
向下兼容新版本 - 新增
{
"name":"Alice",
"age":18,
"address":"Beijing"
}
非向下兼容新版本 - 修改
{
"newName":"Alice",
"age":18
}
非向下兼容新版本 - 刪除
{
"age":18
}
極端情況
如果整個契約變動很大,並不滿足 “向下兼容”,建議新建 API,path
採用 v1
, v2
等字樣區分。
5. 三方庫版本設計
三方庫:公司之外的開源庫, 比如 apache、ibm、google 等發佈的依賴
推薦方案:
同二方庫版本設計,需要更加註重版本,嚴格落實 “基於版本研發”。
發佈:
Maven 私服 / 中央倉庫 / Jar 包 多版本代碼發佈。
6. Web API 版本設計
背景:調用方多樣性(H5 無版本、移動終端有版本),但通信協議一致。
推薦方案:
參考三方庫版本設計
發佈:
自建服務器發佈,“僞多版本發佈” (發行版爲最新版本,向下兼容多版本)