Openai MCP

🚀 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代碼規範，可以確保項目的高質量、一致性和可維護性，同時提升開發效率和團隊協作。