Crystal框架配置参数加载机制详解？

• 前言
• 定义
• 配置参数定义的形式
• 配置参数文件定义在哪里？
• 配置参数加载的优先级
• 如何使用配置参数？
• 最佳实践
  • Jar项目中如何定义配置参数？
  • War项目中如何定义或重载Jar包中的配置参数？
  • 开发人员如何自定义配置参数？
  • 如何采用数据库管理配置参数？
• 相关的文章

前言

基于Crystal框架开发的应用，在开发和部署过程中，不可或缺的需要和配置参数打交道，本文详细介绍下Crystal框架对配置参数的加载机制。

支持以下功能的框架最低版本为：v2.2.0，建议采用v2.3.0以上版本。

定义

什么是配置参数？

• • 这里的配置参数特指Crystal框架应用启动和运行过程中，需要获取的参数，而这些参数在开发过程中特意保留，用于不同用户或部署场景情况下，实施工程师可以修改的参数。

配置参数与数据字典的差异

• • 配置参数不等同与数据字典，前者一般只允许在部署阶段修改，生产过程中修改可能导致系统不可运行；后者可在生产过程中，根据业务需要，由系统管理员修改。
  • 配置参数一般指系统运行的技术参数；
  • 数据字典一般指业务逻辑需要的相关参数；

配置参数定义的形式

配置参数一般采用properties文件格式，每行以key=value格式书写。

jpa.entity.scan.packages = com.gsoft
jpa.persistence.unit.name = jpa.crystal
jpa.repositories.base.package = com.gsoft
persistence.transaction.type = JTA
hibernate.cache.use_second_level_cache = true
hibernate.cache.use_query_cache = false
hibernate.max_fetch_depth = 4
hibernate.cache.region.factory_class = org.hibernate.cache.SingletonEhCacheRegionFactory

文件名规则：项目名（Jar包名，不含版本号）- [ all | runtime | test ].properties，如：demo-service-all.properties、demo-service-runtime.properties、demo-service-test.properties。

Key命名规则：项目名（jar包名，不含版本号，名称中的“-”符号换成“.”符号）.模块名.变量名，如demo.service.name。

配置参数文件定义在哪里？

配置参数文件默认采用Spring加载，查找路径的配置如下：

生产环境（WAS）

<property name="locations">
    <list>
        <value>classpath*:/config/*-all.properties</value>
        <value>classpath*:/config/*-runtime.properties</value>
        <value>classpath:/profile/config.properties</value>
        <value>classpath:/profile/licence.properties</value>
    </list>
</property>

开发环境（Tomcat）

<property name="locations">
    <list>
        <value>classpath*:/config/*-all.properties</value>
        <value>classpath*:/config/*-test.properties</value>
        <value>classpath:/profile/config.properties</value>
        <value>classpath:/profile/licence.properties</value>
    </list>
</property>

以下路径可以定义参数：

Properties文件可以定义在ClassPath能找到的任意地方，可以在项目引用的任意Jar包中config目录下，也可以在项目的WEB-INF/classes/config目录下。

以下路径可以重载参数：

可以在项目WEB-INF/classes/profires/config.properites中重载指定参数；

也可以在Java Options参数“crystal.properties.file”指定的任意文件中，如-Dcrystal.properties.file = d:/crystal.properties，重载指定参数；

也可以定义在当前用户目录下的crystal.properties文件中重载指定参数；

同时框架还提供了数据库管理配置参数的机制，因此配置参数还可以在数据库中重载指定参数。

配置参数加载的优先级

配置参数按以下顺序优先加载：

1. classpath中的config/*-all.properties文件（顺序随机）
2. classpath中的config/*-runtime.properties或config/*-test.properties文件（顺序随机）
3. classpath中的profile/config.properties文件（唯一，用于war项目，不可包含在Jar中，否则实施过程可能出现配置参数无法被重载的问题）
4. Java Options参数“crystal.properties.file”指定的文件，如果没有指定文件，则查找操作系统当前用户目录下的crystal.properites文件
5. 根据以上文件中定义的数据库链接信息，从指定数据库的参数表crystal_properties表中获取启用的全局参数
6. 从以上数据库参数表中获取当前应用的启用的参数

其中第1、2条，主要用于Jar包设计开发阶段，所保留的配置参数，并提供默认值所用；第二条主要用于不同的环境分别获取不同的配置所用；

其中第3条，主要用于War项目开发或部署时，可重载第1、2条中定义的所有配置参数；

其中第4条，主要是多War项目部署或开发时，可统一重载第1、2、3条中定义的所有配置参数，对同一JVM环境或同一操作系统的多个War包的相同配置重载比较方便；

其中第5、6条，主要是针对统一数据库环境的大量War项目部署情况下，可统一重载第1、2、3、4条中定义的所有配置参数，生产环境较方便，后期还可针对crystal_properties表提供管理Portlet。

Crystal v2.2.0版本在生产环境下使用时，如果没有配置数据库参数对应的数据源，将发生异常，导致无法正常启动。在v2.3.0版本中已解决，未正式发布前，请使用其快照版本。

如何使用配置参数？

项目开发过程中，可以通过以下途径使用配置参数：

1. Spring Bean对象中，可通过@Value注解，交由Spring容器在实例化对象时直接注入

   @Value("${crystal.default.hessian.timeout}")
   private long defaultTimeout;
   @Value("${crystal.default.hessian.url}")
   private String defaultUrl;

2. 调用com.gsoft.crystal.framework.core.util.Utils.getProperty(String)或com.gsoft.crystal.framework.core.util.Utils.getProperty(String, String)方法，直接获取

   String url = Utils.getProperty("crystal.default.hessian.url");

   此方法使用时必须等待Spring容器初始化完成才能有效，否则返回Null。因此在启动过程中的逻辑，不可以调用此方法获取配置参数，如Servlet、Fileter、Listener中的init方法中不可使用。

最佳实践

Jar项目中如何定义配置参数？

在classpath:/config/*-all.properties、classpath:/config/*-runtime.properties、classpath:/config/*-test.properties文件下定义配置参数，Key=Value格式。

以上三个文件分别用于所有环境、生产环境、开发环境下使用。

demo-service-all.properies

demo.service.name = demoService

War项目中如何定义或重载Jar包中的配置参数？

War项目中定义或重载Jar包中的配置参数时，为了防止加载顺序问题，导致出现不想要的结果，因此不建议在项目的classpath:/config目录下定义配置参数文件。

War项目可以在profile/config.properties文件中定义或重载配置参数。

开发人员如何自定义配置参数？

一个项目组的多个开发人员，因个人开发环境不同，往往部分配置参数需配制成不同的值，如果在classpath中定义配置文件，那么就会造成配置文件反复提交SVN或冲突问题。为了解决这个问题，开发环境下，开发人员可以在自己的JVM参数中指定一个Properties文件或本地操作系统当前用户目录下的crystal.properties文件中定义或重载配置参数。

1. 如果项目均在一个Tomcat或一个JVM中运行，Java Options参数“crystal.properties.file”指定一个Properties文件，如-Dcrystal.properties.file=d:/my.properties

2. 如果项目在多个Tomcat或多个JVM中运行，指定文件，则查找操作系统当前用户目录下的crystal.properties文件

   Icon

   以上两种方法不可同时使用，优先处理Java Options参数指定的文件，除非没有指定文件，否则不采用用户目录下的crystal.properties文件

如何采用数据库管理配置参数？

测试环境或生产环境下，碰到较多War项目时，要在很多War项目中逐一修改配置参数值，很容易出错。

这时采用数据库管理配置参数就比较方便，采用数据库管理配置参数时，必须在Properties文件配置的参数中，必须正确设置以下参数：

#应用名，不同的应用不可以重名
crystal.application.name = crystal_framework
#是否需要将配置参数默认值初始化到数据库中，如false，则不初始化，否则初始化
crystal.properties.database.init = true
#配置参数所在数据库的数据源名称，不采用数据源请赋空值
crystal.properties.datasource.name = crystal/properties
#如果采用数据源，以下参数不用配置
#数据库链接驱动
crystal.properties.database.driver = com.mysql.jdbc.Driver
#数据库链接URL
crystal.properties.database.url = jdbc:mysql://localhost:3306/test?useUnicode=true&characterEncoding=utf-8&zeroDateTimeBehavior=convertToNull
#数据库用户名
crystal.properties.database.user = root
#数据库用户密码
crystal.properties.database.password = root

数据库管理参数时，数据源名称或直连数据库的参数建议默认采用项目数据库相关配置参数

2.3.0版本以后：配置参数表的数据库如果和业务数据库在同一数据库中，而未单独配置数据库连接参数的话，系统将采用默认数据库连接参数，具体替换如下：

crystal.properties.datasource.name参数未定义，则采用datasource.jndi.name参数值
crystal.properties.database.driver参数未定义，则采用datasource.driver参数值

crystal.properties.database.url参数未定义，则采用datasource.url参数值

crystal.properties.database.user参数未定义，则采用datasource.user参数值

crystal.properties.database.password参数未定义，则采用datasource.password参数值

系统第一次启动时，Crystal框架会将所有配置参数，初始化到指定数据库的crystal_properties表中，默认所有属性均不启用。

如果数据库表中已经存在相应的属性，则不覆盖。

我们可以通过数据库客户端Mysql-front或PL-SQL Developer等工具，链接数据库并修改配置参数，重启系统后，将先后采用数据库表中启用的p_application=‘global’和p_application=当前应用name的参数重载Properties文件中定义的相同属性。（Properties文件本身不会被修改）

配置参数数据表要求：

表名：crystal_properties

字段名	是否可为空	类型要求	默认值	说明
p_key	否	varchar(255)		参数名
p_value	是	varchar(255)	空	参数值
p_application	否	varchar(255)		所属应用的应用名，‘global’代表所有应用公用参数
p_enabled	否	int(1)	0	是否启用，1代表启用，0代表不启用

Icon

crystal_properties表需要手动创建，主键不做要求，目前没有提供表维护的相关功能

Icon

crystal_properties表中p_enabled=0的参数，以及p_value=“”或p_value=null的参数，均不会被加载，因此不能采用置空参数值的方法，重载相应参数为空值。