# ftpbox-spring-boot-starter **Repository Path**: LevelCoder/ftpbox-spring-boot-starter ## Basic Information - **Project Name**: ftpbox-spring-boot-starter - **Description**: FTPBox 是一个基于 FTP协议的 SpringBoot Starter，使用池技术管理FTP连接，避免频繁创建新连接造成连接耗时问题。提供和 RedisTemplate 一样优雅的 SftpTemplate。主要包含了：文件上传、下载、校验、查看等功能，为用户提供了一种安全的方式来发送和接收文件和文件夹。 - **Primary Language**: Java - **License**: Apache-2.0 - **Default Branch**: master - **Homepage**: None - **GVP Project**: No ## Statistics - **Stars**: 0 - **Forks**: 2 - **Created**: 2024-09-29 - **Last Updated**: 2024-09-29 ## Categories & Tags **Categories**: Uncategorized **Tags**: None ## README # FTPBox ![](https://gitee.com/lihewei7/img/raw/master/images/ftp003.jpg) - **Github：** https://github.com/lihewei7/ftpbox-spring-boot-starter - **Gitee：** https://gitee.com/lihewei7/ftpbox-spring-boot-starter ## FTPBox是什么？ FTPBox 是一个基于 FTP协议的 SpringBoot Starter，使用池技术管理FTP连接，避免频繁创建新连接造成连接耗时问题。提供和 RedisTemplate 一样优雅的 ftpTemplate。主要包含了：文件上传、下载、校验、查看等功能，为用户提供了一种安全的方式来发送和接收文件和文件夹。 ## Maven依赖 - FTPBox 已上传至 Maven 中央仓库，在工程中导入依赖即可使用 ```xml io.github.lihewei7 ftpbox-spring-boot-starter 1.0.5 ``` | 毕业版本 | 描述 | | ------ | ---------------------------------------- | | v1.0.0 | Version initialization | | v1.0.1 | Version optimization | | v1.0.2 | Optimize configuration information | | v1.0.3 | Standardization to name | | v1.0.4 | ChangeDirectory modify to public | | v1.0.5 | Gets the file size based on the file's absolute path | ## 使用 FTPBox 提供 FtpTemplate 类，它与 `spring-boot-starter-data-redis` 提供的 RedisTemplate 使用方法相同，任意方式注入即可使用： 1. 导入 FTPBox 依赖 2. 配置服务器 3. 查看 API 按需使用 ```java @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); } } ``` ## 配置 ### 单主机配置 - ftp基本配置，密码登录 ```yaml ftp: host: localhost port: 22 username: root password: 1234 ``` - 连接池配置（可不配置使用默认值） ```yaml 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 ，密码登录 ```yaml 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 连接池配置（可不配置使用默认值） ```yaml 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 指定下次使用的连接。注意它只能指定下一次的连接！！！ ```java HostsManage.changeHost("rd-1"); // 成功打印 rd-1 对应连接的原始目录 ftpTemplate.execute(ftpClient::pwd); // 第二次执行失败，抛出空指针，需要再次指定对应连接才能继续使用 ftpTemplate.execute(ftpClient::pwd); ``` - `HostsManage.changeHost(hostname, boolean)`：连续使用相同 host 进行操作，避免执行一次 FtpTemplate 就要设置一次 hostName。注意要配合 `HostHolder.clearHost()` 使用！！！ ```java 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 ```java //有时需要批量执行配置的 n 个 host 连接，此时可以通过该方法获取所有或过滤后的 hostName 集合。 for (String hostName : HostsManage.hostNames()) { HostsManage.changeHost(hostName); ftpTemplate.upload("D:\\a.docx", "/home/ftpbox/a.docx"); } ``` - `HostsManage.hostNames(Predicate)`：获取过滤后的 host 连接的 name ```java // 获取所有以“rd-”开头的 hostName for (String hostName : HostsManage.hostNames(s -> s.startsWith("rd-"))) { HostsManage.changeHost(hostName); ftpTemplate.upload("D:\\a.docx", "/home/ftpbox/a.docx"); } ``` ## API ​ 所有方法都可能抛出 `Exception`，这通常代表连接出问题了，也可能是你上传或下载的文件不存在。ftp 操作可能会改变工作目录，因此在连接返回给池前，框架会重置工作目录为原始目录。注意这只会重置远端工作路径，不会重置本地工作路径。下面的介绍全部使用 `配置` 章节中的配置进行说明，因此初始工作目录是 `/root`。 ### upload 上传文件，该方法会递归创建上传的远程文件所在的父目录。 ```java // 上传 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 下载文件，该方法只会创建下载的本地文件，不会创建本地文件的父目录。 ```java // 下载 /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 ```java // 测试 /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 查看文件/目录 ```java // 查看文件 /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 action)` 用于执行自定义 FTP 操作，比如查看 FTP 默认目录（ftpClient 的其他用途，请参考 edtFTPj 的 API） ```java String dir = ftpTemplate.execute(ftpClient::pwd); //或 String dir2 = ftpTemplate.execute(ftpClient -> pwd()); ``` ### executeWithoutResult `executeWithoutResult(FtpCallbackWithoutResult action)`用于执行自定义没有返回值的FTP操作，比如查看默认的 FTP目录（ftpClient 的其他用途，请参考 edtFTPj 的 API） ```java String localPath = "/home/lihw/local/"; String remoteFile = "remote1.txt"; ftpTemplate.executeWithoutResult(ftpClient -> System.out.println(ftpClient.get(localPath,remoteFile))); ```