xiaokeer-gen-project-tree

项目简介

xiaokeer-gen-project-tree 是一个 Python 命令行工具，核心功能是将任意项目的目录结构转换为带有可点击跳转链接的 Markdown 格式文档。项目支持 .gitignore 规则自动解析，适用于项目文档自动化生成、代码仓库结构展示、开发者快速了解项目架构等场景。

主要特性

• 📁 目录结构可视化：将项目目录转换为 Markdown 格式的树形结构
• 🔗 可点击跳转链接：每个文件/文件夹生成对应的相对路径链接
• 🚫 .gitignore 规则支持：自动解析并应用 .gitignore 排除规则
• ⚙️ 灵活配置：支持 JSON 配置文件自定义排除规则
• 🌐 跨平台兼容：正确处理 Windows/Unix 路径差异
• 📝 完善的日志系统：支持 INFO/DEBUG 多级别日志输出

技术栈

类别	技术
编程语言	Python 3.x
路径处理	pathlib
配置解析	json
命令行	argparse
日志系统	logging
数据结构	dataclasses
文件匹配	fnmatch, pathspec
测试框架	unittest

技术亮点

亮点一：pathspec 库的 GitIgnoreSpec 应用

使用 pathspec v1.0+ 新增的 GitIgnoreSpec 类，完整支持 Git 的 .gitignore 语义：

from pathspec import GitIgnoreSpec
spec = GitIgnoreSpec.from_lines(patterns)

优势：

• 完整支持 .gitignore 的所有语法特性
• 正确处理否定模式（!pattern）
• 正确处理目录匹配（foo/）
• 支持双星号通配符（**/node_modules）

亮点二：模块化设计 - 单一职责原则

每个模块职责清晰，耦合度低：

main.py              # 主入口 - 命令行参数解析与流程编排
config.py            # 配置管理 - 配置文件读取与验证
scanner.py           # 目录扫描 - 递归遍历与排除规则应用
gitignore_parser.py  # .gitignore解析 - 规则解析与文件匹配
generator.py         # 文档生成 - Markdown格式化输出

亮点三：数据类（dataclass）应用

使用 Python 3.7+ 的 dataclass 定义 TreeNode，代码简洁且类型安全：

@dataclass
class TreeNode:
    name: str                    # 文件/文件夹名称
    path: Path                   # 绝对路径
    is_dir: bool                 # 是否为目录
    relative_path: str           # 相对路径
    children: List['TreeNode']   # 子节点列表

亮点四：多编码 Fallback 机制

处理不同编码的 .gitignore 文件：

def _read_with_fallback_encoding(path: Path) -> List[str]:
    encodings = ['utf-8', 'gbk', 'gb2312', 'latin-1']
    for encoding in encodings:
        try:
            content = path.read_text(encoding=encoding)
            return content.splitlines()
        except UnicodeDecodeError:
            continue
    return []

亮点五：自定义异常体系

设计了带错误码的异常类，便于错误定位和处理：

错误码	含义
1	配置文件错误
2	项目路径不存在
3	项目路径无效
4	输出权限错误
99	未知错误

亮点六：完整的单元测试覆盖

测试文件覆盖所有核心模块：

测试文件	测试数量	覆盖场景
test_config.py	15个	配置验证、错误处理、中文路径
test_scanner.py	14个	目录扫描、排除规则、.gitignore解析
test_generator.py	16个	文档生成、格式验证、特殊字符

相关链接

• 代码仓库：GitHub