Angular 8集成Spring Boot 2详解

主要内容：Spring Boot 2基础知识、异常处理、测试、CORS配置、Actuator监控，集成springfox-swagger生成JSON API文档；利用Swagger UI、Postman进行Rest API测试；Angular基础知识、国际化、测试、NZ-ZORRO；Angular与Spring Boot、Spring Security、JWT集成的方法；Spring Boot、Angular集成Sonar、Jenkins等。

本文参考了Rich Freedman先生的博客"Integrating Angular 2 with Spring Boot, JWT, and CORS"，使用了部分代码(tour-of-heroes-jwt-full)，博客地址请见文末参考文档。前端基于Angular官方样例Tour of Heroes。完整源码请从github下载：heroes-api, heroes-web 。

技术堆栈

• Spring Boot 2.1.6.RELEASE
• Spring Security
• Spring Data
• Spring Actuator
• JWT
• Springfox Swagger 2.9.2
• Angular 8.0

测试工具： Postman
代码质量检查： Sonar
CI： Jenkins
推荐IDE： IntelliJ IDEA、WebStorm/Visual Studio Code

Java代码中使用了lombok注解，IDE需安装lombok插件。

Spring Boot

创建Spring Boot App

创建Spring Boot项目最简易的方式是使用SPRING INITIALIZR

输入Group、Artifact，选择Dependency（Web、JPA、Security、Actuator、H2、PostgreSQL、Lombok）后，点击Generate the project，会生成zip包。下载后解压，编辑POM文件，添加java-jwt和springfox-swagger。我们选用了两个数据库H2、PostgreSQL，分别用于开发、测试环境，将其修改到两个profile dev和prod内。完成的POM文件如下：

    4.0.0

    org.itrunner
    heroes-api
    1.0.0
    jar

    heroes
    Demo project for Spring Boot

    
        org.springframework.boot
        spring-boot-starter-parent
        2.1.6.RELEASE
        
    

    
        UTF-8
        UTF-8
        dev
        1.8
    

    
        
            dev
            
            
                dev
            
            
                
                    com.h2database
                    h2
                    runtime
                
            
        

        
            prod
            
                prod
            
            
                
                    org.postgresql
                    postgresql
                    runtime
                
            
        
    

    
        
            org.springframework.boot
            spring-boot-starter-data-jpa
        
        
            org.springframework.boot
            spring-boot-starter-web
        
        
            org.springframework.boot
            spring-boot-starter-security
        
        
            org.springframework.boot
            spring-boot-starter-actuator
        
        
            com.auth0
            java-jwt
            3.8.1
        
        
            io.springfox
            springfox-swagger2
            2.9.2
        
        
            io.springfox
            springfox-swagger-ui
            2.9.2
        
        
            org.projectlombok
            lombok
            true
        
        
            org.springframework.boot
            spring-boot-starter-test
            test
        
        
            org.springframework.security
            spring-security-test
            test
        
    

    
        
            
                org.springframework.boot
                spring-boot-maven-plugin
            
        
    

Application配置

Spring Boot可以零配置运行，为适应不同的环境可添加配置文件application.properties或application.yml来自定义配置、扩展配置。
本文以YML为例，dev和prod profile使用了不同的配置文件：
application.yml

spring:
  profiles:
    active: @project.profile@
  banner:
    charset: utf-8
    image:
      location: classpath:banner.jpg
    location: classpath:banner.txt
  messages:
    encoding: UTF-8
    basename: messages
  resources:
    add-mappings: true

management:
  server:
    port: 8090
  endpoints:
    web:
      base-path: /actuator
      exposure:
        include: health,info
  endpoint:
    health:
      show-details: always
info:
  app:
    name: heroes
    version: 1.0

springfox:
  documentation:
    swagger:
      v2:
        path: /api-docs

api:
  base-path: /api

cors:
  allowed-origins: "*"
  allowed-methods: GET,POST,DELETE,PUT,OPTIONS
  allowed-headers: Accept,Accept-Encoding,Accept-Language,Authorization,Connection,Content-Type,Host,Origin,Referer,User-Agent,X-Requested-With

jwt:
  header: Authorization
  secret: mySecret
  expiration: 7200
  issuer: ITRunner
  authentication-path: /api/auth

application-dev.yml

spring:
  jpa:
    hibernate:
      ddl-auto: create-drop
    properties:
      hibernate:
        format_sql: true
    show-sql: true
  datasource:
    platform: h2
    initialization-mode: always
server:
  port: 8080
cors:
  allowed-origins: "*"

application-prod.yml

spring:
  jpa:
    database-platform: org.hibernate.dialect.PostgreSQLDialect
    hibernate:
      ddl-auto: update
    properties:
      hibernate:
        default_schema: heroes
        format_sql: true
        jdbc:
          lob:
            non_contextual_creation: true
    show-sql: true
  datasource:
    platform: postgresql
    driver-class-name: org.postgresql.Driver
    url: jdbc:postgresql://localhost:5432/postgres
    username: hero
    password: mypassword
    initialization-mode: never
server:
  port: 8000
cors:
  allowed-origins: itrunner.org

配置文件中包含了Banner、Swagger、CORS、JWT、Actuator、Profile等内容，其中active profile使用@project.profile@与pom属性建立了关联，这些将在后面的演示中用到。

下面是用来读取自定义配置的类Config:

package org.itrunner.heroes.config;

import org.springframework.boot.context.properties.ConfigurationProperties;
import org.springframework.stereotype.Component;

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

@Component
@ConfigurationProperties
public class Config {

    private Cors cors = new Cors();

    private Jwt jwt = new Jwt();

    // getter & setter

    public static class Cors {
        private List allowedOrigins = new ArrayList<>();

        private List allowedMethods = new ArrayList<>();

        private List allowedHeaders = new ArrayList<>();

        // getter & setter
    }

    public static class Jwt {
        private String header;

        private String secret;

        private Long expiration;

        private String issuer;

        private String authenticationPath;

        // getter & setter
    }
}

自定义Banner

  banner:
    charset: utf-8
    image:
      location: classpath:banner.jpg
    location: classpath:banner.txt
  resources:
    add-mappings: true

Spring Boot启动时会在控制台输出Banner信息，支持文本和图片。图片支持gif、jpg、png等格式，会转换成ASCII码输出。

Log配置

Spring Boot Log支持Java Util Logging、 Log4J2、Logback，默认使用Logback。Log可以在application.properties或application.yml中配置。
application.properties:

logging.file=/var/log/heroes.log
logging.level.org.springframework.web=debug

也可以使用单独的配置文件(放在resources目录下)
logback-spring.xml:

国际化

在配置文件中，可以定义国际化资源文件位置、编码，默认分别为messages、UTF-8：

messages:
  encoding: UTF-8
  basename: messages

messages.properties

hero.notFound=Could not find hero with id {0}

Messages Component

package org.itrunner.heroes.util;

import org.springframework.context.MessageSource;
import org.springframework.context.i18n.LocaleContextHolder;
import org.springframework.stereotype.Component;

import javax.annotation.Resource;

@Component
public class Messages {
    @Resource
    private MessageSource messageSource;

    public String getMessage(String code) {
        return getMessage(code, null);
    }

    public String getMessage(String code, Object[] objects) {
        return messageSource.getMessage(code, objects, LocaleContextHolder.getLocale());
    }
}

初始化数据

配置中可定义Spring Boot启动时是否初始化数据：

  datasource:
    initialization-mode: always

在resources下创建data.sql文件，内容如下：

INSERT INTO HERO(ID, HERO_NAME, CREATE_BY, CREATE_TIME) VALUES(NEXTVAL('HERO_SEQ'), 'Dr Nice', 'admin', to_date('01-07-2019', 'dd-MM-yyyy'));
INSERT INTO HERO(ID, HERO_NAME, CREATE_BY, CREATE_TIME) VALUES(NEXTVAL('HERO_SEQ'), 'Narco', 'admin', to_date('01-07-2019', 'dd-MM-yyyy'));
INSERT INTO HERO(ID, HERO_NAME, CREATE_BY, CREATE_TIME) VALUES(NEXTVAL('HERO_SEQ'), 'Bombasto', 'admin', to_date('01-07-2019', 'dd-MM-yyyy'));
INSERT INTO HERO(ID, HERO_NAME, CREATE_BY, CREATE_TIME) VALUES(NEXTVAL('HERO_SEQ'), 'Celeritas', 'admin', to_date('01-07-2019', 'dd-MM-yyyy'));
INSERT INTO HERO(ID, HERO_NAME, CREATE_BY, CREATE_TIME) VALUES(NEXTVAL('HERO_SEQ'), 'Magneta', 'admin', to_date('01-07-2019', 'dd-MM-yyyy'));
INSERT INTO HERO(ID, HERO_NAME, CREATE_BY, CREATE_TIME) VALUES(NEXTVAL('HERO_SEQ'), 'RubberMan', 'admin', to_date('01-07-2019', 'dd-MM-yyyy'));
INSERT INTO HERO(ID, HERO_NAME, CREATE_BY, CREATE_TIME) VALUES(NEXTVAL('HERO_SEQ'), 'Dynama', 'admin', to_date('01-07-2019', 'dd-MM-yyyy'));
INSERT INTO HERO(ID, HERO_NAME, CREATE_BY, CREATE_TIME) VALUES(NEXTVAL('HERO_SEQ'), 'Dr IQ', 'admin', to_date('01-07-2019', 'dd-MM-yyyy'));
INSERT INTO HERO(ID, HERO_NAME, CREATE_BY, CREATE_TIME) VALUES(NEXTVAL('HERO_SEQ'), 'Magma', 'admin', to_date('01-07-2019', 'dd-MM-yyyy'));
INSERT INTO HERO(ID, HERO_NAME, CREATE_BY, CREATE_TIME) VALUES(NEXTVAL('HERO_SEQ'), 'Tornado', 'admin', to_date('01-07-2019', 'dd-MM-yyyy'));

INSERT INTO USERS(ID, USERNAME, PASSWORD, EMAIL, ENABLED) VALUES (NEXTVAL('USER_SEQ'), 'admin', '$2a$08$lDnHPz7eUkSi6ao14Twuau08mzhWrL4kyZGGU5xfiGALO/Vxd5DOi', '[email protected]', TRUE);
INSERT INTO USERS(ID, USERNAME, PASSWORD, EMAIL, ENABLED) VALUES (NEXTVAL('USER_SEQ'), 'jason', '$2a$10$6m2VoqZAxa.HJNErs2lZyOFde92PzjPqc88WL2QXYT3IXqZmYMk8i', '[email protected]', TRUE);
INSERT INTO USERS(ID, USERNAME, PASSWORD, EMAIL, ENABLED) VALUES (NEXTVAL('USER_SEQ'), 'coco', '$2a$10$TBPPC.JbSjH1tuauM8yRauF2k09biw8mUDmYHMREbNSXPWzwY81Ju', '[email protected]', FALSE);

INSERT INTO AUTHORITY (ID, AUTHORITY_NAME) VALUES (NEXTVAL('AUTHORITY_SEQ'), 'ROLE_USER');
INSERT INTO AUTHORITY (ID, AUTHORITY_NAME) VALUES (NEXTVAL('AUTHORITY_SEQ'), 'ROLE_ADMIN');

INSERT INTO USER_AUTHORITY (USER_ID, AUTHORITY_ID) VALUES (1, 1);
INSERT INTO USER_AUTHORITY (USER_ID, AUTHORITY_ID) VALUES (1, 2);
INSERT INTO USER_AUTHORITY (USER_ID, AUTHORITY_ID) VALUES (2, 1);
INSERT INTO USER_AUTHORITY (USER_ID, AUTHORITY_ID) VALUES (3, 1);

说明：

1. 不同数据库语法不同时，需分别创建初始化文件，命名格式data-${platform}.sql，比如data-h2.sql、data-postgresql.sql
2. 密码与用户名相同

Domain

在"Tour of Heroes"中使用了angular-in-memory-web-api，此处使用H2嵌入式数据库取代，增加Hero Domain。
Hero Domain

package org.itrunner.heroes.domain;

import lombok.Data;
import lombok.NoArgsConstructor;

import javax.persistence.*;
import javax.validation.constraints.NotNull;
import javax.validation.constraints.Size;
import java.util.Date;

@Entity
@Data
@NoArgsConstructor
@Table(name = "HERO", uniqueConstraints = {@UniqueConstraint(name = "UK_HERO_NAME", columnNames = {"HERO_NAME"})})
public class Hero {
    @Id
    @Column(name = "ID")
    @GeneratedValue(strategy = GenerationType.SEQUENCE, generator = "HERO_SEQ")
    @SequenceGenerator(name = "HERO_SEQ", sequenceName = "HERO_SEQ", allocationSize = 1)
    private Long id;

    @NotNull
    @Size(min = 3, max = 30)
    @Column(name = "HERO_NAME", length = 30, nullable = false)
    private String name;

    @Column(name = "CREATE_BY", length = 50, updatable = false, nullable = false)
    private String createBy;

    @Column(name = "CREATE_TIME", updatable = false, nullable = false)
    @Temporal(TemporalType.TIMESTAMP)
    private Date createTime;

    @Column(name = "LAST_MODIFIED_BY", length = 50)
    private String lastModifiedBy;

    @Column(name = "LAST_MODIFIED_TIME")
    @Temporal(TemporalType.TIMESTAMP)
    private Date lastModifiedTime;

    public Hero(Long id, String name) {
        this.id = id;
        this.name = name;
    }
}

在我们的例子中，包含用户验证功能，新增User、Authority Domain：
User Domain

package org.itrunner.heroes.domain;

import lombok.Getter;
import lombok.Setter;

import javax.persistence.*;
import javax.validation.constraints.NotNull;
import javax.validation.constraints.Size;
import java.util.List;

@Entity
@Getter
@Setter
@Table(name = "USERS", uniqueConstraints = {
        @UniqueConstraint(name = "UK_USERS_USERNAME", columnNames = {"USERNAME"}),
        @UniqueConstraint(name = "UK_USERS_EMAIL", columnNames = {"EMAIL"})})
public class User {
    @Id
    @Column(name = "ID")
    @GeneratedValue(strategy = GenerationType.SEQUENCE, generator = "USER_SEQ")
    @SequenceGenerator(name = "USER_SEQ", sequenceName = "USER_SEQ", allocationSize = 1)
    private Long id;

    @Column(name = "USERNAME", length = 50, nullable = false)
    @NotNull
    @Size(min = 4, max = 50)
    private String username;

    @Column(name = "PASSWORD", length = 100, nullable = false)
    @NotNull
    @Size(min = 4, max = 100)
    private String password;

    @Column(name = "EMAIL", length = 50, nullable = false)
    @NotNull
    @Size(min = 4, max = 50)
    private String email;

    @Column(name = "ENABLED")
    @NotNull
    private Boolean enabled;

    @ManyToMany(fetch = FetchType.EAGER)
    @JoinTable(name = "USER_AUTHORITY", joinColumns = {@JoinColumn(name = "USER_ID", referencedColumnName = "ID", foreignKey = @ForeignKey(name = "FK_USER_ID"))},
            inverseJoinColumns = {@JoinColumn(name = "AUTHORITY_ID", referencedColumnName = "ID", foreignKey = @ForeignKey(name = "FK_AUTHORITY_ID"))})
    private List authorities;
}

Authority Domain

package org.itrunner.heroes.domain;

import lombok.Data;

import javax.persistence.*;
import javax.validation.constraints.NotNull;
import java.util.List;

@Entity
@Data
@Table(name = "AUTHORITY")
public class Authority {
    @Id
    @Column(name = "ID")
    @GeneratedValue(strategy = GenerationType.SEQUENCE, generator = "AUTHORITY_SEQ")
    @SequenceGenerator(name = "AUTHORITY_SEQ", sequenceName = "AUTHORITY_SEQ", allocationSize = 1)
    private Long id;

    @Column(name = "AUTHORITY_NAME", length = 50, nullable = false)
    @NotNull
    @Enumerated(EnumType.STRING)
    private AuthorityName name;

    @ManyToMany(mappedBy = "authorities", fetch = FetchType.LAZY)
    private List users;
}

AuthorityName

package org.itrunner.heroes.domain;

public enum AuthorityName {
    ROLE_USER, ROLE_ADMIN
}

Repository

JpaRepository提供了常用的方法，仅需增加一些自定义实现：
HeroRepository

package org.itrunner.heroes.repository;

import org.itrunner.heroes.domain.Hero;
import org.springframework.data.jpa.repository.JpaRepository;
import org.springframework.data.jpa.repository.Query;
import org.springframework.data.repository.query.Param;

import java.util.List;

public interface HeroRepository extends JpaRepository {

    @Query("select h from Hero h where lower(h.name) like CONCAT('%', lower(:name), '%')")
    List findByName(@Param("name") String name);

}

UserRepository

package org.itrunner.heroes.repository;

import org.itrunner.heroes.domain.User;
import org.springframework.data.jpa.repository.JpaRepository;

import java.util.Optional;

public interface UserRepository extends JpaRepository {
    Optional findByUsername(String username);
}

Service

为演示Service的使用，增加了HeroService，Service层启用transaction。

package org.itrunner.heroes.service;

import org.itrunner.heroes.domain.Hero;
import org.itrunner.heroes.exception.HeroNotFoundException;
import org.itrunner.heroes.repository.HeroRepository;
import org.itrunner.heroes.util.Messages;
import org.springframework.beans.factory.annotation.Autowired;
import org.springframework.stereotype.Service;
import org.springframework.transaction.annotation.Transactional;

import java.util.List;

@Service
@Transactional
public class HeroService {
    private final HeroRepository repository;
    private final Messages messages;

    @Autowired
    public HeroService(HeroRepository repository, Messages messages) {
        this.repository = repository;
        this.messages = messages;
    }

    public Hero getHeroById(Long id) {
        return repository.findById(id).orElseThrow(() -> new HeroNotFoundException(messages.getMessage("hero.notFound", new Object[]{id})));
    }

    public List getAllHeroes() {
        return repository.findAll();
    }

    public List findHeroesByName(String name) {
        return repository.findByName(name);
    }

    public Hero saveHero(Hero hero) {
        return repository.save(hero);
    }

    public void deleteHero(Long id) {
        repository.deleteById(id);
    }
}

Rest Controller

HeroController
演示了GET、POST、PUT、DELETE方法的使用。

package org.itrunner.heroes.controller;

import org.itrunner.heroes.domain.Hero;
import org.itrunner.heroes.service.HeroService;
import org.springframework.beans.factory.annotation.Autowired;
import org.springframework.http.MediaType;
import org.springframework.web.bind.annotation.*;

import java.util.List;

@RestController
@RequestMapping(value = "${api.base-path}", produces = MediaType.APPLICATION_JSON_VALUE)
public class HeroController {
    @Autowired
    private HeroService service;

    @GetMapping("/heroes/{id}")
    public Hero getHeroById(@PathVariable("id") Long id) {
        return service.getHeroById(id);
    }

    @GetMapping("/heroes")
    public List getHeroes() {
        return service.getAllHeroes();
    }

    @GetMapping("/heroes/")
    public List searchHeroes(@RequestParam("name") String name) {
        return service.findHeroesByName(name);
    }

    @PostMapping("/heroes")
    public Hero addHero(@RequestBody Hero hero) {
        return service.saveHero(hero);
    }

    @PutMapping("/heroes")
    public Hero updateHero(@RequestBody Hero hero) {
        return service.saveHero(hero);
    }

    @DeleteMapping("/heroes/{id}")
    public void deleteHero(@PathVariable("id") Long id) {
        service.deleteHero(id);
    }
}

异常处理

HeroController中没有处理异常的代码，如数据操作失败会返回什么结果呢？例如，添加了重复的记录，会显示如下信息：

Spring Framework提供默认的HandlerExceptionResolver：DefaultHandlerExceptionResolver、ExceptionHandlerExceptionResolver、ResponseStatusExceptionResolver等，可查看全局异常处理方法DispatcherServlet.processHandlerException()了解处理过程。最终，BasicErrorController的error(HttpServletRequest request)方法返回ResponseEntity：

public ResponseEntity> error(HttpServletRequest request) {
    Map body = getErrorAttributes(request, isIncludeStackTrace(request, MediaType.ALL));
    HttpStatus status = getStatus(request);
    return new ResponseEntity<>(body, status);
}

显然返回500错误一般是不合适的，错误信息也需要修改，可使用@ExceptionHandler自定义异常处理机制，如下：

@ExceptionHandler(DataAccessException.class)
public ResponseEntity> handleDataAccessException(DataAccessException exception) {
    LOG.error(exception.getMessage(), exception);
    Map body = new HashMap<>();
    body.put("message", exception.getMessage());
    return ResponseEntity.badRequest().body(body);
}

如@ExceptionHandler中未指定参数将会处理方法参数列表中的所有异常。

对于自定义的异常，可使用@ResponseStatus注解定义code和reason，未定义reason时message将显示异常信息。

package org.itrunner.heroes.exception;

import org.springframework.web.bind.annotation.ResponseStatus;

import static org.springframework.http.HttpStatus.NOT_FOUND;

@ResponseStatus(code = NOT_FOUND)
public class HeroNotFoundException extends RuntimeException {
    public HeroNotFoundException(String message) {
        super(message);
    }
}

更通用的方法是使用@ControllerAdvice定义一个类统一处理Exception，如下：
RestResponseEntityExceptionHandler

package org.itrunner.heroes.exception;

import org.springframework.dao.DataAccessException;
import org.springframework.dao.DataIntegrityViolationException;
import org.springframework.dao.DuplicateKeyException;
import org.springframework.http.HttpHeaders;
import org.springframework.http.HttpStatus;
import org.springframework.http.ResponseEntity;
import org.springframework.validation.FieldError;
import org.springframework.validation.ObjectError;
import org.springframework.web.bind.MethodArgumentNotValidException;
import org.springframework.web.bind.annotation.ControllerAdvice;
import org.springframework.web.bind.annotation.ExceptionHandler;
import org.springframework.web.context.request.WebRequest;
import org.springframework.web.servlet.mvc.method.annotation.ResponseEntityExceptionHandler;

import javax.persistence.EntityNotFoundException;
import java.util.List;

@ControllerAdvice(basePackages = {"org.itrunner.heroes.controller"})
public class RestResponseEntityExceptionHandler extends ResponseEntityExceptionHandler {

    @ExceptionHandler({
            EntityNotFoundException.class,
            DuplicateKeyException.class,
            DataIntegrityViolationException.class,
            DataAccessException.class,
            Exception.class
    })
    public final ResponseEntity