软件开发最佳实践知识库
本技能提供软件开发中的最佳实践指导，涵盖代码质量、架构设计、团队协作等方面。
核心原则
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)
- •使用领域语言：使用业务领域的术语
示例：
go
// ❌ 不好的命名
func proc(d []byte) int { ... }
var x int = 5
// ✅ 好的命名
func ProcessUserData(data []byte) int { ... }
var maxRetryAttempts int = 5
函数设计
- •小函数：一个函数只做一件事
- •参数限制：参数不超过 3-4 个，更多时考虑对象
- •避免副作用：函数应该是纯函数或明确其副作用
- •返回值：有意义的返回值，明确的错误处理
注释规范
- •代码即文档：好的代码不需要太多注释
- •解释为什么：注释应该说明为什么这样做，而非做了什么
- •及时更新：注释要与代码同步
- •API 文档：公共 API 必须有文档注释
3. 错误处理
明确的错误处理
go
// ❌ 吞掉错误
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 原则
- •命名不清：提供更好的命名建议
- •缺少错误处理：指出错误处理的最佳实践
- •性能问题：提供优化建议
- •安全风险：指出潜在的安全问题
检查清单
在代码审查或开发时，参考以下清单：
代码质量
- • 命名清晰、有意义
- • 函数职责单一
- • 无重复代码
- • 错误处理完善
- • 有必要的注释
性能
- • 算法效率合理
- • 资源正确释放
- • 无明显性能瓶颈
安全
- • 输入已验证
- • 无敏感信息泄露
- • 权限检查正确
测试
- • 有对应的单元测试
- • 关键路径已覆盖
- • 边界条件已测试
文档
- • 公共 API 有文档
- • 复杂逻辑有说明
- • README 已更新