这段 Java 文档详细描述了 Apache Commons Net 库中的 FTPClient 类，它是用于与 FTP 服务器进行文件传输的高级封装工具。它隐藏了底层网络通信细节，提供了一个简洁、安全、跨平台的 API 接口。

我们来 逐段解析 这段文档的核心内容，并结合你之前学习的 FTP 协议术语（如 PI, DTP, reply, type 等），帮助你从 理论到实践 全面理解。

🌟 一、核心功能概述

FTPClient encapsulates all the functionality necessary to store and retrieve files from an FTP server. This class takes care of all low level details…

🔹 含义：

FTPClient 是一个 完整的 FTP 客户端实现。

它封装了所有与 FTP 服务器交互的底层细节（如连接、命令、数据传输、编码转换等）。

提供了高层接口，让你只需调用 storeFile() 或 retrieveFile() 就能完成上传/下载。

✅ 类比：

就像你开车不需要懂发动机原理一样，

使用 FTPClient 不需要手动发送 USER, PASS, RETR, STOR 命令，

它自动帮你完成这些协议交互。

🚪 二、基本使用流程（必须掌握）

FTPClient ftp = new FTPClient();

ftp.connect(server);

if (!FTPReply.isPositiveCompletion(ftp.getReplyCode())) {

ftp.disconnect();

throw new IOException("Connection refused");

}

// ... 操作文件

ftp.logout();

ftp.disconnect();

🔹 关键步骤：

步骤

说明

1. new FTPClient()

创建客户端对象

2. connect(server)

建立控制连接（端口 21）

3. 检查 getReplyCode()

必须检查是否连接成功（如 220 表示就绪）

4. login()

登录（发送 USER/PASS）

5. 文件操作

如 listFiles(), retrieveFile(), storeFile()

6. logout()

安全登出（可选但推荐）

7. disconnect()

断开连接，释放资源

⚠️ 重要：即使发生异常，也必须在 finally 块中调用 disconnect()，否则会泄露 socket 资源！

📡 三、FTP 命令返回值处理规则

The convention for all the FTP command methods… return boolean or other value.

🔹 方法返回值约定：

返回类型

成功

失败

boolean

true（收到 2xx 成功码）

false（收到 4xx/5xx 错误码）

其他对象（如 FTPFile[]）

返回数据

返回 null

🔹 如何获取详细错误码？

boolean success = ftp.changeWorkingDirectory(