软件开发最佳实践知识库

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

核心原则

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 已更新