# 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行
- 使用设计模式提高扩展性
- 定期重构优化代码结构
- 使用静态分析工具检查代码