Apache Commons Configuration 2.15.1 介绍与选型指南

目标：面向需要从多种来源（properties/XML/INI/JNDI/JDBC 等）统一读取配置的 Java 开发者与架构师，梳理 Apache Commons Configuration 的定位、核心概念、官方用法示例与同类选型对比。本文为认知篇（A1），仅基于官方来源联网查证，不包含本地安装与实测内容。

一、信息基准

本章说明本文所有结论的数据来源与版本依据，便于读者复核时效性。

1.1 查询日期与版本依据

1.2 官方来源清单

• 官方主站：https://commons.apache.org/configuration/
• 快速入门：https://commons.apache.org/proper/commons-configuration/userguide/quick_start.html
• 用户指南目录：https://commons.apache.org/proper/commons-configuration/userguide/index.html
• 发布历史：https://commons.apache.org/proper/commons-configuration/changes-report.html
• Maven Central 元数据：https://repo1.maven.org/maven2/org/apache/commons/commons-configuration2/maven-metadata.xml
• GitHub 同步副本：https://github.com/apache/commons-configuration
• 2.0 迁移指南：https://commons.apache.org/proper/commons-configuration/userguide/upgradeto2_0.html

二、软件概述

Apache Commons Configuration 提供一个通用配置接口，使 Java 应用能从多种来源读取配置数据，并对单值与多值配置参数提供类型化访问（官方首页自述：config.getDouble("number")、config.getInteger("number")，查询日期 2026-10-18）。最新稳定版 2.15.1，Apache-2.0 许可。

2.1 项目背景与 1.x 终止维护

官方首页记载：Configuration 起源于 Apache JServ 的代码，后经 Jakarta Turbine、Jakarta Velocity 演进，进入 Commons 时名为 ExtendedProperties，2003 年底晋升为 Commons Proper 组件。官方明确：1.x 代码库不再接收更新，依赖加载不可信配置文件类拒绝服务问题不在 1.x 安全模型修复范围内；新项目应使用 2016 年首发的 2.x（坐标 org.apache.commons:commons-configuration2）；1.x 升 2.x 至少需要改 import 语句，详见官方 2.0 迁移指南（查询日期 2026-10-18）。

2.2 版本与许可

• 当前版本 2.15.1（2026-05-26，Maven Central 与 GitHub 标签双源核实）。
• 近期节奏（GitHub 标签，查询日期 2026-10-18）：2.13.0（2025-11-26）、2.14.0（2026-04-08）、2.15.0（2026-05-13）、2.15.1（2026-05-26），处于活跃维护期。

2.3 生态位

Configuration 服务于"应用内配置装载"层：把 properties、XML、INI、JNDI、JDBC、系统属性等多种物理来源抽象为统一的 Configuration 接口，并支持多来源合并与类型化取值。它与 Spring/微服务配置中心不同——不含配置分发、灰度推送等平台能力，适合嵌入式、库内默认配置与轻量服务。

三、核心概念

以下概念出自官方首页与用户指南（查询日期 2026-10-18）。

3.1 Configuration 接口：统一的键值视图

Configuration 是一切来源的统一抽象：按字符串键读取，get 系列方法（如 getString、getInt、getDouble）提供类型转换（String/int/long/double/BigDecimal/List 等）。键不存在时默认返回 null（返回原始类型的方法则抛异常，因为没有 null 值形态），可传入默认值兜底（官方快速入门 "Accessing properties"，查询日期 2026-10-18）。

3.2 多来源装载

官方首页列出的可装载来源：Properties 文件、XML 文档、Windows INI 文件、属性列表文件（plist）、JNDI、JDBC 数据源、系统属性、Applet 参数、Servlet 参数。每种来源对应一个 Configuration 实现类（如 PropertiesConfiguration、XMLConfiguration）。

3.3 层次配置与表达式引擎

XMLConfiguration 等层次配置（hierarchical configuration）把嵌套文档映射为点分层键：子标签依次拼接，属性用 [@attr] 语法，重复元素自动成为列表；键中还可用 0 起始的圆括号下标定位具体元素（如 processing.paths.path(1)）。表达式引擎组件负责键的解释求值，可切换为支持 XPath 的实现（官方快速入门 "Reading an XML file"/"Expression engines"，查询日期 2026-10-18）。

3.4 配置构建器（Builders）

Configuration 对象通过配置构建器创建；不同来源可用 CombinedConfigurationBuilder 与 CombinedConfiguration 混合。构建器提供影响加载行为与配置对象行为的大量设置，文件型构建器还提供 save() 把修改写回磁盘；官方推荐需要修改并保存配置的场景一律走构建器。简单场景可用 Configurations 辅助类（线程安全、实例可共享复用）。

3.5 自定义来源

继承 AbstractConfiguration 或 AbstractHierarchicalConfiguration 即可接入自定义配置来源（官方首页 "Additional sources" 章节，查询日期 2026-10-18）。

四、功能特性

4.1 类型化取值与默认值

一次装载、多种类型读取（官方首页示例即 getDouble/getInteger），配合默认值参数避免散落的判空代码；多值属性天然支持 getList。

4.2 跨格式统一操作

properties/XML/INI/plist 等格式共享同一套 get/set/add/save 语义：setProperty 覆盖既有值（不存在则创建），addProperty 追加使键成为列表（官方快速入门 "Updating a configuration"，查询日期 2026-10-18）。

4.3 组合与继承

CombinedConfiguration 把多个来源按声明顺序叠加，实现"默认值文件 + 环境覆盖文件 + 系统属性"的分层覆盖模型，这是它相对单文件配置库的核心结构优势。

4.4 可写回磁盘

通过 FileBasedConfigurationBuilder（或 Configurations.xmlBuilder() 等便捷入口）装载的配置可调用 builder.save() 持久化修改；直接从只读入口获得的配置修改仅在内存生效（官方快速入门 "Saving a configuration"，查询日期 2026-10-18）。

五、快速上手

本章示例引自官方快速入门（https://commons.apache.org/proper/commons-configuration/userguide/quick_start.html，查询日期 2026-10-18）；官方示例中的省略行按其文字说明补全为完整取值代码，示例口令按演示惯例替换，未做本地运行验证。

5.1 Maven 依赖

<dependency>
    <groupId>org.apache.commons</groupId>
    <artifactId>commons-configuration2</artifactId>
    <version>2.15.1</version>
</dependency>

坐标来源：Maven Central org.apache.commons:commons-configuration2 元数据（查询日期 2026-10-18）。

5.2 读取 properties 文件

官方示例文件 database.properties（口令值为演示占位，接入真实环境请走凭据管理）：

database.host = db.acme.com
database.port = 8199
database.user = admin
database.password = q1w2e3r4
database.timeout = 60000

官方装载与类型化读取代码：

Configurations configs = new Configurations();
try {
    Configuration config = configs.properties(new File("config.properties"));
    String dbHost = config.getString("database.host");
    int dbPort = config.getInt("database.port");
    String dbUser = config.getString("database.user");
    String dbPassword = config.getString("database.password", "secret"); // 提供默认值
    long dbTimeout = config.getLong("database.timeout");
} catch (ConfigurationException cex) {
    // 装载失败的处理
}

5.3 读取 XML 与层次键

官方示例文件 paths.xml：

<?xml version="1.0" encoding="ISO-8859-1" ?>
<configuration>
  <processing stage="qa">
    <paths>
      <path>/data/path1</path>
      <path>/data/otherpath</path>
      <path>/var/log</path>
    </paths>
  </processing>
</configuration>

官方读取代码（注意 xml() 返回 XMLConfiguration；官方强调 Configurations 线程安全、实例可共享复用）：

Configurations configs = new Configurations();
try {
    XMLConfiguration config = configs.xml("paths.xml");
    String stage = config.getString("processing[@stage]");
    List<String> paths = config.getList(String.class, "processing.paths.path");
    String secondPath = config.getString("processing.paths.path(1)"); // 下标 0 起始
} catch (ConfigurationException cex) {
    // 装载失败的处理
}

5.4 修改并保存

官方示例（经 xmlBuilder 获得可写回的构建器，修改后 save() 持久化）：

Configurations configs = new Configurations();
try {
    FileBasedConfigurationBuilder<XMLConfiguration> builder = configs.xmlBuilder("paths.xml");
    XMLConfiguration config = builder.getConfiguration();
    config.addProperty("newProperty", "newValue");
    builder.save();
} catch (ConfigurationException cex) {
    // 装载或保存失败的处理
}

六、适用场景与限制

6.1 适用场景

• 传统 Java/Jakarta EE 或纯 Java 服务，需要统一读取 properties/XML/INI 等多格式配置，并做类型化访问；
• 需要"基础配置 + 覆盖配置 + 系统属性"分层合并（CombinedConfiguration）的应用；
• 库内默认配置装载（库作者不希望强加 Spring 依赖时，Configuration 是轻量选项）；
• 需要程序化修改配置并写回文件的桌面/运维工具型应用。

6.2 限制与注意事项

• 1.x 停更且有安全边界声明：官方明确 1.x 不再更新、不可信数据类 DoS 不在修复范围，任何场景都应使用 2.x 坐标（见 2.1）；
• 无云原生语义：不提供配置中心订阅、热更新推送、灰度发布等能力，动态刷新需自行基于 Reloading 机制扩展或改用配置平台；
• 类型系统以 JDK 为主：没有 Spring 那样的宽松绑定（kebab-case 自动映射、Duration 单位换算等），复杂对象绑定需手工转换；
• 依赖注入生态零整合：不提供 @Value/@ConfigurationProperties 式声明式绑定，Spring 项目通常无需引入本库。

6.3 不适合的场景

• Spring Boot 项目：其外部化配置（application.yml + profile + 绑定）已覆盖本库主要价值；
• 微服务/Kubernetes 环境：优先选择 ConfigMap 挂载 + Spring Cloud Config/Nacos 等配置中心方案；
• AKKA/Play/Pekko 等 Typesafe 生态项目：HOCON 是其原生格式（见第七章）。

七、同类选型对比

💡 技术拓展（配置格式的取舍）：properties 简单但无层级与类型；XML 层级强但冗长；HOCON（Typesafe Config）兼顾层级、合并与引用语法；YAML 层级清晰但缩进易错、类型歧义多。选格式本质上是在"人写配置的出错率"与"工具链支持度"之间权衡——Commons Configuration 的优势在于不绑定任何一种格式。

选型建议：非 Spring 的传统 Java 应用要统一多格式配置，选 Commons Configuration 2.x；Typesafe/JVM 服务器生态（AKKA/Pekko/Play）直接用 Typesafe Config 的 HOCON；Spring Boot 项目用自带外部化配置；Jakarta EE/Quarkus 微服务按规范选 MicroProfile Config + SmallRye 实现。

八、参考链接

1. 官方主站：https://commons.apache.org/configuration/
2. 快速入门：https://commons.apache.org/proper/commons-configuration/userguide/quick_start.html
3. 2.0 迁移指南：https://commons.apache.org/proper/commons-configuration/userguide/upgradeto2_0.html
4. Maven Central 元数据：https://repo1.maven.org/maven2/org/apache/commons/commons-configuration2/maven-metadata.xml
5. GitHub 同步副本与发布标签：https://github.com/apache/commons-configuration
6. Typesafe Config 仓库：https://github.com/lightbend/config
7. Spring Boot 外部化配置文档：https://docs.spring.io/spring-boot/reference/features/external-config.html
8. MicroProfile Config 规范：https://github.com/microprofile/microprofile-config
9. SmallRye Config：https://smallrye.io/smallrye-config/