参数配置 | Next-gen Tech Edu

多环境配置

Mon, 01 Jan 0001 00:00:00 +0000

多环境配置

在构建环境之初，一个很重要的特性就是根据不同的环境自动使用不同的配置文件，从而完成譬如测试数据库与开发数据库的动态切换。而 Spring Boot 提供了一个非常好用的动态切换配置文件的方法，在 application.properties 文件中指定 spring.profiles.active 参数，那么 Spring 会自动在 classpath 或者 classpath:./config 目录下寻找 application-{profile}.properties 文件，并且将其中内容提取出来用作创建 Bean 的时候动态替换占位符。在命令行方式启动 Spring Boot 应用时，连续的两个减号 –就是对 application.properties 中的属性值进行赋值的标识。所以，java -jar xxx.jar --server.port=8888 命令，等价于我们在 application.properties 中添加属性 server.port=8888。

指定环境启动

通过命令行来修改属性值是 Spring Boot 非常重要的一个特性，通过此特性，理论上已经使得我们应用的属性在启动前是可变的，所以其中端口号也好、数据库连接也好，都是可以在应用启动时发生改变，而不同于以往的 Spring 应用通过 Maven 的 Profile 在编译器进行不同环境的构建。其最大的区别就是，Spring Boot 的这种方式，可以让应用程序的打包内容，贯穿开发、测试以及线上部署，而 Maven 不同 Profile 的方案每个环境所构建的包，其内容本质上是不同的。但是，如果每个参数都需要通过命令行来指定，这显然也不是一个好的方案，所以下面我们看看如果在 Spring Boot 中实现多环境的配置。

在 Spring Boot 中多环境配置文件名需要满足 application-{profile}.properties的格式，其中 {profile}对应你的环境标识，比如：

application-dev.properties：开发环境
application-test.properties：测试环境
application-prod.properties：生产环境

至于哪个具体的配置文件会被加载，需要在 application.properties 文件中通过 spring.profiles.active 属性来设置，其值对应配置文件中的 {profile} 值。如：spring.profiles.active=test就会加载 application-test.properties 配置文件内容。

application.properties 中配置通用内容，并设置 spring.profiles.active=dev，以开发环境为默认配置
application-{profile}.properties 中配置各个环境不同的内容
通过命令行方式去激活不同环境的配置

注意，2.4 版本之前，我们在 yaml 配置文件中，使用 spring.profiles 来定义不同环境的标识，比如下面这样。

spring:
 profiles: "dev"

name: dev.didispace.com

---
spring:
 profiles: "test"

name: test.didispace.com

---
spring:
 profiles: "prod"

name: prod.didispace.com

而在本次 2.4 版本升级之后，我们需要将 spring.profiles 配置用 spring.config.activate.on-profile 替代，比如上面的配置需要修改为如下配置：

spring:
 config:
 activate:
 on-profile: "dev"

name: dev.didispace.com

---
spring:
 config:
 activate:
 on-profile: "test"

name: test.didispace.com

---
spring:
 config:
 activate:
 on-profile: "prod"

name: prod.didispace.com

应用启动的时候，我们要加载不同的环境配置的参数不变，依然采用 spring.profiles.active 参数，对应值采用 spring.config.activate.on-profile 定义的标识名称。比如下面的命令就能激活 dev 环境的配置。

java -jar myapp.jar -Dspring.profiles.active=dev

我们也可以将 spring.profiles.active 写入 yaml 配置中，这样的作用就可以指定默认使用某一个环境的配置，通常我们可以设置成开发环境，这样有利于我们平时的开发调试，而真正部署到其他环境的时候则多以命令参数激活为主。

spring:
 profiles:
 active: "dev"

默认配置文件

Spring Boot 的默认配置文件位置为：src/main/resources/application.properties。关于 Spring Boot 应用的配置内容都可以集中在该文件中了，根据我们引入的不同 Starter 模块，可以在这里定义诸如：容器端口名、数据库链接信息、日志级别等各种配置信息。比如，我们需要自定义 web 模块的服务端口号，可以在 application.properties 中添加 server.port=8888 来指定服务端口为 8888，也可以通过 spring.application.name=hello 来指定应用名（该名字在 Spring Cloud 应用中会被注册为服务名）。

配置加载顺序

Spring Boot 为了能够更合理的重写各属性的值，使用了下面这种较为特别的属性加载顺序：

命令行中传入的参数。
SPRING_APPLICATION_JSON 中的属性。SPRING_APPLICATION_JSON 是以 JSON 格式配置在系统环境变量中的内容。
java:comp/env 中的 JNDI 属性。
Java 的系统属性，可以通过 System.getProperties() 获得的内容。
操作系统的环境变量
通过 random.* 配置的随机属性
位于当前应用 jar 包之外，针对不同 {profile}环境的配置文件内容，例如：application-{profile}.properties 或是 YAML 定义的配置文件
位于当前应用 jar 包之内，针对不同 {profile}环境的配置文件内容，例如：application-{profile}.properties 或是 YAML 定义的配置文件
位于当前应用 jar 包之外的 application.properties和 YAML配置内容
位于当前应用 jar 包之内的 application.properties和 YAML配置内容
在 @Configuration注解修改的类中，通过 @PropertySource 注解定义的属性
应用默认属性，使用 SpringApplication.setDefaultProperties 定义的内容

优先级按上面的顺序有高到低，数字越小优先级越高。可以看到，其中第 7 项和第 9 项都是从应用 jar 包之外读取配置文件，所以，实现外部化配置的原理就是从此切入，为其指定外部配置文件的加载位置来取代 jar 包之内的配置内容。通过这样的实现，我们的工程在配置中就变的非常干净，我们只需要在本地放置开发需要的配置即可，而其他环境的配置就可以不用关心，由其对应环境的负责人去维护即可。

配置文件

Mon, 01 Jan 0001 00:00:00 +0000

Spring Boot 配置文件

Spring Boot 针对我们常用的开发场景提供了一系列自动化配置来减少原本复杂而又几乎很少改动的模板化配置内容；本部分会对 Spring Boot 中配置文件的基础使用进行介绍。Spring Boot 提供了两种常用的配置文件，分别是 properties 文件和 yml 文件；他们的作用都是修改 Spring Boot 自动配置的默认值。值得一提的是，在 Spring Boot 2.0 中推出了 Relaxed Binding 2.0，对原有的属性绑定功能做了非常多的改进以帮助我们更容易的在 Spring 应用中加载和读取配置信息。在 Spring Boot 2.0 中对配置属性加载的时候会除了像 1.x 版本时候那样移除特殊字符外，还会将配置均以全小写的方式进行匹配和加载。所以，下面的 4 种配置方式都是等价的：

spring.jpa.databaseplatform=mysql
spring.jpa.database-platform=mysql
spring.jpa.databasePlatform=mysql
spring.JPA.database_platform=mysql

spring:
 jpa:
 databaseplatform: mysql
 database-platform: mysql
 databasePlatform: mysql
 database_platform: mysql

推荐使用全小写配合 - 分隔符的方式来配置，比如：spring.jpa.database-platform=mysql。

YAML

Spring Boot 的配置文件除了可以使用传统的 properties 文件之外，还支持现在被广泛推荐使用的 YAML 文件。YAML（英语发音：/ˈjæməl/，尾音类似 camel 骆驼）是一个可读性高，用来表达资料序列的格式。YAML 参考了其他多种语言，包括：C 语言、Python、Perl，并从 XML、电子邮件的数据格式（RFC 2822）中获得灵感。YAML 采用的配置格式不像 properties 的配置那样以单纯的键值对形式来表示，而是以类似大纲的缩进形式来表示。比如：

environments:
 dev:
 url: http://dev.bar.com
 name: Developer Setup
 prod:
 url: http://foo.bar.com
 name: My Cool App"

# 表示数组
spring:
 my-example:
 url:
 - http://example.com
 - http://spring.io

spring:
 my-example:
 url: http://example.com, http://spring.io

yaml:
 str: 字符串可以不加引号
 specialStr: "双引号直接输出\n特殊字符"
 specialStr2: '单引号可以转义\n特殊字符'
 flag: false
 num: 666
 Dnum: 88.88
 list:
 - one
 - two
 - two
 set: [1, 2, 2, 3]
 map: { k1: v1, k2: v2 }
 positions:
 - name: wx
 salary: 15000.00
 - name: wxBlog
 salary: 18888.88

创建实体类 YamlEntity.java 获取配置文件中的属性值，通过注解 @ConfigurationProperties 获取配置文件中的指定值并注入到实体类中。

/**
 * YAML 语法实体类
 * 切记点：
 * 一、冒号后面加空格，即 key:(空格)value
 * 二、每行参数左边空格数量决定了该参数的层级，不可乱输入。
 */
@Component
@ConfigurationProperties(prefix = "yaml")
public class YamlEntity {
 // 字面值，字符串，布尔，数值
 private String str; // 普通字符串
 private String specialStr; // 转义特殊字符串
 private String specialStr2; // 输出特殊字符串
 private Boolean flag; // 布尔类型
 private Integer num; // 整数
 private Double dNum; // 小数

 // 数组，List 和 Set，两种写法：第一种：-空格value，每个值占一行，需缩进对齐；第二种：[1,2,...n] 行内写法
 private List<Object> list; // list可重复集合
 private Set<Object> set; // set不可重复集合

 // Map 和实体类，两种写法：第一种：key 空格 value，每个值占一行，需缩进对齐；第二种：{key: value,....} 行内写法
 private Map<String, Object> map; // Map K-V
 private List<Position> positions; // 复合结构，集合对象
// 省略getter，setter，toString方法
}

通过 YAML 的配置方式，我们可以看到配置信息利用阶梯化缩进的方式，其结构显得更为清晰易读，同时配置内容的字符量也得到显著的减少。除此之外，YAML 还可以在一个单个文件中通过使用 spring.profiles 属性来定义多个不同的环境配置。例如下面的内容，在指定为 test 环境时，server.port 将使用 8882 端口；而在 prod 环境，server.port 将使用 8883 端口；如果没有指定环境，server.port 将使用 8881 端口。

server:
 port: 8881
---
spring:
 profiles: test
 server:
 port: 8882
---
spring:
 profiles: prod
 server:
 port: 8883"

YAML 目前还有一些不足，它无法通过 @PropertySource 注解来加载配置。但是，YAML 加载属性到内存中保存的时候是有序的，所以当配置文件中的信息需要具备顺序含义时，YAML 的配置方式比起 properties 配置文件更有优势。

命名约定

在 Spring Boot 2.0 中对配置属性加载的时候会除了像 1.x 版本时候那样移除特殊字符外，还会将配置均以全小写的方式进行匹配和加载。所以，下面的 4 种配置方式都是等价的：

properties 格式：

spring.jpa.databaseplatform=mysql
spring.jpa.database-platform=mysql
spring.jpa.databasePlatform=mysql
spring.JPA.database_platform=mysql

yaml 格式：

spring:
 jpa:
 databaseplatform: mysql
 database-platform: mysql
 databasePlatform: mysql
 database_platform: mysql

推荐使用全小写配合-分隔符的方式来配置，比如：spring.jpa.database-platform=mysql；在 properties 文件中使用 [] 来定位列表类型，比如：

spring.my-example.url[0]=http://example.com
spring.my-example.url[1]=http://spring.io

也支持使用逗号分割的配置方式，上面与下面的配置是等价的：

spring.my-example.url=http://example.com,http://spring.io

而在 yaml 文件中使用可以使用如下配置：

spring:
 my-example:
 url:
 - http://example.com
 - http://spring.io

也支持逗号分割的方式：

spring:
 my-example:
 url: http://example.com, http://spring.io

注意：在 Spring Boot 2.0 中对于 List 类型的配置必须是连续的，不然会抛出 UnboundConfigurationPropertiesException 异常，所以如下配置是不允许的：

foo[0]=a
foo[2]=b

在 Spring Boot 1.x 中上述配置是可以的，foo[1]由于没有配置，它的值会是 null。Map 类型在 properties 和 yaml 中的标准配置方式如下：

properties 格式：

spring.my-example.foo=bar
spring.my-example.hello=world

yaml 格式：

spring:
my-example:
foo: bar
hello: world

注意：如果 Map 类型的 key 包含非字母数字和-的字符，需要用[]括起来，比如：

spring:
my-example:
'[foo.baz]': bar

嵌入属性

Spring 也较好地支持了对于嵌入属性的处理，譬如：

public class Credentials {
 private String authMethod;
 private String username;
 private String password;
// standard getters and setters
}

public class ConfigProperties {
 private String host;
 private int port;
 private String from;
 private List<String> defaultRecipients;
 private Map<String, String> additionalHeaders;
 private Credentials credentials;
// standard getters and setters
}

其对应的属性文件如下：

#Simple properties
mail.hostname=mailer@mail.com
mail.port=9000
mail.from=mailer@mail.com

#List properties
mail.defaultRecipients[0]=admin@mail.com
mail.defaultRecipients[1]=owner@mail.com

#Map Properties
mail.additionalHeaders.redelivery=true
mail.additionalHeaders.secure=true

#Object properties
mail.credentials.username=john
mail.credentials.password=password
mail.credentials.authMethod=SHA1

参数引用

在 application.properties 中的各个参数之间，我们也可以直接通过使用 PlaceHolder 的方式来进行引用，就像下面的设置：

book.name=xxx
book.author=xxx
book.desc=${book.author} is writing《${book.name}》

book.desc 参数引用了上文中定义的 book.name 和 book.author 属性，最后该属性的值就是 xxx is writing《xxx》。当 Docker 启动 SpringBoot 打包的服务时，且一些参数需要从外界获取而非写死在 properties 文件里，通过以下两步完成此需求：

在配置文件中配置环境变量

spring.redis.host=${REDIS_HOST:127.0.0.1}
spring.redis.port=6379
spring.redis.timeout=30000

以上表示 REDIS_HOST 在系统环境变量中获取，如果获取不到默认值为 127.0.0.1。

在启动 Docker 容器时传入环境参数

$ docker run -d --name test2 ｛镜像名｝ -e REDIS_HOST=192.168.0.1

使用随机数

在一些特殊情况下，有些参数我们希望它每次加载的时候不是一个固定的值，比如：密钥、服务端口等。在 Spring Boot 的属性配置文件中，我们可以通过使用 ${random} 配置来产生随机的 int 值、long 值或者 string 字符串，这样我们就可以容易的通过配置来属性的随机生成，而不是在程序中通过编码来实现这些逻辑。${random} 的配置方式主要有一下几种，读者可作为参考使用。

# 随机字符串
com.didispace.blog.value=${random.value}
# 随机int
com.didispace.blog.number=${random.int}
# 随机long
com.didispace.blog.bignumber=${random.long}
# 10以内的随机数
com.didispace.blog.test1=${random.int(10)}
# 10-20的随机数
com.didispace.blog.test2=${random.int[10,20]}

Properties

properties 文件大家经常用，这里就简单介绍一下。其语法结构形如：key=value。注意中文乱码问题，需要转码成 ASCII。具体如下所示：

userinfo.account=wx
userinfo.age=25
userinfo.active=true
userinfo.created-date=2018/03/31 16:54:30
userinfo.map.k1=v1
userinfo.map.k2=v2
userinfo.list=one,two,three
userinfo.position.name=Test
userinfo.position.salary=19999.99

在 properties 文件中使用 [] 来定位列表类型，比如：

spring.my-example.url[0]=http://example.com
spring.my-example.url[1]=http://spring.io"

也支持使用逗号分割的配置方式，上面与下面的配置是等价的：

spring.my-example.url=http://example.com,http://spring.io

在 Spring Boot 2.0 中对于 List 类型的配置必须是连续的，不然会抛出 UnboundConfigurationPropertiesException 异常。

配置引用

Mon, 01 Jan 0001 00:00:00 +0000

@ConfigurationProperties

Spring Boot 通过 ConfigurationProperties 注解从配置文件中获取属性，可以通过设置 prefix 指定需要批量导入的数据。支持获取字面值，集合，Map，对象等复杂数据。ConfigurationProperties 注解的优缺点如下：

可以从配置文件中批量注入属性；
支持获取复杂的数据类型；
对属性名匹配的要求较低，比如 user-name，user_name，userName，USER_NAME 都可以取值；
支持 Java 的 JSR303 数据校验；
缺点是不支持强大的 SpEL 表达式；

Properties

/**
 * 用户信息
 * @ConfigurationProperties : 被修饰类中的所有属性会和配置文件中的指定值（该值通过prefix找到）进行绑定
 */
@Component
@ConfigurationProperties(prefix = "userInfo")
public class UserInfo {
 private String account;
 private Integer age;
 private Boolean active;
 private Date createdDate;
 private Map<String, Object> map;
 private List<Object> list;
 private Position position;
// 省略getter，setter，toString方法
}

配置文件占位符

在 application.properties 中的各个参数之间，我们也可以直接通过使用 PlaceHolder 的方式来进行引用，就像下面的设置：

book.name=SpringCloud
book.author=Test
book.desc=${book.author} is writing《${book.name}》

在一些特殊情况下，有些参数我们希望它每次加载的时候不是一个固定的值，比如：密钥、服务端口等。在 Spring Boot 的属性配置文件中，我们可以通过使用 ${random}配置来产生随机的 int 值、long 值或者 string 字符串，这样我们就可以容易的通过配置来属性的随机生成，而不是在程序中通过编码来实现这些逻辑。

ran: # 这里的prefix不能是random，
 ran-value: ${random.value}
 ran-int: ${random.int}
 ran-long: ${random.long}
 ran-int-num: ${random.int(10)}
 ran-int-range: ${random.int[10,20]}
 ran-placeholder: placeholder_${ran.ran-value:此处不能有空格，且key为完整路径}

其对应的 Java 代码类似于：

/**
 * 随机数和占位符语法类
 */
@Component
@ConfigurationProperties(prefix = "ran")
public class RandomEntity {
 private String ranValue; // 随机生成一个字符串
 private Integer ranInt; // 随机生成一个整数
 private Long ranLong; // 随机生成一个长整数
 private Integer ranIntNum; // 在指定范围内随机生成一个整数
 private Integer ranIntRange; // 在指定区间内随机生成一个整数
 private String ranPlaceholder; // 占位符
// 省略getter，setter，toString方法e
}

属性校验

@ConfigurationProperties 使用 JSR-303 格式提供属性验证。这允许各种各样的事情，例如，让 hostName 属性成为强制性的：

@NotBlank
private String hostName;

@Length(max = 4, min = 1)
private String authMethod;

@Min(1025)
@Max(65536)
private int port;

@Pattern(regexp = "^[a-z0-9._%+-]+@[a-z0-9.-]+\\.[a-z]{2,6}$")
private String from;

@Value

Value 注解的优缺点与 @ConfigurationProperties 正好相反，它只能一个个配置注入值；不支持数组、集合等复杂的数据类型；不支持数据校验；对属性名匹配有严格的要求。最大的特点是支持 SpEL 表达式，使其拥有更丰富的功能。@Value 的使用方式，对于如下的 YAML 定义文件：

wx:
 nick-name: wx
 email: aa@aa
 iphone: 1234567890
 abilities: [java, sql, html]
 created_date: 2010/03/31 15:27:30

其对应的 Java 类使用如下：

/**
 * Value 注解语法类
 * 第一步：在属性上添加注解Value注入参数
 * 第二步：把Value注解修饰的类添加到Spring的IOC容器中；
 * 第三步：添加数据校验注解，检查是否支持数据校验；
 *
 * 注意点：
 * 一、nickName 和 createdDate 在 yml 配置文件中，对应参数分别是中划线和下划线，用于测试其对属性名匹配的松散性
 * 二、email和iphone 测试其支持JSR303数据校验
 * 三、abilities 测试其支持复杂的数据结构
 *
 * 结论：
 * 一、createDate取值必须和yml配置文件中的参数保持一致，
 * 二、既是在iphone上添加邮箱验证注解依然可以通过测试，
 * 三、不支持复杂的数据结构，提示错误和第一条相同：IllegalArgumentException: Could not resolve placeholder 'wx.abilities' in value "${wx.abilities}"
 */
@Component
@Validated
public class ValueEntity {
 @Value("${wx.nick-name}")
 private String nickName;

 @Value("${wx.email}")
 private String email;

 @Email
 @Value("${wx.iphone}") // 解析成功，并不支持数据校验
 private String iphone;

 // @Value("${wx.abilities}") // 解析错误，并不支持复杂的数据结构
 private List<String> abilities;

 // @Value("${wx.ceatredDate}") // 解析错误，并不支持松散匹配属性，必须严格一致
 private Date createdDate;

 // Value注解的强大一面：支持SpEL表达式
 @Value("#{(1+2-3)/4*5}") // 算术运算
 private String operator;

 @Value("#{1>2 || 2 <= 3}") // 关系运算
 private Boolean comparison;

 @Value("#{systemProperties['java.version']}") // 系统配置：os.name
 private String systemProperties;

 @Value("#{T(java.lang.Math).abs(-18)}") // 表达式
 private String mapExpression;
// 省略getter，setter，toString方法
}

@PropertySource

@PropertySource 注解，用于代替 <context:property-placeholader/> 配置，加载 properties 配置文件。有时候我们需要去加载非默认的 profile 文件中的属性，此时就可以用 @PropertySource 将配置文件加载到上下文中，并且通过 @Value 进行注入：

@PropertySource("classpath:foo.properties")
@PropertySource("classpath:bar.properties")
public class PropertiesWithJavaConfig {
 //...
}

@PropertySources({
 @PropertySource("classpath:foo.properties"),
 @PropertySource("classpath:bar.properties")
})
public class PropertiesWithJavaConfig {
 //...
}

@Value( "${jdbc.url}" )
private String jdbcUrl;

@Value( "${jdbc.url:aDefaultUrl}" )
private String jdbcUrl;

Binder

在 Spring Boot 2.0 中增加了新的绑定 API 来帮助我们更容易的获取配置信息。假设在 propertes 配置中有这样一个配置：wx.foo=bar。我们为它创建对应的配置类：

@Data
@ConfigurationProperties(prefix = "wx")
public class FooProperties {
 private String foo;
}

接下来，通过最新的 Binder 就可以这样来拿配置信息了：

@SpringBootApplication
public class Application {

 public static void main(String[] args) {
 ApplicationContext context = SpringApplication.run(Application.class, args);
 Binder binder = Binder.get(context.getEnvironment());

 // 绑定简单配置
 FooProperties foo = binder
 .bind("wx", Bindable.of(FooProperties.class))
 .get();
 System.out.println(foo.getFoo());
 }
}

对于复杂的 List 类型：

wx.post[0]=Why Spring Boot
wx.post[1]=Why Spring Cloud
wx.posts[0].title=Why Spring Boot
wx.posts[0].content=It is perfect!
wx.posts[1].title=Why Spring Cloud
wx.posts[1].content=It is perfect too!

要获取这些配置依然很简单，可以这样实现：

ApplicationContext context = SpringApplication.run(Application.class, args);
Binder binder = Binder.get(context.getEnvironment());
// 绑定List配置
List<String> post = binder.bind("wx.post", Bindable.listOf(String.class)).get();
System.out.println(post);
List<PostInfo> posts = binder.bind("wx.posts", Bindable.listOf(PostInfo.class)).get();
System.out.println(posts);