chatExcel

# 代码审查清单 ## 概述 本文档提供了 ChatExcel MCP 项目的代码审查清单，确保代码质量、安全性和可维护性的一致性标准。 ## 通用代码质量检查 ### 1. 代码风格和格式 #### 基础格式 - [ ] 代码已通过 `black` 格式化 - [ ] 导入语句已通过 `isort` 排序 - [ ] 行长度不超过 88 字符 - [ ] 使用 4 个空格缩进，不使用制表符 - [ ] 文件末尾有且仅有一个换行符 #### 命名规范 - [ ] 变量和函数使用 `snake_case` - [ ] 类名使用 `PascalCase` - [ ] 常量使用 `UPPER_SNAKE_CASE` - [ ] 私有成员以单下划线开头 - [ ] 特殊方法使用双下划线包围 - [ ] 名称具有描述性，避免缩写 #### 注释和文档 - [ ] 所有公共函数和类都有文档字符串 - [ ] 文档字符串遵循 Google 或 NumPy 风格 - [ ] 复杂逻辑有适当的行内注释 - [ ] 注释内容准确且有用 - [ ] 避免显而易见的注释 ### 2. 类型注解 #### 类型覆盖 - [ ] 所有函数参数都有类型注解 - [ ] 所有函数都有返回类型注解 - [ ] 类属性有适当的类型注解 - [ ] 使用 `Optional` 标记可选参数 - [ ] 复杂类型使用 `Union`、`List`、`Dict` 等 #### 类型准确性 - [ ] 类型注解与实际使用一致 - [ ] 避免使用 `Any` 类型（除非必要） - [ ] 泛型类型参数正确指定 - [ ] 导入必要的类型模块 ### 3. 代码结构 #### 函数设计 - [ ] 函数职责单一，功能明确 - [ ] 函数长度合理（通常不超过 50 行） - [ ] 参数数量合理（通常不超过 5 个） - [ ] 避免深层嵌套（不超过 3 层） - [ ] 使用早期返回减少嵌套 #### 类设计 - [ ] 类职责单一，符合单一职责原则 - [ ] 继承关系合理，避免过深继承 - [ ] 接口设计清晰，易于使用 - [ ] 适当使用组合而非继承 - [ ] 遵循开闭原则 ## 异常处理检查 ### 1. 异常使用 - [ ] 使用项目定义的自定义异常类 - [ ] 异常类型选择准确和具体 - [ ] 异常参数完整且正确 - [ ] 异常消息清晰且有用 - [ ] 提供了解决建议 ### 2. 异常处理 - [ ] 捕获具体的异常类型，避免裸露的 `except:` - [ ] 异常处理逻辑合理 - [ ] 使用 `from e` 保持异常链 - [ ] 适当的资源清理（使用 `finally` 或上下文管理器） - [ ] 记录适当的日志 ### 3. 异常传播 - [ ] 异常在适当的层级被处理 - [ ] 不要吞没异常（除非有充分理由） - [ ] 异常转换合理且保持信息 - [ ] API 边界有统一的异常处理 ## 安全性检查 ### 1. 输入验证 - [ ] 所有外部输入都经过验证 - [ ] 使用白名单而非黑名单验证 - [ ] 文件路径验证，防止路径遍历 - [ ] 数据类型和范围验证 - [ ] SQL 注入防护（如果适用） ### 2. 敏感信息 - [ ] 不在代码中硬编码密码、密钥等 - [ ] 敏感信息不出现在日志中 - [ ] 使用环境变量或配置文件管理敏感信息 - [ ] 错误消息不泄露敏感信息 ### 3. 权限和访问控制 - [ ] 文件操作有适当的权限检查 - [ ] 代码执行有安全限制 - [ ] 资源访问有适当的边界检查 - [ ] 使用最小权限原则 ## 性能检查 ### 1. 算法效率 - [ ] 算法复杂度合理 - [ ] 避免不必要的循环嵌套 - [ ] 使用适当的数据结构 - [ ] 避免重复计算 ### 2. 资源使用 - [ ] 内存使用合理，避免内存泄漏 - [ ] 文件和网络连接正确关闭 - [ ] 大数据处理考虑分批处理 - [ ] 使用生成器处理大量数据 ### 3. 缓存和优化 - [ ] 适当使用缓存减少重复计算 - [ ] 数据库查询优化 - [ ] 避免 N+1 查询问题 - [ ] 考虑异步处理提高并发性 ## 测试检查 ### 1. 测试覆盖 - [ ] 新功能有对应的单元测试 - [ ] 测试覆盖主要代码路径 - [ ] 边界条件有测试覆盖 - [ ] 异常情况有测试覆盖 - [ ] 集成测试覆盖关键流程 ### 2. 测试质量 - [ ] 测试用例独立，不相互依赖 - [ ] 测试数据清晰且有代表性 - [ ] 断言明确且有意义 - [ ] 测试名称描述性强 - [ ] 使用适当的测试工具和框架 ### 3. 可测试性 - [ ] 代码设计便于测试 - [ ] 依赖可以被模拟（mock） - [ ] 避免硬编码依赖 - [ ] 使用依赖注入提高可测试性 ## 依赖管理检查 ### 1. 依赖选择 - [ ] 依赖库选择合理且必要 - [ ] 避免引入过重的依赖 - [ ] 依赖版本固定或有合理的版本范围 - [ ] 检查依赖的安全漏洞 ### 2. 导入管理 - [ ] 导入语句按标准排序 - [ ] 避免循环导入 - [ ] 使用相对导入（项目内）和绝对导入（第三方） - [ ] 移除未使用的导入 ## 配置和环境检查 ### 1. 配置管理 - [ ] 配置项有合理的默认值 - [ ] 配置验证逻辑完整 - [ ] 环境特定配置分离 - [ ] 配置变更向后兼容 ### 2. 环境兼容性 - [ ] 代码在目标 Python 版本上运行 - [ ] 跨平台兼容性考虑 - [ ] 依赖版本兼容性检查 - [ ] 环境变量使用合理 ## 文档检查 ### 1. 代码文档 - [ ] README 文件完整且最新 - [ ] API 文档准确且完整 - [ ] 安装和使用说明清晰 - [ ] 变更日志维护及时 ### 2. 内联文档 - [ ] 复杂算法有解释说明 - [ ] 业务逻辑有适当注释 - [ ] TODO 和 FIXME 有跟踪 - [ ] 文档与代码保持同步 ## Git 和版本控制检查 ### 1. 提交质量 - [ ] 提交消息清晰且描述性强 - [ ] 提交粒度合理，一次提交一个逻辑变更 - [ ] 避免提交调试代码和临时文件 - [ ] 敏感信息不在版本历史中 ### 2. 分支管理 - [ ] 功能分支命名规范 - [ ] 合并请求有适当的描述 - [ ] 代码冲突正确解决 - [ ] 分支历史清晰 ## 特定领域检查 ### 1. Excel 处理 - [ ] 文件格式验证完整 - [ ] 大文件处理考虑内存限制 - [ ] 编码问题处理正确 - [ ] 公式解析安全可靠 ### 2. 数据处理 - [ ] 数据类型转换安全 - [ ] 缺失值处理合理 - [ ] 数据验证逻辑完整 - [ ] 性能优化适当 ### 3. MCP 集成 - [ ] MCP 协议实现正确 - [ ] 工具注册和调用正确 - [ ] 错误处理符合 MCP 规范 - [ ] 资源管理合理 ## 审查流程 ### 1. 自审查 - [ ] 代码作者完成自审查 - [ ] 运行所有测试并通过 - [ ] 运行静态分析工具 - [ ] 检查代码覆盖率 ### 2. 同行审查 - [ ] 至少一名同事审查代码 - [ ] 审查意见得到适当回应 - [ ] 重要变更有多人审查 - [ ] 审查记录完整 ### 3. 自动化检查 - [ ] CI/CD 流水线通过 - [ ] 静态分析工具通过 - [ ] 安全扫描通过 - [ ] 性能测试通过（如果适用） ## 审查工具 ### 1. 静态分析工具 - `black` - 代码格式化 - `isort` - 导入排序 - `flake8` - 代码风格检查 - `mypy` - 类型检查 - `bandit` - 安全检查 - `pylint` - 代码质量检查 ### 2. 测试工具 - `pytest` - 单元测试 - `coverage` - 代码覆盖率 - `tox` - 多环境测试 ### 3. 依赖检查 - `safety` - 安全漏洞检查 - `pip-audit` - 依赖审计 - `pipdeptree` - 依赖树分析 ## 审查记录 ### 审查清单模板 ```markdown ## 代码审查记录 **PR/MR**: #[编号] **审查者**: [姓名] **审查日期**: [日期] **代码作者**: [姓名] ### 检查项目 - [ ] 代码风格和格式 - [ ] 类型注解 - [ ] 异常处理 - [ ] 安全性 - [ ] 性能 - [ ] 测试覆盖 - [ ] 文档 ### 主要问题 1. [问题描述] 2. [问题描述] ### 建议改进 1. [改进建议] 2. [改进建议] ### 审查结论 - [ ] 批准合并 - [ ] 需要修改后重新审查 - [ ] 拒绝合并 ### 备注 [其他说明] ``` --- **版本**: 1.0 **更新日期**: 2024-12-20 **维护者**: ChatExcel Team