接口文檔設計分為兩部分：
一、對外接口設計規范，
- 提供完整的接口文檔
- 提供接口調用的代碼Demo
示例如下：
請求的基本參數
| 參數 |
參數名稱 |
類型 （長度范圍） |
參數說明 |
是否可為空 |
樣例 |
| 基本參數 |
|||||
|
|
接口名稱 |
String(64) |
|
不可空 |
send_goods_confirm_by_platform |
|
|
合作者身份ID |
String(16) |
|
可空 |
2088001159940003 |
|
|
參數編碼字符集 |
String(10) |
|
不可空 |
GBK |
|
|
簽名 |
String(64) |
|
不可空 |
e8qdwl9caset5zugii2r7q0k8ikopxor |
|
|
簽名方式 |
String(10) |
|
不可空 |
MD5 |
|
|
頁面跳轉同步返回頁面路徑 |
String(1000) |
|
可空 |
|
|
|
備注 |
String(1000) |
|
可空 |
|
同步返回時，需要的基本參數
| 參數 |
參數名稱 |
類型 （長度范圍） |
參數說明 |
是否可為空 |
樣例 |
|
| 基本參數 |
|
|||||
|
|
成功標識 |
String(1) |
|
不可空 |
T |
|
|
|
合作者身份ID |
String(16) |
|
可空 |
2088001159940003 |
|
|
|
參數編碼字符集 |
String(10) |
|
不可空 |
GBK |
|
|
|
簽名 |
String(64) |
|
不可空 |
e8qdwl9caset5zugii2r7q0k8ikopxor |
|
|
|
簽名方式 |
String(10) |
|
不可空 |
MD5 |
|
|
|
返回錯誤碼 |
String(30) |
|
可空 |
PARTNER_ID_NOT_EXIST |
|
|
|
返回錯誤原因 |
String(200) |
|
可空 |
合作方Id不存在 |
|
|
|
備注 |
String(1000) |
|
可空 |
|
|
二、內部接口規范，
- 發布façade接口jar包，包含了API、request、response
- 提供接口對應的response返回碼說明，及接口所需屬性枚舉常量定義
示例如下：
| 接口名稱: |
XXXXXXXXXXXXXXX |
|||
| 請求參數 |
屬性 |
描述 |
是否必填 |
字段類型 |
|
|
|
|
Y |
String(32) |
|
|
|
Y |
String(32) |
|
|
|
|
Y |
String(32) |
|
|
|
|
Y |
String(32) |
|
|
|
|
Y |
String(32) |
|
|
|
|
Y |
Money |
|
|
|
|
N |
String(32) |
|
|
|
|
N |
String(32) |
|
|
|
|
N |
String(2) |
|
|
|
|
N |
String(32) |
|
|
|
|
N |
String(32) |
|
|
|
|
N |
String(64) |
|
|
|
|
N |
String(256) |
|
|
|
|
N |
String(12) |
|
|
|
|
N |
String(64) |
|
|
|
|
N |
String(64) |
|
|
|
|
N |
String(1) |
|
|
|
|
|
String(1) |
|
|
|
|
N |
String(256) |
|
|
|
|
N |
String(2000) |
|
|
|
|
|
|
|
| 返回參數 |
屬性 |
描述 |
是否必填 |
字段類型 |
|
|
|
返回碼 |
Y |
String |
|
|
返回信息 |
N |
String |
|
|
|
擴展信息 |
N |
String |
|
python開發規范
-
版本控制git
-
開發流程git flow
接口
| 請求方式 | url | 動作 | 中文說明 |
|---|---|---|---|
| GET | /resources/ |
list | 列表 |
| POST | /resources/ |
create | 創建 |
| GET | /resources/:id |
retrieve | 詳細 |
| PUT | /resources/:id |
update | 更新 |
| PATCH | /resources/:id |
partial_update | 部分更新 |
| DELETE | /resources/:id |
destroy | 刪除 |
數據
-
請求支持form-date,json,x-www-form-urlencode
-
返回格式統一為json
-
一個請求對應一個serializer
錯誤
-
錯誤信息包含在返回內容里
-
不同的錯誤對應不同的錯誤信息代碼
-
http錯誤碼按照標准用法使用
認證
-
jwt
-
token
-
oauth2
權限
-
以中間件形式作為權限鑒別插件，根據http請求格式直接判斷權限
-
用戶登錄成功時，將用戶信息與權限信息緩存保證效率
日志
-
日志以中間件形式提供
-
根據業務需求氛圍入庫日志與普通日志
文檔(待完善)
根據上面的接口格式寫文檔
{
"resources": { "list": { "params": {}, "response": {} }, "create": { "request": {}, "response": {} }, "retrieve": { "response": {} }, "update": { "request": {}, "response": {} }, "partial_update": { "request": {}, "response": {} }, "destroy": {} } }測試
業務所需接口測試覆蓋率100%
部署
-
docker
-
docker-compose
-
docker-machine
-
docker-swarm
服務器資源監控
接口設計規范
浙江大學電子服務研究中心
首先，在閱讀本文檔前請務必確認您已經對面向對象的基本概念有所了解。
根據目前實驗室所使用的系統架構，制定本文檔，主要闡述一些service層和DAO層接口設計的基本原則和規范要求。
總體規范
- 接口中方法的返回不能為void，至少也要通知調用者，操作是否成功
- 接上條，凡是返回操作是否成功的方法，返回類型要設置為int而不是boolean
- 方法名只能使用英文，盡量簡單易懂，駝峰規則，首字母小寫，不得含有數字
- 方法名最好使用動賓結構。
- 接口中所有方法都必須寫注釋
- 接口中所有方法都必須是public的
- 每個方法的位置應當是明確的，不要將不屬於某接口的方法放入該接口中，也不要寫功能重復的方法
service層接口規范
service層是每個模塊邏輯處理的位置，一個service對應一個action和若干個DAO，service中每一個方法都來自頁面功能的需求，所有service層的接口都必須繼承自BaseService，所有方法都應當以BaseForm（或其子類）的對象作為參數，根據需要可以添加PageInfo的對象，其他參數一般不要添加。
以下方法是在BaseService中已經聲明的：
| /** * 添加一條新數據 * @return 消息編碼 */ public int addData(BaseForm thisForm); |
| /** * 編輯一條數據 * @return 消息編碼 */ public int editData(BaseForm thisForm); |
| /** * 刪除一條或多條數據 * @return 消息編碼 */ public int removeData(BaseForm thisForm); |
| /** * 返回一條數據，並用於頁面展示 * @return BaseForm */ public BaseForm showData(BaseForm baseForm); |
實例：
| /** * 分頁顯示照片 */ public List<DataPhoto> getDataPhotoByConditionsInPage(PageInfo pageInfo, DataPhotoForm dataPhotoForm);
/** * 獲取某個相冊下的所有照片 */ public List<DataPhoto> getAllDataPhoto(DataPhotoForm dataPhotoForm);
/** * 刪除某個相冊下的所有照片 */ public int removeDataPhotoByGroup (DataPhotoForm dataPhotoForm);
/** * 獲取某相冊相片及回復 */ public Map<Integer, List<DataPhotoReply>> getDataPhotoAndReplyByGroup (DataPhotoForm dataPhotoForm); |
DAO層接口規范
DAO層的作用是操作數據庫，每一個接口對應數據庫中的一個表，可以被多個service調用。DAO層接口中所有的方法都與數據庫的“增刪改查”相聯系。所有的DAO層接口都必須繼承自BaseDAO
以下是BaseDAO中已經聲明的方法：
| /** * 將一個Model添加進數據庫 */ public int insertModel(BaseModel model); |
| /** * 更新Model */ public int updateModel(BaseModel model); |
| /** * 刪除一條或多條數據 */ public int deleteModels(int[] ids); |
實例：
| /** * 分頁顯示照片 */ public List<DataPhoto> getDataPhotoByConditionsInPage(PageInfo pageInfo, DataPhoto dataPhoto); |
| /** * 獲取某個相冊下的所有照片 */ public List<DataPhoto> getAllDataPhotoByGroup(DataPhoto dataPhoto); |
| /** * 刪除某個相冊下的所有照片 */ public int deleteDataPhotoByGroup(DataPhoto dataPhoto); |
| /** * 獲取相片及其回復 */ public Map<Integer, List<DataPhotoReply>> getDataPhotoAndReplyByGroup (DataPhoto dataPhoto); |
| /** * 插入一條數據后，立刻返回該條數據id */ public int getPhotoIdRightNow(); |