摘要：刪除后指定產(chǎn)品不存在獲取商品列表未分頁(yè)獲取全部商品成功系列的表殼材料為輕巧的銀色及深空灰色陽(yáng)極氧化鋁金屬，強(qiáng)化玻璃材質(zhì)為顯示屏提供保護(hù)。外觀設(shè)計(jì)不再棱角分明，表層玻璃邊有一個(gè)弧度向下延伸，與陽(yáng)極氧化鋁金屬機(jī)身邊框銜接。

API 就是開(kāi)發(fā)者使用的界面。我的目標(biāo)不僅是能用，而且好用，跨平臺(tái)（PC, Android, IOS, etc...）使用。本文將詳細(xì)介紹 API 的設(shè)計(jì)及異常處理，并將異常信息進(jìn)行封裝友好地反饋給前端.

上篇文章 前后端完全分離初探 只是講了些寬泛的概念，接下來(lái)的文章將直接上干貨，干貨的源碼會(huì)掛在 GitHub 上。

前后端完全分離后，前端和后端如何交互？答：通過(guò)雙方協(xié)商好的API。

接下來(lái)我分享我自己設(shè)計(jì)的 API 接口，歡迎各位朋友指教。

將涉及的實(shí)體抽象成資源，即按 id 訪問(wèn)資源，在 url 上做文章，以后再也不用為 url 起名字而苦惱了；

使用 HTTP 動(dòng)詞對(duì)資源進(jìn)行 CRUD（增刪改查）：

get -> 查, post -> 增, put -> 改, delete -> 刪

URL 命名規(guī)則，對(duì)于資源無(wú)法使用一個(gè)單數(shù)名詞表示的情況，我使用中橫線 - 連接

資源采用名詞命名，e.g：產(chǎn)品 -> product

新增資源，e.g：新增產(chǎn)品 url -> /product, verb -> POST

修改資源，e.g：修改產(chǎn)品 url -> /products/{id}, verb -> PUT

資源詳情，e.g：指定產(chǎn)品詳情 url -> /products/{id}, verb -> GET

刪除資源，e.g：刪除產(chǎn)品 url -> /products/{id}, verb -> DELETE

資源列表，e.g：產(chǎn)品列表 url -> /products, verb -> GET

資源關(guān)聯(lián)關(guān)系，e.g：收藏產(chǎn)品 url -> /products/{id}/star, verb -> PUT

資源關(guān)聯(lián)關(guān)系，e.g：刪除收藏產(chǎn)品 url -> /products/{id}/star, verb -> DELETE

目前我 API 的設(shè)計(jì)只涉及這兩點(diǎn)，至于第三點(diǎn) HATEOAS(Hypermedia As The Engine Of Application State) 那就由讀者自己去選擇了，

本文中只涉及了設(shè)計(jì)的理念，具體的實(shí)現(xiàn)請(qǐng)下載源碼 rest-api，項(xiàng)目?jī)?nèi)寫(xiě)了比較詳細(xì)的注釋。

實(shí)戰(zhàn)將從業(yè)務(wù)場(chǎng)景出發(fā)，詳細(xì)介紹如何使用 HTTP verb 對(duì)資源進(jìn)行操作（狀態(tài)轉(zhuǎn)移），使用 JSON 返回結(jié)果（資源表述），并定義 JSON 的基礎(chǔ)結(jié)構(gòu)。

requestParams：

{
}

responseBody：

{
  "meta": {
  },
  "data": {
  }
}

meta 中封裝操作成功或失敗的消息，data 中封裝返回的具體數(shù)據(jù)。

當(dāng)新建商品或更新產(chǎn)品時(shí)，相關(guān)屬性封裝在 JSON 中，通過(guò) POST 或 PUT 發(fā)送。

{
  "name": "Apple Watch SPORT",
  "description": "Sport 系列的表殼材料為輕巧的銀色及深空灰色陽(yáng)極氧化鋁金屬，強(qiáng)化 Ion-X 玻璃材質(zhì)為顯示屏提供保護(hù)。搭配高性能 Fluoroelastomer 表帶，共有 5 款繽紛色彩。"
}

當(dāng)用戶對(duì)商品進(jìn)行操作后，將得到響應(yīng)結(jié)果。GET, POST, PUT 操作成功，返回如下結(jié)果

{
  "meta": {
    "code": 201,
    "message": "創(chuàng)建成功"
  },
  "data": {
    "id": "5308e9c2-a4ce-4dca-9373-cc1ffe63d5f9",
    "name": "Apple Watch SPORT",
    "description": "Sport 系列的表殼材料為輕巧的銀色及深空灰色陽(yáng)極氧化鋁金屬，強(qiáng)化 Ion-X 玻璃材質(zhì)為顯示屏提供保護(hù)。搭配高性能 Fluoroelastomer 表帶，共有 5 款繽紛色彩。"
  }
}

DELETE 操作成功，返回如下結(jié)果

{
  "meta": {
    "code": 204,
    "message": "刪除成功"
  }
}

電商網(wǎng)站的管理員對(duì)商品進(jìn)行新增、編輯、刪除、瀏覽的操作，暫時(shí)不考慮認(rèn)證授權(quán)，只關(guān)注對(duì)商品的操作。

為了以后便于做分布式，所有資源 id（表主鍵）均采用 uuid。

新增商品

url: /api/product

method: POST

requestParams:

{
  "name": "Apple Watch SPORT",
  "description": "Sport 系列的表殼材料為輕巧的銀色及深空灰色陽(yáng)極氧化鋁金屬，強(qiáng)化 Ion-X 玻璃材質(zhì)為顯示屏提供保護(hù)。搭配高性能 Fluoroelastomer 表帶，共有 5 款繽紛色彩。"
}

responseBody

{
  "meta": {
    "code": 201,
    "message": "創(chuàng)建成功"
  },
  "data": {
    "id": "5308e9c2-a4ce-4dca-9373-cc1ffe63d5f9",
    "name": "Apple Watch SPORT",
    "description": "Sport 系列的表殼材料為輕巧的銀色及深空灰色陽(yáng)極氧化鋁金屬，強(qiáng)化 Ion-X 玻璃材質(zhì)為顯示屏提供保護(hù)。搭配高性能 Fluoroelastomer 表帶，共有 5 款繽紛色彩。"
  }
}

編輯商品

url: /api/products/{id}

method: PUT

requestParams:

{
  "name": "iPhone 6",
  "description": "此次蘋(píng)果發(fā)布會(huì)發(fā)布了iPhone 6與iPhone 6 Plus，搭載iOS 8，尺寸分別是4.7和5.5英寸。外觀設(shè)計(jì)不再棱角分明，表層玻璃邊有一個(gè)弧度向下延伸，與陽(yáng)極氧化鋁金屬機(jī)身邊框銜接。機(jī)身背部采用三段式設(shè)計(jì)。機(jī)身更薄，續(xù)航能力更強(qiáng)。"
}

responseBody

{
  "meta": {
    "code": 200,
    "message": "修改成功"
  },
  "data": {
    "id": "5308e9c2-a4ce-4dca-9373-cc1ffe63d5f9",
    "name": "iPhone 6",
    "description": "此次蘋(píng)果發(fā)布會(huì)發(fā)布了iPhone 6與iPhone 6 Plus，搭載iOS 8，尺寸分別是4.7和5.5英寸。外觀設(shè)計(jì)不再棱角分明，表層玻璃邊有一個(gè)弧度向下延伸，與陽(yáng)極氧化鋁金屬機(jī)身邊框銜接。機(jī)身背部采用三段式設(shè)計(jì)。機(jī)身更薄，續(xù)航能力更強(qiáng)。"
  }
}

刪除商品

url: /api/products/{id}

method: DELETE

responseBody

{
  "meta": {
    "code": 204,
    "message": "刪除成功"
  },
  "data": {}
}

獲取商品詳情

url: /api/products/{id}

method: GET

responseBody:

//刪除前

{
  "meta": {
    "code": 200,
    "message": "查詢成功"
  },
  "data": {
    "id": "5308e9c2-a4ce-4dca-9373-cc1ffe63d5f9",
    "name": "Apple Watch SPORT",
    "description": "Sport 系列的表殼材料為輕巧的銀色及深空灰色陽(yáng)極氧化鋁金屬，強(qiáng)化 Ion-X 玻璃材質(zhì)為顯示屏提供保護(hù)。搭配高性能 Fluoroelastomer 表帶，共有 5 款繽紛色彩。"
  }
}

//刪除后
{
  "meta": {
    "code": 404,
    "message": "指定產(chǎn)品不存在"
  }
}

獲取商品列表(未分頁(yè))

url: /api/products

method: GET

responseBody

{
  "meta": {
    "code": 200,
    "message": "獲取全部商品成功"
  },
  "data": [
    {
      "id": "5308e9c2-a4ce-4dca-9373-cc1ffe63d5f9",
      "name": "Apple Watch SPORT",
      "description": "Sport 系列的表殼材料為輕巧的銀色及深空灰色陽(yáng)極氧化鋁金屬，強(qiáng)化 Ion-X 玻璃材質(zhì)為顯示屏提供保護(hù)。搭配高性能 Fluoroelastomer 表帶，共有 5 款繽紛色彩。"
    },
    {
      "id": "9db1992a-c342-4ff0-a2a4-aeb3dbfd93f6",
      "name": "Apple Watch SPORT",
      "description": "Sport 系列的表殼材料為輕巧的銀色及深空灰色陽(yáng)極氧化鋁金屬，強(qiáng)化 Ion-X 玻璃材質(zhì)為顯示屏提供保護(hù)。搭配高性能 Fluoroelastomer 表帶，共有 5 款繽紛色彩。"
    },
    {
      "id": "4481619b-45c5-4729-9539-f93bb01f10d8",
      "name": "Apple Watch SPORT",
      "description": "Sport 系列的表殼材料為輕巧的銀色及深空灰色陽(yáng)極氧化鋁金屬，強(qiáng)化 Ion-X 玻璃材質(zhì)為顯示屏提供保護(hù)。搭配高性能 Fluoroelastomer 表帶，共有 5 款繽紛色彩。"
    }
  ]
}

業(yè)務(wù)場(chǎng)景一中只涉及了單個(gè)資源的操作，但實(shí)際場(chǎng)景中還有些關(guān)聯(lián)操作；如用戶去電商網(wǎng)站瀏覽商品，并收藏了一些商品，之后又取消收藏了部分商品。

暫時(shí)不考慮用戶認(rèn)證授權(quán)，以后加了token后，用戶信息可以從中獲取。

收藏商品

url: /api/products/{id}/star

method: PUT

responseBody

{
  "meta": {
    "code": 200,
    "message": "收藏商品[5308e9c2-a4ce-4dca-9373-cc1ffe63d5f9]成功"
  },
  "data": [
    {
      "id": "5308e9c2-a4ce-4dca-9373-cc1ffe63d5f9",
      "name": "iPhone 6",
      "description": "此次蘋(píng)果發(fā)布會(huì)發(fā)布了iPhone 6與iPhone 6 Plus，搭載iOS 8，尺寸分別是4.7和5.5英寸。外觀設(shè)計(jì)不再棱角分明，表層玻璃邊有一個(gè)弧度向下延伸，與陽(yáng)極氧化鋁金屬機(jī)身邊框銜接。機(jī)身背部采用三段式設(shè)計(jì)。機(jī)身更薄，續(xù)航能力更強(qiáng)。"
    }
  ]
}

取消收藏商品

url: /api/products/{id}/star

method: DELETE

responseBody

{
  "meta": {
    "code": 200,
    "message": "刪除收藏商品[5308e9c2-a4ce-4dca-9373-cc1ffe63d5f9]成功"
  },
  "data": []
}

所有自定義異常繼承 RuntimeException，在業(yè)務(wù)層拋出，統(tǒng)一在 Controller 層進(jìn)行處理。

異常分為全局異常和局部異常，例如 http method unsupported (405)，unauthorized (401)，accessDenied (403)，not found (404) 等屬于全局異常。針對(duì)對(duì)獨(dú)立業(yè)務(wù)的一些異常屬于局部異常，例如產(chǎn)品編輯出錯(cuò)。

異常在 Controller 中進(jìn)行處理，并封裝成 json 返回給前端，封裝后的數(shù)據(jù)如下，相關(guān)實(shí)現(xiàn)見(jiàn)源碼

{
  "meta": {
    "code": 404,
    "message": "指定產(chǎn)品不存在"
  }
}

{
  "meta": {
    "code": 405,
    "message": "Request method "POST" not supported"
  }
}

前后端完全分離初探

前后端完全分離之API設(shè)計(jì)

前后端完全分離之安全認(rèn)證與授權(quán)-上

前后端完全分離之安全認(rèn)證與授權(quán)-下

前后端完全分離之前端模塊化開(kāi)發(fā)

前后端完全分離之前端路由系統(tǒng)

前后端完全分離之后端面向服務(wù)的模塊化開(kāi)發(fā)

原文出自 前后端完全分離之API設(shè)計(jì)，歡迎轉(zhuǎn)載，轉(zhuǎn)載請(qǐng)注明出處。