Ubuntu 22.04 安装 Apache Commons Numbers 指南

目标：在 Ubuntu 22.04 服务器上完成 Apache Commons Numbers 1.3 的依赖安装与最小可运行验证，覆盖 Maven 在线集成与官方 bin 包离线直跑两条路线，全部命令已在 Ubuntu 22.04 实测通过。

一、环境信息

操作系统：Ubuntu 22.04.5 LTS（x86_64）
架构：amd64
JDK：OpenJDK 17.0.20.1（apt 仓库 openjdk-17-jdk，17.0.20.1+1-1~22.04）
构建工具：Apache Maven 3.6.3（apt 仓库 maven 3.6.3-5）
组件版本：Apache Commons Numbers 1.3（要求 Java 8 及以上，字节码版本 52，2026 年 4 月发布）
Maven 坐标：org.apache.commons:commons-numbers-bom:1.3（BOM），按需引用 commons-numbers-core、commons-numbers-fraction、commons-numbers-angle 等 11 个运行时模块
工作目录：/root/commons-numbers-demo

二、前置条件

具备 root 或 sudo 权限的 Ubuntu 22.04 服务器一台；
服务器可访问公网（apt 仓库与 Maven 中央仓库 repo1.maven.org），离线环境请直接采用方案 B；
磁盘剩余空间不低于 2 GB（openjdk-17-jdk 及其依赖约占 500 MB，Maven 本地仓库缓存约占 100 MB）；
确认系统时间准确，避免 Maven 校验 HTTPS 证书时出错。

三、版本选型说明

Apache Commons Numbers 是 Apache 官方的轻量级数值计算库，由多个功能独立的模块组成。官方下载目录的当前版本列表如下（实测输出）：

$ curl -s https://downloads.apache.org/commons/numbers/
1.0/  1.1/  1.2/  1.3/

可见 1.x 稳定系列已迭代到 1.0、1.1、1.2、1.3 四个版本，1.3 为最新稳定版，本指南全部实验基于 1.3。

Numbers 1.3 的运行时模块共 11 个（另有 commons-numbers-bom 依赖清单与 commons-numbers-examples 示例包，不属于运行时依赖），逐一列明如下：

模块 artifactId	核心类	职责
commons-numbers-core	Precision、ArithmeticUtils、Sum、DD	浮点比较、整数运算与溢出、扩展精度求和
commons-numbers-angle	Angle、Reduce、CosAngle	角度、弧度、圈数三种单位与归一化、夹角余弦
commons-numbers-arrays	Selection、SortInPlace、MultidimensionalCounter	顺序统计量、同步排序、多维计数器
commons-numbers-combinatorics	Factorial、BinomialCoefficient、Stirling、Combinations	阶乘、二项式系数、斯特林数、组合枚举
commons-numbers-complex	Complex	复数运算
commons-numbers-field	FP64、FP64Field、FractionField	可插拔域代数抽象
commons-numbers-fraction	Fraction、BigFraction、ContinuedFraction	分数与连分数
commons-numbers-gamma	Gamma、LogGamma、Digamma、Erf、Beta	伽马函数族与误差函数
commons-numbers-primes	Primes	素数判定、生成、因子分解
commons-numbers-quaternion	Quaternion、Slerp	四元数与球面线性插值
commons-numbers-rootfinder	BrentSolver	Brent 法求根

💡 技术拓展：模块选型建议——Numbers 采用按模块拆分发布的设计，下游按需引入即可，不必全量引入。常见组合：只需浮点比较与整数运算选 commons-numbers-core（零依赖）；涉及分数精确计算补 commons-numbers-fraction（会传递依赖 core）；需要特殊函数（伽马、误差函数）补 commons-numbers-gamma；复数、四元数分别对应 complex、quaternion。本文验证工程选用 core、fraction、angle 三个模块，覆盖数论、分数、角度三类典型能力。

选 1.3 而非旧版的理由：1.3 修复了 Fraction.compareTo 在负数场景的错误（NUMBERS-207），且要求仅 Java 8，兼容面广；1.3 发布于 2026 年 4 月，是当前官方最新维护线。

四、安装方案 A：Maven 依赖（推荐）

4.1 方案说明

Maven 方案通过 commons-numbers-bom 统一管理 11 个模块的版本号，工程里只写 groupId 与 artifactId，升级版本只改一处。该方案适合在线服务器与 CI 环境。

4.2 安装 JDK 17 与 Maven

Ubuntu 22.04 官方源同时提供 openjdk-17-jdk 与 maven，一条命令即可装完：

apt-get update -qq
DEBIAN_FRONTEND=noninteractive apt-get install -y openjdk-17-jdk maven

输出节选（实测首尾，完整日志约 1300 行）：

Reading package lists...
Building dependency tree...
Reading state information...
The following additional packages will be installed:
  adwaita-icon-theme alsa-topology-conf alsa-ucm-conf at-spi2-core
  ca-certificates-java dbus dbus-user-session dconf-gsettings-backend
  dconf-service default-jre-headless dmsetup fontconfig fontconfig-config
Unpacking maven (3.6.3-5) ...
Setting up openjdk-17-jdk:amd64 (17.0.20.1+1-1~22.04) ...
Setting up maven (3.6.3-5) ...

要点提示：注意依赖清单里出现了 default-jre-headless，它会带上 openjdk-11-jre-headless，这是 Maven 包的传递依赖，属正常现象；编译仍由 openjdk-17-jdk 完成，无需卸载。

验证安装结果：

java -version
mvn -version

实测回显：

openjdk version "17.0.20.1" 2026-08-18
OpenJDK Runtime Environment (build 17.0.20.1+1-1~22.04)
OpenJDK 64-Bit Server VM (build 17.0.20.1+1-1~22.04, 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
OS name: "linux", version: "6.8.0-138-generic", arch: "amd64", family: "unix"

验证结果：JDK 17.0.20.1 与 Maven 3.6.3 就绪。platform encoding: ANSI_X3.4-1968 说明系统默认 locale 未启用 UTF-8，涉及中文输出的运行命令需补 -Dfile.encoding=UTF-8（见第七章配置说明）。

4.3 创建工程并引入依赖

创建最小验证工程 /root/commons-numbers-demo：

mkdir -p /root/commons-numbers-demo/src/main/java

写入 pom.xml：

vi /root/commons-numbers-demo/pom.xml

pom.xml 完整内容（BOM 管 11 个模块版本，本工程先引 core、fraction、angle 三个模块）：

<?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>com.example.numbers</groupId>
  <artifactId>commons-numbers-demo</artifactId>
  <version>1.0.0</version>
  <packaging>jar</packaging>

  <properties>
    <maven.compiler.source>17</maven.compiler.source>
    <maven.compiler.target>17</maven.compiler.target>
    <project.build.sourceEncoding>UTF-8</project.build.sourceEncoding>
  </properties>

  <dependencyManagement>
    <dependencies>
      <dependency>
        <groupId>org.apache.commons</groupId>
        <artifactId>commons-numbers-bom</artifactId>
        <version>1.3</version>
        <type>pom</type>
        <scope>import</scope>
      </dependency>
    </dependencies>
  </dependencyManagement>

  <dependencies>
    <dependency>
      <groupId>org.apache.commons</groupId>
      <artifactId>commons-numbers-core</artifactId>
    </dependency>
    <dependency>
      <groupId>org.apache.commons</groupId>
      <artifactId>commons-numbers-fraction</artifactId>
    </dependency>
    <dependency>
      <groupId>org.apache.commons</groupId>
      <artifactId>commons-numbers-angle</artifactId>
    </dependency>
  </dependencies>

  <build>
    <finalName>commons-numbers-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>Demo</mainClass>
                </transformer>
              </transformers>
            </configuration>
          </execution>
        </executions>
      </plugin>
    </plugins>
  </build>
</project>

💡 技术拓展：依赖版本管理方式对比——方式一是如上使用 commons-numbers-bom 的 import scope，11 个模块版本统一由 BOM 锁定；方式二是每个依赖单独写 <version>1.3</version>。前者多模块协同升级只需改一行，后者灵活但易出现模块间版本漂移。Numbers 1.3 起 11 个模块同版本发布，推荐方式一。本文采用方式一。

4.4 编写最小验证代码

vi /root/commons-numbers-demo/src/main/java/Demo.java

Demo.java 完整内容：

import org.apache.commons.numbers.angle.Angle;
import org.apache.commons.numbers.core.ArithmeticUtils;
import org.apache.commons.numbers.fraction.Fraction;

public class Demo {
    public static void main(String[] args) {
        System.out.println("---- core: ArithmeticUtils ----");
        System.out.println("gcd(48, 18) = " + ArithmeticUtils.gcd(48, 18));
        System.out.println("pow(2, 10)  = " + ArithmeticUtils.pow(2, 10));
        System.out.println("---- fraction: Fraction ----");
        System.out.println("Fraction.of(1, 3).add(Fraction.of(1, 6)) = "
                + Fraction.of(1, 3).add(Fraction.of(1, 6)));
        System.out.println("Fraction.of(2, 4)（构造即约分）           = " + Fraction.of(2, 4));
        System.out.println("---- angle: Angle ----");
        System.out.println("Angle.Deg.of(90).toRad().getAsDouble()   = "
                + Angle.Deg.of(90).toRad().getAsDouble());
        System.out.println("commons-numbers 1.3 OK");
    }
}

4.5 编译打包与运行

cd /root/commons-numbers-demo
mvn -q -B package

mvn -q -B package 在成功时无任何输出，退出码为 0（实测 BUILD_EXIT=0）。查看产物：

ls -l target/commons-numbers-demo.jar

实测回显：

-rw-r--r-- 1 root root 70414 Oct 15 00:58 target/commons-numbers-demo.jar

shade 插件已把 core、fraction、angle 三个模块的全部 38 个类文件合并进该 jar。运行：

java -Dfile.encoding=UTF-8 -Dstdout.encoding=UTF-8 -jar target/commons-numbers-demo.jar

实测回显：

---- core: ArithmeticUtils ----
gcd(48, 18) = 6
pow(2, 10)  = 1024
---- fraction: Fraction ----
Fraction.of(1, 3).add(Fraction.of(1, 6)) = 1 / 2
Fraction.of(2, 4)（构造即约分）           = 1 / 2
---- angle: Angle ----
Angle.Deg.of(90).toRad().getAsDouble()   = 1.5707963267948966
commons-numbers 1.3 OK

验证结果：三个模块的 API 全部调用成功，gcd、分数加法约分、度转弧度结果均正确，方案 A 验证通过。

4.6 依赖关系核对

cd /root/commons-numbers-demo
mvn -B dependency:tree

输出节选（实测）：

[INFO] com.example.numbers:commons-numbers-demo:jar:1.0.0
[INFO] +- org.apache.commons:commons-numbers-core:jar:1.3:compile
[INFO] +- org.apache.commons:commons-numbers-fraction:jar:1.3:compile
[INFO] \- org.apache.commons:commons-numbers-angle:jar:1.3:compile
[INFO] ------------------------------------------------------------------------
[INFO] BUILD SUCCESS

要点提示：fraction、angle 与 core 同版本共存于编译期 classpath，无版本冲突；Numbers 各模块之间几乎无相互依赖，树形结构非常干净。

五、安装方案 B：官方 bin 包 + jar 直跑

5.1 方案说明

官方 bin 包把 11 个模块的 jar 打在一个 tarball 里，解压后直接以 classpath 方式运行，全程不需要 Maven，适合离线服务器、排障环境或临时验证。

5.2 下载与完整性校验

cd /opt
curl -O https://downloads.apache.org/commons/numbers/binaries/commons-numbers-1.3-bin.tar.gz
curl -O https://downloads.apache.org/commons/numbers/binaries/commons-numbers-1.3-bin.tar.gz.sha512
cat commons-numbers-1.3-bin.tar.gz.sha512
sha512sum commons-numbers-1.3-bin.tar.gz

实测回显（首行为官方校验文件内容，第二行为本地计算结果，两者一致）：

94ab95fce6c7729d07a58c02c3cca384fd74a2d8bb9cdad7c8943c673f2afefc92a67abfbce81437e17428f04863f9b0b32d46f9987346ac3e71ab3116927306  commons-numbers-1.3-bin.tar.gz
94ab95fce6c7729d07a58c02c3cca384fd74a2d8bb9cdad7c8943c673f2afefc92a67abfbce81437e17428f04863f9b0b32d46f9987346ac3e71ab3116927306  commons-numbers-1.3-bin.tar.gz

验证结果：SHA-512 校验一致，包完整。

5.3 解压并查看模块清单

tar xzf commons-numbers-1.3-bin.tar.gz
ls commons-numbers-1.3/

实测回显：

DEPENDENCIES  LICENSE.txt  NOTICE.txt  RELEASE-NOTES.txt
commons-numbers-angle-1.3.jar        commons-numbers-gamma-1.3.jar
commons-numbers-arrays-1.3.jar       commons-numbers-primes-1.3.jar
commons-numbers-combinatorics-1.3.jar  commons-numbers-quaternion-1.3.jar
commons-numbers-complex-1.3.jar      commons-numbers-rootfinder-1.3.jar
commons-numbers-core-1.3.jar
commons-numbers-field-1.3.jar
commons-numbers-fraction-1.3.jar

11 个 jar 与第三章模块清单一一对应。

5.4 javac 编译与 java 直跑

将方案 A 的 Demo.java 复制到 /opt/jar-run，不经过 Maven 直接编译运行：

mkdir -p /opt/jar-run/out
cd /opt/jar-run
cp /opt/commons-numbers-1.3/commons-numbers-core-1.3.jar .
cp /opt/commons-numbers-1.3/commons-numbers-fraction-1.3.jar .
cp /opt/commons-numbers-1.3/commons-numbers-angle-1.3.jar .
cp /root/commons-numbers-demo/src/main/java/Demo.java .
javac -encoding UTF-8 -cp 'commons-numbers-core-1.3.jar:commons-numbers-fraction-1.3.jar:commons-numbers-angle-1.3.jar' -d out Demo.java
java -Dfile.encoding=UTF-8 -Dstdout.encoding=UTF-8 -cp 'out:commons-numbers-core-1.3.jar:commons-numbers-fraction-1.3.jar:commons-numbers-angle-1.3.jar' Demo

实测回显：

---- core: ArithmeticUtils ----
gcd(48, 18) = 6
pow(2, 10)  = 1024
---- fraction: Fraction ----
Fraction.of(1, 3).add(Fraction.of(1, 6)) = 1 / 2
Fraction.of(2, 4)（构造即约分）           = 1 / 2
---- angle: Angle ----
Angle.Deg.of(90).toRad().getAsDouble()   = 1.5707963267948966
commons-numbers 1.3 OK

验证结果：与方案 A 输出完全一致，方案 B 验证通过。若只想跑完整模块，classpath 可直接用通配写法 java -cp '/opt/commons-numbers-1.3/*' 主类名。

六、方案对比与选择建议

维度	方案 A：Maven 依赖	方案 B：bin 包 jar 直跑
网络要求	需访问 Maven 中央仓库	仅下载一次 tarball，之后完全离线
版本管理	BOM 统一管理，升级改一行	手动替换 jar，需自己保证模块同版本
与 CI/CD 集成	原生支持	需额外维护 jar 分发
适合场景	常规研发、持续集成	离线内网、临时排障、脚本类小工具

选择建议：生产研发一律走方案 A；内网无法出网或只想快速验证 API 时用方案 B。

七、配置说明

JAVA_HOME：Ubuntu 的 openjdk-17-jdk 默认已把 java/javac 挂到 /usr/bin，一般无需设置 JAVA_HOME；若同机多 JDK，可在 /etc/environment 中追加 JAVA_HOME=/usr/lib/jvm/java-17-openjdk-amd64 后重新登录生效。
编码：apt 环境默认 locale 为 POSIX，Maven 报 platform encoding: ANSI_X3.4-1968。涉及中文输出的程序，运行时统一加 -Dfile.encoding=UTF-8 -Dstdout.encoding=UTF-8（JDK 17 默认 file.encoding 为 GBK/ANSI_X3.4 时中文会乱码）；长期方案是 apt-get install locales 后配置 zh_CN.UTF-8 或 C.UTF-8。
Maven 私服：企业内网可将 commons-numbers-bom 与各模块 jar 经 mvn deploy 发布到内部仓库（如 Nexus、Artifactory），工程内通过 <repositories> 指向私服即可，坐标不变。
模块裁剪：pom 中只保留实际用到的模块。11 个模块互不强依赖，仅 fraction、angle、complex、quaternion 等少数模块传递依赖 core，按需引入不会拉入多余 jar。

八、常见问题（FAQ）

Q1：安装 maven 时为何会带上 openjdk-11-jre-headless？ A：Ubuntu 22.04 的 maven 包依赖 default-jre-headless，默认指向 openjdk-11-jre。Maven 3.6.3 能在 JDK 11 上运行，而你的项目编译用的是 openjdk-17-jdk 提供的 javac（mvn -version 显示的 Java version 即 Maven 自身运行环境）。想让 Maven 本身也跑在 17 上，可改用二进制发行版安装 Maven 3.9，或用 update-java-alternatives 调整默认 JRE。

Q2：运行时报中文乱码怎么办？ A：给 java 命令加 -Dfile.encoding=UTF-8 -Dstdout.encoding=UTF-8，并确保源码以 UTF-8 保存（pom 中已设置 project.build.sourceEncoding=UTF-8，编译不受系统 locale 影响）。

Q3：mvn package 提示无法解析 commons-numbers-bom？ A：检查网络能否访问 repo1.maven.org；内网环境需在 pom 或 settings.xml 中配置镜像代理，或直接采用方案 B。

Q4：Fraction 的异常类为什么 catch 不到？ A：org.apache.commons.numbers.fraction.FractionException 是包级私有类，包外只能捕获其公共父类。实测 Fraction.of(1, 0) 抛出 FractionException: Denominator must be different from 0，业务代码用 catch (RuntimeException e) 接住即可。

Q5：Numbers 和 commons-math3 什么关系？ A：Numbers 是 math3 中数值基础部分的现代化拆分重写，API 风格改为不可变对象与静态工厂（如 Fraction.of(1, 3) 而非 new Fraction(1, 3)），模块更细、体积更小。新项目建议直接用 Numbers，math3 停留在 3.6.1 且不再演进。

九、卸载与清理

rm -rf /root/commons-numbers-demo
rm -rf /opt/jar-run
rm -rf /opt/commons-numbers-1.3 /opt/commons-numbers-1.3-bin.tar.gz /opt/commons-numbers-1.3-bin.tar.gz.sha512
rm -rf /root/.m2/repository/org/apache/commons/commons-numbers-*
apt-get purge -y maven openjdk-17-jdk
apt-get autoremove -y

输出节选（实测）：

Removing maven (3.6.3-5) ...
Removing openjdk-17-jdk:amd64 (17.0.20.1+1-1~22.04) ...

要点提示：purge 会连同配置一起删除；/root/.m2/repository 下其他组织的缓存不受影响，如需彻底清空可整目录删除。

十、参考链接

Apache Commons Numbers 官方主页：https://commons.apache.org/proper/commons-numbers/
官方下载目录：https://downloads.apache.org/commons/numbers/
Maven 中央仓库 BOM：https://repo1.maven.org/maven2/org/apache/commons/commons-numbers-bom/
用户指南（javadoc 入口）：https://commons.apache.org/proper/commons-numbers/javadocs/api-release/index.html
发行说明（1.3）：https://commons.apache.org/proper/commons-numbers/changes-report.html
Ubuntu openjdk 软件包页：https://packages.ubuntu.com/jammy/openjdk-17-jdk