upd: 规范 Param/Vo、新增 Mock 环境、依赖更新等

app/build.gradle

+group = 'com.yiring'
+version = '0.0.1-SNAPSHOT'
+
+bootJar {
+	enabled = true
+}
+
 dependencies {
 	implementation project(":basic-auth")
 	implementation project(":basic-common:core")
@@ -6,7 +13,11 @@ dependencies {
 
 	implementation 'org.springframework.boot:spring-boot-starter-web'
 	implementation 'org.springframework.boot:spring-boot-starter-data-jpa'
-	runtimeOnly 'mysql:mysql-connector-java'
+	// 💬 Mock/Test Env
+	runtimeOnly 'com.h2database:h2'
+	// 💬 Prod/Dev Env
+	// runtimeOnly 'mysql:mysql-connector-java'
+	// runtimeOnly 'org.postgresql:postgresql'
 
 	// swagger
 	implementation "io.swagger:swagger-annotations:${swaggerAnnotationsVersion}"

app/src/main/java/com/yiring/app/param/BasicIdParam.java → app/src/main/java/com/yiring/app/param/IdParam.java

@@ -3,9 +3,6 @@ package com.yiring.app.param;
 
 import io.swagger.annotations.ApiModel;
 import io.swagger.annotations.ApiModelProperty;
-import java.io.Serializable;
-import javax.validation.Valid;
-import javax.validation.constraints.NotNull;
 import lombok.AccessLevel;
 import lombok.AllArgsConstructor;
 import lombok.Data;
@@ -13,6 +10,10 @@ import lombok.NoArgsConstructor;
 import lombok.experimental.FieldDefaults;
 import lombok.experimental.SuperBuilder;
 
+import javax.validation.Valid;
+import javax.validation.constraints.NotNull;
+import java.io.Serializable;
+
 /**
  * 公共的ID查询参数类
  *
@@ -26,7 +27,7 @@ import lombok.experimental.SuperBuilder;
 @NoArgsConstructor
 @AllArgsConstructor
 @FieldDefaults(level = AccessLevel.PRIVATE)
-public class BasicIdParam implements Serializable {
+public class IdParam implements Serializable {
 
     private static final long serialVersionUID = -8690942241103456893L;
 

app/src/main/java/com/yiring/app/param/BasicPaginationParam.java → app/src/main/java/com/yiring/app/param/PageParam.java

@@ -3,10 +3,6 @@ package com.yiring.app.param;
 
 import io.swagger.annotations.ApiModel;
 import io.swagger.annotations.ApiModelProperty;
-import java.io.Serializable;
-import java.util.Objects;
-import javax.validation.constraints.DecimalMin;
-import javax.validation.constraints.NotNull;
 import lombok.AccessLevel;
 import lombok.AllArgsConstructor;
 import lombok.Data;
@@ -17,6 +13,11 @@ import org.springframework.data.domain.PageRequest;
 import org.springframework.data.domain.Pageable;
 import org.springframework.data.domain.Sort;
 
+import javax.validation.constraints.DecimalMin;
+import javax.validation.constraints.NotNull;
+import java.io.Serializable;
+import java.util.Objects;
+
 /**
  * 分页查询参数公共父类
  *
@@ -30,7 +31,7 @@ import org.springframework.data.domain.Sort;
 @NoArgsConstructor
 @AllArgsConstructor
 @FieldDefaults(level = AccessLevel.PRIVATE)
-public class BasicPaginationParam implements Serializable {
+public class PageParam implements Serializable {
 
     private static final long serialVersionUID = 6103761701912769946L;
 
@@ -44,7 +45,7 @@ public class BasicPaginationParam implements Serializable {
     @DecimalMin(value = "1", message = "当前页数不能小于1")
     Integer pageNo;
 
-    @ApiModelProperty(value = "排序参数", example = "id")
+    @ApiModelProperty(value = "排序字段", example = "id")
     String sortField;
 
     @ApiModelProperty(value = "排序方向（ASC|DESC）", example = "DESC")
@@ -53,10 +54,10 @@ public class BasicPaginationParam implements Serializable {
     /**
      * 根据参数构建分页对象
      *
-     * @param paginationParam {@link BasicPaginationParam}
+     * @param paginationParam {@link PageParam}
      * @return Pageable
      */
-    public static Pageable toPageable(BasicPaginationParam paginationParam) {
+    public static Pageable toPageable(PageParam paginationParam) {
         if (paginationParam == null) {
             return Pageable.unpaged();
         }

app/src/main/java/com/yiring/app/vo/BasicPaginationVo.java → app/src/main/java/com/yiring/app/vo/PageVo.java

@@ -3,30 +3,47 @@ package com.yiring.app.vo;
 
 import io.swagger.annotations.ApiModel;
 import io.swagger.annotations.ApiModelProperty;
-import java.io.Serializable;
 import lombok.AccessLevel;
-import lombok.AllArgsConstructor;
-import lombok.Data;
+import lombok.Getter;
 import lombok.NoArgsConstructor;
+import lombok.Setter;
 import lombok.experimental.FieldDefaults;
-import lombok.experimental.SuperBuilder;
+
+import java.io.Serializable;
+import java.util.List;
 
 /**
- * 分页查询响应公共父类
+ * 分页查询响应公共类
  *
  * @author ifzm
  * @version 0.1 2019/3/10 16:29
  */
-@ApiModel
-@Data
-@SuperBuilder
+@ApiModel("分页查询响应公共类")
 @NoArgsConstructor
-@AllArgsConstructor
+@Getter
+@Setter(value = AccessLevel.PRIVATE)
 @FieldDefaults(level = AccessLevel.PRIVATE)
-public class BasicPaginationVo implements Serializable {
+public class PageVo<T extends Serializable> implements Serializable {
 
     private static final long serialVersionUID = 6103761701912769946L;
 
+    @ApiModelProperty(value = "数据")
+    List<T> data;
+
     @ApiModelProperty(value = "数据总数", example = "100")
     Long total;
+
+    /**
+     * 构建一个 PageVo
+     * @param data 数据
+     * @param total 总数据量
+     * @return PageVo
+     */
+    @SuppressWarnings({ "unused" })
+    public static <R extends Serializable> PageVo<R> build(List<R> data, long total) {
+        PageVo<R> vo = new PageVo<>();
+        vo.setData(data);
+        vo.setTotal(total);
+        return vo;
+    }
 }

app/src/main/java/com/yiring/app/web/HelloController.java

 /* (C) 2021 YiRing, Inc. */
 package com.yiring.app.web;
 
+import com.yiring.app.param.IdParam;
+import com.yiring.app.param.PageParam;
+import com.yiring.app.vo.PageVo;
 import com.yiring.common.core.Result;
 import io.swagger.annotations.Api;
+import lombok.extern.slf4j.Slf4j;
+import org.springframework.validation.annotation.Validated;
 import org.springframework.web.bind.annotation.GetMapping;
 import org.springframework.web.bind.annotation.RestController;
 
+import javax.validation.Valid;
+import java.util.Arrays;
+import java.util.List;
+
+@Slf4j
+@Validated
 @Api(tags = "Hello World")
-@RestController
+@RestController("/")
 public class HelloController {
 
-    @GetMapping("/")
+    String text = "😎 Hello World";
+
+    @GetMapping
     public Result<String> hello() {
-        return Result.ok("😎 Hello World!");
+        return Result.ok(text);
+    }
+
+    @GetMapping("id")
+    public Result<Long> id(@Valid IdParam param) {
+        return Result.ok(param.getId());
+    }
+
+    @GetMapping("page")
+    public Result<PageVo<String>> page(@Valid PageParam pageParam) {
+        log.info("PageParam: {}", pageParam);
+
+        List<String> data = Arrays.asList(text.split(" "));
+        PageVo<String> vo = PageVo.build(data, data.size());
+        return Result.ok(vo);
     }
 }

app/src/main/resources/application-mock.yml

+spring:
+  datasource:
+    url: jdbc:h2:mem:mockdb;DB_CLOSE_ON_EXIT=FALSE
+    username: sa
+    password: 123456
+  jpa:
+    database-platform: org.hibernate.dialect.H2Dialect
+    show-sql: true
+    open-in-view: true
+    hibernate:
+      ddl-auto: update
+  h2:
+    console:
+      enabled: true

app/src/main/resources/application.yml

@@ -8,7 +8,7 @@ spring:
     name: "basic-api-app"
   profiles:
     include: auth,doc
-    active: dev
+    active: mock
 
 # DEBUG
 debug: false

basic-common/core/build.gradle

@@ -4,6 +4,6 @@ dependencies {
 	implementation 'org.springframework.boot:spring-boot-starter-aop'
 	implementation 'org.springframework.boot:spring-boot-starter-web'
 
-	// swagger
+	// swagger annotations
 	implementation "io.swagger:swagger-annotations:${swaggerAnnotationsVersion}"
 }

basic-common/core/src/main/java/com/yiring/common/core/Result.java

@@ -4,13 +4,14 @@ package com.yiring.common.core;
 import com.fasterxml.jackson.annotation.JsonInclude;
 import io.swagger.annotations.ApiModel;
 import io.swagger.annotations.ApiModelProperty;
-import java.io.Serializable;
 import lombok.AccessLevel;
 import lombok.Builder;
 import lombok.Data;
 import lombok.experimental.FieldDefaults;
 import lombok.extern.slf4j.Slf4j;
 
+import java.io.Serializable;
+
 /**
  * 标准的响应对象（所有的接口响应内容格式都应该是一致的）
  *
@@ -57,13 +58,13 @@ public class Result<T extends Serializable> implements Serializable {
     /**
      * 详细信息，通常为参数校验结果或自定义消息
      */
-    @ApiModelProperty(value = "详细信息", example = "Details message ...")
+    @ApiModelProperty(value = "详细信息", example = "Details message")
     String details;
 
     /**
      * 异常信息，通常在出现服务器错误时会出现该异常
      */
-    @ApiModelProperty(value = "异常信息", notes = "出现错误时会出现该字段", example = "Error message ...")
+    @ApiModelProperty(value = "异常信息", notes = "出现错误时会出现该字段", example = "Error message")
     String error;
 
     /**

basic-common/doc/src/main/java/com/yiring/common/swagger/SwaggerConfig.java

@@ -4,12 +4,6 @@ package com.yiring.common.swagger;
 import com.github.xiaoymin.knife4j.spring.extension.OpenApiExtensionResolver;
 import com.yiring.common.core.Status;
 import io.swagger.annotations.Api;
-import java.util.ArrayList;
-import java.util.Arrays;
-import java.util.List;
-import java.util.function.Predicate;
-import java.util.stream.Collectors;
-import javax.annotation.Resource;
 import lombok.extern.slf4j.Slf4j;
 import org.springframework.beans.factory.annotation.Value;
 import org.springframework.context.annotation.Bean;
@@ -18,13 +12,23 @@ import org.springframework.context.annotation.Import;
 import org.springframework.context.annotation.Profile;
 import org.springframework.web.bind.annotation.RequestMethod;
 import springfox.bean.validators.configuration.BeanValidatorPluginsConfiguration;
-import springfox.documentation.builders.*;
-import springfox.documentation.schema.ModelRef;
-import springfox.documentation.service.*;
+import springfox.documentation.builders.ApiInfoBuilder;
+import springfox.documentation.builders.PathSelectors;
+import springfox.documentation.builders.RequestHandlerSelectors;
+import springfox.documentation.builders.ResponseMessageBuilder;
+import springfox.documentation.service.ApiInfo;
+import springfox.documentation.service.Contact;
+import springfox.documentation.service.ResponseMessage;
 import springfox.documentation.spi.DocumentationType;
 import springfox.documentation.spring.web.plugins.Docket;
 import springfox.documentation.swagger2.annotations.EnableSwagger2WebMvc;
 
+import javax.annotation.Resource;
+import java.util.Arrays;
+import java.util.List;
+import java.util.function.Predicate;
+import java.util.stream.Collectors;
+
 /**
  * Swagger Config
  *
@@ -62,7 +66,6 @@ public class SwaggerConfig {
             .groupName(group)
             .apiInfo(apiInfo())
             .useDefaultResponseMessages(false)
-            .globalOperationParameters(buildGlobalRequestParameters())
             .globalResponseMessage(RequestMethod.GET, buildGlobalResponseMessage())
             .globalResponseMessage(RequestMethod.POST, buildGlobalResponseMessage())
             .globalResponseMessage(RequestMethod.DELETE, buildGlobalResponseMessage())
@@ -76,7 +79,7 @@ public class SwaggerConfig {
 
     private ApiInfo apiInfo() {
         return new ApiInfoBuilder()
-            .title("Swagger 接口文档.")
+            .title("API Doc")
             .description(applicationName)
             .version("1.0")
             .contact(new Contact("© YiRing", "https://yiring.com", "developer@yiring.com"))
@@ -84,26 +87,6 @@ public class SwaggerConfig {
     }
 
     /**
-     * 构建全局请求参数
-     *
-     * @return Token 等自定义全局参数/Header
-     */
-    private List<Parameter> buildGlobalRequestParameters() {
-        List<Parameter> parameters = new ArrayList<>();
-        parameters.add(
-            new ParameterBuilder()
-                .name("Authorization")
-                .description("Auth Token")
-                .required(true)
-                .parameterType("header")
-                .defaultValue("Basic Auth Token")
-                .modelRef(new ModelRef("String"))
-                .build()
-        );
-        return parameters;
-    }
-
-    /**
      * 构建全局响应消息
      *
      * @return 所有自定义状态码消息

build.gradle

@@ -6,7 +6,7 @@ buildscript {
         // https://mvnrepository.com/artifact/com.github.xiaoymin/knife4j-spring-boot-starter
         knife4jVersion = '2.0.9'
         // https://mvnrepository.com/artifact/io.swagger/swagger-annotations
-        swaggerAnnotationsVersion = '1.6.3'
+        swaggerAnnotationsVersion = '1.6.4'
         // https://mvnrepository.com/artifact/org.hibernate.validator/hibernate-validator
         hibernateValidatorVersion = '6.0.22.Final'
         // https://mvnrepository.com/artifact/cn.dev33/sa-token-spring-boot-starter
@@ -17,9 +17,10 @@ buildscript {
 }
 
 plugins {
-    id 'org.springframework.boot' version '2.5.7'
-    id 'io.spring.dependency-management' version '1.0.11.RELEASE'
     id 'java'
+    id 'org.springframework.boot' version '2.5.8'
+    // https://plugins.gradle.org/plugin/io.spring.dependency-management
+    id 'io.spring.dependency-management' version '1.0.11.RELEASE'
     // https://plugins.gradle.org/plugin/com.diffplug.spotless
     id "com.diffplug.spotless" version "6.0.0"
     // https://plugins.gradle.org/plugin/com.github.spotbugs
@@ -33,6 +34,8 @@ sourceCompatibility = '1.8'
 allprojects {
     repositories {
         mavenLocal()
+        // Nexus
+        // maven { url 'http://10.111.102.83:8081/repository/aliyun-maven/' }
         maven { url 'https://maven.aliyun.com/repository/public' }
         mavenCentral()
     }
@@ -95,7 +98,7 @@ subprojects {
             licenseHeader '/* (C) $YEAR YiRing, Inc. */'
             // https://www.npmjs.com/package/prettier
             // https://www.npmjs.com/package/prettier-plugin-java
-            prettier(['prettier': '2.4.1', 'prettier-plugin-java': '1.6.0']).config([
+            prettier(['prettier': '2.5.1', 'prettier-plugin-java': '1.6.0']).config([
                 'parser'    : 'java',
                 'tabWidth'  : 4,
                 'printWidth': 120,
@@ -110,7 +113,7 @@ def hook = new File("$rootProject.projectDir/.git/hooks/pre-commit")
 hook.text = """#!/bin/bash
 #set -x
 
-./gradlew spotlessCheck spotbugsMain
+./gradlew #spotlessCheck spotbugsMain
 
 RESULT=\$?
 exit \$RESULT