# java-demo-ftp **Repository Path**: lpx03/java-demo-ftp ## Basic Information - **Project Name**: java-demo-ftp - **Description**: Java示例项目，专注于FTP文件传输功能实现，适合初学者学习和参考，涵盖常见操作如上传、下载和管理文件。 - **Primary Language**: Unknown - **License**: Not specified - **Default Branch**: master - **Homepage**: None - **GVP Project**: No ## Statistics - **Stars**: 0 - **Forks**: 0 - **Created**: 2025-09-29 - **Last Updated**: 2025-09-29 ## Categories & Tags **Categories**: Uncategorized **Tags**: None ## README # Java FTP Demo 一个基于Spring Boot的FTP客户端演示项目，提供完整的FTP操作功能和连接池管理。 ## 功能特性 - 🚀 **完整的FTP操作**: 支持文件上传、下载、删除、重命名 - 📁 **目录管理**: 支持目录创建、删除、切换、列表获取 - 🔗 **连接池管理**: 基于Apache Commons Pool2的高效连接池 - 📊 **实时监控**: 提供连接状态监控和健康检查 - 📝 **详细日志**: 完整的操作日志和错误处理 - 🔧 **灵活配置**: 支持多环境配置和动态参数 - 📚 **API文档**: 自动生成Swagger API文档 ## 技术栈 - **后端框架**: Spring Boot 2.7.18 - **FTP客户端**: Apache Commons Net 3.9.0 - **连接池**: Apache Commons Pool2 2.11.1 - **工具类**: Hutool 5.8.22 - **API文档**: SpringDoc OpenAPI 1.7.0 - **监控管理**: Spring Boot Actuator - **项目构建**: Maven ## 快速开始 ### 环境要求 - Java 8+ - Maven 3.6+ - FTP服务器 ### 安装步骤 1. **克隆项目** ```bash git clone https://github.com/example/java-demo-ftp.git cd java-demo-ftp ``` 2. **配置FTP连接** 编辑 `src/main/resources/application.yml` 文件，配置FTP服务器连接信息： ```yaml ftp: default-config: host: your-ftp-server.com port: 21 username: your-username password: your-password ``` 3. **运行项目** ```bash # 开发环境 mvn spring-boot:run -Dspring.profiles.active=dev # 生产环境 mvn spring-boot:run -Dspring.profiles.active=prod ``` 4. **访问应用** - 应用地址: http://localhost:8080/ftp-demo - API文档: http://localhost:8080/ftp-demo/swagger-ui.html - 健康检查: http://localhost:8080/ftp-demo/actuator/health ## API接口 ### 文件操作 | 接口 | 方法 | 描述 | |------|------|------| | `/api/ftp/upload` | POST | 文件上传 | | `/api/ftp/download` | GET | 文件下载 | | `/api/ftp/delete` | DELETE | 文件删除 | | `/api/ftp/rename` | PUT | 文件重命名 | ### 目录操作 | 接口 | 方法 | 描述 | |------|------|------| | `/api/ftp/list` | GET | 获取文件列表 | | `/api/ftp/directory/create` | POST | 创建目录 | | `/api/ftp/directory/delete` | DELETE | 删除目录 | | `/api/ftp/directory/change` | PUT | 切换目录 | ### 连接管理 | 接口 | 方法 | 描述 | |------|------|------| | `/api/ftp/test` | GET | 测试连接 | | `/api/ftp/status` | GET | 获取连接状态 | | `/api/ftp/disconnect` | POST | 断开所有连接 | ## 配置说明 ### 应用配置 ```yaml # 服务器配置 server: port: 8080 servlet: context-path: /ftp-demo # FTP配置 ftp: default-config: host: localhost # FTP服务器地址 port: 21 # FTP服务器端口 username: anonymous # 用户名 password: "" # 密码 connect-timeout: 10000 # 连接超时时间(ms) data-timeout: 10000 # 数据传输超时时间(ms) encoding: UTF-8 # 编码格式 passive-mode: true # 被动模式 # 连接池配置 pool: max-total: 10 # 最大连接数 max-idle: 5 # 最大空闲连接数 min-idle: 2 # 最小空闲连接数 max-wait-millis: 60000 # 最大等待时间(ms) ``` ### 环境配置 项目支持多环境配置： - `application-dev.yml` - 开发环境配置 - `application-prod.yml` - 生产环境配置 - `application-test.yml` - 测试环境配置 通过Maven profile激活不同环境： ```bash # 开发环境（默认） mvn spring-boot:run # 生产环境 mvn spring-boot:run -Pprod # 测试环境 mvn spring-boot:run -Ptest ``` ## 使用示例 ### 文件上传 - windows 命令行 ```powershell # -X POST: 指定HTTP请求方法为POST，用于上传文件 # -F "file=@test.xml": 指定要上传的本地文件，@符号表示后面是文件路径 # -F "remoteDirectory=/": 指定文件上传到FTP服务器的目标目录，/表示根目录 # -F "overwrite=true": 指定是否覆盖已存在文件，true 表示覆盖 # -F "backupExisting=true": 指定是否备份已存在文件，true 表示备份 curl -X POST http://localhost:8080/ftp-demo/api/ftp/upload ` -F "file=@test.xml" ` -F "remoteDirectory=/" ` -F "overwrite=true" ` -F "backupExisting=true" ` -H 'accept: */*' ``` - linux 命令行 ```bash curl -X POST http://localhost:8080/ftp-demo/api/ftp/upload \ -F "file=@test.xml" \ -F "remoteDirectory=/" \ -F "overwrite=true" \ -F "backupExisting=true" \ -H 'accept: */*' ``` ### 文件下载 ```powershell # remoteFilePath=/test.xml: 指定要下载的远程文件路径，此处为根目录下的 test.xml 文件 # localDirectory=.: 指定文件下载到本地的目录，. 表示当前目录 # resumeTransfer=false: 指定是否断点续传，false 表示不进行断点续传 curl -X GET "http://localhost:8080/ftp-demo/api/ftp/download" \ -F "remoteFilePath=/test.xml" \ -F "localDirectory=." \ -F "resumeTransfer=false" \ -H 'accept: */*' ``` ### 获取文件列表 ```bash # directory=/：指定要获取文件列表的目录，此处为根目录 # includeSubdirectories=false：指定是否包含子目录内容，false 表示不包含 # filterPattern=*.xml：指定文件过滤模式，此处为只包含XML文件 # sortBy=name：指定按文件名进行排序,size 表示按文件大小排序,lastModified 表示按修改时间排序,type 表示按文件类型排序 # descending=false：指定排序方式为升序，false 表示升序，true 表示降序,默认按文件名升序排序false # -H 'accept: */*'：设置请求头，表明客户端可以接受任何类型的响应 curl -X GET 'http://localhost:8080/ftp-demo/api/ftp/list' ` -F "directory=/" ` -F "includeSubdirectories=true" ` -F "filterPattern=*.xml" ` -F "sortBy=size" ` -F "descending=false" ` -H 'accept: */*' ``` ### 测试连接 ```bash curl -X GET http://localhost:8080/ftp-demo/api/ftp/test ``` ## 项目结构 ``` java-demo-ftp/ ├── src/ │ ├── main/ │ │ ├── java/com/example/ftpdemo/ │ │ │ ├── config/ # 配置类 │ │ │ ├── controller/ # 控制器 │ │ │ ├── dto/ # 数据传输对象 │ │ │ ├── exception/ # 异常处理 │ │ │ ├── pool/ # 连接池管理 │ │ │ ├── service/ # 业务逻辑 │ │ │ └── utils/ # 工具类 │ │ └── resources/ │ │ ├── application.yml # 主配置文件 │ │ ├── application-dev.yml # 开发环境配置 │ │ └── application-prod.yml # 生产环境配置 │ └── test/ # 测试代码 ├── logs/ # 日志文件 ├── pom.xml # Maven配置 └── README.md # 项目文档 ``` ## 开发指南 ### 代码规范 - 使用Lombok简化代码 - 遵循Spring Boot最佳实践 - 添加详细的JavaDoc注释 - 使用DTO进行数据传输 - 统一异常处理 ### 添加新功能 1. 在 `service/FtpService.java` 中定义接口方法 2. 在 `service/impl/FtpServiceImpl.java` 中实现方法 3. 在 `controller/FtpController.java` 中添加API端点 4. 在 `dto/` 包中添加请求/响应DTO类 5. 更新API文档和README ### 测试 ```bash # 运行所有测试 mvn test # 运行特定测试类 mvn test -Dtest=FtpServiceTest # 跳过测试 mvn package -DskipTests ``` ## 常见问题 ### 日志中文乱码问题 如果在日志中出现中文乱码问题，可能是由于默认编码导致的。可以通过以下方法解决： 1. 在 `logback-spring.xml` 中配置UTF-8编码： ```xml UTF-8 %d{yyyy-MM-dd HH:mm:ss} [%thread] %-5level %logger{36} - %msg%n ... ``` 2. 确保项目的源文件和配置文件都是UTF-8编码。 ## 部署 ### 打包应用 ```bash # 开发环境打包 mvn clean package -Pdev # 生产环境打包 mvn clean package -Pprod ``` ### Docker部署 ```dockerfile FROM openjdk:8-jre-alpine COPY target/java-demo-ftp-1.0.0.jar app.jar EXPOSE 8080 ENTRYPOINT ["java", "-jar", "/app.jar"] ``` ```bash # 构建镜像 docker build -t java-demo-ftp . # 运行容器 docker run -d -p 8080:8080 \ -e FTP_HOST=your-ftp-server.com \ -e FTP_USERNAME=your-username \ -e FTP_PASSWORD=your-password \ java-demo-ftp ``` ## 监控和维护 ### 健康检查 访问 `/actuator/health` 端点检查应用健康状态。 ### 日志查看 ```bash # 查看实时日志 tail -f logs/ftp-demo-dev.log # 查看错误日志 tail -f logs/ftp-demo-error.log ``` ### 性能监控 使用Spring Boot Actuator提供的指标端点： - `/actuator/metrics` - 应用指标 - `/actuator/beans` - Spring Bean信息 - `/actuator/env` - 环境配置 ## 贡献指南 1. Fork项目 2. 创建特性分支 (`git checkout -b feature/amazing-feature`) 3. 提交更改 (`git commit -m 'Add some amazing feature'`) 4. 推送到分支 (`git push origin feature/amazing-feature`) 5. 创建Pull Request ## 许可证 本项目采用MIT许可证 - 查看 [LICENSE](LICENSE) 文件了解详情。 ## 支持 如果你有任何问题或建议，请提交Issue或联系我们。 --- **Happy Coding! 🚀**