fscan — 目录扫描工具

轻量、跨平台的目录树扫描工具，支持流式输出与多种过滤选项。

✨ 特性

• 🌲 树状目录输出（类似 tree 命令）
• 🔍 可选扩展名过滤（-e）
• 💾 流式模式：边遍历边写入，低内存占用
• 📁 支持输出到文件（-o）
• 🛡️ 安全保护：递归深度限制、符号链接循环检测
• ⚡ 高性能：大缓冲区设计，支持大规模目录扫描
• 🧪 完整的单元测试覆盖

🚀 快速开始

构建

go build -o fscan.exe

基本使用

# 扫描当前目录（默认递归）
fscan.exe

# 扫描指定目录
fscan.exe C:\Users\YourName\Documents

# 只显示 .txt 文件
fscan.exe -e .txt

# 非递归，只显示当前层级
fscan.exe -r=false

# 指定输出文件路径
fscan.exe -o result.txt

# 不保存到文件，只在控制台显示
fscan.exe -s=false

📋 命令行参数

参数	类型	默认值	说明
-r	bool	true	是否递归查找子目录
-e	string	""	扩展名过滤（例如：.txt 或 txt）
-s	bool	true	是否保存结果到文件
-o	string	""	输出文件路径（空则在扫描目录下创建 dir_scan_result.txt）

⚙️ 配置文件

支持通过配置文件设置默认参数，搜索顺序：

1. 当前工作目录：fscan.conf
2. 用户主目录：.fscan.conf
3. 可执行文件目录：fscan.conf

配置文件示例（fscan.conf）：

# fscan.conf — 默认配置
# 注：文件为简单 key=value 格式，支持以 # 或 ; 开头的注释行

# 是否递归查找（true/false）
r = true

# 扩展名过滤（可带或不带前导点，例如：.txt 或 txt）
e = 

# 是否保存结果到文件（true/false）
s = true

# 输出文件路径（空表示在扫描目录下创建 dir_scan_result.txt）
o = 

🔒 安全特性

递归深度限制

• 最大递归深度：1000 层
• 防止极深目录结构导致栈溢出
• 超过限制时显示警告信息

符号链接循环检测

• 自动检测并跳过符号链接循环
• 避免无限递归和程序挂起
• 显示循环引用警告

错误处理

• Goroutine 泄漏保护（使用 defer 确保资源释放）
• 文件创建失败自动回退到当前目录
• 详细的错误信息提示

📊 性能优化

• 大缓冲区：输出通道缓冲区 10,000 条消息
• 流式处理：边遍历边写入，内存占用低
• 双缓冲写入：32KB 缓冲区用于控制台和文件输出
• 适用场景：可处理包含数十万文件的大型目录

🧪 测试

运行单元测试：

go test -v

运行性能测试：

go test -bench=. -benchmem

📝 更新日志

v1.1.0 (2026-02-20)

🔧 BUG修复

• ✅ 修复 goroutine 泄漏风险，确保程序异常时能正常退出
• ✅ 修复文件保存路径显示错误问题
• ✅ 添加递归深度限制（最大 1000 层），防止栈溢出
• ✅ 添加符号链接循环检测，避免无限递归

⚡ 性能改进

• ⬆️ 增加输出通道缓冲区到 10,000，提升大规模扫描性能
• 📈 优化错误处理逻辑，提供更清晰的错误信息

📚 文档改进

• 📝 更新配置文件注释，移除过时参数说明
• 💬 添加代码注释，提升可维护性
• 🧪 新增单元测试框架，覆盖核心功能

⚠️ 注意事项

• 最大递归深度限制为 1000 层
• 自动检测并跳过符号链接循环
• 建议在大型目录扫描时使用 -s 参数保存结果

v1.0.0 - 初始版本

• 基础目录扫描功能
• 递归遍历支持
• 扩展名过滤
• 结果保存功能

🛠️ 技术细节

架构设计

• AppContext 模式：封装运行时状态，避免全局变量
• 通道通信：使用 Go channel 实现异步输出
• Goroutine 管理：独立的输出处理协程，提升性能

代码质量

• ✅ 完整的单元测试覆盖
• ✅ 详细的代码注释
• ✅ 错误处理完善
• ✅ 符合 Go 语言最佳实践

📄 许可证

本项目使用 MIT 许可证，详见 LICENSE 文件。

🤝 贡献

欢迎提交 Issue 和 Pull Request！

📮 联系方式

如有问题或建议，请通过 GitHub Issues 联系。

---

注意：Windows 下编译会生成 fscan.exe，已在 .gitignore 中配置忽略可执行文件。