Apache Commons Net 3.13.0 介绍与选型指南

一、信息基准

• 查询日期：2026-10-18（本文全部版本与论断均于该日通过官方来源联网查证，未做本地安装实测）。
• 版本依据：Apache Commons Net 官方组件页（commons.apache.org/proper/commons-net/）标注"Last Published: 15 Mar 2026 / Version: 3.13.0"；Maven Central 元数据（repo1.maven.org/maven2/commons-net/commons-net/maven-metadata.xml）latest=3.13.0、release=3.13.0，最后更新 2026-03-18。确定 3.13.0 为当前最新稳定版。
• 官方来源清单：
  • 组件首页：https://commons.apache.org/proper/commons-net/
  • GitHub 仓库 README：https://github.com/apache/commons-net
  • 官方示例源码（FTPClientExample.java）：https://commons.apache.org/proper/commons-net/examples/ftp/FTPClientExample.java
  • Javadoc：https://commons.apache.org/proper/commons-net/apidocs/index.html
  • Maven Central 元数据：https://repo1.maven.org/maven2/commons-net/commons-net/maven-metadata.xml

二、软件概述

2.1 基本信息

2.2 定位与背景

官方定位原文："Apache Commons Net library implements the client side of many basic Internet protocols. The purpose of the library is to provide fundamental protocol access, not higher-level abstractions."——只做基础协议的客户端实现，刻意不提供高层抽象，并在必要时暴露协议底层（如 TFTP 包类与收发方法）供开发者自组实现。历史方面官方介绍：其前身为商用 Java 库 NetComponents，1998 年后源码捐赠给 Apache 软件基金会，后成为 Apache Commons 独立组件。（来源：commons.apache.org/proper/commons-net/，查询日期 2026-10-18）

三、核心架构

3.1 按协议划分的客户端类族

组件以"每个协议一个客户端类"组织：FTP/FTPS 对应 FTPClient/FTPSClient，SMTP/POP3/IMAP 对应 SMTPClient/POP3Client/IMAPClient（及各自 S 变体），另有 NNTPClient、TelnetClient、TFTPClient、NTPUDPClient 等；官方示例目录（examples/ftp、examples/mail、examples/nntp、examples/ntp、examples/telnet、examples/unix）与包结构一一对应，均可从官网源码链接直接阅读。（来源：官方组件页 Examples 章节，查询日期 2026-10-18）

3.2 典型调用骨架（官方示例源码流程）

官方 FTPClientExample.java 的连接骨架流程为：ftp.connect(server, port) → ftp.getReplyCode() → FTPReply.isPositiveCompletion(reply) 校验（失败即 ftp.disconnect()）→ ftp.login(user, password) → 传输 → ftp.logout()。该"连接后必须检查应答码"的写法是官方示例反复强调的模式。（来源：官方示例源码 examples/ftp/FTPClientExample.java，查询日期 2026-10-18）

3.3 示例应用与可运行性

官方组件页说明发布包内附带可运行示例："java -jar [path/]commons-net-examples-3.8.0.jar FTPClientExample [parameters]"，示例源码同时包含在源码包与二进制包中。（来源：官方组件页 Examples 章节，查询日期 2026-10-18）

四、功能特性

4.1 支持的协议（官方 Features 原文清单）

• FTP/FTPS
• FTP over HTTP（实验性）
• NNTP
• SMTP(S)
• POP3(S)
• IMAP(S)
• Telnet
• TFTP
• Finger
• Whois
• rexec/rcmd/rlogin
• Time（rdate）与 Daytime
• Echo
• Discard
• NTP/SNTP

（来源：https://commons.apache.org/proper/commons-net/ Features 章节，查询日期 2026-10-18）

4.2 FTP 客户端能力要点

• FTPS 加密支持（FTPSClient）；FTP over HTTP 代理（实验性 FTPHTTPClient）；
• 服务器目录列表解析可配置（官方示例与 Javadoc 提供 FTPClientConfig 以适配不同服务器格式）；
• 官方示例覆盖下载/上传、LIST、MLST、服务器对服务器传输（ServerToServerFTP）、简单 TFTP 客户端（TFTPExample）。（来源：官方组件页 Examples 章节与示例源码，查询日期 2026-10-18）

4.3 邮件与时间协议客户端

官方示例提供 IMAPMail/POP3Mail/SMTPMail 演示对应客户端类用法；NTP/SNTP 由 NTPUDPClient 支持，示例 NTPClient 展示读取 stratum、root delay 等报文字段；Time/Daytime/Echo/Finger/Whois/rexec/rlogin 等"传统 Unix 工具"协议均有对应示例类。（来源：官方组件页 Examples 章节，查询日期 2026-10-18）

五、快速上手

说明：本篇为 A1 认知篇，以下内容引自官方文档原文并标注来源，未做本地运行实测。

5.1 Maven 依赖（官方 README 原文）

<dependency>
  <groupId>commons-net</groupId>
  <artifactId>commons-net</artifactId>
  <version>3.13.0</version>
</dependency>

（来源：https://github.com/apache/commons-net README "Getting the latest release"，查询日期 2026-10-18）

5.2 官方示例源码（FTP 连接骨架，原文节选）

ftp.connect(server, port);
// After connection attempt, you should check the reply code to verify
// success.
reply = ftp.getReplyCode();
if (!FTPReply.isPositiveCompletion(reply)) {
    ftp.disconnect();
    System.err.println("FTP server refused connection.");
    System.exit(1);
}

随后按官方示例流程调用 ftp.login(user, password)、传输操作与 ftp.logout()。（来源：https://commons.apache.org/proper/commons-net/examples/ftp/FTPClientExample.java，查询日期 2026-10-18）

5.3 运行官方示例

官方原文用法（示例 jar 与主 jar 同目录）：

java -cp commons-net-examples-3.8.0.jar;commons-net-3.8.0.jar examples/ftp/FTPClientExample [parameters]

（来源：官方组件页 Examples 章节；参数随版本号替换为所用版本，查询日期 2026-10-18）

六、适用场景与限制

6.1 适用场景

• Java 应用内嵌 FTP/FTPS 文件传输客户端（与服务器目录列表格式解析、应答码处理等细节一起托管给库）；
• 需要发送/收取邮件协议级操作的轻量工具（SMTP/POP3/IMAP 客户端，而非完整邮件框架）；
• NTP 校时、Telnet 交互、TFTP、NNTP、Whois 等小众协议的 Java 客户端实现。

6.2 限制与注意

• 只做"协议客户端"，不含 SSH/SFTP——需要 SSH 系能力时须另选 JSch/SSHJ（见第七章）；
• 定位为"基础协议访问而非高层抽象"（官方原文明示部分设计有意违背 OO 封装），调用方需要自行处理应答码、流关闭与异常路径；
• FTP over HTTP 为实验性能力；邮件协议客户端无离线缓存、IDLE 推送等高层特性。

七、同类选型对比

7.1 对比表

（来源：各组件官方仓库 GitHub API 与 Maven Central 检索，查询日期 2026-10-18）

7.2 选型建议

一句话：FTP/FTPS/Telnet/NTP/邮件协议级客户端等经典 TCP 协议需求首选 Commons Net（协议覆盖面与官方维护度最佳）；SSH/SFTP 需求在 Commons Net 中不存在，应选 mwiede 版 JSch（兼容原 API、持续维护）或功能更现代的 SSHJ；edtFTPj 类商业 FTP 库仅建议存量合规环境延续。

八、参考链接

1. 组件首页：https://commons.apache.org/proper/commons-net/
2. GitHub 仓库：https://github.com/apache/commons-net
3. FTPClientExample 官方示例源码：https://commons.apache.org/proper/commons-net/examples/ftp/FTPClientExample.java
4. 官方示例索引：https://commons.apache.org/proper/commons-net/（Examples 章节）
5. Javadoc：https://commons.apache.org/proper/commons-net/apidocs/index.html
6. Maven Central 元数据：https://repo1.maven.org/maven2/commons-net/commons-net/maven-metadata.xml
7. mwiede/jsch（JSch 社区维护版）：https://github.com/mwiede/jsch
8. SSHJ：https://github.com/hierynomus/sshj