development.md

开发指南

English | 中文 | Français | Español | العربية | Русский

本文档提供了有关开发流程、代码标准和为 MCP 数据库工具项目做贡献的最佳实践的详细信息。

代码质量

质量门禁

我们使用SonarCloud维护高代码质量标准。所有拉取请求必须通过以下质量门禁：

• 代码覆盖率：≥ 80%
• 代码质量：
  • 无阻断或严重问题
  • 主要问题少于10个
  • 代码重复率 < 3%
• 安全性：
  • 无安全漏洞
  • 无安全热点

自动化检查

我们的CI/CD流程自动执行：

1. 完整测试套件执行
2. 代码覆盖率分析
3. SonarCloud静态代码分析
4. 质量门禁验证

不满足这些标准的拉取请求将自动被阻止合并。

代码风格

我们使用Ruff进行代码风格检查和格式化，确保代码质量和一致性。

基本规则

1. 行长度：最大88个字符
2. 缩进：使用4个空格（不使用制表符）
3. 引号：使用双引号作为字符串引号
4. 命名规范：
   • 类名：使用CamelCase（如DatabaseHandler）
   • 函数和变量：使用snake_case（如execute_query）
   • 常量：使用大写加下划线（如MAX_CONNECTIONS）
   • 私有方法和属性：使用单下划线前缀（如_connect）

导入规则

1. 导入顺序：

   • 标准库
   • 第三方库
   • 本地应用/库

2. 每个导入组之间应有一个空行

代码组织

1. 类定义之间应有两个空行
2. 方法定义之间应有一个空行
3. 相关的代码应该分组在一起

Ruff规则集

本项目使用以下Ruff规则集：

• E: pycodestyle错误
• F: pyflakes
• I: isort
• N: pep8-naming
• UP: pyupgrade
• B: flake8-bugbear
• C4: flake8-comprehensions
• SIM: flake8-simplify
• T20: flake8-print

本地开发

安装工具

# 安装Ruff
uv pip install ruff

# 安装pre-commit
uv pip install pre-commit
pre-commit install

代码检查

# 检查整个项目
ruff check .

# 自动修复问题
ruff check --fix .

代码格式化

# 检查格式
ruff format --check .

# 自动格式化
ruff format .

使用pre-commit

项目已配置pre-commit钩子，提交代码时会自动运行Ruff检查和格式化。

# 手动运行pre-commit
pre-commit run --all-files

测试与覆盖率

# 运行带覆盖率的测试
pytest --cov=src/mcp_dbutils --cov-report=xml:coverage.xml tests/

其他开发工具

1. 在IDE中使用SonarLint及早发现问题
2. 在PR评论中查看SonarCloud分析结果

常见问题

如何忽略特定规则？

在代码中使用注释忽略特定行的规则：

# 忽略整行
some_code_here  # noqa

# 忽略特定规则
some_code_here  # noqa: E501

# 忽略多个规则
some_code_here  # noqa: E501, F401

如何在项目级别忽略规则？

在pyproject.toml的[tool.ruff]部分添加：

ignore = ["E501"]

如何处理第三方库导入问题？

如果第三方库导入顺序有问题，可以在pyproject.toml中配置：

[tool.ruff.isort]
known-third-party = ["third_party_lib"]

CI/CD 集成

GitHub Actions 会在每次推送和 PR 时自动运行 Ruff 检查和格式化，确保代码符合规范。

自动化流程

每个 PR 会触发以下自动化检查：

1. 代码风格检查：使用 Ruff 验证代码是否符合项目风格规范
2. 单元测试：运行所有测试确保功能正常
3. 代码覆盖率：确保测试覆盖率达到要求
4. SonarCloud 分析：进行深度代码质量和安全性分析

如何查看 CI 结果

1. 在 GitHub PR 页面查看 "Checks" 标签页
2. 点击具体的检查查看详细信息
3. 对于 SonarCloud 分析，可以点击链接查看完整报告

版本更新

MCP数据库工具会定期发布更新，包含新功能、性能改进和错误修复。大多数情况下，更新过程由MCP客户端自动管理，您无需手动干预。

获取最新版本

• 使用MCP客户端：大多数MCP客户端（如Claude Desktop、Cursor等）会自动更新到最新版本

• 手动检查更新：

  • 访问GitHub仓库查看最新版本
  • 阅读发布说明了解新功能和变更

• 问题报告：

  • 如果您在更新后遇到问题，请提交issue