# 程序員開發指南 ## 服務端開發指南 ### API接口規范 ### 消息規范 系統使用統一的消息返回機制，所有的API返回JSON數據，格式一致。如果所請求的API需要授權，而用戶沒有獲得授權，直接拋出HTTP:401錯誤，客戶端檢測到401狀態直接跳轉到登錄頁面進行授權。 ```json { errno: 1000, errmsg: '錯誤消息', data: {} } ``` | 字段 | 含義 | 說明 | | ------ | ------ | ------ | | errno | 錯誤代碼 | 通常返回 0，表示請求正常返回接口數據；如果請求出錯，返回具體的錯誤代碼，并在data字段返回錯誤的附加信息 | | errmsg | 錯誤消息 | 返回數據的解釋性描述文字 | | data | 返回的業務數據 | 一般返回對象格式 | > 錯誤代碼 | 錯誤代碼 | 含義 | 說明 | | ------ | ------ | ------ | | 0 | 正常返回 | 請求的接口正確的返回業務數據，非0表示請求出錯 | | 1000 | 一般錯誤 | 通用的錯誤代碼 | | 1001 | 請求接口參數校驗錯誤 | 參數格式、類型不正確等 | ## 客戶端開發指南 ### 發送請求 >所有的請求被封裝成Promise 以下請求用戶傳遞用戶名和密碼，返回通信的TOKEN ``` let userInfo = { username : 'admin', password : '123456' } ``` 發送請求到`/api/system/token/create`接口， 由于request集中處理請求，自動加上了請求的前綴`api`，所以客戶端編寫API的時候不需要再加上api前綴。 ## 前后端通信機制 ```javascript import request from '@/common/request' export default { create(userInfo) { return new Promise((resolve, reject) => { request.post('/system/token/create', userInfo).then(response => { resolve(response) }) }) } } ``` 前后端的通信使用TOKEN機制，TOKEN放在請求的header中。 用戶通過讀取vuex保存的token，發送給服務端 ``` const token = store.getters['token']; if (token) { //給所有請求添加自定義header request.headers["Authorization"] = token; } ``` 服務端首先通過framework中間件校驗客戶端發送的TOKEN是否合法，如果篡改了TOKEN或者TOKEN過期，則刪除傳遞的用戶信息，后續進一步判斷請求的API是否需要檢測用戶身份。 ``` //分離請求用戶的身份信息，業務上要求某些API只能用戶自身才能訪問，所以需要提取登錄用戶的信息 let userInfo = {}; //發起請求的用戶基本信息 //讀取請求用戶的身份信息 const authorization = ctx.request.header.authorization;//解碼客戶端請求攜帶的用戶信息 try { //將用戶信息寫入到context，這樣每一個控制器都可以讀到 userInfo = jsonwebtoken.verify(authorization, ctx.config('jwt')['secret']); delete userInfo.iat; //刪除附上去的字段信息 delete userInfo.exp; //校驗客戶端傳過來的TOKEN是否被改過 md5_old = userInfo.md5; let tmp = think.extend({}, userInfo); delete tmp.md5; let md5_new = think.service('utils').getVerifiedUserInfo(tmp) if (md5_new === md5_old) { ctx.userInfo = userInfo; } else { ctx.userInfo = {}; userInfo = {}; } } catch (err) { ctx.userInfo = {}; userInfo = {}; } ... // 檢測登錄的用戶信息 // 必須登陸 if (think.isEmpty(userInfo) || think.isEmpty(userInfo.username)) { return ctx.throw(401, `請登錄以后訪問。`); } ```