说实话，FTP 这个协议老得像古董，但在工业控制、内网文件同步这些场景里，它依然有其不可替代的价值。前段时间，我决定用 WinForms 和 C# 从头实现一个完整的 FTP 客户端，过程中从连接管理、异步目录浏览到带断点续传的传输队列，踩了不少坑。今天，我就把核心的设计思路和几个关键的技术实现细节拆解开，希望能帮你绕过这些“雷区”。
很多人在写 WinForms 项目时，常常陷入一个困境：FrmMain.cs 最终膨胀到几千行，UI逻辑、业务逻辑、数据访问全部搅在一起。这样的代码后期维护起来，简直是一种折磨。
为了避免这个问题，我把这个项目拆成了清晰的三层：
- Core 层：包含
FTPClient（负责 FTP 协议通信）、ConnectionManager（管理连接历史）、FileTransfer（调度传输队列）等核心业务逻辑。
- Models 层：纯粹的数据模型，例如
FTPConnection、TransferTask、FileItem 等。
- Forms 层：只负责 UI 的呈现和用户的交互事件，不触及任何具体的业务逻辑。
在 FrmMain 的构造函数中，三个核心对象各司其职：
_ftpClient = new FTPClient();
_connectionManager = new ConnectionManager();
_fileTransfer = new FileTransfer(_ftpClient);
其中 FileTransfer 通过依赖注入的方式接收 FTPClient 实例，这使得单元测试和未来替换实现都变得非常方便。结构简单，职责清晰。
👨💻 先看效果
来看看我们最终实现的客户端界面效果。
（FTP客户端主界面，显示本地与远程目录面板，顶部为连接配置区域，底部为状态栏。）
（连接成功后，远程目录面板显示出服务器上的文件和文件夹列表。）
（“配置连接”对话框，用于管理保存的连接配置。）
🔌 连接管理——历史记录怎么做才不烦人
ConnectionManager 的核心功能非常朴素：维护一个最多 20 条的连接历史列表。每次连接成功，就将这条记录置顶，并自动去除重复项。
using AppFTPClient.Models;
using AppFTPClient.Utils;
namespace AppFTPClient.Core;
public class ConnectionManager
{
private readonly AppConfig _config;
public ConnectionManager()
{
_config = Config.Load();
}
public IReadOnlyList<FTPConnection> ConnectionHistory => _config.ConnectionHistory;
public FTPConnection? CurrentConnection { get; private set; }
public void SetCurrent(FTPConnection connection)
{
CurrentConnection = connection;
SaveConnection(connection);
}
public void ClearCurrent()
{
CurrentConnection = null;
}
public FTPConnection? GetMostRecent()
{
return _config.ConnectionHistory.FirstOrDefault();
}
public void SaveConnection(FTPConnection connection)
{
var existing = _config.ConnectionHistory.FirstOrDefault(x =>
string.Equals(x.Server, connection.Server, StringComparison.OrdinalIgnoreCase) &&
x.Port == connection.Port &&
string.Equals(x.Username, connection.Username, StringComparison.OrdinalIgnoreCase));
if (existing is not null)
{
_config.ConnectionHistory.Remove(existing);
}
_config.ConnectionHistory.Insert(0, connection);
if (_config.ConnectionHistory.Count > 20)
{
_config.ConnectionHistory.RemoveRange(20, _config.ConnectionHistory.Count - 20);
}
Config.Save(_config);
}
public string LastLocalPath
{
get => _config.LastLocalPath;
set
{
_config.LastLocalPath = value;
Config.Save(_config);
}
}
public string LastRemotePath
{
get => _config.LastRemotePath;
set
{
_config.LastRemotePath = value;
Config.Save(_config);
}
}
}
去重判断使用了 Server + Port + Username 这个三元组。这里特别需要注意使用了 StringComparison.OrdinalIgnoreCase——因为 FTP 服务器地址通常是大小写不敏感的。如果不加这个设置，用户手打的 FTP.Example.com 和 ftp.example.com 就会被系统认为是两条不同的记录，体验很差。
此外，我们还持久化了 LastLocalPath 和 LastRemotePath。每次打开软件时，会自动恢复到上次浏览的本地和远程目录。这个细节很多现成的工具都没做，但实际使用中非常贴心。
⚡ 异步目录加载——UI 线程的命根子
LoadRemoteDirectoryAsync 是整个客户端中最容易“翻车”的地方。网络 I/O 操作如果不做异步处理，界面就会卡死，用户体验直接崩塌。
private async Task LoadRemoteDirectoryAsync(string path)
{
if (!_ftpClient.IsConnected) return;
try
{
var items = await _ftpClient.GetDirectoryListingAsync(path);
_currentRemotePath = NormalizeRemotePath(path);
// ... 更新 UI
}
catch (Exception ex)
{
UpdateStatus($"远程目录读取失败: {ex.Message}");
Logger.Error("加载远程目录失败", ex);
}
}
有几个细节值得深入探讨：
路径规范化不能省。 远程路径的拼接是个高频操作，用户可能手动输入 //data/files，也可能从树节点拼接出 \backup，我们必须统一处理：
private static string NormalizeRemotePath(string path)
{
if (string.IsNullOrWhiteSpace(path)) return "/";
var normalized = path.Replace('\\', '/');
if (!normalized.StartsWith('/')) normalized = "/" + normalized;
while (normalized.Contains("//"))
normalized = normalized.Replace("//", "/");
return normalized;
}
这个函数会被高频调用，写得稍微啰嗦一点没关系，但健壮性是第一位的。
SafeUI 封装必须有。 传输进度的回调通常是从后台线程触发的，如果直接操作 UI 控件，会抛出 InvalidOperationException。因此，我们需要一个统一的包装方法：
private void SafeUI(Action action)
{
if (InvokeRequired)
{
BeginInvoke(action);
return;
}
action();
}
这里用的是 BeginInvoke 而不是 Invoke，这是为了避免后台线程被 UI 线程阻塞从而导致死锁。这个坑很多开发者都踩过，值得牢记。
📦 传输队列——断点续传的正确姿势
FileTransfer 是整个项目中最复杂的一块。它的内部维护了一个 Queue<TransferTask> 和一个 SemaphoreSlim 信号量。后台有一个长期运行的 ProcessQueueAsync 协程在等待并处理任务。
private readonly Queue<TransferTask> _queue = new();
private readonly SemaphoreSlim _signal = new(0);
private void Enqueue(TransferTask task)
{
lock (_syncRoot)
{
_queue.Enqueue(task);
_taskMap[task.Id] = task;
}
_signal.Release(); // 通知消费者有新任务
TaskUpdated?.Invoke(this, task);
}
每入队一个任务，就调用一次 _signal.Release()。消费端则通过 _signal.WaitAsync() 来阻塞等待新任务。这是经典的生产者-消费者模式实现，比轮询更省资源，比 BlockingCollection 在某些场景下更灵活。
断点续传怎么实现？ 在下载任务入队时，我们会先检查本地文件是否已经存在：
public TransferTask EnqueueDownload(string remotePath, string localPath)
{
var resumeOffset = 0L;
if (File.Exists(localPath))
{
resumeOffset = new FileInfo(localPath).Length;
}
var task = new TransferTask
{
Type = TransferType.Download,
SourcePath = remotePath,
DestinationPath = localPath,
ResumeOffsetBytes = resumeOffset,
Message = resumeOffset > 0 ? "断点续传" : string.Empty
};
// ...
}
ResumeOffsetBytes 记录了已下载的字节数。在后续调用 FTPClient.DownloadFileAsync 时，会将它作为 REST 命令的偏移量参数传递。FTP 协议本身是支持 REST 命令的，这正是实现断点续传的底层基础。
暂停和恢复的状态机 是这部分逻辑里最烧脑的。暂停操作分为两种情况：如果任务还在队列中未被执行，直接从队列中移除即可；如果任务正在执行中，则需要通过其关联的 CancellationTokenSource 来取消操作。
关键在于，我们需要区分这次取消是用户主动“暂停”还是“真正取消”。我们的做法是，在调用取消的同时，在一个 _pausedTaskIds 集合中为这个任务打上标记。
catch (OperationCanceledException)
{
if (_pausedTaskIds.TryRemove(transferTask.Id, out _))
{
transferTask.Status = TransferStatus.Paused;
transferTask.Message = "已暂停";
// 记录当前已下载字节数，供恢复时使用
if (transferTask.Type == TransferType.Download && File.Exists(transferTask.DestinationPath))
{
transferTask.ResumeOffsetBytes = new FileInfo(transferTask.DestinationPath).Length;
}
}
else
{
transferTask.Status = TransferStatus.Canceled;
transferTask.Message = "已取消";
}
}
这样，在 catch 块中，我们就可以通过检查这个标记来判断异常原因，并正确更新任务状态。这种“用标记位区分取消原因”的技巧，在管理复杂的异步任务时非常实用。
WinForms 默认的控件样式确实有点“复古”。不过，通过纯代码设置颜色和属性，完全可以实现不错的视觉效果。我在项目中采用了一套蓝色系的配色方案：
var bgMain = Color.FromArgb(245, 248, 255); // 主背景，接近白色的淡蓝
var bgPanel = Color.FromArgb(232, 240, 255); // 面板背景
var accent = Color.FromArgb(37, 99, 235); // 强调色，深蓝
StyleButton(btnConnect, accent, Color.FromArgb(29, 78, 216), Color.White);
对于按钮，使用 FlatStyle.Flat 并配合自定义的背景色和边框色，可以去掉默认的立体感，让界面看起来更现代。对于 ListView 控件，务必设置 FullRowSelect = true 和 HideSelection = false，这样选中状态在控件失去焦点后依然会保持高亮。这个细节很多开发者会忽略，导致用户操作后找不到刚才选中了哪一项。
🌲 远程目录树的懒加载
远程服务器的目录结构可能非常深，一次性全部加载是不现实的。这里我采用了经典的“占位节点”懒加载方案：每个目录节点在初始化时，只添加一个文本为 "..." 的虚拟子节点。只有当用户展开这个节点时，才真正向服务器请求该目录下的子目录列表。
private async void tvRemote_BeforeExpand(object sender, TreeViewCancelEventArgs e)
{
if (e.Node.Nodes.Count == 1 && e.Node.Nodes[0].Text == "...")
{
e.Node.Nodes.Clear();
var items = await _ftpClient.GetDirectoryListingAsync(path);
foreach (var dir in items.Where(x => x.IsDirectory && x.Name is not "." and not ".."))
{
var node = new TreeNode(dir.Name) { Tag = dir.FullPath };
node.Nodes.Add("..."); // 继续放置占位节点
e.Node.Nodes.Add(node);
}
}
}
这个模式在文件树、组织架构树等需要动态加载的场景中极为通用。另外，将节点的完整路径字符串保存在 Tag 属性中，可以省去从节点文本反向查找路径的麻烦。
🐛 顺手记一个值得注意的代码问题
在检查代码时，我发现 ConnectAsync 方法里对 Server 字段的空值判断写了两遍：
if (string.IsNullOrWhiteSpace(connection.Server))
{
MessageBox.Show("请输入FTP服务器地址", ...);
return;
}
// 下面紧接着又判断了一次，完全多余
if (string.IsNullOrWhiteSpace(connection.Server))
{
MessageBox.Show("请输入FTP服务器地址", ...);
return;
}
这种重复判断不会影响功能，但它清楚地表明这段代码可能是通过复制粘贴产生的，并且没有经过仔细清理。在实际项目中，像连接前的参数校验这类逻辑，应该统一放在 BuildConnectionFromInputs 方法之后、真正开始 ConnectAsync 之前进行，这样逻辑会更清晰，也更容易维护。
写在最后
回顾整个项目，给我印象最深的，反而不是某个具体的技术难点，而是 职责边界的清晰划分 所带来的好处。FrmMain 只负责展示，FileTransfer 只负责任务调度，ConnectionManager 只负责数据的持久化——每个类都有且仅有一件核心的事情要做，修改起来心里特别有底，极大地提升了代码的可维护性。
虽然 WinForms 技术本身已不再年轻，但这些关于分层、解耦、异步处理和状态管理的设计思路，在任何 GUI 或后端 & 架构项目中都不过时。通过这次开源实战性质的“造轮子”，不仅加深了对网络/系统协议的理解，更重要的是巩固了软件工程的基本功。下次你再动手写任何桌面或工具类软件时，不妨先把层次和职责捋清楚，后续的开发会省心很多。
如果你对本文涉及的C#/.Net技术细节或完整的项目源码感兴趣，欢迎到 云栈社区 的对应板块进行更深入的交流与探讨。
发表于 2 小时前
|
查看: 2|
回复: 0
