通用开发原则
引言
OneArchive 项目遵循一系列通用开发原则，确保代码质量、可维护性和团队协作一致性。
基本原则
依赖版本管理
代码基于项目当前实际使用的依赖库版本。禁止使用已废弃或未来版本的 API。
编写代码前，确认项目依赖版本，例如检查 Cargo.toml 或 package.json 文件。
代码复用
优先复用项目中已有的函数、结构体、组件或工具方法，避免重复造轮子。
代码质量要求
代码逻辑清晰、简洁且高度可读。避免过度工程或炫技式写法。
发现现有代码存在逻辑问题、架构缺陷或潜在风险时，主动指出并改进，而非强行生成看似正确的代码。
1. 设计原则
1.1. 单一职责原则
每个函数、结构体或模块只负责一个明确的功能。
- 函数不应超过 50 行，理想长度 25 行以内。
- 将复杂逻辑拆分为多个专用组件，避免"上帝对象"。
1.2. 开放封闭原则
对扩展开放，对修改封闭。
- 使用抽象和接口实现扩展性。
- 通过抽象层实现扩展，而非直接修改现有代码。
1.3. 依赖倒置原则
高层模块不应依赖低层模块，两者都应依赖抽象。
- 通过接口或抽象类实现解耦。
- 优先使用依赖注入而非直接实例化。
1.4. DRY 原则
消除重复代码。
- 提取公共逻辑到独立函数或模块。
- 使用适当的抽象减少模板代码。
- 避免在多个地方重复相同的逻辑。
2. 代码结构优化
2.1. 函数拆分
复杂函数应拆分为多个专用函数，每个函数负责单一职责。
- 遵循单一职责原则，确保函数逻辑清晰。
- 示例：将验证、处理、保存逻辑分离到独立函数。
2.2. 数据结构设计
使用专用结构体或类传递复杂数据，提高代码可读性。
- 合理拆分数据结构，避免过度复杂的设计。
- 为数据结构提供适当的方法实现。
2.3. 错误处理规范
使用自定义错误类型而非泛化错误处理。
- 定义具体的错误类型，便于错误分类和处理。
- 避免在业务逻辑中使用通用异常，除非在顶层入口点。
2.4. 内存和性能优化
避免不必要的内存分配和拷贝。
- 优先使用引用。
- 考虑异步处理以提高并发性能。
- 使用缓存机制避免重复计算。
2.5. 模块化架构
关注点分离，将不同职责的代码组织到独立模块。
- 使用接口定义抽象，实现解耦。
- 遵循预定义的模块组织规范，确保代码组织一致性。
3. 数据访问层设计
3.1. Repository 模式
采用 Repository 模式作为数据访问层的抽象。
- 为每个聚合根定义接口，使用领域语言而非技术术语。
- 通过接口隔离业务逻辑与具体数据存储实现。
3.2. 抽象层设计
业务逻辑代码不得直接依赖具体的数据存储技术。
- 通过统一的接口实现数据存储平滑切换。
- 优先使用编译时抽象以获得更好的性能。
3.3. 依赖注入
服务层通过接口或抽象类型接收数据访问组件。
- 避免直接实例化数据访问对象，实现解耦。
- 支持运行时和编译时依赖注入，根据性能需求选择。
3.4. 统一错误处理
定义统一的错误类型，封装不同数据存储的错误。
- 使用条件编译包含不同实现的错误变体。
- 所有数据访问方法返回统一的 Result 类型。
4. 测试规范
- 为所有公共 API 编写单元测试。
- 为关键业务逻辑编写集成测试。
- 监控测试覆盖率，确保代码质量。
5. 发布流程要求
5.1. Release 前检查
每次发布前，完成以下检查：
- 代码格式化：确保所有代码已通过格式化工具处理。
- 静态分析：确保代码分析工具没有报告严重问题。
- 测试通过：确保所有测试用例通过。
- 代码覆盖率报告：生成并审查代码覆盖率报告，确保关键路径有足够覆盖。
5.2. 代码覆盖率要求
- 核心模块代码覆盖率达到 80% 以上。
- CI/CD 流程中自动生成覆盖率报告，作为 Release 必要条件。
- 将每次 Release 覆盖率报告存档，便于追踪覆盖率趋势。