🚀 MCP 代码规范

本代码规范旨在确保项目的高质量、一致性和可维护性，同时提升开发效率和团队协作。以下将从基本规则、高级规范、代码审查、部署要求和项目维护等方面详细阐述。

🚀 快速开始

遵循本代码规范，开发者可从以下基本规则入手，逐步深入了解和应用整个规范体系。

✨ 主要特性

• 全面性：涵盖命名、格式、文件结构、异常处理等基础规则，以及依赖管理、测试、文档编写等高级规范。
• 规范性：严格遵循PEP8和Google Python Style Guide，保证代码风格的统一。
• 安全性：对输入验证、访问控制等安全方面有明确要求，及时修复安全漏洞。
• 可维护性：通过定期清理代码、处理技术债务等方式，维护项目的可维护性和扩展性。

📚 详细文档

🔍 基本规则

命名约定

• 变量和函数名采用蛇形命名法（snake_case）。
• 类名使用驼峰命名法（PascalCase）。
• 常量全大写，单词间用下划线分隔（UPPER_SNAKE_CASE）。

代码格式

• 每个函数或类前后需有注释说明功能。
• 代码块缩进使用4个空格，禁止使用制表符。
• 行长不超过120字符，必要时折行。

文件结构

• 每个文件要有模块级别的文档字符串。
• 相关函数和类按逻辑分组，每组之间加一行空行分隔。
• 导入模块后加一行空行。

注释

• 重要逻辑添加块注释解释。
• 私有方法前加注释说明用途。
• 注释与代码间至少一行空行分隔。

异常处理

• 所有可能抛出异常的地方必须有try - except块。
• 自定义异常继承自BaseException，放在单独文件。
• 异常信息包含错误码和详细描述。

日志记录

• 使用logging模块记录日志。
• 日志级别分为DEBUG、INFO、WARNING、ERROR、CRITICAL。
• 重要操作记录INFO及以上日志。

🌟 高级规范

依赖管理

• 所有第三方库使用pipenv或poetry管理。
• 环境文件（如Pipfile）必须包含项目所有依赖。
• 禁止直接安装开发版本依赖。

测试要求

• 每个功能模块必须有单元测试。
• 测试用例覆盖所有主要代码路径。
• 使用pytest进行测试，输出覆盖率报告。

文档编写

• 项目提供完整API文档和用户手册。
• 文档使用Sphinx或类似工具生成。
• 每个模块、类、函数都有详细的doctring。

版本控制

• 使用Git进行版本管理。
• 提交信息遵循Conventional Commits规范。
• 项目有明确的分支策略和合并流程。

👀 代码审查

提交前检查

• 运行lint工具检查代码格式。
• 执行单元测试确保所有用例通过。
• 确保没有暴露敏感信息。

代码风格

• 遵循PEP8和Google Python Style Guide。
• 保持代码简洁，避免复杂逻辑。
• 注重代码的可读性和可维护性。

安全规范

• 输入验证：所有外部输入都必须经过验证。
• 访问控制：敏感操作需要权限检查。
• 安全漏洞及时修复并更新依赖。

🚀 部署要求

环境准备

• 确保生产环境与开发环境一致。
• 配置环境变量管理不同环境设置。
• 使用容器化部署（Docker）。

配置管理

• 使用Ansible或Chef进行配置管理。
• 配置文件版本控制，避免硬编码。
• 支持动态配置和热重载。

监控与报警

• 部署Prometheus监控系统。
• 设置合理的报警阈值。
• 提供日志分析工具。

🛠️ 项目维护

代码库管理

• 定期清理无用代码和依赖。
• 处理技术债务，保持代码质量。
• 维护项目的可维护性和扩展性。

版本发布

• 使用语义化版本控制（SEMVER）。
• 发布前更新CHANGELOG。
• 提供升级指南和迁移说明。

社区贡献

• 欢迎外部开发者贡献代码。
• 设立明确的贡献流程和规范。
• 维护良好的开源社区关系。

通过遵循以上MCP代码规范，可以确保项目的高质量、一致性和可维护性，同时提升开发效率和团队协作。