XHS-Downloader开发规范终极指南：贡献代码前必读的完整风格指南

想要为XHS-Downloader这个优秀的小红书作品采集工具贡献代码？在提交PR之前，这份完整的开发规范指南将帮助你快速了解项目的代码风格要求，确保你的贡献能够顺利被接受！🔥

XHS-Downloader是一个基于AIOHTTP模块实现的免费、轻量、开源的小红书图文/视频作品采集工具。作为GitHub上备受欢迎的开源项目，它拥有清晰的项目结构和严格的代码规范，这有助于保持代码库的整洁和可维护性。

📋 项目架构概览

XHS-Downloader采用模块化设计，代码结构清晰，主要包含以下几个核心模块：

• CLI模块：位于source/CLI/目录，处理命令行接口
• TUI模块：位于source/TUI/目录，提供图形用户界面
• 应用模块：位于source/application/目录，核心业务逻辑
• 扩展模块：位于source/expansion/目录，提供各种工具函数
• 翻译模块：位于source/translation/目录，支持多语言

XHS-Downloader命令行界面展示了详细的参数说明和交互逻辑

🎯 代码风格与格式化规范

Ruff工具配置

项目使用Ruff作为主要的代码格式化和linting工具，配置位于pyproject.toml文件中：

[tool.ruff]
line-length = 88
indent-width = 4
target-version = "py312"

[tool.ruff.format]
quote-style = "double"
indent-style = "space"
skip-magic-trailing-comma = false

关键配置说明：

• 行长度限制：88个字符
• 缩进：4个空格
• Python版本：3.12
• 引号风格：双引号
• 魔法尾随逗号：保留

命名规范要求

• 变量和函数名：使用蛇形命名法（snake_case）
• 类名：使用帕斯卡命名法（PascalCase）
• 常量：使用全大写蛇形命名法

🚀 开发工作流最佳实践

分支管理策略

• 主分支：master分支用于稳定版本发布
• 开发分支：develop分支用于日常开发
• 功能分支：从develop分支创建，命名格式为feature/功能描述

提交信息规范

每个提交都应该包含清晰、简洁的提交信息，遵循以下格式：

<类型>: <简短描述>

常见类型示例：

• feat: 新功能
• fix: 错误修复
• docs: 文档更新
• style: 代码风格调整

🔧 核心模块开发指南

应用模块开发

应用模块位于source/application/目录，包含主要的业务逻辑：

• app.py：核心应用类，负责作品信息提取和下载
• download.py：文件下载处理
• request.py：HTTP请求封装

关键类结构：

class XHS:
    def __init__(self, ...):
        # 初始化参数
    async def extract(self, url, download=False, ...):
        # 作品信息提取逻辑

配置参数处理

所有配置参数都通过source/module/settings.py进行管理，确保参数验证和兼容性处理。

📝 测试与质量保证

代码质量检查

在提交代码前，请确保：

1. 运行Ruff进行代码格式检查
2. 确保所有功能按预期工作
3. 添加适当的注释和文档

💡 实用开发技巧

参数验证

使用类型提示和参数验证确保代码的健壮性：

def extract(
    self,
    url: str,
    download: bool = False,
    index: list | tuple = None,
    log=None,
    bar=None,
    data: bool = True,
) -> list[dict]:

异步编程最佳实践

项目广泛使用异步编程，确保：

• 正确使用async/await
• 适当的错误处理
• 资源清理

🎉 贡献流程总结

遵循这些开发规范，你的贡献将更容易被审查和接受：

1. 从develop分支拉取最新代码
2. 创建功能分支进行开发
3. 确保代码风格一致
4. 编写清晰的提交信息
5. 提交PR到develop分支

记住，清晰的代码和规范的提交不仅有助于维护者审查，也方便其他贡献者理解你的工作。让我们一起维护这个优秀的开源项目！✨

XHS-Downloader图形界面展示了完整的用户交互体验

现在你已经掌握了XHS-Downloader的开发规范，可以开始你的贡献之旅了！