# Go语言开发规范

本文档定义了Installer Builder项目的Go语言开发规范，旨在提高代码质量、可维护性和一致性。所有项目贡献者和AI代码生成都应遵循这些规范。

## 1. 项目结构和代码组织

### 1.1 目录结构

/

├── cmd/ # 命令行入口点

│ ├── cli/ # CLI应用

│ └── gui/ # GUI应用

├── internal/ # 内部包，不对外暴露

│ ├── config/ # 配置处理

│ ├── builder/ # 构建引擎

│ ├── platform/ # 平台适配

│ ├── packager/ # 包类型构建器

│ ├── script/ # 脚本执行

│ └── plugin/ # 插件系统

├── pkg/ # 可导出的包，可能被其他项目使用

│ ├── api/ # 公共API

│ └── schema/ # 配置Schema

├── ui/ # GUI相关代码

│ ├── frontend/ # Wails前端

│ └── assets/ # UI资源

├── plugins/ # 插件目录

├── examples/ # 示例配置和项目

├── scripts/ # 构建和开发脚本

└── doc/ # 文档


### 1.2 包设计原则

- 每个包应该有单一的职责
- 避免循环依赖
- 包名应该简短、清晰，使用小写单词
- 内部实现细节放在`internal/`目录下
- 可重用的、稳定的API放在`pkg/`目录下

## 2. 命名约定

### 2.1 包名

- 使用简短、简洁、有意义的名称
- 使用小写字母，不使用下划线或混合大小写
- 避免使用常见变量名作为包名（如`util`、`common`等）

### 2.2 文件名

- 使用小写字母
- 使用下划线分隔多个单词
- 测试文件使用`_test.go`后缀

### 2.3 变量和常量

- 使用驼峰命名法
- 局部变量使用简短名称
- 全局变量和常量使用描述性名称
- 不导出的变量和常量以小写字母开头
- 导出的变量和常量以大写字母开头

### 2.4 函数和方法

- 使用驼峰命名法
- 不导出的函数和方法以小写字母开头
- 导出的函数和方法以大写字母开头
- 名称应该表明函数的作用
- 接收器名称应该简短，通常是类型名称的首字母

### 2.5 接口

- 单一方法接口名称应以方法名加`er`后缀命名（如`Reader`、`Writer`）
- 多方法接口应该使用描述其行为的名称

### 2.6 结构体

- 使用驼峰命名法
- 不导出的结构体以小写字母开头
- 导出的结构体以大写字母开头
- 结构体字段遵循与变量相同的命名规则

## 3. 代码风格

### 3.1 格式化

- 使用`gofmt`或`goimports`自动格式化代码
- 缩进使用制表符（tab）
- 行长度建议不超过100个字符

### 3.2 导入

- 按标准库、第三方包、项目内部包的顺序分组
- 每组之间用空行分隔
- 使用点导入（`.`）仅限于测试文件中导入测试包

### 3.3 声明

- 变量声明尽量靠近使用位置
- 相关的常量和变量分组声明
- 使用`var`关键字声明零值变量，使用短声明`:=`声明并初始化变量

### 3.4 控制结构

- `if`、`for`、`switch`等关键字与左括号之间有一个空格
- 左大括号不换行
- `else`、`else if`与右大括号在同一行
- 避免嵌套过深的控制结构，考虑提前返回

## 4. 错误处理

### 4.1 错误返回

- 错误作为最后一个返回值
- 使用描述性错误信息
- 使用`fmt.Errorf`添加上下文信息
- 考虑使用自定义错误类型和错误包装

### 4.2 错误检查

- 立即检查错误，避免嵌套
- 使用`if err != nil`模式
- 避免使用`_`忽略错误，除非有明确理由

### 4.3 错误日志

- 在调用栈的适当位置记录错误
- 避免多次记录同一错误
- 包含足够的上下文信息

### 4.4 错误处理策略

- 对于库函数，通常返回错误而不是处理它
- 对于应用程序，在适当的抽象层处理错误
- 使用`panic`仅限于不可恢复的情况

## 5. 注释规范

### 5.1 包注释

- 每个包应该有包注释，位于`doc.go`文件或包的主文件中
- 包注释应该提供包的用途、用法和任何重要的注意事项

### 5.2 导出符号注释

- 所有导出的函数、类型、常量和变量都应该有注释
- 注释以符号名称开头，使用完整的句子
- 遵循`godoc`约定

### 5.3 实现注释

- 对于复杂的实现，添加注释解释原理和算法
- 对于不明显的代码，解释为什么这样做，而不仅仅是做了什么

### 5.4 TODO和FIXME

- 使用`// TODO: `标记计划改进的地方
- 使用`// FIXME: `标记需要修复的问题
- 包含足够的上下文信息和可能的解决方向

## 6. 测试要求

### 6.1 测试覆盖率

- 核心功能应该有单元测试
- 目标测试覆盖率至少70%
- 关键路径和边界条件必须测试

### 6.2 测试组织

- 使用表驱动测试
- 测试文件与被测试文件放在同一目录
- 使用`_test.go`后缀命名测试文件

### 6.3 测试命名

- 测试函数命名为`Test<Function>`
- 基准测试命名为`Benchmark<Function>`
- 示例测试命名为`Example<Function>`

### 6.4 测试工具

- 使用标准库的`testing`包
- 可以使用`testify`等辅助库提高测试效率
- 使用`go test -race`检测竞态条件

## 7. 依赖管理

### 7.1 依赖选择

- 优先使用标准库
- 选择活跃维护、文档完善的第三方库
- 避免引入过多依赖

### 7.2 版本控制

- 使用Go Modules进行依赖管理
- 在`go.mod`中明确指定依赖版本
- 定期更新依赖以获取安全修复

### 7.3 依赖隔离

- 考虑使用接口隔离第三方依赖
- 为核心功能编写适配器，便于将来替换依赖

## 8. 并发处理

### 8.1 并发模式

- 优先使用高级并发原语（如`sync.WaitGroup`、通道）
- 避免共享内存，通过通信共享
- 使用适当的同步机制保护共享资源

### 8.2 Goroutine管理

- 确保所有启动的goroutine都能正确终止
- 使用上下文（`context.Context`）传递取消信号
- 避免goroutine泄漏

### 8.3 并发安全

- 明确标记非并发安全的类型和函数
- 使用`sync/atomic`包进行原子操作
- 使用`-race`标志测试并发代码

## 9. 日志记录

### 9.1 日志级别

- 使用适当的日志级别（Debug、Info、Warning、Error、Fatal）
- 在开发环境和生产环境使用不同的日志级别

### 9.2 日志内容

- 包含足够的上下文信息
- 避免记录敏感信息
- 使用结构化日志便于分析

### 9.3 日志接口

- 使用抽象的日志接口，便于将来替换日志实现
- 考虑使用`uber-go/zap`或`sirupsen/logrus`等成熟的日志库

## 10. 代码审查清单

### 10.1 功能性

- 代码是否实现了预期功能
- 是否处理了所有边界条件
- 错误处理是否完善

### 10.2 可维护性

- 代码是否易于理解
- 是否有适当的注释
- 是否遵循项目的代码风格

### 10.3 性能

- 是否有明显的性能问题
- 是否有不必要的计算或内存分配
- 并发代码是否正确且高效

### 10.4 安全性

- 是否有安全漏洞
- 是否正确处理用户输入
- 是否泄露敏感信息

## 11. AI代码生成指南

### 11.1 代码生成原则

- 生成的代码应遵循本文档中的所有规范
- 优先生成简洁、可读性高的代码
- 包含适当的注释和文档

### 11.2 代码生成提示

- 明确指定需要生成的功能和接口
- 提供足够的上下文信息
- 指定任何特殊要求或约束

### 11.3 代码审查

- 生成的代码应经过人工审查
- 检查是否符合项目规范
- 验证功能正确性和性能