Apache Commons Statistics 1.3 快速入门与集成示例
以 Apache Commons Statistics 1.3 为例给出 10 分钟最小可用示例、依赖树与多模块选装实测、BOM 统一版本管理用法与 Maven 工程常见坑，命令回显均在 Ubuntu 22.04 实测通过。
Apache Commons Statistics 1.3 快速入门与集成示例
目标：10 分钟内跑通 Apache Commons Statistics 1.3 的第一个统计程序，掌握五个功能模块的选装方式与 BOM 统一版本管理，并避开 Maven 集成中的三个高频坑；本文全部命令与回显均已在 Ubuntu 22.04 实测通过。
Apache Commons Statistics 1.3 采用多模块组织：descriptive（描述统计）、inference（假设检验）、interval（置信区间）、ranking（排名）、distribution（概率分布），另有 bom 统一版本。本文从零创建一个 Maven 工程，先跑通最小验证程序，再实测依赖树看清各模块的传递依赖，最后演示 BOM 用法并总结集成时的常见坑。安装与环境搭建的完整过程见《Ubuntu 22.04 安装 Apache Commons Statistics 指南》。
一、环境信息
- 操作系统：Ubuntu 22.04.5 LTS
- 架构：x86_64
- JDK：OpenJDK 17.0.20.1（apt 包
openjdk-17-jdk） - 构建工具：Apache Maven 3.6.3
- 组件版本：commons-statistics 1.3（官方当前最新稳定版）
- Maven 坐标：
org.apache.commons:commons-statistics-descriptive:1.3（最小验证）、org.apache.commons:commons-statistics-bom:1.3（BOM 演示） - 工作目录：
/work/install-demo（最小验证工程）、/work/bom-demo（BOM 演示工程）
环境确认（实时回显）：
java -version 2>&1 && mvn -version | head -4
openjdk version "17.0.20.1" 2026-08-18
OpenJDK Runtime Environment (build 17.0.20.1+1-1-22.04-Ubuntu)
OpenJDK 64-Bit Server VM (build 17.0.20.1+1-1-22.04-Ubuntu, mixed mode, sharing)
Apache Maven 3.6.3
Maven home: /usr/share/maven
Java version: 17.0.20.1, vendor: Ubuntu, runtime: /usr/lib/jvm/java-17-openjdk-amd64
Default locale: en_US, platform encoding: ANSI_X3.4-1968
💡 技术拓展：Commons Statistics 1.x 与同类统计库的定位差异——
维度 Commons Statistics 1.3 Commons Math 3.6.1 组织形态 多模块，按需引入 单一 jar（commons-math3） Java 基线 Java 8+ Java 8+（3.2 起要求） API 风格 不可变累积器 + 函数式（create/accept/getAsDouble） 经典可变对象（addValue/getResult） 假设检验 inference 模块，流式 API stat.inference 包 维护状态 活跃开发中 功能冻结，仅安全修复 本文所用：Commons Statistics 1.3。新项目优先选它；维护仅依赖 commons-math3 的老代码时才继续用 Math。
二、10 分钟最小可用
本节从空目录开始，创建工程、引入依赖、写第一个统计程序并编译运行。整个过程只需三步。
2.1 创建工程并引入依赖
mkdir -p /work/install-demo/src/main/java
pom.xml（完整内容，文件路径 /work/install-demo/pom.xml）：
<?xml version="1.0" encoding="UTF-8"?>
<project xmlns="http://maven.apache.org/POM/4.0.0"
xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
xsi:schemaLocation="http://maven.apache.org/POM/4.0.0 http://maven.apache.org/xsd/maven-4.0.0.xsd">
<modelVersion>4.0.0</modelVersion>
<groupId>demo</groupId>
<artifactId>statistics-install-demo</artifactId>
<version>1.0.0</version>
<packaging>jar</packaging>
<properties>
<project.build.sourceEncoding>UTF-8</project.build.sourceEncoding>
<maven.compiler.release>17</maven.compiler.release>
</properties>
<dependencies>
<dependency>
<groupId>org.apache.commons</groupId>
<artifactId>commons-statistics-descriptive</artifactId>
<version>1.3</version>
</dependency>
</dependencies>
<build>
<finalName>statistics-install-demo</finalName>
<plugins>
<plugin>
<groupId>org.apache.maven.plugins</groupId>
<artifactId>maven-compiler-plugin</artifactId>
<version>3.11.0</version>
</plugin>
<plugin>
<groupId>org.apache.maven.plugins</groupId>
<artifactId>maven-shade-plugin</artifactId>
<version>3.5.1</version>
<executions>
<execution>
<phase>package</phase>
<goals>
<goal>shade</goal>
</goals>
<configuration>
<transformers>
<transformer implementation="org.apache.maven.plugins.shade.resource.ManifestResourceTransformer">
<mainClass>QuickStart</mainClass>
</transformer>
</transformers>
</configuration>
</execution>
</executions>
</plugin>
</plugins>
</build>
</project>
逐项说明关键配置：
commons-statistics-descriptive:1.3：最小验证的唯一运行期依赖，只做描述统计够用了。maven.compiler.release=17：按 JDK 17 语义编译；Commons Statistics 1.3 字节码基线是 Java 8，目标机为 JDK 8 时改成 8 即可。maven-compiler-plugin 3.11.0显式固定：第四章 4.2 节会实测不固定它会发生什么。maven-shade-plugin：打出内嵌依赖的胖 jar，Main-Class指向QuickStart，java -jar即可独立运行。
2.2 编写第一个程序
QuickStart.java（完整内容，文件路径 /work/install-demo/src/main/java/QuickStart.java）：
import org.apache.commons.statistics.descriptive.Mean;
import org.apache.commons.statistics.descriptive.Variance;
public class QuickStart {
public static void main(String[] args) {
double[] data = {9, 2, 5, 4, 12, 7, 8, 11, 9, 3};
Mean mean = Mean.of(data);
Variance variance = Variance.of(data);
System.out.println("n=" + data.length
+ " mean=" + mean.getAsDouble()
+ " variance=" + variance.getAsDouble());
System.out.println("commons-statistics OK");
}
}
程序演示了 Commons Statistics 最典型的两种用法之一：Mean.of(data) 工厂方法对全量数组一次性计算。另一种是 Mean.create() 后逐个 accept(v) 的流式累积，两者走同一套增量算法，结果完全一致。手算核对：总和 70 → 均值 7.0；偏差平方和 104 → 样本方差 104/9 = 11.5556。
2.3 编译与运行
cd /work/install-demo && mvn -q -B package
echo "BUILD_EXIT=$?"
BUILD_EXIT=0
-q 静默模式下无输出即成功（首次构建实测约 5 分钟，主要是下载依赖与插件）。运行：
java -Dfile.encoding=UTF-8 -jar target/statistics-install-demo.jar
n=10 mean=7.0 variance=11.555555555555555
commons-statistics OK
2.4 验证点与预期结果
| 验证点 | 预期 | 实测 |
|---|---|---|
mvn package 退出码 | 0 | 0 |
| 胖 jar 产物 | target/statistics-install-demo.jar 存在 | 194966 字节 |
| 均值 | 7.0（70/10） | 7.0 |
| 样本方差 | 11.555555555555555（104/9） | 11.555555555555555 |
| 中文/特殊字符输出 | 无乱码 | 无乱码 |
要点提示：Mean.of 与 Variance.of 返回的是不可变结果对象，getAsDouble() 取值；若数据是分批到达的，改用 create() + accept()，详细 API 见《Apache Commons Statistics 1.3 常用 API 与统计工具详解》。
三、依赖树与多模块选装
本节实测依赖树，回答两个高频问题：只加一个模块会带入什么？多个模块一起用怎么管版本？
3.1 依赖树实测
在最小验证工程里查看完整依赖树：
cd /work/install-demo && mvn -B dependency:tree 2>&1 | grep -E "\+-|\\\\-"
[INFO] \- org.apache.commons:commons-statistics-descriptive:jar:1.3:compile
[INFO] +- org.apache.commons:commons-numbers-core:jar:1.3:compile
[INFO] \- org.apache.commons:commons-numbers-arrays:jar:1.3:compile
解读：descriptive 1.3 传递依赖 commons-numbers-core:1.3 与 commons-numbers-arrays:1.3（Apache Commons Numbers 项目的数值基础库）。Maven 会自动下载它们，无需手工声明；只有 jar 直跑场景才需要手工补齐（见第四章 4.3 节实录）。
3.2 五个功能模块怎么选
Commons Statistics 1.3 各模块的职责与依赖关系（依赖树逐一实测核实）：
| 模块 | 核心类 | 传递依赖（实测） | 典型场景 |
|---|---|---|---|
| descriptive | Min/Max/Sum/Mean/Variance/StandardDeviation/Skewness/Kurtosis/Median/Quantile/DoubleStatistics | numbers-core 1.3、numbers-arrays 1.3 | 描述统计与流式累积 |
| inference | TTest/ChiSquareTest/BinomialTest/GTest | distribution 1.3、numbers-combinatorics/fraction/gamma 1.3、rng-client-api 1.6 | 假设检验 |
| interval | BinomialConfidenceInterval/NormalConfidenceInterval | distribution 1.3 | 置信区间 |
| ranking | NaturalRanking | 无 | 排名与平局处理 |
| distribution | NormalDistribution/BinomialDistribution 等 | rng-sampling 1.6、numbers-rootfinder 1.3 | 概率分布与采样 |
选装建议：只做描述统计就只加 descriptive（依赖面最小）；做假设检验加 inference（自动带入 distribution）；做区间估计加 interval（同样自动带入 distribution）；ranking 随用随加。五个模块可以任意组合，版本一致即可，无冲突。
3.3 BOM 统一版本管理
当同时使用三个及以上模块时，推荐用官方 commons-statistics-bom 做版本管理：dependencyManagement 导入 BOM 后，各模块依赖不再写 <version>，升级只改一处。演示工程 bom-demo 的关键配置（文件路径 /work/bom-demo/pom.xml，完整依赖段）：
<dependencyManagement>
<dependencies>
<dependency>
<groupId>org.apache.commons</groupId>
<artifactId>commons-statistics-bom</artifactId>
<version>1.3</version>
<type>pom</type>
<scope>import</scope>
</dependency>
</dependencies>
</dependencyManagement>
<dependencies>
<dependency>
<groupId>org.apache.commons</groupId>
<artifactId>commons-statistics-descriptive</artifactId>
</dependency>
<dependency>
<groupId>org.apache.commons</groupId>
<artifactId>commons-statistics-ranking</artifactId>
</dependency>
</dependencies>
编译并验证版本托管生效（实时回显）：
cd /work/bom-demo && mvn -q -B compile
echo "COMPILE_EXIT=$?"
mvn -B dependency:tree 2>&1 | grep -E "\+-|\\\\-"
COMPILE_EXIT=0
[INFO] +- org.apache.commons:commons-statistics-descriptive:jar:1.3:compile
[INFO] | +- org.apache.commons:commons-numbers-core:jar:1.3:compile
[INFO] | \- org.apache.commons:commons-numbers-arrays:jar:1.3:compile
[INFO] \- org.apache.commons:commons-statistics-ranking:jar:1.3:compile
验证点：两个依赖都没写 <version>，依赖树显示它们被 BOM 解析为 1.3（descriptive 的 numbers-arrays 一行在树中显示为 commons-numbers-arrays:jar:1.3，与 3.1 节一致），编译退出码 0。运行主程序（复用 2.2 节的 QuickStart）输出 n=10 mean=7.0 variance=11.555555555555555 与 commons-statistics OK，与最小验证工程完全一致。
要点提示：BOM 本身不带入任何 jar，只做版本仲裁；未来升级到新版本（如 1.4）时只需修改 BOM 的 <version> 一处。
四、Maven 工程常见坑
本节三个坑全部实测复现，均给出可落地的修复。
4.1 平台编码 ANSI_X3.4-1968 导致源码编译失败
最小化安装的 Ubuntu 22.04 默认 POSIX locale，mvn -version 显示 platform encoding: ANSI_X3.4-1968（见第一章回显）。源码含中文注释/字符串时，javac 按 ASCII 解码会报 unmappable character 或产出乱码。修复两层：
- 编译期：pom 设
<project.build.sourceEncoding>UTF-8</project.build.sourceEncoding>（2.1 节 pom 已含）。 - 运行期：
java命令加-Dfile.encoding=UTF-8（2.3 节命令已含），或系统级export LANG=C.UTF-8。
4.2 不固定 compiler 插件版本：Source option 5 报错
把 2.1 节 pom 中的显式 maven-compiler-plugin 声明删掉再构建（实测复现）：
cd /work/pitfall-demo && mvn -B package 2>&1 | grep -E "maven-compiler-plugin:|Source option|Target option|BUILD" | head -5
[INFO] --- maven-compiler-plugin:3.1:compile (default-compile) @ statistics-pitfall-demo ---
[INFO] Compiling 1 source file to /work/pitfall-demo/target/classes
[ERROR] Failed to execute goal org.apache.maven.plugins:maven-compiler-plugin:3.1:compile (default-compile) on project statistics-pitfall-demo: Compilation failure: Compilation failure:
[ERROR] Source option 5 is no longer supported. Use 7 or later.
[ERROR] Target option 5 is no longer supported. Use 7 or later.
原因：Maven 3.6.3 默认绑定 compiler 插件 3.1（回显第一行），它不认识 maven.compiler.release 属性（该属性自插件 3.6 起支持），退回 source/target 1.5，被 JDK 17 拒绝。修复：显式固定 maven-compiler-plugin 为 3.11.0（2.1 节 pom 已含）。同样的实验在 CentOS 8 的 Maven 3.5.4 下报错完全一致。
4.3 jar 直跑漏传递依赖：NoClassDefFoundError
不用 Maven、直接 javac -cp descriptive-1.3.jar 编译再 java -cp 运行时（实测复现）：
java -cp out:commons-statistics-descriptive-1.3.jar QuickStart
Exception in thread "main" java.lang.NoClassDefFoundError: org/apache/commons/numbers/core/Sum
at org.apache.commons.statistics.descriptive.FirstMoment.of(FirstMoment.java:156)
at org.apache.commons.statistics.descriptive.Mean.of(Mean.java:124)
at QuickStart.main(QuickStart.java:7)
Caused by: java.lang.ClassNotFoundException: org.apache.commons.numbers.core.Sum
原因：3.1 节依赖树中的传递依赖 commons-numbers-core:1.3、commons-numbers-arrays:1.3 没进 classpath，Mean.of 内部触发 numbers 类加载即失败。修复：把两个 numbers jar 一并加入 -cp（完整命令与校验过程见《Ubuntu 22.04 安装 Apache Commons Statistics 指南》5.4 节），或改用 Maven 由其自动解析。ranking 与 interval 模块自身无 numbers 传递依赖，inference 的传递依赖较多，jar 直跑场景建议一律用 shade 胖 jar 分发。
五、技术选型建议
本节给出 Commons Statistics 与常见替代方案的选择依据，均基于 1.3 的真实模块结构。
| 场景 | 推荐 | 理由 |
|---|---|---|
| 新项目的描述统计/检验/排名 | Commons Statistics 1.3 | 模块化按需引入，API 现代化，仍在活跃维护 |
| 老代码已深度绑定 commons-math3 | 继续用 Math 3.6.1 | 迁移收益小于风险；两者可共存（包名不同） |
| 只需要矩阵/线性代数 | 其他专用库 | Statistics 不含矩阵运算，避免大材小用 |
| 只需要流式累积均值/方差 | descriptive 单模块 | 传递依赖仅两个 numbers jar，依赖面最小 |
💡 技术拓展：Commons Statistics 与 commons-math3 的包名完全不冲突（
org.apache.commons.statistics与org.apache.commons.math3），同一工程可共存过渡；迁移时注意 Math 的addValue/getResult可变 API 对应 Statistics 的accept/getAsDouble。 本文所用：Commons Statistics 1.3 全家桶按需选装，单一工程内避免混用两套统计实现造成结果口径不一致。
六、参考链接
- Apache Commons Statistics 官方主页：https://commons.apache.org/proper/commons-statistics/
- Commons Statistics 1.3 发布说明：https://downloads.apache.org/commons/statistics/RELEASE-NOTES.txt
- Maven 中央仓库 descriptive 模块：https://repo1.maven.org/maven2/org/apache/commons/commons-statistics-descriptive/
- Maven 中央仓库 bom 模块：https://repo1.maven.org/maven2/org/apache/commons/commons-statistics-bom/
- Commons Numbers 项目（传递依赖来源）：https://commons.apache.org/proper/commons-numbers/