Spring Boot Reference Guide Memorandum

此文章为Spring Boot Reference Guide(2.1.5.RELEASE)的备忘录。

You can use Spring Boot to create a Java application that can be started by using java -jar or more traditional war deployments.

Spring Boot 2.1.5.RELEASE requires:

Java 8 and is compatible up to Java 11(included).

Spring Framework 5.1.6.RELEASE or above

Maven 3.3 or above

Including the appropriate spring-boot-*.jar files on your classpath in the same way as any standard Java library.

Install appropriate Maven, make POM file inheriting from the spring-boot-starter-patent project and declare dependence spring-boot-starter-web. Optionally config Maven plugin to package the project as an executable jar file.

    4.0.0

    com.example
    myproject
    0.0.1-SNAPSHOT

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

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

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

DEPENDENCIES AUTO UPGRATED
SPRING-BOOT-START-PARENT 1
The spring-boot-start-parent provides a dependency-management section so that we can omit version tags for "blessed" dependences. When you upgrade Spring Boot itself, these dependencies are upgraded as well in a consistent way.
With this setup, we can also override individual dependencies by configure as below

    Fowler-SR2

Install the Spring Boot CLI and run spring run app.groovy.

@RestController
class ThisWillActuallyRun {

    @RequestMapping("/")
    String home() {
        "Hello World!"
    }

}

Generate a new project structure by going to https://start.spring.io to shortcut steps.

Using scope=import dependencies as follows to keep the benefit of the dependency management(but not th e plugin management) and override individual dependencies.

    
        
        
            org.springframework.data
            spring-data-releasetrain
            Fowler-SR2
            pom
            import
        
        
            org.springframework.boot
            spring-boot-dependencies
            2.1.5.RELEASE
            pom
            import
        
    

Upgrading from an Early Version of Spring Boot, you may need spring-boot-properties-migrator

Create a Maven pom.xml file and complete it, then run mvn package to test the working build.

mvn dependency:tree

src/main/java/Example.java

import org.springframework.boot.*;
import org.springframework.boot.autoconfigure.*;
import org.springframework.web.bind.annotation.*;

@RestController
@EnableAutoConfiguration    // Tell Spring Boot to "guess" how you want to configure Spring based on the jar dependences.
public class Example {

    @RequestMapping("/")
    String home() {
        return "Hello World!";
    }

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

}

Run mvn spring-boot:run to start the application.

Add the spring-boot-maven-plugin to out pom.xml to used to create an executable jar.

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

MAMUAL OPERATIION REQUIRED
SPRING-BOOT-START-PARENT 2
the spring-boot-starter-parent POM includes  configuration to bind the package goal. if you do not use the parent POM, you need to declare this configuration yourself. See https://docs.spring.io/spring-boot/docs/2.1.5.RELEASE/maven-plugin/usage.html for more detail.

run mvn package to create an executable jar.

run jave -jar target/myproject-0.0.1-SNAPSHOT.jar to launch the application.

You can use jar -tvf to peek inside.

EXAMPLES
some samples can be referenced at https://github.com/spring-projects/spring-boot/tree/v2.1.5.RELEASE/spring-boot-samples

DEPENDENCIES LIST
All the spring modules that can use with Spring Boot, as well as refined third part libraries, can be found at https://github.com/spring-projects/spring-boot/blob/v2.1.5.RELEASE/spring-boot-project/spring-boot-dependencies/pom.xml

The @SpringBootApplication annotation is often placed on the main classpath, and it implicitly defines as base "search package" for certain items. Using a root package also allows the component scan to apply only on this project.

SpringBootApplication
@SpringBootApplication == @EnableAutoConfiguration + @ComponentScan + @Configuration

Typical Layout:

com
 +- example
     +- myapplication
         +- Application.java
         |
         +- customer
         |   +- Customer.java
         |   +- CustomerController.java
         |   +- CustomerService.java
         |   +- CustomerRepository.java
         |
         +- order
             +- Order.java
             +- OrderController.java
             +- OrderService.java
             +- OrderRepository.java

We generally recommend that the primary source be a single @Configuration class. Usually, the main class is a good candidate as the primary *@Configurations

@Import can be used to import additional configuration classes.

Alternatively, @ComponentScan can be used to automatically pick up all Spring component including @Configuration classes.

@ImportResource can be used to import load XML configurations file(Totally not recommended)

@EnableAutoConfiguration or @SpringBootApplication attempts to automatically configure application based on the jar dependencies. we generally recommend that you add one or the other to your primary @Configuration class only.

--DEBUG SWITCH WHEN START
To find out what auto-configuration is currently being applied.

We can define exclusion both at the annotation level and ny using the property.

@ComponentsScan in maim class will automatically register @Component, @Service, @Repository, @Controller etc. as Spring Beans

    
        org.springframework.boot
        spring-boot-devtools
        true
    

Developer tools are automatically disabled when running a fully packages. Applications launched from java -jar or started from a special class loader are considered as fully packages.
If that does not apply to you, try to exclude devtools or set the -Dspring.devtools.restart.enabled=false system property.

devtool properties

DevTools relies on the application context’s shutdown hook to close it during a restart. It does not work correctly if you have disabled the shutdown hook (SpringApplication.setRegisterShutdownHook(false)).

RESTART TECHNOLOGY
Two class loader, base and restart. Classes that do not change(for example third part jar) are loaded into base. Classes that are under development are loaded into restart. When restart, throw restart away. Take advantages of already available and populated base class loader.
Generally speaking, any project in IDE is loaded with the restart and any regular .jar file is loaded with base.

spring.devtools.restart.log-condition-evaluation-delta=false

Disable the logging of the report that shows the condition evaluation delta when restart triggered.

spring.devtools.restart.exclude=static/,public/
spring.devtools.restart.additional-exclude
spring.devtools.restart.additional-paths
spring.devtools.restart.enabled(when false, restart class loader still be initiated but does not watch for file change)
(System property)spring.devtools.restart.enabled(completely disable)

public static void main(String[] args) {
    System.setProperty("spring.devtools.restart.enabled", "false");
    SpringApplication.run(MyApp.class, args);
}

spring.devtools.restart.trigger-file
spring.devtools.livereload.enabled

LIVE RELOAD
trigger browser refresh when a resource is changed.[http://livereload.com/extensi...]

Can be used in development environment.

FailureAnalyzers to handle error occur when failed to start.
If no analyzer was matched, you can use DEBUG mode when launching application to see detail info.

Adding a banner.txt file to class path.

Setting spring.banner.location property to locate an other file(spring.banner.charset).

Add banner.gif .pnf .jpg to class path.

Setting spring.banner.image.location

SpringApplication.setBanner, .org.springFramework.boot.banner interface and printBanner method.

Placeholders can be used.
MANIFEST.MF
spring.main.banner-mode: console, log, off

https://docs.spring.io/spring-boot/docs/2.1.5.RELEASE/api/org/springframework/boot/builder/SpringApplicationBuilder.html

You often need not use application events, bunt it is handy to know that they exist.

Determine WebApplicationType:

If Spring MVC is present, an AnnotationConfigServletWebServerApplicationContext is used

If Spring MVC is not present and Spring WebFlux is present, an AnnotationConfigReactiveWebServerApplicationContext is used

Otherwise, AnnotationConfigApplicationContext is used

Changed by setWebApplicationType(WebApplicationType). setApplicationContextClass(…​).

import org.springframework.boot.*;
import org.springframework.beans.factory.annotation.*;
import org.springframework.stereotype.*;

@Component
public class MyBean {

    @Autowired
    public MyBean(ApplicationArguments args) {
        boolean debug = args.containsOption("debug");
        List files = args.getNonOptionArgs();
        // if run with "--debug logfile.txt" debug=true, files=["logfile.txt"]
    }

}

Or can be used by @Value annotation

Used when you want to run some special code once the SpringApplication has started.

Override order

~/.spring-boot-devtools.properties

Command line arguments. java -jar app.jar —ame=“Spring”. disabled by: SpringApplication.setAddCommandLineProperties(false)

SPRING_APPLICATION_JSON.

$ SPRING_APPLICATION_JSON="{"acme":{"name":"test"}}" && java -jar myapp.jar

java -Dspring.application.json="{"name":"test"}" -jar myapp.jar

java -jar myapp.jar --spring.application.json="{"name":"test"}

Java system properties

OS environment variables

application.properties

Name and path can be changed:

java -jar myproject.jar --spring.config.name=myproject.

java -jar myproject.jar --spring.config.location=classpath:/default.properties,classpath:/override.properties

Search order by default:

file:./config/

file:./

classpath:/config/

classpath:/

Usage: @Value("${name}")

my.secret=${random.value}
my.number=${random.int}
my.bignumber=${random.long}
my.uuid=${random.uuid}
my.number.less.than.ten=${random.int(10)}
my.number.in.range=${random.int[1024,65536]}

[To Be Continued]