http api設計規範

規範

• api 接口必須加版本号，初始版本 【v1】,多個版本api版本可能同時線上
• 不使用rest的PUT和DELETE，因為很多浏覽器不支援，很多架構也不支援

• POST在需要傳輸大量資料的時候使用，其餘使用GET就可以了；

  這裡GET和POST沒有明确的含義，GET也可以新增

• 所有路徑path全部小寫，以下劃線分隔，所有參數，包括POST裡面的body，以及header使用駝峰。例如： http://127.0.0.1/v1/wechat/mch_info/list_mch_info?page=2&perPage=100
• 我們傳回一般統一使用json格式傳回
• 使用Token令牌來做使用者身份的校驗與權限分級
• 暴露外部請求一定使用SSL

Path具體的實作

path = /{版本}/{具體的業務功能}/{表名}/{行為}

• {版本}：開始時全部為V1，
• {具體的業務功能}：

pp的setting，資料庫命名為 app_setting，那麼，具體的業務功能=setting

架構組的wechat，資料庫命名為arch_wechat，那麼，具體的業務功能=wechat

• {表名}:就是資料的表名
• {行為}：一般就是方法名
• ?limit=10：指定傳回記錄的數量
• ?offset=10：指定傳回記錄的開始位置。
• ?page=2&perPage=100：指定第幾頁，以及每頁的記錄數。
• ?sortBy=name&order=asc：指定傳回結果按照哪個屬性排序，以及排序順序。

http協定	方法	行為path	說明
POST	add(POJO)	/add	添加一個對象，接收json資訊
GET	insert(param …)	/insert?param1=?&param1=?	插入一個對象，多個參數的方式，作用和add一樣，隻是傳參數方式不同
	deleteById(long)	/delete_by_id?id=?	資料庫不删除，但是業務上有删除的語意
	update(POJO)	/update	更新一個對象，接收json資訊
	updateById(long)	/update_by_id?id=?	{表名}中已經具體指明了實體，所有這裡可以不用update_pojo_by_id
	getById(long)	/get_by_id?id=?	{表名}中已經具體指明了實體，所有這裡可以不用get_pojo_by_id
	listByParam(Object)	/list_by_param?param=?&page=2&perPage=100	list查詢多個，預設全部,可以帶上limit，offset，page，sortBy，order等參數

*參考資料庫設計

https://blog.csdn.net/zengqiang1/article/details/79338660

【推薦】表的命名最好是加上“業務名稱_表的作用”。

正例:app_user / trade_config

【推薦】庫名與應用名稱盡量一緻，{業務項目}_{功能},業務項目和功能怎麼寫參*

Request

• 請求必須帶上公共參數，沒有這些公共參數，可以不填寫值，但是必須帶上
• 公共參數裡面的token是必須帶上的，因為我們會基于這個token，做使用者登入驗證

• 公共參數寫到http header裡面，key:_head,value json格式，後端直接轉為對象

  {

“token”: “123”, //sso token，必須帶上，通過這個參數驗證使用者是否登入，已經确認是哪個使用者

“timestamp”: “1234”, //發送請求時間戳

“userId”: “123”, //sso 使用者id

“channel”: “123”, //管道來源,從哪個管道上面下載下傳的包（iOS就隻有一個App Store，Android有小米，應用寶，豌豆莢等國内的管道),這個也必須有一個對照表

“channelCode”: “123”, //管道辨別，self：自有管道，其他外部管道也可以注冊企鵝使用者，比如問診的業務管道映射為：’sq:手機qq管道,qb:qq浏覽器管道’,表明來自于哪個管道，這個也必須有一個對照表

“pushId”: “134”, //假如産品或者營運需要我們給部分使用者推送消息，可以根據其他公共參數把使用者分群，然後拿到pushid給他push消息。

“initStamp”: “123”, //首次安裝包時間戳

“device”: “123”, //裝置名

“deviceId”: “123”, //裝置唯一碼

“systemVersion”: “123”, //APP專用，系統平台（Android，iOS）的版本号

“comeFrom”: “123”, //項目來源，例如APP要做一個母親節的活動,或者520活動，from=母親節活動,from=520活動，表明我做活動的一個轉化率,這個也必須有一個對照表

“platformId”: “123”, //platformId 對照表@see 例如 1:web，2:iOS，3:Android，4:miniApp

“appName”: “123”, //appName 應用名稱，對照表，, 例如app:app應用，cai:競猜小程式

“appVersion”: “123”, //我們自己的app版本号

“extra”: “123” //額外參數，後續做ABTesting等場景的時候會用到，也可以做一些額外的業務需求字段，視各業務而定

}

壓縮格式

{"token":"123","timestamp":"1234","userId":"123","channel":"123","channelCode":"123","pushId":"134","initStamp":"123","device":"123","deviceId":"123","systemVersion":"123","come_from":"123","platformId":"123","appName":"123","appVersion":"123","extra":"123"}           

資料庫字段對應

CREATE TABLE `user_extra_relation` (
  `id` bigint(20) unsigned NOT NULL AUTO_INCREMENT COMMENT '自增主鍵',
  `user_id` bigint(20) DEFAULT NULL COMMENT 'user表中的id',
  `come_from` varchar(64)  NOT NULL DEFAULT '' COMMENT '項目來源，例如APP要做一個母親節的活動,或者520活動，from=母親節活動,from=520活動，表明我做活動的一個轉化率,這個也必須有一個對照表,
  `device_id` varchar(64)  NOT NULL DEFAULT '' COMMENT '第一次産生使用者注冊的裝置id',
  `channel_code` varchar(32)  NOT NULL DEFAULT 'self' COMMENT '管道辨別，self：自有管道，其他外部管道也可以注冊使用者,非必傳，預設 self',
  `platform_id` tinyint(3) unsigned NOT NULL DEFAULT '0' COMMENT '平台ID，platformId 對照表,例如 1:web，2:iOS，3:Android，4:miniApp',
  `app_name` varchar(32)  NOT NULL DEFAULT '' COMMENT 'appName 應用名稱,
  `token` varchar(64)  NOT NULL DEFAULT '' COMMENT '使用者token',
  `timestamp` varchar(64)  NOT NULL DEFAULT '' COMMENT '發送請求時間戳',
  `channel` varchar(32)  NOT NULL DEFAULT '' COMMENT '管道來源,從哪個管道上面下載下傳的包（iOS就隻有一個App Store，Android有小米，應用寶，豌豆莢等國内的管道),這個也必須有一個對照表https://lexiangla.com/docs/27c78dba373e11e8892b5254004fae61',
  `push_id` varchar(64)  NOT NULL DEFAULT '' COMMENT '假如産品或者營運需要我們給部分使用者推送消息，可以根據其他公共參數把使用者分群，然後拿到pushid給他push消息。',
  `init_stamp` varchar(64)  NOT NULL DEFAULT '' COMMENT '首次安裝包時間戳',
  `device` varchar(64)  NOT NULL DEFAULT '' COMMENT '裝置名',
  `system_version` varchar(32)  NOT NULL DEFAULT '' COMMENT '系統版本',
  `app_version` varchar(32)  NOT NULL DEFAULT '' COMMENT '我們自己APP的版本号',
  `extra` varchar(128)  NOT NULL DEFAULT '' COMMENT '額外參數，後續做ABTesting等場景的時候會用到，也可以做一些額外的業務需求字段，視各業務而定',
  `is_delete` tinyint(3) unsigned NOT NULL DEFAULT '0' COMMENT '是否删除 0-未删除、1-删除',
  `gmt_create` datetime NOT NULL DEFAULT CURRENT_TIMESTAMP COMMENT '建立時間',
  `gmt_modified` datetime NOT NULL DEFAULT CURRENT_TIMESTAMP ON UPDATE CURRENT_TIMESTAMP COMMENT '修改時間',
  PRIMARY KEY (`id`),
  UNIQUE KEY `uk_user_id` (`user_id`)
) ENGINE=InnoDB COMMENT='使用者附加資訊表，表明使用者來源等，第一次産生userId時插入資訊到此表'           

Response

• 采用JSON，不要使用XML
• 預設情況下要支援gzip
• 格式統一：

{
      "code" : 0,
      "msg" : "Something bad happened",
      "data" : {

      }
    }           

• code: 0為成功，非0為失敗

• msg: 當code為非0時，擷取錯誤資訊。當code-

  為0時，msg一般為”success”。

• data: 當code為0時，擷取結果，全部以json方式表示。當code為非0時，data沒有資料

錯誤處理

不要直接将異常抛給用戶端處理，一般需要一個統一的異常處理類，并且以統一格式将異常資訊傳回前端，統一格式參照目錄“Response”

辨別映射

• 保留錯誤碼，可以自定義錯誤碼,錯誤碼全部參考

錯誤碼	描述
請求成功

• 性别關系映射

id	性
未設定
1	男
2	女

• platformId 描述

	web
	iOS
3	Android
4	miniApp
5	mp微信公衆号

• appName 描述

appName	應用名稱
app	XXXapp
jincai	競猜小程式

• channelCode 管道辨別描述，預設為self(自有管道)，來源于哪次活動，添加活動，需要在這裡添加相應辨別

channelCode	管道辨別
self	自有管道

• userCateGorg 使用者類别，預設為客戶。以後可能我們還會有銷售，或者其他

userCateGorg	使用者類别
co	客戶