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

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

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

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

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

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

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

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

URL 命名規(guī)則，對于資源無法使用一個單數(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è)計只涉及這兩點，至于第三點 HATEOAS(Hypermedia As The Engine Of Application State) 那就由讀者自己去選擇了，

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

實戰(zhàn)將從業(yè)務(wù)場景出發(fā)，詳細(xì)介紹如何使用 HTTP verb 對資源進(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)品時，相關(guān)屬性封裝在 JSON 中，通過 POST 或 PUT 發(fā)送。

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

當(dāng)用戶對商品進(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 系列的表殼材料為輕巧的銀色及深空灰色陽極氧化鋁金屬，強化 Ion-X 玻璃材質(zhì)為顯示屏提供保護(hù)。搭配高性能 Fluoroelastomer 表帶，共有 5 款繽紛色彩。"
  }
}

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

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

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

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

新增商品

url: /api/product

method: POST

requestParams:

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

編輯商品

url: /api/products/{id}

method: PUT

requestParams:

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

responseBody

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

刪除商品

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 系列的表殼材料為輕巧的銀色及深空灰色陽極氧化鋁金屬，強化 Ion-X 玻璃材質(zhì)為顯示屏提供保護(hù)。搭配高性能 Fluoroelastomer 表帶，共有 5 款繽紛色彩。"
  }
}

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

獲取商品列表(未分頁)

url: /api/products

method: GET

responseBody

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

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

暫時不考慮用戶認(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": "此次蘋果發(fā)布會發(fā)布了iPhone 6與iPhone 6 Plus，搭載iOS 8，尺寸分別是4.7和5.5英寸。外觀設(shè)計不再棱角分明，表層玻璃邊有一個弧度向下延伸，與陽極氧化鋁金屬機身邊框銜接。機身背部采用三段式設(shè)計。機身更薄，續(xù)航能力更強。"
    }
  ]
}

取消收藏商品

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) 等屬于全局異常。針對對獨立業(yè)務(wù)的一些異常屬于局部異常，例如產(chǎn)品編輯出錯。

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

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

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

前后端完全分離初探

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

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

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

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

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

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

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