Spring Cloud微服務接口這麼多怎麼調試？

導讀
html

今天和你們聊一下Spring Cloud微服務下服務接口調試及管理的話題！咱們知道在微服務架構下，軟件系統會被拆分紅不少個獨立運行的服務，而這些服務間須要交互通訊，就須要定義各類各樣的服務接口。具體來講，在基於Spring Cloud的微服務模式中，各個微服務會基於Spring MVC的Controller定義多個該微服務須要向外部發布的接口。java

根據各個微服務功能邊界定義的不一樣，有些微服務會提供與具體業務相關的接口，如支付接口、帳戶接口等；而有些微服務則會提供一些公共性質的服務接口，如短信接口、統一認證接口之類。而這些微服務每每又是由多個不一樣的團隊在開發維護，傳統方式下服務接口的定義每每須要服務提供方提供良好的、可閱讀性比較高的接口文檔才能夠比較方便地對接和測試，而事實上，隨着時間的推移、人員的迭代更新，不少狀況下這些早期的接口文檔每每很快就會由於無人維護而過期，即使不過期，微服務模式下這樣的方式也會由於服務接口文檔太多而讓開發人員顯得抓狂！node

那麼有沒有一種更便捷地方式，可讓開發接口的同時，自動就能生成與服務接口高度一致的文檔來呢？答案是有的，接下來就和你們一塊兒聊聊到底有什麼樣方式可讓微服務的接口管理變得更加容易些！web

接口管理方式介紹
spring

事實上，市面上已經有多種開源項目提供了這樣的支持！如：Swagger、ApiDoc、RAP、DOCLever、CrapApi等，這些項目都提供了對於Api在線文檔的管理功能，那麼在Spring Cloud體系中哪種方式更加適合呢？下面，咱們一塊兒來對比下這些項目的優缺點。數據庫

Swagger編程

Swagger是一款基於YAML、JSON語言的文檔在線生成和代碼自動生成的工具。它的優勢以下：json

1）、它能夠直接嵌入在Spring Boot項目中，經過開發時編寫註釋，從而自動生成接口文檔，實現代碼與文檔的高度一致；
2）、能夠分析接口的結構，而且還能夠經過發起請求來驗證接口的正確性；
3）、它提供了多種編程語言的先後端分離解決方案，支持根據定義的接口導出各類語言的服務端或客戶端代碼；
4）、它還包括了Swagger Editor，這是使用yaml語言的Swagger API的編輯器，支持導出yaml和json格式的接口文件；
5）、包含了Swagger UI，它能夠將Swagger Editor編輯好的接口文檔以html的形式展現出來；
6）、免費開源，支持國際化，生態豐富、社區活躍；後端

它的缺點是：api

1）、對代碼有侵入性；
2）、不一樣項目的Swagger接口文檔是分離的，須要到不一樣的地方去找；
3）、Swagger UI展示出來的接口文檔缺少分類，使用體驗比較差；
4）、不一樣項目的接口文檔沒有權限管理，缺乏Mock；

官網地址：https://swagger.io/

ApiDoc

ApiDoc是一款輕量級的相似於Swagger的在線文檔生成工具。其缺點也相似於Swagger，接口管理、自動測試等功能也比較弱，而且其社區、生態國際化方面都還不如Swagger。

官網地址：http://apidocjs.com/

RAP

RAP是一個可視化接口管理工具，它能夠經過分析接口結構，動態生成模擬數據，校驗真實接口正確性，圍繞接口定義，經過一系列自動化工具提高微服務模式下的協做效率。

它的優勢以下：

1）、支持項目管理、團隊管理、文檔版本管理；
2）、支持Mock測試數據；
3）、阿里大廠出品，在阿里巴巴內部獲得實踐；
4）、支持接口檢索；
5）、能夠分析接口結構，發起請求校驗接口的正確性；
6）、免費開源

缺點以下：

1）、文檔和接口分離，很容易出現不一致的現象；
2）、每一個接口都須要手工編輯；
3）、後端採用nodejs編寫，與基於Java的Spring Cloud技術棧不一致；

官網地址：http://rapapi.org/org/index.do

DOCLever

DOCLever也是一個免費開源的接口管理工具，它的優勢以下：

1）、支持項目管理、團隊管理、文檔工具豐富；
2）、支持豐富的Mock測試數據；
3）、用戶案例也比較豐富：滴滴、美團、58同城、同城旅遊等；
4）、支持接口檢索；
5）、能夠分析接口的結構、發起請求校驗接口正確性、參數也很豐富；
6）、支持複雜場景的自動化測試，好比獲取驗證碼、登錄，獲取訂單列表，甚至獲取某個特定訂單詳情等上下文關聯的操做；

缺點以下：

1）、文檔和接口分離，很容易出現不一致的現象；
2）、每一個接口都須要手工編輯；
3）、後端也是採用nodejs編寫，與Spring Cloud的Java技術棧不符；

官網地址：http://doclever.cn

CrapApi

優勢以下：

1）、支持項目管理、團隊管理、文檔版本管理；
2）、支持Mock測試數據；
3）、支持接口檢索；
4）、能夠分析接口結構、發起請求校驗接口的正確性；
5）、支持接口監控、設置報警規則，接口不可用時及時通知服務負責人；
6）、後端基於Java開發，與Spring Cloud技術棧Java匹配；
7）、免費開源；

缺點：

1）、文檔和接口分離，很容易出現不一致的現象；
2）、每一個接口都須要手工編輯；
3）、使用案例較少，功能不夠完善，可能會有不少坑；

官網地址：http://api.crap.cn

Spring Cloud集成Swagger

經過對上述開源項目的分析，除Swagger外其他項目採起的都是文檔和代碼分離的方式，雖然這樣會減小對代碼的侵入，可是也會形成文檔和代碼的不一致現象，因此在基於Spring Cloud的微服務項目中，咱們選擇Swagger做爲微服務接口管理工具。

那麼基於Spring Boot的Spring Cloud微服務該如何集成Swagger呢？

1）、在Spring Boot微服務項目中引入Maven依賴：

 <dependency>
     <groupId>io.springfox</groupId>
     <artifactId>springfox-swagger2</artifactId>
     <version>2.2.2</version>
 </dependency>
 <dependency>
     <groupId>io.springfox</groupId>
     <artifactId>springfox-swagger-ui</artifactId>
     <version>2.2.2</version>
 </dependency>

2）、建立Swagger2配置類：

@Configuration
@EnableSwagger2
@Profile("!production")
public class SwaggerConfiguration {
    @Bean
    public Docket docket() {
        return new Docket(DocumentationType.SWAGGER_2)
                .groupName("Api")
                .select()
                .apis(withClassAnnotation(RestController.class))
                .build()
                .globalOperationParameters(commonParameters())
                .apiInfo(apiInfo());
    }

    private ApiInfo apiInfo() {
        return new ApiInfoBuilder()
                .title("Api")
                .version("1.0.0-SNAPSHOT")
                .build();
    }

    private List<Parameter> commonParameters() {
        List<Parameter> parameters = Lists.newArrayList();
        parameters.add(new ParameterBuilder()
                .name("war")
                .description("backdoor 在測試環境繞過鑑權")
                .modelRef(new ModelRef("string"))
                .parameterType("query")
                .required(false)
                .defaultValue("war123")
                .build());
        parameters.add(new ParameterBuilder()
                .name("uid")
                .description("backdoor 設定的用戶ID")
                .modelRef(new ModelRef("string"))
                .parameterType("query")
                .required(false)
                .defaultValue("1000053")
                .build());
        parameters.add(new ParameterBuilder()
                .name("Authorization")
                .description("生產環境中，須要傳遞的用戶當前 Token")
                .modelRef(new ModelRef("string"))
                .parameterType("header")
                .required(false)
                .defaultValue("Bearer XXXXX")
                .build());
        return parameters;
    }
}

以上配置類中，咱們能夠經過@Profile("!production")註解指定生效的環境，如這裏咱們設置除在生產環境外，其餘環境都生效。

3）、添加文檔內容

在完成上述配置後，其實已經能夠生產文檔內容了，可是這樣的文檔主要針對請求自己，描述的主要來源是函數的命名，多用戶並不友好，爲了讓文檔更加易於閱讀和理解，咱們能夠經過Swagger註解來增長一些說明。這些註解主要有：

@Api：用在類上，說明該類的做用。
@ApiOperation：註解來給API增長方法說明。
@ApiImplicitParams : 用在方法上包含一組參數說明。
@ApiImplicitParam：用來註解來給方法入參增長說明。
@ApiResponses：用於表示一組響應。
@ApiResponse：用在@ApiResponses中，通常用於表達一個錯誤的響應信息。
@ApiModel：描述一個Model的信息（通常用在請求參數沒法使用@ApiImplicitParam註解進行描述的時候）。

接下來，咱們經過一個實際的微服務接口定義案例來演示下：

@Api(value = "運維端系統用戶層外部接口", description = "用於組裝直接面向運維App端相關服務")
@RestController
@Slf4j
public class OperationUserController {

    @Autowired
    OperationUserService operationUserServiceImpl;

    @ApiOperation(value = "運維端用戶註冊", httpMethod = "POST")
    @RequestMapping(value = "/userRegister", method = RequestMethod.POST)
    public APIResponse sysUserRegister(@RequestParam(value = "mobileNo") String mobileNo,
            @RequestParam(value = "email") String email,
            @RequestParam(value = "nickName", required = false) String nickName,
            @RequestParam(value = "idName") String idName, @RequestParam(value = "idType") String idType,
            @RequestParam(value = "idNo") String idNo, @RequestParam(value = "gender") String gender,
            @RequestParam(value = "password") String password, @RequestParam(value = "verifyCode") String verifyCode,
            @RequestParam(value = "creator") String creator) {
        UserRegisterReqVo userRegisterReqVo = UserRegisterReqVo.builder().mobileNo(mobileNo).email(email)
                .nickName(nickName).idName(idName).idType(idType).idNo(idNo).gender(gender).passwd(password)
                .passcode(verifyCode).creator(creator).build();
        UserRegisterResVo userRegisterResVo;
        try {
            userRegisterResVo = operationUserServiceImpl.userRegister(userRegisterReqVo);
        } catch (BizException e) {
            log.error(e.toString() + "_" + e.getMessage(), e);
            return APIResponse.error(e.getCode(), e.getMessage());
        } catch (Exception e) {
            log.error(e.toString() + "_" + e.getMessage(), e);
            return APIResponse
                    .error(ApiResultStatus.INTERNAL_SERVER_ERROR.getApiResultStatus(),
                            ApiResultStatus.INTERNAL_SERVER_ERROR.getMessageResourceName());
        }
        return APIResponse
                .success(ApiResultStatus.SUCCESS.getApiResultStatus(), ApiResultStatus.SUCCESS.getMessageResourceName(),
                        userRegisterResVo);
    }
}

以上咱們在微服務下定義了一個用戶註冊接口，此時啓動微服務，而後輸入微服務的IP+端口+/swagger-ui.html，就能夠看到Swagger-UI了，以下：

經過Swagger-UI咱們就能夠校驗的方式測試接口了，同時由於接口字段都在UI有說明和暫時，而且是與實際代碼徹底一致的，因此在對接時基於這些接口定義進行對接就能夠了！

推薦閱讀：

Spring Boot集成Flyway實現數據庫版本控制？

Spring Cloud微服務如何實現熔斷降級？

Spring Cloud微服務如何設計異常處理機制？

Spring Cloud微服務中網關服務是如何實現的?（Zuul篇）

Spring Cloud是怎麼運行的？

基於SpringCloud的微服務架構演變史？

Spring Boot究竟是怎麼運行的，你知道嗎？

—————END—————

識別圖片二維碼，關注「無敵碼農」獲取精彩內容

本文分享自微信公衆號 - 無敵碼農（jiangqiaodege）。
若有侵權，請聯繫 support@oschina.cn 刪除。
本文參與「OSC源創計劃」，歡迎正在閱讀的你也加入，一塊兒分享。