SpringBoot從入門到精通教程（二十六）- 全局header/body接口請求參數+Swagger2集成/接口規範用法

需求背景

在實際服務端API接口項目開發過程中，會有一些項目約定規範用法Tips，這次整理分享一下我過去使用過的，希望對你有用

問題痛點

• 項目開發時，沒有統一參數規範約定，App對接成本、代碼維護成本太高
• 過去開發人員寫代碼時，要寫很多必須要寫但是又重複的代碼，比如構造函數、getter/setter方法等
• 一個接口返回時，無論內部是返回成功、失敗、異常等，都統一返回了http狀態碼200，導致當集成監控工具時（因爲監控工具一般是檢測http狀態碼），無法監控區分，需要二次自定義開發/寫腳本等

Tips技術點

1. 接口參數規範

• 請求服務端接口時，統一使用全局header/body接口請求參數
• body參數統一使用DTO對象傳輸，使用註解@NotEmpty進行參數空校驗

2. 開發代碼規範

• 使用lombok組件，讓代碼更簡潔，實現優雅編碼
• 接口返回值需區分http狀態碼200

3. 集成swagger

十分簡單、簡潔易用的在線接口文檔組件swagger

Swagger入門教程用法：SpringBoot從入門到精通教程（二十四）- Swagger集成用法

代碼演示

1. 項目目錄結構

2. pom.xml依賴組件

<?xml version="1.0" encoding="UTF-8"?>
<project xmlns="http://maven.apache.org/POM/4.0.0"
	xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
	xsi:schemaLocation="http://maven.apache.org/POM/4.0.0 http://maven.apache.org/xsd/maven-4.0.0.xsd">
	<modelVersion>4.0.0</modelVersion>

	<parent>
		<groupId>com.md</groupId>
		<artifactId>spring-boot2-parent</artifactId>
		<version>0.0.1-SNAPSHOT</version>
		<relativePath>../pom.xml</relativePath>
	</parent>

	<artifactId>spring-boot2-swagger-req-params</artifactId>
	<packaging>jar</packaging>

	<name>spring-boot2-swagger-req-params</name>
	<description>Spring Boot, MVC, Rest API for App</description>

	<properties>
		<project.build.sourceEncoding>UTF-8</project.build.sourceEncoding>
		<java.version>1.8</java.version>
		<swagger.version>2.9.2</swagger.version>
	</properties>

	<dependencies>
		<dependency>
			<groupId>org.springframework.boot</groupId>
			<artifactId>spring-boot-starter</artifactId>
		</dependency>
		<!-- 構建成可運行的Web項目 -->
		<dependency>
			<groupId>org.springframework.boot</groupId>
			<artifactId>spring-boot-starter-web</artifactId>
		</dependency>
		<dependency>
			<groupId>net.sf.json-lib</groupId>
			<artifactId>json-lib-ext-spring</artifactId>
		</dependency>
		<!-- swagger集成 -->
		<dependency>
			<groupId>io.springfox</groupId>
			<artifactId>springfox-swagger2</artifactId>
			<version>${swagger.version}</version>
		</dependency>
		<!-- 默認swagger-ui -->
		<dependency>
			<groupId>io.springfox</groupId>
			<artifactId>springfox-swagger-ui</artifactId>
			<version>${swagger.version}</version>
		</dependency>
		<!-- 更易用第三方swagger-ui組件 -->
		<dependency>
			<groupId>com.github.xiaoymin</groupId>
			<artifactId>swagger-bootstrap-ui</artifactId>
			<version>1.9.3</version>
		</dependency>
		<dependency>
			<groupId>org.projectlombok</groupId>
			<artifactId>lombok</artifactId>
		</dependency>
		<dependency>
			<groupId>com.alibaba</groupId>
			<artifactId>fastjson</artifactId>
		</dependency>
	</dependencies>

	<build>
		<plugins>
			<plugin>
				<groupId>org.springframework.boot</groupId>
				<artifactId>spring-boot-maven-plugin</artifactId>
			</plugin>
		</plugins>
	</build>

</project>

3. 定義全局header參數

在SwaggerConfig.java文件中，可以新增全局header參數（接口定義本身不需要再重複寫了），所有接口會自動帶上這個參數，比如userId或者token等

我這裏使用了userId，完整代碼如下：

package com.md.demo;

import java.util.ArrayList;
import java.util.List;

import org.springframework.context.annotation.Bean;
import org.springframework.context.annotation.Configuration;

import springfox.documentation.builders.ApiInfoBuilder;
import springfox.documentation.builders.ParameterBuilder;
import springfox.documentation.builders.PathSelectors;
import springfox.documentation.builders.RequestHandlerSelectors;
import springfox.documentation.schema.ModelRef;
import springfox.documentation.service.ApiInfo;
import springfox.documentation.service.Parameter;
import springfox.documentation.spi.DocumentationType;
import springfox.documentation.spring.web.plugins.Docket;
import springfox.documentation.swagger2.annotations.EnableSwagger2;

@Configuration
@EnableSwagger2
public class SwaggerConfig {

	/**
	 * 創建一個Docket對象 調用select()方法， 生成ApiSelectorBuilder對象實例，該對象負責定義外漏的API入口
	 * 通過使用RequestHandlerSelectors和PathSelectors來提供Predicate，在此我們使用any()方法，將所有API都通過Swagger進行文檔管理
	 * 
	 * @return
	 */
	@Bean
	public Docket createRestApi() {
		// 定義全局header參數
		ParameterBuilder useridPar = new ParameterBuilder();
		List<Parameter> pars = new ArrayList<>();
		useridPar.name("userId").defaultValue("").description("用戶id").modelRef(new ModelRef("string"))
				.parameterType("header").required(false).build();
		pars.add(useridPar.build());
		
		return new Docket(DocumentationType.SWAGGER_2)
				.apiInfo(apiInfo()).select()
				//如果不想將所有的接口都通過swagger管理的話，可以將RequestHandlerSelectors.any()修改爲RequestHandlerSelectors.basePackage()
				//.apis(RequestHandlerSelectors.any())
				.apis(RequestHandlerSelectors.basePackage("com.md"))
				.paths(PathSelectors.any())
				.build()
				.globalOperationParameters(pars);
	}

	@SuppressWarnings("deprecation")
	private ApiInfo apiInfo() {
		return new ApiInfoBuilder()
				// 標題
				.title("SpringBoot2 中使用Swagger2 構建RESTful APIs")
				// 簡介
				.description("This a demo for Swagger2")
				// 服務條款
				.termsOfServiceUrl("https://blog.csdn.net/hemin1003")
				// 作者個人信息
				.contact("Minbo.He")
				// 版本
				.version("1.0").build();
	}
}

4. 定義DTO參數對象

GetByIdDTO.java

package com.md.demo.dto;

import javax.validation.constraints.NotEmpty;

import io.swagger.annotations.ApiModel;
import io.swagger.annotations.ApiModelProperty;
import lombok.Data;

@Data
@ApiModel("根據用戶ID標識查詢")
public class GetByIdDTO {

	@ApiModelProperty(value = "用戶ID標識", required = true)
	@NotEmpty(message = "用戶ID標識不能爲空")
	private String id;
}

5. 定義一個接口基類

BaseController.java，接收參數合法性校驗結果

package com.md.demo.util;

import java.util.List;

import org.springframework.validation.BindingResult;
import org.springframework.validation.ObjectError;

/**
 * 基類
 * 
 * @author Minbo
 *
 */
public class BaseController {

	@SuppressWarnings({ "rawtypes", "unchecked" })
	public JsonResult getJsonResult(Object model, BindingResult result) {
		if (result.hasErrors()) {
			StringBuilder stringBuilder = new StringBuilder();
			List<ObjectError> allErrors = result.getAllErrors();
			for (ObjectError objectError : allErrors) {
				String defaultMessage = objectError.getDefaultMessage();
				// 驗證失敗時提示內容一起拼接返回
				stringBuilder.append(defaultMessage).append(";");
			}
			return new JsonResult(CodeEnums.PARA_ERR.getCode(), stringBuilder.toString(), model);
		}
		return null;
	}
}

6. 定義一個http狀態碼工具類

HttpStatusCodeUtil.java

package com.md.demo.util;

import javax.servlet.http.HttpServletResponse;

import lombok.extern.slf4j.Slf4j;

/**
 * http響應碼工具類
 * 
 * @author Minbo
 *
 */
@Slf4j
public class HttpStatusCodeUtil {

	/**
	 * 設置http響應碼
	 * 
	 * @param response
	 * @param statusCode
	 */
	public static void setCode(HttpServletResponse response, Integer statusCode) {
		try {
			response.setStatus(statusCode);
		} catch (Exception ex) {
			log.error("設置http響應碼異常：" + ex.getMessage(), ex);
		}
	}
}

7. 接口訪問層（@RequestHeader和@RequestBody）

InitController.java

package com.md.demo.rest;

import org.slf4j.Logger;
import org.slf4j.LoggerFactory;
import org.springframework.web.bind.annotation.RequestHeader;
import org.springframework.web.bind.annotation.RequestMapping;
import org.springframework.web.bind.annotation.RestController;

import com.md.demo.util.JsonResult;

import io.swagger.annotations.ApiImplicitParam;
import io.swagger.annotations.ApiOperation;

/**
 * @author Minbo
 */
@RestController
public class InitController {

	protected static Logger logger = LoggerFactory.getLogger(InitController.class);

	/**
	 * http://localhost:9090/hello
	 * 
	 * @return
	 */
	@ApiOperation(value = "/hello 歡迎入口", httpMethod = "GET")
	@RequestMapping(value = "/hello")
	public String hello() {
		logger.info("hello");
		return "Hello greetings from spring-boot2-swagger-req-params";
	}

	@ApiOperation(value = "/getUserName 根據用戶id獲得用戶的姓名", notes = "id不能爲空", httpMethod = "GET")
	@ApiImplicitParam(dataType = "string", name = "userId", value = "用戶id", required = true)
	@RequestMapping(value = "/getUserName")
	@SuppressWarnings({ "rawtypes" })
	public JsonResult getUserName(@RequestHeader String userId) {
		String result = "hello " + userId + "，name=張三";
		return JsonResult.ok(result);
	}

	/**
	 * Swagger註解用法：
	 * 
	 * @Api：修飾整個類，描述Controller的作用
	 * @ApiOperation：描述一個類的一個方法，或者說一個接口
	 * @ApiParam：單個參數描述
	 * @ApiModel：用對象來接收參數
	 * @ApiProperty：用對象接收參數時，描述對象的一個字段
	 * @ApiResponse：HTTP響應其中1個描述
	 * @ApiResponses：HTTP響應整體描述
	 * @ApiIgnore：使用該註解忽略這個API
	 * @ApiError ：發生錯誤返回的信息
	 * @ApiImplicitParam：一個請求參數
	 * @ApiImplicitParams：多個請求參數
	 */
}

DemoController.java

package com.md.demo.rest;

import javax.servlet.http.HttpServletRequest;
import javax.servlet.http.HttpServletResponse;

import org.springframework.beans.factory.annotation.Autowired;
import org.springframework.validation.BindingResult;
import org.springframework.validation.annotation.Validated;
import org.springframework.web.bind.annotation.PostMapping;
import org.springframework.web.bind.annotation.RequestBody;
import org.springframework.web.bind.annotation.RequestMapping;
import org.springframework.web.bind.annotation.RestController;

import com.md.demo.dto.GetByIdDTO;
import com.md.demo.service.IUserService;
import com.md.demo.util.BaseController;
import com.md.demo.util.HttpStatusCodeUtil;
import com.md.demo.util.JsonResult;
import com.md.demo.vo.UserVO;

import io.swagger.annotations.Api;
import io.swagger.annotations.ApiOperation;
import lombok.extern.slf4j.Slf4j;

/**
 * @author Minbo
 */
@RestController
@RequestMapping("/demo")
@Api(tags = { "接口-演示" })
@Slf4j
public class DemoController extends BaseController {

	@Autowired
	private IUserService userService;

	@ApiOperation(value = "根據id獲得用戶信息", notes = "id不能爲空", httpMethod = "POST")
	@PostMapping(value = "/getUserById")
	@SuppressWarnings({ "rawtypes", "unchecked" })
	public JsonResult<UserVO> getUserById(@Validated @RequestBody GetByIdDTO dto, BindingResult result,
			HttpServletRequest request, HttpServletResponse response) {
		// 驗證參數合法性（@NotEmpty註解）
		JsonResult validResult = super.getJsonResult(dto, result);
		if (validResult != null) {
			// 設置http響應碼，利於監控工具，不要統一使用200
			HttpStatusCodeUtil.setCode(response, 4403);
			return validResult;
		}

		// 獲取用戶ID
		String userId = request.getHeader("userId");
		log.info("獲取用戶ID，userId={}", userId);

		// 邏輯處理
		UserVO obj = this.userService.getUserById(dto);
		return JsonResult.ok(obj);
	}
}

說明：

• 使用了註解@Validated，驗證@NotEmpty
• 使用了BindingResult對象，接收參數合法性檢查結果
• 如果參數校驗不通過，則自定義設置http響應碼
• 使用了@Slf4j註解，可自動集成log日誌輸出

接口測試

1. 接口自動增加了全局header參數

2. 接口body參數用法，以及自動附加了接口數據模型說明

返回數據模型說明：UserVO.java類

3. 接口成功時：響應返回內容

各個字段及內容，會自動映射對應上，客戶端接入時簡單、高效

4. 接口異常時：響應返回內容

完整源碼下載

我的Github源碼地址：

https://github.com/hemin1003/spring-boot-study/tree/master/spring-boot2-study/spring-boot2-parent/spring-boot2-swagger-req-params

下一章教程

SpringBoot從入門到精通教程（二十七）- @Valid註解用法詳解+全局處理器Exception優雅處理參數驗證用法

該系列教程

SpringBoot從入門到精通教程

Swagger入門教程用法：SpringBoot從入門到精通教程（二十四）- Swagger集成用法

我的專欄

• SpringBoot系列專欄
• 高可用高併發實戰專欄
• 微服務架構實戰
• DevOps實戰專欄
• 程序化廣告實戰專欄

 

 

至此，全部介紹就結束了

 

 

-------------------------------

-------------------------------

 

我的CSDN主頁

關於我（個人域名）

我的開源項目集Github

 

期望和大家一起學習，一起成長，共勉，O(∩_∩)O謝謝

歡迎交流問題，可加個人QQ 469580884，

或者，加我的羣號 751925591，一起探討交流問題

不講虛的，只做實幹家

Talk is cheap，show me the code