整合營銷服務商
電腦端+手機端+微信端=數據同步管理
免費咨詢熱線：
電腦端+手機端+微信端=數據同步管理
免費咨詢熱線：
者：人月神話，新浪博客同名
簡介：多年SOA規劃建設，私有云PaaS平臺架構設計經驗，長期從事一線項目實踐
在前面關于微服務方面的文章里面提到，對于多個微服務模塊間往往都是以輕量的Http Rest API接口方式進行集成和協同。那么對于API接口的設計，接口服務的注冊接入，后續的治理管控就是整個微服務架構里面不可或缺的內容。因此今天將對這部分內容重新做下總結。
對于HTTP Rest接口的設計，網上已經有很多文章都有詳細的闡述，今天再重新整理下這里面的一些重點，大家都清楚Rest接口是面向資源的接口設計方法，而且基于原生的Http協議，因此里面就有兩個最關鍵的點，一個就是對資源的理解，一個就是對操作的理解。
圖片來源網絡
什么是RESTful架構，重要的幾點如下：
對資源的理解
就是我們平常上網訪問的一張圖片、一個文檔、一個視頻等。這些資源我們通過URI來定位，也就是一個URI表示一個資源。資源是做一個具體的實體信息，它可以有多種的展現方式。而把實體展現出來就是表現層，例如一個txt文本信息，它可以輸出成html、json、xml等格式，一個圖片他可以jpg、png等方式展現，這個就是表現層的意思。
URI確定一個資源，但是如何確定它的具體表現形式呢？應該在HTTP請求的頭信息中用Accept和Content-Type字段指定，這兩個字段才是對”表現層”的描述。
對操作的理解
客戶端能通知服務器端的手段，只能是HTTP協議。
具體來說，就是HTTP協議里面，四個表示操作方式的動詞：GET、POST、PUT、DELETE。它們分別對應四種基本操作：GET用來獲取資源，POST用來新建資源（也可以用于更新資源），PUT用來更新資源，DELETE用來刪除資源。
對于資源的任何操作，都應該映射到HTTP的幾個有限的方法（常用的有GET/POST/PUT/DELETE 四個方法，還有不常用的PATCH/HEAD/OPTIONS方法）上面。所以RESTful API建模的過程，可以看作是具有統一接口約束的面向對象建模過程。
按照HTTP協議的規定，GET方法是安全且冪等的，POST方法是既不安全也不冪等的（可以用來作為所有寫操作的通配方法），PUT、 DELETE方法都是不安全但冪等的。將對資源的操作合理映射到這四個方法上面，既不過度使用某個方法（例如過度使用GET方法或POST方法），也不添 加過多的操作以至于HTTP的四個方法不夠用。
面向資源的設計
圖片來源網絡
注意傳統的接口設計一般是面向方法和操作的，即一般都是動賓結構為主的方法操作。比如查詢用戶信息接口，更新供應商狀態接口，刪除人員信息接口等等。而對于面向資源的設計，一個大的轉變就是首先要識別和定義資源，再來對資源的Http各種操作方法進行定義。
資源可以理解為對象，更多的是數據模型，這種數據模型本身就是有層次結構，本身是可以嵌套或遞進的。比如你可以將訂單理解為一個資源，那么這個訂單資源本身是一個層次化的結構對象，包括了訂單頭信息，也包括了訂單明細信息。我們可以對這個層次化的資源結構進行詳細定義。
在數據庫設計的時候，經常會出現視圖的設計，或者說表之間的關聯，而這種視圖本身就不是一種資源實體，但是在進行資源定義的時候，我們可以定義這種層次化的對象結構。
舉個例子來說，在對訂單這種資源對象進行定義的時候，在訂單明細中傳統的視圖中會關聯訂單明細表和物料表形成訂單行ID，物料編碼ID，物料名稱，類型，訂購數量的關聯視圖信息。但是在資源定義的時候，我們仍然只需要定義訂單行信息，但是訂單行信息中出現了物料，我們形成一個對物料資源信息的Ref引用，而獲取到完整的物料屬性信息。
當然資源本身也有關聯關系，我們可以定義這種關聯關系來獲取到關聯資源的信息，比如某個用戶發布的評論信息，我們可以先定位到該用戶資源，然后再定位到該用戶資源對應的評論資源。
具體可以參考：
http://www.ruanyifeng.com/blog/2014/05/restful_api.html
http://blog.51cto.com/xxdeelon/2083707
為了使 API 看上去簡單明了，可讀性強，我們一般使用名詞，而不是動詞來命名這些資源。比如下面這些都是糟糕的設計，比如下面的動賓結構的方法名作為資源：
之所以糟糕，不僅僅是它們顯得拖沓冗長，最重要的是，使用這樣的風格和名字沒有固定的形式，不同的開發者往往需要閱讀你的文檔才能開始使用，也沒有充分利用HTTP Method，何況使用自己的動詞可能會產生和HTTP Method沖突的情況。使用 REST 風格的優秀設計應該像下面這些:
這些API所有的操作只有一個節點 /users，顯得簡潔明了，如果熟悉 HTTP Method 的開發者，一眼看上去就能猜到應該如何使用。
注：在現在進行Http Rest API接口設計的時候，實際上往往并沒有遵循面向資源設計的思路，仍然是參考上面的操作+數據的設計方法，比如有些公司的設計規范往往還是全部約定為使用POST接口設計，這個并不能說就一定不合理。這種情況更多就是使用Http API而已。
您可能已經注意到了，以上 API 中資源命名都使用了復數的形式。這是一個約定，它可以省去設計時考慮數據具體細節的麻煩（數據是復數還是單數？）?，F在大很多常見的系統都使用了復數形式。比如Twitter 的 REST APIs 和 Facebook 的 Graph API 基本都是復數形式。
然而實際系統一般都不可能只有單一資源，資源和資源之間有各種關系是很正常的情況，那么如何設計存在關聯資源（數據）的API呢？如果要設計一個資源擁有另外一個資源的情況的API，例如，設計一個包含用戶（users）和用戶的評論（comments）的 API 可以采用這樣的形式：
當然，如果一個資源并不依附其它資源而可以獨立存在，是沒有必要這樣設計的，完全可以使用和 users 一樣的形式提供，如果要查詢其中的關系，可以使用其它資源作為 ID 的形式來過濾。
例如 /comments?user_id=1234。關于這點詳細內容可以參見下面的第三條“優雅的設計條件過濾，排序，搜索和限制返回數據的參數形式”。
對于Http Rest接口設計規范，可參考
https://blog.csdn.net/zghwaicsdn/article/details/53788535
https://blog.csdn.net/zl1zl2zl3/article/details/73867113
https://blog.csdn.net/yyjava/article/details/81626991
https://www.jianshu.com/p/00d1ab8cc073
http://wangwei.info/about-rest-api/
資源定義格式：
URI=scheme "://" authority "/" path [ "?" query ] [ "#" fragment ]
URL是URI的一個子集(一種具體實現)，對于REST API來說一個資源一般對應一個唯一的URI(URL)。在URI的設計中，我們會遵循一些規則，使接口看起透明易讀，方便使用者調用。
"/"分隔符一般用來對資源層級的劃分
例如 http://api.canvas.restapi.org/shapes/polygons/quadrilaterals/squares
對于REST API來說，"/"只是一個分隔符，并無其他含義。為了避免混淆，"/"不應該出現在URL的末尾。
在RESTful架構中，每個網址代表一種資源（resource），所以網址中不能有動詞，只能有名詞，而且所用的名詞往往與數據庫的表格名對應。一般來說，數據庫中的表都是同種記錄的"集合"（collection），所以API中的名詞也應該使用復數。
在我們在實施過程中如何通過一些工具支撐來進行接口設計的規范化和標準化問題。大家都知道，在采用傳統的SOAP WebService服務接口的時候，由于SOAP WS服務本身有WSDL和XSD文件的強接口契約規范格式要求，因此很容易基于從上向下，規范先行的思路來進行服務實施流程管控。即：
可以看到傳統的WS服務實施下，我們可以通過規范和契約先行的方式很好的控制接口的標準化和一致性，同時大家遵循完全相同的一套WSDL文件進行接口的提供或開發，基本不存在接口實現中數據結構不一致的問題。
在采用RestAPI接口進行設計的時候，實際上仍然有一個關鍵點，就是設計要先行，先設計，然后再進行開發和測試，同時設計文件能給標準化和結構化，通過設計文件來生成相應的客戶端和服務端代碼框架，通過設計文件來生成相應的測試用例，通過設計文件來生成對應的API接口設計文檔。
設計先行，是Http Rest接口服務實施中的一個關鍵點。
1. 設計工具的選擇問題
當前兩者主流的設計規范和建模語言，一個是RAML，一個是WADL。
RAML(RESTful API Modeling Language） 即 RESTful API 建模語言)是對 RESTful API的一種簡單和直接的描述。它是一種讓人們易于閱讀并且能讓機器對特定的文檔能解析的語言。
RAML 是基于 YAML,能幫助設計 RESTful API 和鼓勵對API的發掘和重用,依靠標準和最佳實踐從而編寫更高質量的API。通過RAML定義,因為機器能夠看得懂,所以可以衍生出一些附加的功能服務,像是解析并自動生成對應的客戶端調用代碼、服務端代碼 結構, API說明文檔。
https://www.w3cschool.cn/web_api_next/qw2zpozt.html
https://raml.org/projects
https://www.cnblogs.com/softidea/p/5728952.html
WADL（Web Application Description Language）是一種用于描述web應用對外提供接口語言，它使用XML來表示。其中主要包括每個資源的定位（URI）、請求類型（GET、POST等）、請求參數類型（路徑參數、query參數等）、響應值和響應類型等一系列內容。
根據這個XML，可以直接讀取到系統提供的所有REST API，并能夠進行調用。由于WADL使用XML描述，對于開發者來說，可以通過標準的xslt進行轉換，將機器讀取的XML轉換成便于人讀取的HTML，進而行成API文檔。
https://coolex.info/blog/547.html
http://blog.chinaunix.net/uid-9789791-id-1997442.html
http://www.doc88.com/p-6661149184381.html
注：對于兩種接口規范如何選擇的問題？個人認為如果我們需要一套接口規范同時兼容傳統的SAOP WebService和Http Rest API，那么采用WADL更好。如果已經是全新Http Rest接口設計，往往當前RAML更加主流。
主流的Swagger設計工具
對于設計工具，這里只談下Swagger設計工具，這個工具最大的好處就是只需要通過編輯器進行Rest接口設計文件的定義，然后可以自動生成測試框架，自動生成客戶端和服務端多種語言下的開發框架，生成API接口設計文檔，這個工具本身設計完成內容還可以導出為YAML文件或Json文件，也支撐文件導入。
https://swagger.io/tools/
Swagger 是一個規范和完整的框架，用于生成、描述、調用和可視化 RESTful 風格的 Web 服務。Swagger的目標是對REST API定義一個標準的和語言無關的接口，可讓人和計算機無需訪問源碼、文檔或網絡流量監測就可以發現和理解服務的能力。
當通過Swagger進行正確定義，用戶可以理解遠程服務并使用最少實現邏輯與遠程服務進行交互。與為底層編程所實現的接口類似，Swagger消除了調用服務時可能會有的猜測。Swagger是一組開源項目，其中主要要項目如下：
Swagger API Spec包含以下部分內容，詳細參考：
https://www.cnblogs.com/jpfss/p/8072443.html
注意通過Swagger-Editor編輯器可以完成整個接口的定義和接口設計工作，同時一方面用于客戶端和服務端代碼框架的生成，一方面用于幫助文檔的生成。但是Swagger對于幫助文檔的生成需要在代碼框架里面增加注解，相對來說注解編寫的工作量較大。這也是網上很多提到的文檔生成方面Swagger往往并不是最佳選擇。
原有的接口服務規范編寫思路改進
對于原來的接口服務規范編寫思路，可以看到幾個改進或優化思路。
1. 還是保留先編寫Word格式的接口服務規范，然后再將Word接口服務規范轉為標準的YAML或WADL接口規范定義文件，同時再生產客戶端或服務端的代碼框架文件。
2. 拋棄Word編寫規范模式，直接在類似Swagger編輯器中對接口文件進行設計，設計完成后發出文件進行評審和檢查，沒問題后由集成平臺歸檔并導入管控生產服務規范，同時生成客戶端和服務端代碼框架一同下發。
現在發現的一個問題不好解決點在于，在進行接口文件設計的時候能否直接增加字段和數據項的中文描述和業務備注說明，該信息最終體現到生成的文檔上?；蛘哒f我們需要通過YAML或Json文件，來逆向生成Word文檔，然后Word文檔再下發給業務系統補充中文描述信息。
API文檔的生成
如果采用Swagger工具來進行API接口服務的設計，可以看到在編輯器里面，設計過程和文檔生成過程基本是同步的，即一個API接口設計好后，文檔基本就已經生成完成并可用。當前唯一發現的問題就是沒有想過的中文描述，如果需要中文信息，還需要在代碼框架里面增加注解，這個過程來說就想到繁瑣了。
通過Swagger注解生成文檔：
https://www.jianshu.com/p/0438034ee55f
SpringBoot項目生成RESTfull API的文檔，第二篇給出SpringBoot和Swagger整合思路
https://www.jianshu.com/p/af7a6f29bf4f
http://blog.didispace.com/springbootswagger2/
https://gitee.com/didispace/SpringBoot-Learning
Wisdom REST Client
Wisdom RESTClient supports automated testing and automatically generating RESTful API document based on history cases. Wisdom RESTClient可以自動化測試RESTful API 接口，同時，基于測試過的歷史數據，可以自動生成API文檔。
工具地址：https://github.com/Wisdom-Projects/rest-client
這個工具是偏測試后的文檔生成，最終生成的文檔展現和Swagger展現效果類似。
Api2Doc文檔生成工具
Api2Doc 專注于 Restful API 文檔的自動生成，它的原理與 Swagger2 是類似的，都是通過反射，分析 Controller 中的信息生成文檔，但它要比 Swagger2 好很多。最大的不同是： Api2Doc 比 Swagger2 要少寫很多代碼。
第一是對應注解過程本身更加簡單，其次就是可以自動分析類引用，將類定義中關于數據項的注釋信息引用到最終生成的文檔中，這個功能就相當好用了，很好的解決了我們前面提到的數據項中文描述的問題。
參考：
http://blog.51cto.com/13613194/2090764
https://www.cnblogs.com/yoyotl/p/6376624.html
使用Asciidoc代替Markdown和Word撰寫開發文檔
Asciidoc是另外一個可以用于HttpRest接口文檔生成的工具。該工具簡潔而不簡陋的語法，它專門為編寫書籍而生，在語法的支持上很到位，但不像Word那樣可以隨性，可以讓你的文檔更統一美觀。AsciidocFX工具開源跨平臺，使用體驗很不錯，更可以導出HTML、PDF、EBook等格式
具體參考：
https://my.oschina.net/gudaoxuri/blog/524132
http://houqp.github.io/wbwa/wbwa.html
感覺該工具完全可以用于幫助手冊的制作。常用的列表，段落，超鏈接，圖片，表格，代碼等能力都支持。
對于API管理平臺參考
https://www.eolinker.com/#/
對于Eolinker基本提供了一套完整的API全生命周期管理方案。無論您使用什么語言開發，無論是 HTTPS、Websocket、TCP、UDP 等協議，還是 Restful、SOAP、WebService 等規范，Eolinker 都可以幫您統一規范地管理起來，并提供強大的文檔管理、協作、測試、分享功能。
由于我們原來重點是實施傳統ESB服務總線項目，以SOAP WS服務接入為主，并形成了完整的SOA治理管控平臺，實現服務全生命周期管理和運維監控。而對于Http Rest接口服務的注冊接入和后續管控，要完全重新實現一套面向Http Rest接口的平臺并不太現實。
因此需要基于當前的SOA管控平臺來思考如何平滑擴展對Http Rest接口服務的支撐能力。
首先我們要意識到，ESB總線和微服務網關是可以并行存在的。在一個集團企業內部，有些業務域已經完全實施微服務架構轉型和改造，而有些業務系統仍然采用了傳統架構，企業在朝微服務架構轉型過程中實際上是一個逐漸過渡的過程。在傳統架構支撐中我們搭建了ESB企業服務總線實現接口服務集成和統一管控，而在微服務架構支撐中，我們如何支持？
這里的一個關鍵思路和邊界就是，對于某個業務域完全實施了微服務架構轉型，比如一個大供應鏈系統的建設，里面涉及到招投標，采購，物流，庫存等多個微服務模塊，都按照微服務架構進行設計，開發和集成。那么在這個業務域內部就需要有微服務注冊中心，同時又一個微服務網關統一提供對外能力。
那么企業原來已有的全局ESB服務總線只是和該業務域提供的微服務網關進行對接。這個有點類似于兩級ESB集成模式，即供應鏈內部微服務模塊間的集成不走ESB總線，在內部通過注冊中心或網關完成即可。
其次ESB總線雖然比較重但是不代表性能弱，我們經常會遇到業務系統提出的問題，就是走ESB服務總線集成是否太重，而應該改為輕量的API網關類產品。在這里我們要提出一個關鍵點，就是ESB總線雖然說是一個重型的產品，但是這種重更多是指的其對底層資源和中間件的要求比較高，并不是說重量級的產品性能就差。
對于ESB這種重型產品，底層引擎更加強大，當你只啟用簡單的Http服務代理，安全等功能的時候，其性能，可靠性和穩定性反而是遠遠高于我們經常說的各種開源的API網關類產品的。
舉個例子來說，就拿各種重量級的V6大型越野車來說，其重點是油耗高，剛開始的加速弱點，當時真正加速起來后的性能，通過性和穩定性遠超各種一般的轎車。而且越野車不是說只跑山路爛路有優勢，就是其跑高速路帶來的性能你也不上。
微服務網關或API網關，我們看到，只要是這種網關類產品，就一定需要提供服務代理能力來保證服務位置透明，但是一提供這個能力，那么所有的消息流就一定會通過網關來承載，因此API網關本身受到的性能壓力，高可用性壓力是很大的。也對產品本身也有更高的要求，而對于大型ESB總線在這塊往往已經得到充分驗證。
也就是說，要追求性能，我們不要用ESB總線里面類似協議轉換，數據映射，適配等復雜消耗性能的功能，而將ESB總線當作網關類產品來用就可以了，這樣ESB總線完全可以提供類似API網關應該有的性能。
最后，實現對Http Rest接口服務的注冊和接入并不一定說要完全遵循面向資源編程的思路。談Http Rest接口設計的時候，一定會提到面向資源的編程思路，包括資源的識別和定義，基于資源的各種標準Http操作。但是要注意到，在一個微服務架構內部，我們完全可以按這個思路來執行和推廣。但是在涉及到跨域的基礎，微服務網關和傳統業務系統，ESB集成的時候。
這個接口設計是否一定遵循Http Rest面向資源的設計規范并不那么重要。
也就是說，傳統ESB在接入Http Rest接口的時候，我們完全可以按傳統的接口設計方法進行設計，比如全部走POST接口設計。只是傳統協議走了標準的Http接口協議，傳輸內容走了更加輕量的Json格式而已。只有把這點想明白，才能給繼續思考我們當前的SOA管控平臺，如何能給平滑的實現對Http Rest接口服務接入的支撐。
基于前面的思路，對于當前的SOA管控平臺，需要考慮如何平滑的支撐Http Rest接口服務。
1. 對于新的Http Rest接口的注冊和接入
對于當前已有的基于SOAP WS的服務規范定義文檔，最好的方式就是做到SOAP和REST接口都能給通用，雖然這樣不符合Rest面向資源的要求，也喪失了Rest接口本身的一些靈活性，但是可提升對服務規范的標準化管理。在這種模式下，對于服務規范涉及到的變化估計在于：
也就是說，我們完全可以做到一套服務規范來支撐SOAP和Rest接口，畢竟在做跨系統間接口服務集成的時候，這里的接口更多都是粗粒度的服務定義，并不會涉及到細粒度的數據表或對象的所有CRUD操作?？缦到y間的接口更多的是滿足跨業務協同和數據集成需要即可，是橫向系統和系統之間的接口，而不是類似單個業務系統展現層和邏輯層到DB層的接口。
對于Http Rest接口，傳遞的數據要支持XML和Json兩種格式，這個也需要提前進行約定和配置。而為了兼容當前的服務規范格式，可以看到這樣轉過了的Rest接口方法全部為Post接口，同時接口服務名即為資源對象名，同時在接口調用的時候傳遞的是一個我完整的數據集合對象。這和我們前面講Rest接口的設計和調用是有區別的。
規范定義講清楚后，整個過程就簡單了，原來已有的直接在界面上定義服務規范或者通過Word文檔導入服務規范功能基本都可以保留，做少量變更修改即可。導入的規范本身也可以進一步導出或直接在線查看。
對于Rest接口服務，我們仍然可以遵循一樣的契約先行和自頂向下設計的思路進行。
規范清楚后，接著還是需要導出標準的契約格式文檔，而這里建議還是采用WADL，基于Rest接口的服務定義語言，有強契約格式要求。而對于RAML，更多是Rest接口設計建模的語言，類似于通過RAML來寫文檔。如果我們是以Word服務規范文檔格式為主，實際上是沒必要再用RAML。但是可以考慮服務規范導出RAML語言定義。
RAML(RESTful API Modeling Language 即 RESTful API 建模語言)是對 RESTful API的一種簡單和直接的描述。它是一種讓人們易于閱讀并且能讓機器對特定的文檔能解析的語言。這樣也方便我們后面基于RAML來生成API定義文檔。
在規范導出為WADL設計文件后，那么就有嚴格契約格式要求，業務系統可以基于該WADL定義文件，通過工具自動生成客戶端和服務端的代碼開發框架，然后再填充業務規則和邏輯，這個過程和我們標準的SOAP WS接口服務的設計和開發是一致的，并沒有太多的區別。
在服務提供端按WADL要求開發后Rest接口服務后，由ESB進行服務代理封裝接入，這個需要單獨設計功能支持，即需要采用單獨定制的OSB服務封裝模板。在服務代理接入后，我們原來對于SOAP接口的安全，日志等控制能力全部都需要保留和平滑支持。
服務代理接入后，仍然自動化部署，部署完成后給出代理封裝后的訪問地址。
對于服務調用訪問，本身也會產生日志記錄，對于已有的服務運行日志監控，服務異常日志監控等功能，都需要完全平滑的支撐Http Rest接口服務。對于原有的日志元數據配置表，服務日志運行實例表等也保留一套。
2. 對于SOAP和Rest接口本身的轉換映射問題
當我們采用同一套規范體系的時候，我們就很容易去實現兩種類型接口的轉換和映射。
業務系統如果提供的SOAP WS接口服務，我們需要單獨提供一個功能，將該SOAP WS服務發布為Http Rest接口服務，同時在發布的時候可以選擇是采用XML格式，還是Json格式進行發布。
這樣好處就是原來業務系統以及提供了SOAP接口，但是當我們在對接一個微服務架構體系的時候，消費端為了自身的標準化需要消費Rest接口服務，那么由ESB來完成這種轉換映射即可，原有的業務系統服務提供方不再需要做任何服務設計變更和代碼修改。
當然，如果業務系統本身提供的Http Rest接口服務，為了對已有的歷史系統進行支撐，我們也可以將Http Rest接口服務轉化為SOAP WS服務再進行暴露。在轉換的時候新數據格式只能夠是XML格式。
3. 對于消息發布訂閱，消息中間件的支持
對于消息發布訂閱，我們采用Weblogic JMS消息中間件，但是將JMS能力適配后發布為SOAP WS接口服務。在Http Rest接口服務實施過程中，我們需要支撐將JMS適配后能力直接發布為Rest接口服務。
當然為了簡化，該功能非必須，即我們可以考慮在ESB接口上做兩次代理，即將ESB已經暴露的SOAP WS消息分發服務接口，通過Http Rest接口服務轉換功能直接進行轉換后二次發布。
對于JMS消息訂閱端，本身走Java API接口進行消息消費，本身和服務采用SOAP還是Rest沒有太大關系。
4. 對于Http Rest接口的純代理接入
對于業務系統已有的HttpRest接口，如果不希望按嚴格的服務規范設計和契約先行的思路進行變更，我們也可以直接對已有的Rest接口進行純代理接入，即ESB做完全的代理轉發，不做任何的安全控制，輸入內容消息頭的解析，數據映射轉換等。對于這類Rest接口服務，ESB總線只起代理轉發作用。
對于ESB服務總線和API網關產品來說，在前面很早的博客文章自己就談到過，整體思路是底層引擎是兩套，即一個是偏重的ESB總線引擎，一個是API網關引擎，但是對于SOA治理管控和運營開放則是整合為一套。一個是SOA運維監控平臺是統一的一套，一個是能力開放平臺也統一為一套。
但是我們看到雖然ESB總線是一個偏重的引擎，但是我們不啟用其復雜的協議轉換，數據映射，服務編排等功能的時候仍然可以做為要給輕量的SOA總線來使用。而且我們看到另外一個場景，即企業很多時候不會很快就完成一個微服務架構化的轉型，始終是存在傳統的遺留系統。
因此集成問題和場景本身是很復雜的，即使整個集成趨勢是Http Rest接口集成和API網關集成為主，但是你還是得兼容傳統觀的WS服務集成和簡單的協議轉換能力。
實際上對于ESB總線來說本身就是支持Http Rest接口服務得注冊和接入的。因此實際上對ESB服務總線和API網關引擎存在兩種思路可以選擇。
對于第二種方式相對來說并不會很復雜，也容易實施，即通過對ESB服務總線的升級來完成對ESB總線+API網關兩方面能力的完全支撐。你可以說賣的是ESB服務總線，但是完全兼容適配API網關所有能力。
基于上面這個思路，我們需要做的主要包括
基于以上關鍵點進行進一步的優化和完善后，即能夠為企業提供一套完整的SOA服務總線產品，同時支撐傳統的ESB服務總線能力，又對Http Rest API接口的接入，注冊和管控方面能力得到全面增強。
歡迎關注@人月聊IT 分享SOA，微服務，DevOps平臺規劃和建設。
篇 文章主要是借鑒他人，但是自己很想總結出一套規范，以供向我這樣的新手使用，用來規范代碼，如果有什么好的提議，請不吝賜教，本篇文章長期更新！
一、重要概念：
REST,即Representational State Transfer的縮寫。我對這個詞組的翻譯是"表現層狀態轉化"。
Resource（資源） ：對象的單個實例。 例如，一只動物。它可以是一段文本、一張圖片、一首歌曲、一種服務，總之就是一個具體的實在。你可以用一個URI（統一資源定位符）指向它，每種資源對應一個特定的URI。要獲取這個資源，訪問它的URI就可以，因此URI就成了每一個資源的地址或獨一無二的識別符。
集合：對象的集合。 例如，動物。
第三方：使用我們接口的開發者
表現層（Representation）
"資源"是一種信息實體，它可以有多種外在表現形式。我們把"資源"具體呈現出來的形式，叫做它的"表現層"（Representation）。
狀態轉化（State Transfer）
訪問一個網站，就代表了客戶端和服務器的一個互動過程。在這個過程中，勢必涉及到數據和狀態的變化。互聯網通信協議HTTP協議，是一個無狀態協議。這意味著，所有的狀態都保存在服務器端。因此，如果客戶端想要操作服務器，必須通過某種手段，讓服務器端發生"狀態轉化"（State Transfer）。而這種轉化是建立在表現層之上的，所以就是"表現層狀態轉化"。
客戶端用到的手段，只能是HTTP協議。具體來說，就是HTTP協議里面，四個表示操作方式的動詞：GET、POST、PUT、DELETE。它們分別對應四種基本操作：GET用來獲取資源，POST用來新建資源（也可以用于更新資源），PUT用來更新資源，DELETE用來刪除資源。
比如，文本可以用txt格式表現，也可以用HTML格式、XML格式、JSON格式表現，甚至可以采用二進制格式；圖片可以用JPG格式表現，也可以用PNG格式表現。
URI只代表資源的實體，不代表它的形式。嚴格地說，有些網址最后的".html"后綴名是不必要的，因為這個后綴名表示格式，屬于"表現層"范疇，而URI應該只代表"資源"的位置。它的具體表現形式，應該在HTTP請求的頭信息中用Accept和Content-Type字段指定，這兩個字段才是對"表現層"的描述。
綜合上面的解釋，我們總結一下什么是RESTful架構：
（1）每一個URI代表一種資源；
（2）客戶端和服務器之間，傳遞這種資源的某種表現層；
（3）客戶端通過四個HTTP動詞，對服務器端資源進行操作，實現"表現層狀態轉化"。
二、REST接口規范
1、動作
GET （SELECT）：從服務器檢索特定資源，或資源列表。POST （CREATE）：在服務器上創建一個新的資源。PUT （UPDATE）：更新服務器上的資源，提供整個資源。PATCH （UPDATE）：更新服務器上的資源，僅提供更改的屬性。DELETE （DELETE）：從服務器刪除資源。
首先是四個半種動作：post、delete、put/patch、get因為put/patch只能算作一類，所以將patch歸為半個。
另外還有有兩個較少知名的HTTP動詞：HEAD - 檢索有關資源的元數據，例如數據的哈?；蛏洗胃聲r間。OPTIONS - 檢索關于客戶端被允許對資源做什么的信息。
2、路徑（接口命名）
路徑又稱"終點"（endpoint），表示API的具體網址。
在RESTful架構中，每個網址代表一種資源（resource），所以網址中不能有動詞，只能有名詞，而且所用的名詞往往與數據庫的表格名對應。一般來說，數據庫中的表都是同種記錄的"集合"（collection），所以API中的名詞也應該使用復數。
舉例來說，有一個API提供動物園（zoo）的信息，還包括各種動物和雇員的信息，則它的路徑應該設計成下面這樣。
接口盡量使用名詞，禁止使用動詞，下面是一些例子。
GET /zoos：列出所有動物園 POST /zoos：新建一個動物園 GET /zoos/ID：獲取某個指定動物園的信息 PUT /zoos/ID：更新某個指定動物園的信息（提供該動物園的全部信息） PATCH /zoos/ID：更新某個指定動物園的信息（提供該動物園的部分信息） DELETE /zoos/ID：刪除某個動物園 GET /zoos/ID/animals：列出某個指定動物園的所有動物 DELETE /zoos/ID/animals/ID：刪除某個指定動物園的指定動物
反例：
/getAllCars /createNewCar /deleteAllRedCars
再比如，某個URI是/posts/show/1，其中show是動詞，這個URI就設計錯了，正確的寫法應該是/posts/1，然后用GET方法表示show。
如果某些動作是HTTP動詞表示不了的，你就應該把動作做成一種資源。比如網上匯款，從賬戶1向賬戶2匯款500元，錯誤的URI是：
POST /accounts/1/transfer/500/to/2
正確的寫法是把動詞transfer改成名詞transaction，資源不能是動詞，但是可以是一種服務：
POST /transaction HTTP/1.1
Host: 127.0.0.1
from=1&to=2&amount=500.00
理清資源的層次結構，比如業務針對的范圍是學校，那么學校會是一級資源(/school)，老師(/school/teachers)，學生(/school/students)就是二級資源。
3、版本（Versioning）
應該將API的版本號放入URL。如：
https://api.example.com/v1/
另一種做法是，將版本號放在HTTP頭信息中，但不如放入URL方便和直觀。Github采用這種做法。
4、過濾信息（Filtering）
如果記錄數量很多，服務器不可能都將它們返回給用戶。API應該提供參數，過濾返回結果。下面是一些常見的參數。
?limit=10：指定返回記錄的數量 ?offset=10：指定返回記錄的開始位置。 ?page_number=2&page_size=100：指定第幾頁，以及每頁的記錄數。 ?sortby=name&order=asc：指定返回結果按照哪個屬性排序，以及排序順序。 ?animal_type_id=1：指定篩選條件 參數的設計允許存在冗余，即允許API路徑和URL參數偶爾有重復。比如， GET /zoo/ID/animals 與 GET /animals?zoo_id=ID 的含義是相同的。
5、狀態碼（Status Codes）
狀態碼范圍
1xx 信息，請求收到，繼續處理。范圍保留用于底層HTTP的東西，你很可能永遠也用不到。 2xx 成功，行為被成功地接受、理解和采納 3xx 重定向，為了完成請求，必須進一步執行的動作 4xx 客戶端錯誤，請求包含語法錯誤或者請求無法實現。范圍保留用于響應客戶端做出的錯誤，例如。他們提供不良數據或要求不存在的東西。這些請求應該是冪等的，而不是更改服務器的狀態。 5xx 范圍的狀態碼是保留給服務器端錯誤用的。這些錯誤常常是從底層的函數拋出來的，甚至 開發人員也通常沒法處理，發送這類狀態碼的目的以確?？蛻舳双@得某種響應。 當收到5xx響應時，客戶端不可能知道服務器的狀態，所以這類狀態碼是要盡可能的避免。
服務器向用戶返回的狀態碼和提示信息，常見的有以下一些（方括號中是該狀態碼對應的HTTP動詞）。
200 OK - [GET]：服務器成功返回用戶請求的數據，該操作是冪等的（Idempotent）。 201 CREATED - [POST/PUT/PATCH]：用戶新建或修改數據成功。 202 Accepted - [*]：表示一個請求已經進入后臺排隊（異步任務） 204 NO CONTENT - [DELETE]：用戶刪除數據成功。 400 INVALID REQUEST - [POST/PUT/PATCH]：用戶發出的請求有錯誤，服務器沒有進行新建或修改數據的操作，該操作是冪等的。 401 Unauthorized - [*]：表示用戶沒有權限（令牌、用戶名、密碼錯誤）。 403 Forbidden - [*] 表示用戶得到授權（與401錯誤相對），但是訪問是被禁止的。 404 NOT FOUND - [*]：用戶發出的請求針對的是不存在的記錄，服務器沒有進行操作，該操作是冪等的。 406 Not Acceptable - [GET]：用戶請求的格式不可得（比如用戶請求JSON格式，但是只有XML格式）。 410 Gone -[GET]：用戶請求的資源被永久刪除，且不會再得到的。 422 Unprocesable entity - [POST/PUT/PATCH] 當創建一個對象時，發生一個驗證錯誤。 500 INTERNAL SERVER ERROR - [*]：服務器發生錯誤，用戶將無法判斷發出的請求是否成功。 502 網關錯誤 503 Service Unavailable 504 網關超時
參考資料：
RESTful API 設計指南--阮一峰：http://www.ruanyifeng.com/blog/2014/05/restful_api.html
首先 RESTful架構，就是目前最流行的一種互聯網軟件架構。它結構清晰、符合標準、易于理解、擴展方便，所以正得到越來越多網站的采用。
REST這個詞，是 Roy Thomas Fielding 在他2000年的博士論文中提出的。
REST，即 Representational State Transfer 的縮寫，如果一個架構符合REST原則，就稱它為RESTful架構。
要理解RESTful架構，最好的方法就是去理解Representational State Transfer這個詞組到底是什么意思，它的每一個詞代表了什么涵義。如果你把這個名稱搞懂了，也就不難體會REST是一種什么樣的設計。
REST的名稱"表現層狀態轉化"中，省略了主語。"表現層"其實指的是"資源"（Resources）的"表現層"。
所謂"資源"，就是網絡上的一個實體，或者說是網絡上的一個具體信息。它可以是一段文本、一張圖片、一首歌曲、一種服務，總之就是一個具體的實在。你可以用一個URI（統一資源定位符）指向它，每種資源對應一個特定的URI。要獲取這個資源，訪問它的URI就可以，因此URI就成了每一個資源的地址或獨一無二的識別符。
所謂"上網"，就是與互聯網上一系列的"資源"互動，調用它的URI。
"資源"是一種信息實體，它可以有多種外在表現形式。我們把"資源"具體呈現出來的形式，叫做它的"表現層"（Representation）。
比如，文本可以用txt格式表現，也可以用HTML格式、XML格式、JSON格式表現，甚至可以采用二進制格式；圖片可以用JPG格式表現，也可以用PNG格式表現。
URI只代表資源的實體，不代表它的形式。嚴格地說，有些網址最后的".html"后綴名是不必要的，因為這個后綴名表示格式，屬于"表現層"范疇，而URI應該只代表"資源"的位置。它的具體表現形式，應該在HTTP請求的頭信息中用Accept和Content-Type字段指定，這兩個字段才是對"表現層"的描述。
訪問一個網站，就代表了客戶端和服務器的一個互動過程。在這個過程中，勢必涉及到數據和狀態的變化。
互聯網通信協議HTTP協議，是一個無狀態協議。這意味著，所有的狀態都保存在服務器端。因此，如果客戶端想要操作服務器，必須通過某種手段，讓服務器端發生"狀態轉化"（State Transfer）。而這種轉化是建立在表現層之上的，所以就是"表現層狀態轉化"。
客戶端用到的手段，只能是HTTP協議。具體來說，就是HTTP協議里面，四個表示操作方式的動詞：GET、POST、PUT、DELETE。它們分別對應四種基本操作：GET用來獲取資源，POST用來新建資源（也可以用于更新資源），PUT用來更新資源，DELETE用來刪除資源。
綜合上面的解釋，我們總結一下什么是RESTful架構：
?。?）每一個URI代表一種資源；
?。?）客戶端和服務器之間，傳遞這種資源的某種表現層；
?。?）客戶端通過四個HTTP動詞，對服務器端資源進行操作，實現"表現層狀態轉化"。
舉例說明：對用戶表的的操作，增刪改查平衡車那個都是這么寫：
每種業務都有自己的路徑，增刪改查前端會看到四種不同的路徑，代碼整體看起來比較冗余
很明顯的區別，請求路徑統一，通過請求方式區分獲取、刪除、修改、保存 等動作，清爽多了
既然這么簡潔，我們實操一下吧
第1步：application.propertities 文件配置 spring.mvc.hiddenmethod.filter.enable=true,開啟表單的REST風格支持（這個源碼分析部分會講到）
第2部：編寫一個前端頁面實測一下 REST 風格的提交:
注意下頁面的 hidden隱藏域參數細節（后面源碼部分會提到）
點擊四個按鈕，發現跳轉正確！
他是怎么跳轉的，看源碼分析
SpringBoot的處理思路是：既然瀏覽器天然只能發送 GET 和 POST 請求，那可以利用前后的參數配合，根據約定好的參數，把POST或者GET 定向地轉成 PUT 或 DELETE 請求
實現對REST 請求風格的支持主要得益于HiddenMethodFilter 類，它同樣是在WebMvcAutoConfiguration 這個自動配置類中在項目啟動時自動注入的。
著重看一下 HiddenHttpMethodFilter ，顧名思義 隱藏HTTP方法過濾器，它的類注釋翻譯完粘貼過來：由于瀏覽器目前僅支持 GET 和 POST，因此一種常用技術（例如 Prototype 庫使用的技術）是使用帶有附加隱藏表單字段 ( _method ) 的普通 POST 來傳遞“真正的”HTTP 方法。 此過濾器讀取該參數并相應地更改HttpServletRequestWrapper.getMethod()返回值。 只允許"PUT" 、 "DELETE"和"PATCH" HTTP 方法。
請求參數的名稱默認為_method ，但可以通過methodParam屬性進行調整。
看下 HiddenHttpMethodFilter 的核心方法 doFilterInternal() , 他是如何吧我們的隱藏表單解析的
如何獲取？
轉發分享此文，后臺私信小編：“666”即可獲取。（注：轉發分享，感謝大家）
*請認真填寫需求信息，我們會在24小時內與您取得聯系。
