接口文檔設計

接口文檔設計分爲兩部分：

1、對外接口設計規範，

1. 提供完整的接口文檔
2. 提供接口調用的代碼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)		可空

2、內部接口規範，

1. 發佈façade接口jar包，包含了API、request、response
2. 提供接口對應的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

 

基於HTTP標準協議的API接口設計規範構思

• node.js
 
•  python
 
• javascript
 
• golang

 

Prasanta 2016年12月19日發佈

• 贊  |   0收藏  |  3
• 1.7k 次瀏覽

開發規範

1. 版本控制git

2. 開發流程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	刪除

數據

1. 請求支持form-date,json,x-www-form-urlencode

2. 返回格式統一爲json

3. 一個請求對應一個serializer

錯誤

1. 錯誤信息包含在返回內容裏

2. 不一樣的錯誤對應不一樣的錯誤信息代碼

3. http錯誤碼按照標準用法使用

認證

1. jwt

2. token

3. oauth2

權限

1. 以中間件形式做爲權限鑑別插件，根據http請求格式直接判斷權限

2. 用戶登陸成功時，將用戶信息與權限信息緩存保證效率

日誌

1. 日誌以中間件形式提供

2. 根據業務需求氛圍入庫日誌與普通日誌

文檔(待完善)

根據上面的接口格式寫文檔

{
  "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層接口設計的基本原則和規範要求。

整體規範

1. 接口中方法的返回不能爲void，至少也要通知調用者，操做是否成功
2. 接上條，凡是返回操做是否成功的方法，返回類型要設置爲int而不是boolean
3. 方法名只能使用英文，儘可能簡單易懂，駝峯規則，首字母小寫，不得含有數字
4. 方法名最好使用動賓結構。
5. 接口中全部方法都必須寫註釋
6. 接口中全部方法都必須是public的
7. 每一個方法的位置應當是明確的，不要將不屬於某接口的方法放入該接口中，也不要寫功能重複的方法

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();