206 lines
4.1 KiB
Markdown
206 lines
4.1 KiB
Markdown
# GoAIDB 编码与代码风格指南
|
||
|
||
## 目标
|
||
制定统一的编码规范，确保代码质量、可读性和可维护性。
|
||
|
||
## 适用范围
|
||
适用于本项目所有Go语言代码的编写和维护。
|
||
|
||
## 通用原则
|
||
1. 保持代码简洁清晰
|
||
2. 写好注释，特别是业务逻辑复杂的部分
|
||
3. 遵循最小化接口原则
|
||
4. 异常处理要全面
|
||
5. 内存管理要谨慎
|
||
|
||
## 命名规范
|
||
### 包命名
|
||
- 使用小写
|
||
- 简短且具有描述性
|
||
- 不使用下划线
|
||
|
||
```go
|
||
// 正确示例
|
||
datastorage
|
||
queryprocessor
|
||
|
||
// 错误示例
|
||
DataStorage // 不应该大写
|
||
very_long_package_name // 太长了
|
||
```
|
||
|
||
### 变量命名
|
||
- 使用驼峰式命名法（CamelCase）
|
||
- 名称应明确表达变量含义
|
||
- 局部变量可以简短些，但不得影响理解
|
||
|
||
```go
|
||
// 正确示例
|
||
userName
|
||
connectionPool
|
||
|
||
// 错误示例
|
||
unm // 含义不明
|
||
cp // 含义不明
|
||
```
|
||
|
||
### 函数命名
|
||
- 动词+名词形式
|
||
- 保持一致性
|
||
- 清晰表达函数作用
|
||
|
||
```go
|
||
// 正确示例
|
||
CalculateUserRank()
|
||
ProcessQueryRequest()
|
||
|
||
// 错误示例
|
||
UserRank() // 动作不明确
|
||
DoSomething() // 含义模糊
|
||
```
|
||
|
||
## 格式规范
|
||
### 缩进
|
||
- 使用4个空格缩进
|
||
- 不使用Tab
|
||
|
||
### 行长度
|
||
- 每行不超过80个字符
|
||
- 特殊情况(如长URL)例外
|
||
|
||
### 空格
|
||
- 运算符两侧加空格
|
||
- 逗号后加空格
|
||
- 冒号后加空格
|
||
|
||
```go
|
||
// 正确示例
|
||
result := a + b
|
||
args := make([]string, 0, 10)
|
||
|
||
// 错误示例
|
||
result:=a+b
|
||
args:=make([]string,0,10)
|
||
```
|
||
|
||
### 括号
|
||
- 左括号不要独占一行
|
||
- 控制结构必须使用括号
|
||
|
||
```go
|
||
// 正确示例
|
||
if condition {
|
||
// do something
|
||
}
|
||
|
||
// 错误示例
|
||
if condition
|
||
{
|
||
// do something
|
||
}
|
||
```
|
||
|
||
## 注释规范
|
||
### 文件头注释
|
||
每个源文件都应包含以下信息：
|
||
- 文件功能说明
|
||
- 创建日期
|
||
- 创建人
|
||
- 修改记录（如有）
|
||
|
||
```go
|
||
/*
|
||
* @file: server.go
|
||
* @description: TCP服务器核心实现
|
||
* @author: 开发者姓名
|
||
* @date: 2023-06-01
|
||
*/
|
||
```
|
||
|
||
### 函数注释
|
||
- 所有导出函数必须添加注释
|
||
- 使用Godoc标准格式
|
||
|
||
```go
|
||
// ProcessQuery 处理客户端查询请求
|
||
// 参数:
|
||
// query - 查询语句
|
||
// 返回值:
|
||
// Result - 查询结果
|
||
// error - 错误信息
|
||
func ProcessQuery(query string) (Result, error) {
|
||
// 函数实现
|
||
}
|
||
```
|
||
|
||
### 行内注释
|
||
- 解释复杂逻辑
|
||
- 标记待办事项
|
||
|
||
```go
|
||
// TODO: 优化性能
|
||
// HACK: 临时解决方案
|
||
// FIXME: 需要修复的问题
|
||
```
|
||
|
||
## 错误处理
|
||
- 所有错误必须检查
|
||
- 提供有意义的错误信息
|
||
- 统一错误处理机制
|
||
|
||
```go
|
||
// 正确示例
|
||
if err != nil {
|
||
log.Errorf("查询处理失败: %v", err)
|
||
return nil, fmt.Errorf("query processing failed: %w", err)
|
||
}
|
||
|
||
// 错误示例
|
||
if err != nil {
|
||
return nil // 静默忽略错误
|
||
}
|
||
```
|
||
|
||
## 日志规范
|
||
### 日志级别使用
|
||
- **Error**：记录错误事件，使用`log.Error()`，适用于不可恢复的错误
|
||
- **Warn**：记录警告事件，使用`log.Warn()`，表示潜在问题但不会中断流程
|
||
- **Info**：记录重要流程事件，使用`log.Info()`，用于关键节点的状态报告
|
||
- **Debug**：记录调试信息，使用`log.Debug()`，用于开发阶段的问题追踪
|
||
|
||
### 日志格式
|
||
- 所有日志必须包含上下文信息（如模块名、操作对象）
|
||
- 错误日志必须包含错误详情
|
||
- 关键操作应包含操作结果状态
|
||
|
||
```go
|
||
// 正确示例
|
||
log.Error("存储层更新失败", "error", err, "db", dbName)
|
||
log.Warn("查询条件未命中索引", "collection", collName)
|
||
log.Info("更新操作完成", "matched", matchedCount, "modified", modifiedCount)
|
||
|
||
// 错误示例
|
||
log.Debug("错误不应使用debug级别") // 错误类型日志应使用Error级别
|
||
log.Info("error", err) // 错误信息应使用Error级别并包含明确描述
|
||
```
|
||
|
||
## 测试规范
|
||
- 所有关键功能必须有单元测试
|
||
- 测试用例覆盖主要分支
|
||
- 测试文件以_test.go结尾
|
||
|
||
## Git提交规范
|
||
- 提交信息清晰明了
|
||
- 推荐格式: [模块] 操作描述
|
||
|
||
```text
|
||
[server] 修复连接池泄漏问题
|
||
[parser] 支持新的查询语法
|
||
```
|
||
|
||
## 其他建议
|
||
- 保持函数单一职责
|
||
- 控制函数长度不超过50行
|
||
- 使用设计模式提高扩展性
|
||
- 定期重构优化代码结构
|
||
- 使用静态分析工具检查代码 |