AsyncSSH中SFTPClient.put方法的max_requests和block_size参数行为解析

在AsyncSSH项目的最新版本(v2.18.0和v2.17.0)中，SFTPClient.put方法关于max_requests和block_size参数的行为存在一些需要开发者注意的特性。本文将深入分析这些参数的实际行为与文档描述的差异，帮助开发者更好地理解和使用这些功能。

参数文档描述与实际行为的差异

根据AsyncSSH官方文档，SFTPClient.put方法的block_size参数用于指定上传文件时读写请求的大小，默认值为服务器允许的最大值，如果服务器未公布限制则默认为16KB。而max_requests参数则指定并行读写请求的最大数量，默认值为128。

然而在实际使用中发现，当明确指定max_requests=1和block_size=32KB时，系统仍然会并行发送两个16KB的写请求，这与预期行为不符。这表明底层实现可能存在参数传递的问题。

问题根源分析

经过深入分析，发现问题出在SFTPFileCopier类的实现上。当SFTPClient.put方法被调用时，虽然高层参数设置正确，但在创建目标文件句柄时(_dstfs.open调用)，没有将block_size和max_requests参数传递给底层文件对象。这导致底层仍然使用默认的16KB块大小，而不是用户指定的32KB。

解决方案与修复

项目维护者Ron Frederick在后续版本(v2.19.0)中修复了这个问题。主要修改包括：

1. 修正了文档中的描述错误，将"when downloading the files"更正为"when uploading the files"
2. 确保block_size参数在文件打开时被正确传递
3. 修复了block_size=0时的特殊处理逻辑

性能优化建议

在实际使用中，开发者需要注意：

1. 设置max_requests=1会显著降低SFTP传输性能，特别是对于大文件传输
2. 当服务器不支持limits扩展时(如OpenSSH 8.4及以下版本)，AsyncSSH会使用16KB的安全写入大小
3. 在OpenSSH 8.5及以上版本中，可以利用limits扩展获得更好的性能

最佳实践

对于需要精确控制传输参数的场景，建议：

1. 明确指定block_size参数，特别是在服务器不支持limits扩展时
2. 避免不必要地将max_requests设置为1，除非有特殊需求
3. 考虑服务器版本对功能支持的影响
4. 对于性能敏感的应用，建议使用AsyncSSH 2.19.0或更高版本

通过理解这些底层行为特性，开发者可以更好地优化SFTP文件传输性能，避免潜在的性能陷阱。