# Rust 项目开发规范
## 1. 设计哲学
### 1.1 最小化设计原则
- **简洁接口**: 提供最小且必要的API表面，避免过度设计
- **无硬编码限制**: 避免在代码中硬编码配置、模型名或提供商信息
- **避免复杂配置**: 减少不必要的配置文件和注册表，提供合理默认值
- **清晰抽象**: 直接API使用模式，提供直观的抽象层
### 1.2 协议/接口优先
- **按功能分组**: 按API协议或功能领域而非公司/产品分组代码
- **共享实现**: 相似功能应共享实现逻辑，避免代码重复
- **可扩展架构**: 通过接口和适配器模式实现可扩展性
### 1.3 类型安全和错误处理
- **强类型设计**: 利用Rust的强类型系统减少运行时错误
- **统一错误处理**: 定义专用错误类型，提供一致的错误处理体验
- **详尽的错误信息**: 错误应包含足够上下文信息，便于调试
- **合理的错误传播**: 使用`?`操作符简化错误处理流程
## 2. 代码组织结构
### 2.1 模块设计
- **功能分离**: 将代码按功能和抽象级别组织到不同模块
- **扁平层次**: 避免过深的模块嵌套，优先使用扁平结构
- **核心与扩展分离**: 核心功能与可选/扩展功能明确分离
- **协议/适配器模式**: 采用协议和适配器模式组织多后端支持
- **文档位置**: 除README外，所有文档应放在`docs/`目录下
- **测试位置**: 所有测试代码应放在`tests/`目录下
### 2.2 推荐的项目结构
```
/
/docs # 文档目录
/api # API文档
/guides # 指南文档
/tutorials # 教程文档
/src # 源代码
/client # 客户端接口
/config # 配置相关类型和实现
/protocols # 协议抽象和具体实现
/core # 核心抽象接口
/impl1 # 具体实现1
/impl2 # 具体实现2
/types # 共享的数据类型
/error # 错误处理
/utils # 工具函数
/features # 可选功能模块
lib.rs # 库入口点，导出公共API
main.rs # 应用入口点（如适用）
/tests # 集成测试
/common # 测试公共代码
client_tests.rs # 客户端测试
protocol_tests.rs # 协议测试
README.md # 根目录唯一文档
CHANGELOG.md # 变更日志
Cargo.toml # Rust包配置
```
### 2.3 目录创建规范
- **docs目录**: 项目必须包含`docs/`目录，用于存放所有文档（除README外）
- **tests目录**: 项目必须包含`tests/`目录，用于存放集成测试
- **自动创建**: 初始化新项目时应自动创建这些目录结构
- **目录用途**: 每个目录应有明确的用途说明和组织规范
## 3. 命名规范
### 3.1 基础命名规则
- **结构体和枚举**: CamelCase（如`ChatRequest`, `LlmClient`）
- **函数和方法**: snake_case（如`fetch_models`, `chat_stream`）
- **模块和文件**: snake_case（如`error.rs`, `http_transport.rs`）
- **常量**: SCREAMING_SNAKE_CASE（如`MAX_RETRY_ATTEMPTS`）
- **特性(trait)**: CamelCase，通常带有-able后缀（如`ProviderAdapter`, `ErrorMapper`）
### 3.2 特殊命名约定
- **协议相关**: 采用协议名称+Protocol格式（如`OpenAIProtocol`）
- **内部/私有成员**: 使用下划线前缀（如`_internal_field`）
- **类型参数**: 单字母大写（如`T`, `U`, `R`）
- **生命周期参数**: 单引号+小写字母（如`'a`, `'static`）
## 4. 代码风格和规范
### 4.1 文档规范
- **模块级文档**: 每个模块应有详细的文档注释，说明模块用途和使用方法
- **公共API文档**: 所有公共函数、结构体、枚举等应有完整文档注释
- **示例代码**: 提供简洁的示例代码，展示API的典型用法
- **文档测试**: 使用`///`注释中的代码示例作为文档测试
### 4.2 代码格式
- **使用rustfmt**: 遵循rustfmt默认格式
- **行长度**: 优先保持行长度在100个字符以内
- **空白使用**: 合理使用空行使代码更易读
- **花括号风格**: 与Rust标准库保持一致（左花括号不换行）
### 4.3 注释最佳实践
- **解释"为什么"**: 注释应解释设计决策和非显而易见的逻辑
- **避免冗余注释**: 不注释显而易见的代码
- **TODO注释**: 使用`TODO:`前缀标记待完成项，并尽可能添加负责人或截止日期
- **FIXME注释**: 使用`FIXME:`前缀标记已知问题或需要改进的地方
## 5. 抽象设计模式
### 5.1 核心抽象接口
- **Provider模式**: 定义统一的Provider接口，封装不同后端实现
- **Adapter模式**: 使用适配器模式转换不同API的请求和响应格式
- **ErrorMapper模式**: 专用组件负责错误转换和处理
### 5.2 Rust惯用模式
- **零成本抽象**: 优先使用不会产生运行时开销的抽象
- **资源管理**: 利用RAII模式进行资源管理
- **所有权语义**: 合理使用所有权、借用和生命周期
- **泛型设计**: 利用泛型实现通用算法和数据结构
### 5.3 并发和异步模式
- **异步优先**: IO密集型操作优先使用异步实现
- **零拷贝共享**: 使用`Arc`进行高效的资源共享
- **线程安全**: 确保共享数据的线程安全性
- **取消支持**: 实现对异步操作的取消支持
## 6. 依赖管理
### 6.1 依赖选择原则
- **最小依赖**: 精选必要的依赖项，避免依赖膨胀
- **活跃维护**: 优先选择活跃维护的库
- **版本锁定**: 在Cargo.lock中锁定依赖版本，确保构建一致性
### 6.2 特性标志（Feature Flags）
- **可选功能**: 使用特性标志控制可选功能
- **功能组合**: 设计可组合的特性标志系统
- **合理默认**: 默认启用核心功能，可选功能通过特性标志启用
### 6.3 开发依赖
- **测试依赖**: 测试相关依赖放在`[dev-dependencies]`中
- **工具依赖**: 开发工具依赖（如clippy、rustfmt配置）独立管理
## 7. 接口设计原则
### 7.1 统一接口
- **一致的API风格**: 保持所有公共API风格一致
- **简单构造**: 提供便捷的静态构造函数
- **合理默认值**: 为所有可选参数提供合理默认值
- **构建器模式**: 复杂配置时考虑使用构建器模式
### 7.2 类型安全接口
- **专用类型**: 为特定领域创建专用类型，避免原始类型滥用
- **枚举优于布尔值**: 使用枚举代替布尔参数，提高代码可读性
- **编译时检查**: 尽可能将运行时错误转换为编译时错误
- **类型别名**: 使用类型别名简化复杂类型定义
### 7.3 兼容性考虑
- **向后兼容**: 对公共API的更改应保持向后兼容
- **版本控制**: 使用语义化版本控制（SemVer）
- **迁移指南**: 提供API变更的详细迁移指南
## 8. 测试和质量保证
### 8.1 测试策略
- **单元测试**: 为每个公共函数和模块编写单元测试
- **集成测试**: 测试组件间的交互
- **文档测试**: 确保示例代码可运行且正确
- **边界测试**: 测试边界条件和错误情况
### 8.2 代码质量工具
- **Clippy**: 启用并遵循Clippy的建议
- **rustfmt**: 自动格式化代码
- **静态分析**: 考虑使用额外的静态分析工具
- **性能分析**: 对性能关键路径进行性能分析
## 9. 反模式（避免的实践）
### 9.1 设计反模式
- **过度设计**: 避免过于复杂的抽象和不必要的功能
- **过早优化**: 优先编写清晰、正确的代码，再考虑优化
- **硬编码值**: 避免在代码中硬编码配置和环境相关值
- **单一职责违反**: 确保每个组件职责单一
### 9.2 Rust特定反模式
- **不必要的克隆**: 避免不必要的数据克隆
- **过度使用unwrap**: 尽量不使用`unwrap()`和`expect()`处理可恢复错误
- **忽视所有权**: 不理解或忽视Rust的所有权系统
- **过度使用unsafe**: 避免不必要的`unsafe`代码
## 10. 项目文档
### 10.1 README文件
- **项目概述**: 清晰说明项目目的和主要功能
- **快速开始**: 提供简洁的入门指南
- **示例代码**: 展示典型用例的示例代码
- **安装指南**: 详细的安装和配置说明
### 10.2 CHANGELOG
- **版本历史**: 记录每个版本的变更
- **变更类型**: 区分功能、修复、优化等不同类型的变更
- **迁移说明**: 提供版本升级的迁移指南
### 10.3 贡献指南
- **开发环境设置**: 详细的开发环境配置说明
- **代码规范**: 项目特定的代码规范和最佳实践
- **提交规范**: Git提交信息的格式和内容规范
- **PR流程**: 详细的Pull Request提交流程
---
本规范基于 [Rust设计模式](https://rust-unofficial.github.io/patterns/) 和 llm-connector 项目的最佳实践，旨在提供一个全面的Rust项目开发指南。具体项目可根据实际需求进行适当调整。