软件开发最佳实践知识库

本技能提供软件开发中的最佳实践指导，涵盖代码质量、架构设计、团队协作等方面。

核心原则

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 原则
• 命名不清：提供更好的命名建议
• 缺少错误处理：指出错误处理的最佳实践
• 性能问题：提供优化建议
• 安全风险：指出潜在的安全问题

检查清单

在代码审查或开发时，参考以下清单：

代码质量

• 命名清晰、有意义
• 函数职责单一
• 无重复代码
• 错误处理完善
• 有必要的注释

性能

• 算法效率合理
• 资源正确释放
• 无明显性能瓶颈

安全

• 输入已验证
• 无敏感信息泄露
• 权限检查正确

测试

• 有对应的单元测试
• 关键路径已覆盖
• 边界条件已测试

文档

• 公共 API 有文档
• 复杂逻辑有说明
• README 已更新