FTPBox Starter

喜欢ヅ旅行 2024-03-22 22:02 37阅读 0赞

![1d200ebe94c4c1ccd81caecea3be4128.jpeg][]

*  **Github：** https://github.com/lihewei7/ftpbox-spring-boot-starter
 *  **Gitee：** https://gitee.com/lihewei7/ftpbox-spring-boot-starter  
    
    
    #### 文章目录 ####
    
     *   *  FTPBox是什么？
         *  Maven依赖
         *  使用
         *  API
         *   *  upload
             *  download
             *  exists
             *  list
             *  execute
             *  executeWithoutResult
         *  配置
         *   *  单主机配置
             *  多主机配置
             *  多Host使用手册

### FTPBox是什么？ ###

FTPBox 是一个基于 FTP协议的 SpringBoot Starter，主要包含了：文件上传、下载、校验、查看等功能，为用户提供了一种安全的方式来发送和接收文件和文件夹。使用池技术管理FTP连接，避免频繁创建新连接造成连接耗时问题。提供和 RedisTemplate 一样优雅的 ftpTemplate。

### Maven依赖 ###

<dependency>
        <groupId>io.github.lihewei7</groupId>
        <artifactId>ftpbox-spring-boot-starter</artifactId>
        <version>1.0.3</version>
    </dependency>

<table> 
 <thead> 
  <tr> 
   <th>毕业版本</th> 
   <th>描述</th> 
  </tr> 
 </thead> 
 <tbody> 
  <tr> 
   <td>v1.0.0</td> 
   <td>Version initialization</td> 
  </tr> 
  <tr> 
   <td>v1.0.1</td> 
   <td>Version optimization</td> 
  </tr> 
  <tr> 
   <td>v1.0.2</td> 
   <td>Optimize configuration information</td> 
  </tr> 
  <tr> 
   <td>v1.0.3</td> 
   <td>Standardization to name</td> 
  </tr> 
 </tbody> 
</table>

### 使用 ###

FTPBox 提供 FtpTemplate 类，它与 `spring-boot-starter-data-redis` 提供的 RedisTemplate 使用方法相同，任意方式注入即可使用：

1.  导入 FTPBox 依赖
2.  应用中添加服务器配置
3.  查看 API 按需使用

@Component
    public class XXXService {
        
      
      @Autowired
      private FtpTemplate ftpTemplate;
    
      public void downloadFileWork(String from, String to) throws Exception {
        
        ftpTemplate.download(from, to);
      }
      
      public void uploadFileWork(String from, String to) throws Exception {
        
        ftpTemplate.upload(from, to);
      }
    }

### API ###

所有方法都可能抛出 `Exception`，这通常代表连接出问题了，也可能是你上传或下载的文件不存在。ftp 操作可能会改变工作目录，因此在连接返回给池前，框架会重置工作目录为原始目录。注意这只会重置远端工作路径，不会重置本地工作路径。下面的介绍全部使用 `配置` 章节中的配置进行说明，因此初始工作目录是 `/root`。

#### upload ####

上传文件，该方法会递归创建上传的远程文件所在的父目录。

// 上传 D:\\a.docx 到 /home/ftpbox/a.docx
    ftpTemplate.upload("D:\\a.docx", "/home/ftpbox/aptx4869.docx");
    
    // 上传 D:\\a.pdf 到 /root/ftpbox/a.pdf
    ftpTemplate.upload("D:\\a.pdf", "ftpbox/a.pdf");
    
    // 上传 D:\\a.doc 到 /root/a.doc
    ftpTemplate.upload("D:\\a.doc", "a.doc");

#### download ####

下载文件，该方法只会创建下载的本地文件，不会创建本地文件的父目录。

// 下载 /home/ftpbox/b.docx 到 D:\\b.docx
    ftpTemplate.download("/home/ftpbox/b.docx", "D:\\b.docx");
    
    // 下载 /root/ftpbox/b.pdf 到 D:\\b.pdf
    ftpTemplate.download("ftpbox/b.pdf", "D:\\b.pdf");
    
    // 下载 /root/b.doc 到 D:\\b.doc
    ftpTemplate.download("b.doc", "D:\\b.doc");

#### exists ####

校验文件是否存在，存在返回true，不存在返回false

// 测试 /home/ftpbox/c.docx 是否存在
    boolean result1 = ftpTemplate.exists("/home/ftpbox/c.pdf");
    // 测试 /root/ftpbox/c.docx 是否存在
    boolean result2 = ftpTemplate.exists("ftpbox/c.docx");
    // 测试 /root/c.docx 是否存在
    boolean result3 = ftpTemplate.exists("c.doc");

#### list ####

查看文件/目录

// 查看文件 /home/ftpbox/d.pdf
    LsEntry[] list1 = ftpTemplate.list("/home/ftpbox/d.pdf");
    // 查看文件 /root/ftpbox/d.docx
    LsEntry[] list2 = ftpTemplate.list("ftpbox/d.docx");
    // 查看文件 /root/d.doc
    LsEntry[] list3 = ftpTemplate.list("d.doc");
    
    // 查看目录 /home/ftpbox
    LsEntry[] list4 = ftpTemplate.list("/home/ftpbox");
    // 查看目录 /root/ftpbox
    LsEntry[] list5 = ftpTemplate.list("ftpbox");

#### execute ####

`execute(FtpCallback<T> action)` 用于执行自定义 FTP 操作，比如查看 FTP 默认目录（ftpClient 的其他用途，请参考 edtFTPj 的 API）

String dir = ftpTemplate.execute(ftpClient::pwd);
    //或
    String dir2 = ftpTemplate.execute(ftpClient -> pwd());

#### executeWithoutResult ####

`executeWithoutResult(FtpCallbackWithoutResult action)`用于执行自定义没有返回值的FTP操作，比如查看默认的 FTP目录（ftpClient 的其他用途，请参考 edtFTPj 的 API）

String localPath = "/home/lihw/local/";
    String remoteFile = "remote1.txt";
    ftpTemplate.executeWithoutResult(ftpClient -> System.out.println(ftpClient.get(localPath,remoteFile)));

### 配置 ###

#### 单主机配置 ####

*  ftp基本配置（密码登录）

ftp:
      host: localhost
      port: 22
      username: root
      password: 1234

*  连接池配置（可不配置使用默认值）

ftp:
      pool:
        min-idle: 1
        max-idle: 8
        max-active: 8
        max-wait: -1
        test-on-borrow: true
        test-on-return: false
        test-while-idle: true
        time-between-eviction-runs: 600000
        min-evictable-idle-time-millis: 1800000

#### 多主机配置 ####

在多 Host 使用 FtpTemplate 需要为 FTPBox 指定将要使用的主机，详细操作见下方API。hosts 下可配置多台主机。rd-1为主机名（ftp.hosts 下 map 中的 key 代表 hostName ，可自定义主机名）

*  多 host ，密码登录

ftp:
      hosts:
        rd-1:
          host: 127.0.0.1
          port: 22
          username: lihw
          password: 1234
        rd-2:
          host: 127.0.0.2
          port: 22
          username: lihw
          password: 1234

*  多 host ，密码 + 密钥登录方式
 *  多 Host 连接池配置（可不配置使用默认值）

ftp:
      pool:
        min-idle-per-key: 1
        max-idle-per-key: 8
        max-active-per-key: 8
        max-active: 8
        max-wait: -1
        test-on-borrow: true
        test-on-return: false
        test-while-idle: true
        time-between-eviction-runs: 600000
        min-evictable-idle-time-millis: 1800000

#### 多Host使用手册 ####

*  `HostsManage.changeHost(hostname)` ：通过 hostName 指定下次使用的连接。注意它只能指定下一次的连接！！！

HostsManage.changeHost("rd-1");
    // 成功打印 rd-1 对应连接的原始目录
    ftpTemplate.execute(ftpClient::pwd);
    // 第二次执行失败，抛出空指针，需要再次指定对应连接才能继续使用
    ftpTemplate.execute(ftpClient::pwd);

*  `HostsManage.changeHost(hostname, boolean)`：连续使用相同 host 进行操作，避免执行一次 FtpTemplate 就要设置一次 hostName。注意要配合 `HostHolder.clearHost()` 使用！！！

HostsManage.changeHost("rd-1", false);
    try {
        
      ftpTemplate.upload("D:\\a.docx", "/home/ftpbox/a.docx");
      ftpTemplate.upload("D:\\b.pdf", "ftpbox/b.pdf");
      ftpTemplate.upload("D:\\c.doc", "c.doc");
    } finally {
        
      HostsManage.clearHost();
    }

*  `HostsManage.hostNames()` 与 ：获取所有的 host 连接的 name

//有时需要批量执行配置的 n 个 host 连接，此时可以通过该方法获取所有或过滤后的 hostName 集合。
    for (String hostName : HostsManage.hostNames()) {
        
       HostsManage.changeHost(hostName);
       ftpTemplate.upload("D:\\a.docx", "/home/ftpbox/a.docx");
    }

*  `HostsManage.hostNames(Predicate<String>)`：获取过滤后的 host 连接的 name

// 获取所有以“rd-”开头的 hostName
    for (String hostName : HostsManage.hostNames(s -> s.startsWith("rd-"))) {
        
      HostsManage.changeHost(hostName);
      ftpTemplate.upload("D:\\a.docx", "/home/ftpbox/a.docx");
    }

[1d200ebe94c4c1ccd81caecea3be4128.jpeg]: https://image.dandelioncloud.cn/pgy_files/images/2024/03/14/02b29cae0c10483b9b1849d4a89ed2eb.png