XYS.Utils.FTP 2.3.1

XYS.Utils.FTP

通用、异步、高并发的 FTP 工具库，基于 FluentFTP 封装。

特性

• FtpAgent 门面：上传/下载（流与本地文件）、列目录、存在判断、删除、建目录、重命名。
• 全部操作异步优先（支持 CancellationToken），另提供同步包装。
• 内置连接池（FtpConnectionPool）复用 AsyncFtpClient，MaxConnections 限并发，空闲超时自动回收。
• FluentFTP 依赖收敛到唯一适配器 FluentFtpConnection；核心逻辑面向 IFtpConnection 抽象，便于替换或单测。
• 支持 net8.0 / net462 / netcoreapp3.1 / netstandard2.0 / netstandard2.1。

快速开始

// 方式一：显式配置
using var agent = new FtpAgent(new FtpOptions
{
    Host = "10.0.0.1", Port = 21, User = "u", Password = "p",
    MaxConnections = 10,
});
await agent.UploadAsync(stream, "/uploads/data.txt");

// 方式二：从 xys.config.json 读取
using var agent2 = FtpAgent.FromConfig("default");

FtpAgent 实现 IDisposable，Dispose 时会释放内部连接池及所有空闲连接。

同步 API

每个异步操作都有一个对应的同步包装（去掉方法名末尾的 Async），内部走 Task.Run(...).GetAwaiter().GetResult()，可安全在任意上下文（含 UI 线程、老 ASP.NET 同步动作）调用，代价是每次多一次线程切换。异步优先，仅在无法改造同步调用链时使用。

using var agent = new FtpAgent(options);
agent.Upload(stream, "/uploads/data.txt");        // 同步等价：UploadAsync
bool exists = agent.FileExists("/uploads/data.txt");

操作清单

错误处理

• 业务失败（如上传返回 FtpStatus != Success、创建目录失败）抛 FtpOperationException，异常发生时不销毁连接，仍可复用。
• 连接级异常（网络断开、TLS 握手失败、IOException 等）由底层抛出并向上冒泡；租约会被标记失败，归还时连接被 Dispose，不回池，下次借出会重建。
• 取消 CancellationToken 会中断当前操作，正在执行中的连接同样会被标记失败并销毁。

try
{
    await agent.UploadAsync(stream, "/a/b.txt", ct: token);
}
catch (FtpOperationException ex)      // 业务失败：路径不存在、权限拒绝等
{
    logger.Warn(ex.Message);
}
catch (OperationCanceledException)     // 取消
{
    ...
}
catch (Exception ex)                    // 网络/IO 异常
{
    logger.Error(ex, "FTP 操作失败");
    throw;
}

连接池调优

线程/请求超过 MaxConnections 时 BorrowAsync 会异步等待可用许可，不阻塞线程；等待可用 CancellationToken 取消。

配置（xys.config.json）

"ftp": {
  "default": {
    "host": "10.0.0.1",
    "port": 21,
    "user": "u",
    "password": "p",
    "useSsl": false,
    "connectTimeout": 15000,
    "maxConnections": 10,
    "idleTimeout": 60000
  }
}

可命名多个节点（例如 ftp:archive、ftp:report），通过 FtpAgent.FromConfig("archive") 分别构造。仓库中的 xys.config.json 不应写入明文凭据，仅在部署环境的实际配置文件中填写。

架构

FtpAgent  ──── 面向调用方，异步 + 同步包装 + 错误分类
   │
   ▼
FtpConnectionPool ── SemaphoreSlim 限并发 + ConcurrentBag 空闲桶 + 空闲超时回收
   │
   ▼
IFtpConnection ── 瘦抽象（13 成员），可被 FakeFtpConnection 替代做单测
   │
   ▼
FluentFtpConnection ── 唯一直接依赖 FluentFTP 的类型