基于springboot的web项目最佳实践

springboot 可以说是现在做javaweb开发最火的技术，我在基于springboot搭建项目的过程中，踩过不少坑，发现整合框架时并非仅仅引入starter 那么简单。

要做到简单，易用，扩展性更好，还需做不少二次封装，于是便写了个基于springboot的web项目脚手架，对一些常用的框架进行整合，并进行了简单的二次封装。

项目名baymax取自动画片超能陆战队里面的大白，大白是一个医护充气机器人，希望这个项目你能像大白一样贴心，可以减少你的工作量。

github https://github.com/zhaoguhong/baymax

web

web模块是开发web项目必不可少的一个模块

maven 依赖

    
      org.springframework.boot
      spring-boot-starter-web
    

对于前后端分离项目，推荐直接使用@RestController注解
需要注意的是，不建议直接用RequstMapping注解并且不指定方法类型的写法，推荐使用GetMaping或者PostMaping之类的注解

@SpringBootApplication
@RestController
public class BaymaxApplication {

  public static void main(String[] args) {
    SpringApplication.run(BaymaxApplication.class, args);
  }

  @GetMapping("/test")
  public String test() {
    return "hello baymax";
  }
}

单元测试

spring 对单元测试也提供了很好的支持

maven 依赖

    
      org.springframework.boot
      spring-boot-starter-test
      test
    

添加 @RunWith(SpringRunner.class) 和 @SpringBootTest 即可进行测试

@RunWith(SpringRunner.class)
@SpringBootTest
public class WebTest {
}

对于Controller层的接口，可以直接用MockMvc进行测试

@RunWith(SpringRunner.class)
@SpringBootTest
public class WebTest {

  @Autowired
  private WebApplicationContext context;
  private MockMvc mvc;

  @Before
  public void setUp() throws Exception {
    mvc = MockMvcBuilders.webAppContextSetup(context).build();
  }

  @Test
  public void testValidation() throws Exception {
    mvc.perform(MockMvcRequestBuilders.get("/test"))
        .andExpect(MockMvcResultMatchers.status().isOk())
        .andDo(MockMvcResultHandlers.print())
        .andExpect(MockMvcResultMatchers.content().string("hello baymax"));
  }

}

actuator应用监控

actuator 是 spring 提供的应用监控功能，常用的配置项如下

# actuator端口 默认应用端口
management.server.port=8082
# 加载所有的端点 默认只加载 info,health
management.endpoints.web.exposure.include=*
# actuator路径前缀，默认 /actuator
management.endpoints.web.base-path=/actuator

lombok

lombok可以在编译期生成对应的java代码，使代码看起来更简洁，同时减少开发工作量

用lombok后的实体类

@Data
public class Demo {
  private Long id;
  private String userName;
  private Integer age;
}

需要注意，@Data 包含 @ToString、@Getter、@Setter、@EqualsAndHashCode、@RequiredArgsConstructor，RequiredArgsConstructor 并不是无参构造，无参构造的注解是NoArgsConstructor

RequiredArgsConstructor 会生成 会生成一个包含常量（final），和标识了@NotNull的变量 的构造方法

baseEntity

把表中的基础字段抽离出来一个BaseEntity,所有的实体类都继承该类

/**
 * 实体类基础类
 */
@Data
public abstract class BaseEntity implements Serializable {
  /**
   * 主键id
   */
  private Long id;
  /**
   * 创建人
   */
  private Long createdBy;
  /**
   * 创建时间
   */
  private Date createdTime;
  /**
   * 更新人
   */
  private Long updatedBy;
  /**
   * 更新时间
   */
  private Date updatedTime;
  /**
   * 是否删除
   */
  private Integer isDeleted;

}

统一响应返回值

前后端分离项目基本上都是ajax调用，所以封装一个统一的返回对象有利于前端统一处理

/**
 * 用于 ajax 请求的响应工具类
 */
@Data
public class ResponseResult {
  // 未登录
  public static final String UN_LOGIN_CODE = "401";
  // 操作失败
  public static final String ERROR_CODE = "400";
  // 服务器内部执行错误
  public static final String UNKNOWN_ERROR_CODE = "500";
  // 操作成功
  public static final String SUCCESS_CODE = "200";
  // 响应信息
  private String msg;
  // 响应code
  private String code;
  // 操作成功，响应数据
  private T data;

  public ResponseResult(String code, String msg, T data) {
    this.msg = msg;
    this.code = code;
    this.data = data;
  }
}

返回给前端的值用ResponseResult包装一下

  /**
   * 测试成功的 ResponseResult
   */
  @GetMapping("/successResult")
  public ResponseResult> test() {
    List demos = demoMapper.getDemos();
    return ResponseResult.success(demos);
  }

  /**
   * 测试失败的 ResponseResult
   */
  @GetMapping("/errorResult")
  public ResponseResult> demo() {
    return ResponseResult.error("操作失败");
  }

ResponseEntity

spring其实封装了ResponseEntity 处理响应，ResponseEntity 包含 状态码，头部信息，响应体 三部分

  /**
   * 测试请求成功
   * @return
   */
  @GetMapping("/responseEntity")
  public ResponseEntity responseEntity() {
    return ResponseEntity.ok("请求成功");
  }

  /**
   * 测试服务器内部错误
   * @return
   */
  @GetMapping("/InternalServerError")
  public ResponseEntity responseEntityerror() {
    return new ResponseEntity<>("出错了", HttpStatus.INTERNAL_SERVER_ERROR);
  }

异常

自定义异常体系

为了方便异常处理，定义一套异常体系，BaymaxException 做为所有自定义异常的父类

// 项目所有自定义异常的父类
public class BaymaxException extends RuntimeException
// 业务异常 该异常的信息会返回给用户
public class BusinessException  extends BaymaxException
// 用户未登录异常
public class NoneLoginException  extends BaymaxException

全局异常处理

对所有的异常处理后再返回给前端

@RestControllerAdvice
public class GlobalControllerExceptionHandler {

  /**
   * 业务异常
   */
  @ExceptionHandler(value = {BusinessException.class})
  public ResponseResult handleBusinessException(BusinessException ex) {
    String msg = ex.getMessage();
    if (StringUtils.isBlank(msg)) {
      msg = "操作失败";
    }
    return ResponseResult.error(msg);
  }

  /**
   * 处理未登录异常
   */
  @ExceptionHandler(value = {NoneLoginException.class})
  public ResponseResult handleNoneLoginException(NoneLoginException ex) {
    return ResponseResult.unLogin();
  }

异常持久化

对于未知的异常，保存到数据库，方便后续排错

需要说明是的，如果项目访问量比较大，推荐用 ELK 这种成熟的日志分析系统，不推荐日志保存到关系型数据库

  @Autowired
  private ExceptionLogMapper exceptionLogMapper;
  /**
   * 处理未知的错误
   */
  @ExceptionHandler(value = {Exception.class})
  public ResponseResult handleunknownException(Exception ex) {
    ExceptionLog log = new ExceptionLog(new Date(), ExceptionUtils.getStackTrace(ex));
    exceptionLogMapper.insert(log);
    ResponseResult result = ResponseResult.unknownError("服务器异常:" + log.getId());
    result.setData(log.getId());
    return result;
  }

异常日志接口

对外开一个异常日志查询接口/anon/exception/{异常日志id}，方便查询

@RestController
@RequestMapping("/anon/exception")
public class ExceptionController {

  @Autowired
  private ExceptionLogMapper exceptionLogMapper;

  @GetMapping(value = "/{id}")
  public String getDemo(@PathVariable(value = "id") Long id) {
    return exceptionLogMapper.selectByPrimaryKey(id).getException();
  }

} 

数据校验

JSR 303定义了一系列的 Bean Validation 规范，Hibernate Validator 是 Bean Validation 的实现，并进行了扩展

spring boot 使用 也非常方便

public class Demo extends BaseEntity{
  @NotBlank(message = "用户名不允许为空")
  private String userName;
  @NotBlank
  private String title;
  @NotNull
  private Integer age;
}

参数前面添加@Valid注解即可

  @PostMapping("/add")
  public ResponseResult add(@RequestBody @Valid Demo demo) {
    demoMapper.insert(demo);
    return ResponseResult.success();
  }

对于校验结果可以每个方法单独处理，如果不处理，会抛出有异常，可以对校验的异常做全局处理

在 GlobalControllerExceptionHandler 添加

  /**
   * 处理校验异常
   */
  @ExceptionHandler(MethodArgumentNotValidException.class)
  public ResponseResult handleValidationException(MethodArgumentNotValidException ex) {
    BindingResult result = ex.getBindingResult();
    if (result.hasErrors()) {
      StringJoiner joiner = new StringJoiner("，");
      List errors = result.getAllErrors();
      errors.forEach(error -> {
        FieldError fieldError = (FieldError) error;
        joiner.add(fieldError.getField() + " " + error.getDefaultMessage());
      });
      return ResponseResult.error(joiner.toString());
    } else {
      return ResponseResult.error("操作失败");
    }
  }

log

spring boot 的默认使用的日志是logback,web模块依赖的有日志 starter，所以这里不用再引入依赖，详细配置

修改日志级别

Actuator 组件提供了日志相关接口，可以查询日志级别或者动态修改日志级别

// 查看所有包/类的日志级别
/actuator/loggers
// 查看指定包/类日志级别 get 请求
/actuator/loggers/com.zhaoguhong.baymax.demo.controller.DemoController
//修改日志级别 post 请求 参数 {"configuredLevel":"debug"}
/actuator/loggers/com.zhaoguhong.baymax.demo.controller.DemoController

日志切面

添加一个日志切面，方便记录方法执行的入参和出参

@Retention(RetentionPolicy.RUNTIME)
@Target(ElementType.METHOD)
public @interface LogAspect {

  /**
   * 日志描述
   */
  String value() default "";

  /**
   * 日志级别
   */
  String level() default "INFO";

}

使用时直接添加到方法上即可

swagger

swagger 是一个很好用的文档生成工具

maven 依赖

    
      io.springfox
      springfox-swagger2
      2.7.0
    
    
      io.springfox
      springfox-swagger-ui
      2.7.0
    

相关配置

@Configuration
@EnableSwagger2
public class SwaggerConfig {

  @Value("${swagger.enable:false}")
  private boolean swaggerEnable;

  //文档访问前缀
  public static final String ACCESS_PREFIX = "/swagger-resources/**,/swagger-ui.html**,/webjars/**,/v2/**";

  @Bean
  public Docket docket() {
    return new Docket(DocumentationType.SWAGGER_2)
        .apiInfo(apiInfo())
        // 设置是否开启swagger,生产环境关闭
        .enable(swaggerEnable)
        .select()
        // 当前包路径
        .apis(RequestHandlerSelectors.basePackage("com.zhaoguhong.baymax"))
        .apis(RequestHandlerSelectors.withMethodAnnotation(ApiOperation.class))
        .paths(PathSelectors.any())
        .build();
  }

  // 构建api文档的详细信息
  private ApiInfo apiInfo() {
    return new ApiInfoBuilder()
        // 页面标题
        .title("接口文档")
        // 创建人
        .contact(new Contact("孤鸿", "https://github.com/zhaoguhong/baymax", ""))
        // 版本号
        .version("1.0")
        // 描述
        .description("大白的接口文档")
        .build();
  }
}

为文档加一个开关

#是否开启swagger文档，生产环境关闭
swagger.enable=true

然后就可以愉快的在写代码的同时写文档了

  @PostMapping("/add")
  @ApiOperation(value = "新增 demo")
  public ResponseResult add(@RequestBody @Valid Demo demo) {
    demoMapper.insert(demo);
    return ResponseResult.success();
  }

@ApiModel("示例")
public class Demo extends BaseEntity{
  @ApiModelProperty("用户名")
  private String userName;
  @ApiModelProperty("标题")
  private String title;
  @ApiModelProperty("年龄")
  private Integer age;
}

访问 localhost:8080/swagger-ui.html 就可以看到效果了

数据库连接池

springboot1.X的数据库连接池是tomcat连接池，springboot2默认的数据库连接池由Tomcat换成 HikariCP，HikariCP是一个高性能的JDBC连接池，号称最快的连接池

Druid 是阿里巴巴数据库事业部出品，为监控而生的数据库连接池，这里选取Druid作为项目的数据库连接池

maven 依赖

    
      com.alibaba
      druid-spring-boot-starter
      1.1.10
    

设置用户名密码

spring.datasource.druid.stat-view-servlet.login-username=admin
spring.datasource.druid.stat-view-servlet.login-password=123456

然后就可以访问 localhost:8080/druid看监控信息了

spring jdbc

maven 依赖

     
      org.springframework.boot
      spring-boot-starter-jdbc
    

spring对jdbc做了封装和抽象，最常用的是 jdbcTemplate 和 NamedParameterJdbcTemplate两个类，前者使用占位符，后者使用命名参数，我在jdbcDao做了一层简单的封装，提供统一的对外接口

jdbcDao主要方法如下：

// 占位符
find(String sql, Object... args)
// 占位符，手动指定映射mapper
find(String sql, Object[] args, RowMapper rowMapper)
// 命名参数
find(String sql, Map paramMap)
// 命名参数，手动指定映射mapper
find(String sql, Map paramMap, RowMapper rowMapper)
//springjdbc 原queryForMap方法,如果没查询到会抛异常，此处如果没有查询到，返回null
queryForMap(String sql, Object... args)
queryForMap(String sql, Map paramMap)
// 分页查询
find(Page page, String sql, Map parameters, RowMapper mapper)
// 分页查询
find(Page page, String sql, RowMapper mapper, Object... args)

jpa

jpa 是 java 持久化的标准，spring data jpa 使操作数据库变得更方便，需要说明的 spring data jpa 本身并不是jpa的实现，它默认使用的 provider 是 hibernate

maven 依赖

    
      org.springframework.boot
      spring-boot-starter-data-jpa
    

我把通用的方法抽取了出来了，封装了一个BaseRepository，使用时，直接继承该接口即可

public interface DemoRepository extends BaseRepository {

}

BaseRepository 主要方法如下

// 新增，会对创建时间，创建人自动赋值
void saveEntity(T entity)
// 更新，会对更新时间，更新人自动赋值
void updateEntity(T entity)
// 逻辑删除
void deleteEntity(T entity)
// 批量保存
void saveEntites(Collection entitys)
// 批量更新
void updateEntites(Collection entitys)
// 批量逻辑删除
void deleteEntites(Collection entitys)
// 根据id获取实体，会过滤掉逻辑删除的
T getById(Long id)

如果想使用传统的sql形式，可以直接使用JpaDao,为了方便使用，我尽量使JpaDao和JdbcDao的接口保持统一

JpaDao主要方法如下

// 占位符 例如：from Demo where id =?
find(String sql, Object... args)
// 命名参数
find(String sql, Map paramMap)
// 分页
find(Page page, String hql, Map parameters)
// 分页
find(Page page, String hql, Object... parameters)

redis

Redis 是性能极佳key-value数据库，常用来做缓存，
java 中常用的客户端有 Jedis 和 Lettuce, spring data redis 是基于 Lettuce 做的二次封装

maven 依赖

    
      org.springframework.boot
      spring-boot-starter-data-redis
    

为了在redis读起来更方便，更改序列化方式

@Configuration
public class RedisConfig {

  /**
   * 设置序列化方式
   */
  @Bean
  public RedisTemplate redisTemplate(RedisConnectionFactory redisConnectionFactory) {
    RedisTemplate redisTemplate = new RedisTemplate<>();
    redisTemplate.setConnectionFactory(redisConnectionFactory);
    redisTemplate.setKeySerializer(RedisSerializer.string());
    redisTemplate.setValueSerializer(jackson2JsonRedisSerializer());
    redisTemplate.setHashKeySerializer(RedisSerializer.string());
    redisTemplate.setHashValueSerializer(jackson2JsonRedisSerializer());
    return redisTemplate;
  }

  @Bean
  public Jackson2JsonRedisSerializer