| name | best-practices |
| description | 提供软件开发最佳实践指导，自动检查和建议改进 |
| allowed-tools | ["fs_read"] |
| triggers | [{"type":"keyword","keywords":["最佳实践","best practice","规范","标准","如何","应该"]},{"type":"context","condition":"during /review"},{"type":"context","condition":"during /optimize"}] |
软件开发最佳实践知识库
本技能提供软件开发中的最佳实践指导，涵盖代码质量、架构设计、团队协作等方面。
核心原则
1. 代码质量原则
SOLID 原则
-
S - Single Responsibility (单一职责)
- 每个类/函数只负责一件事
- 如果一个类有多个修改的理由，说明职责过多
-
O - Open/Closed (开闭原则)
-
L - Liskov Substitution (里氏替换)
-
I - Interface Segregation (接口隔离)
- 不应该强迫客户端依赖它不使用的方法
- 接口应该小而专注
-
D - Dependency Inversion (依赖倒置)
- 依赖于抽象而非具体实现
- 高层模块不应该依赖低层模块
DRY 原则 (Don't Repeat Yourself)
- 避免重复代码
- 提取公共逻辑到函数或模块
- 使用配置而非硬编码
KISS 原则 (Keep It Simple, Stupid)
YAGNI 原则 (You Aren't Gonna Need It)
- 不要实现当前不需要的功能
- 避免过早优化
- 基于实际需求而非假设
2. 代码组织
命名规范
- 清晰表意：名称应该说明用途，而非实现
- 一致性：遵循项目的命名约定
- 避免缩写：除非是广为接受的缩写 (如 HTTP, URL)
- 使用领域语言：使用业务领域的术语
示例：
func proc(d []byte) int { ... }
var x int = 5
func ProcessUserData(data []byte) int { ... }
var maxRetryAttempts int = 5
函数设计
- 小函数：一个函数只做一件事
- 参数限制：参数不超过 3-4 个，更多时考虑对象
- 避免副作用：函数应该是纯函数或明确其副作用
- 返回值：有意义的返回值，明确的错误处理
注释规范
- 代码即文档：好的代码不需要太多注释
- 解释为什么：注释应该说明为什么这样做，而非做了什么
- 及时更新：注释要与代码同步
- API 文档：公共 API 必须有文档注释
3. 错误处理
明确的错误处理
result, _ := someFunction()
result, err := someFunction()
if err != nil {
return fmt.Errorf("failed to process: %w", err)
}
错误上下文
- 错误消息应该包含足够的上下文
- 使用错误包装（error wrapping）保留原始错误
- 在适当的层级处理错误
自定义错误类型
- 对于可恢复的错误，定义专门的错误类型
- 便于调用者识别和处理特定错误
4. 测试最佳实践
测试金字塔
- 单元测试：数量最多，速度最快
- 集成测试：中等数量，测试组件交互
- 端到端测试：少量，测试完整流程
测试编写原则
- AAA 模式：Arrange (准备), Act (执行), Assert (断言)
- 独立性：测试之间不应该有依赖
- 可重复性：多次运行结果一致
- 自描述：测试名称说明测试什么
测试覆盖
- 关键路径必须测试
- 边界条件要测试
- 错误场景要测试
- 覆盖率不是唯一指标，质量更重要
5. 性能最佳实践
数据库
- 使用索引
- 避免 N+1 查询
- 使用批量操作
- 适当的缓存策略
算法和数据结构
- 选择合适的数据结构
- 注意时间复杂度
- 避免不必要的嵌套循环
资源管理
- 及时释放资源（文件句柄、网络连接）
- 使用对象池复用对象
- 注意内存泄漏
6. 安全最佳实践
输入验证
- 永远不要信任用户输入
- 验证、清理所有外部输入
- 使用白名单而非黑名单
认证和授权
敏感数据
- 不要在代码中硬编码密钥
- 使用环境变量或密钥管理服务
- 敏感日志要脱敏
7. 版本控制
Commit 规范
- 清晰的消息：说明做了什么和为什么
- 原子提交：一个 commit 做一件事
- 频繁提交：小步提交，易于回滚
分支策略
- 主分支永远可发布
- 功能分支开发
- 及时合并，避免长期分支
8. 代码审查
审查重点
- 功能正确性
- 代码质量和可维护性
- 潜在的 bug 和边界情况
- 性能问题
- 安全漏洞
审查态度
- 建设性反馈
- 基于事实和标准
- 虚心接受建议
- 解释决策原因
9. 文档
必要的文档
- README：项目概述和快速开始
- API 文档：接口说明和示例
- 架构文档：系统设计和关键决策
- 运维文档：部署和监控
文档原则
10. 持续改进
代码重构
- 小步重构
- 在测试保护下重构
- 不改变外部行为
- 及时清理技术债务
学习和分享
- 代码审查是学习机会
- 分享最佳实践
- 从错误中学习
- 保持技术更新
应用指导
当检测到以下情况时，自动提供相关建议：
- 代码复杂度高：建议拆分函数，应用 SOLID 原则
- 重复代码：建议提取公共逻辑，应用 DRY 原则
- 命名不清：提供更好的命名建议
- 缺少错误处理：指出错误处理的最佳实践
- 性能问题：提供优化建议
- 安全风险：指出潜在的安全问题
检查清单
在代码审查或开发时，参考以下清单：
代码质量
性能
安全
测试
文档
