general-best-practices

通用最佳实践

涵盖适用于各种技术栈和项目类型的软件开发最佳实践。

代码质量

可读性与可维护性

编写简短、专注且职责单一的函数。

为变量、函数和类使用清晰、描述性强的名称。

避免多层嵌套；优先使用提前返回和保护子句。

将函数和方法控制在合理长度内（通常少于 30 行）。

错误处理

始终显式处理错误，而不是默默忽略。

使用包装错误，以便追踪并提供上下文。

提供有意义的错误消息，帮助调试。

在开发期间快速失败并明确报错。

代码组织

将代码组织到逻辑清晰的模块和包中。

分离关注点：将业务逻辑与基础设施代码分开。

采用一致的文件和文件夹命名规范。

在 API 设计中遵循最小意外原则。

架构

整洁架构原则

将代码划分为不同层：

• 表示层／处理器：处理外部请求和响应
• 应用层／服务：编排业务操作
• 领域层：核心业务逻辑和实体
• 基础设施层：外部系统、数据库和框架

设计原则

优先使用组合，而非继承。

面向接口编程，而非面向实现编程。

使用依赖注入以提高可测试性和灵活性。

为变化而设计：隔离业务逻辑，尽量减少对框架的绑定。

在适当情况下应用 SOLID 原则。

测试

单元测试

编写快速、隔离且可重复的测试。

使用表驱动测试覆盖多种场景。

妥善模拟外部依赖。

力求为业务关键代码实现较高的测试覆盖率。

集成测试

测试组件与外部系统之间的交互。

使用单独的测试配置和数据库。

每次测试运行后清理测试数据。

测试组织

将快速单元测试与较慢的集成测试分开。

在开发期间频繁运行快速测试。

在 CI/CD 流水线中包含测试。

安全

输入验证

在服务边界验证所有输入。

绝不信任用户输入；对所有输入进行清理和验证。

使用参数化查询以防止 SQL 注入。

身份验证与授权

为令牌和会话采用安全的默认设置。

在每一层实施适当的访问控制。

安全存储机密信息；绝不将其提交到版本控制系统。

网络安全

所有通信均使用 HTTPS。

实施速率限制以防止滥用。

对外部服务调用使用熔断器。

性能

优化原则

先分析性能再优化；避免过早优化。

定期测量并进行基准测试。

重点关注热点路径和频繁执行的代码。

资源管理

尽量减少关键路径中的内存分配。

对数据库和网络连接使用连接池。

妥善清理并释放资源。

缓存

缓存开销较大的计算结果和频繁访问的数据。

采用适当的缓存失效策略。

考虑缓存一致性和新鲜度要求。

可观测性

日志记录

使用结构化日志（生产环境采用 JSON 格式）。

包含相关上下文：请求 ID、用户 ID、时间戳。

使用适当的日志级别：DEBUG、INFO、WARN、ERROR。

避免记录敏感信息。

指标

跟踪关键指标：延迟、吞吐量、错误率。

为异常和超出阈值的情况设置警报。

使用仪表板了解系统运行状况。

链路追踪

为微服务实现分布式链路追踪。

在服务边界之间传递追踪上下文。

在 Span 中记录重要属性，以便调试。

文档

代码文档

为公共 API 编写清晰的说明。

解释“为什么”，而不只是“是什么”。

让文档尽可能贴近其所描述的代码。

代码变更时同步更新文档。

项目文档

维护清晰的 README，并提供设置说明。

记录架构决策（ADR）。

为团队成员提供贡献指南。

版本控制

提交规范

编写清晰、简洁的提交消息。

进行原子提交，每次提交只代表一个逻辑变更。

保持提交小而聚焦。

分支策略

使用功能分支进行新开发。

保持主分支稳定且可部署。

合并到主分支前审查代码。

工具与自动化

持续集成

在每次提交时自动运行测试。

强制执行代码格式规范和 lint 检查。

在流水线中加入安全扫描。

开发环境

在团队中使用一致的开发环境。

记录设置步骤和前置条件。

自动化常见的开发任务。