alibabacloud-eci/docs/development-guide.md

# 开发指南

## 环境要求

### 必备工具
- **Go 1.13+** - 主要开发语言
- **Git** - 版本控制
- **Make** - 构建工具

### 可选工具
- **Docker** - 容器化构建和测试
- **golangci-lint** - 代码质量检查

## 开发环境设置

### 1. 克隆项目
```bash
git clone https://github.com/virtual-kubelet/alibabacloud-eci.git
cd alibabacloud-eci
```

### 2. 安装依赖
```bash
# 使用Go Modules自动管理依赖
go mod download
```

### 3. 验证环境
```bash
# 检查Go版本
go version

# 验证构建
make build
```

## 构建和测试

### 构建命令
```bash
# 构建二进制文件
make build

# 清理构建产物
make clean

# 运行测试
make test

# 代码静态分析
make vet

# 代码质量检查
make lint

# 依赖管理
make mod
```

### 构建产物
- `bin/virtual-kubelet` - 主程序二进制文件
- 包含版本信息和构建时间戳

## 开发流程

### 1. 代码结构理解
- **main.go** - 程序入口，Cobra命令行框架
- **eci.go** - Virtual Kubelet Provider主要实现
- **eci/** - 阿里云ECI API客户端
- **cmd/** - 命令行子命令定义

### 2. 添加新功能

#### 添加新的Provider方法
```go
// 在eci.go中添加新的Provider接口实现
func (p *ECIProvider) NewMethod(ctx context.Context, pod *v1.Pod) error {
    // 实现逻辑
    return nil
}
```

#### 添加新的ECI API调用
```go
// 在eci/目录下创建新的API文件
func (c *Client) NewECIOperation(params map[string]interface{}) (*Response, error) {
    // 实现ECI API调用
}
```

#### 添加命令行参数
```go
// 在cmd/virtual-kubelet/commands/root/中添加
rootCmd.PersistentFlags().StringVar(&newFlag, "new-flag", "default", "description")
```

### 3. 测试新功能
```bash
# 运行单元测试
make test

# 构建并测试
make build && ./bin/virtual-kubelet --help
```

## 配置管理

### 配置文件格式
项目使用TOML格式配置文件：

```toml
Region = "cn-hangzhou"
OperatingSystem = "Linux"
CPU = "20"
Memory = "100Gi"
Pods = "20"
VSwitch = "vsw-xxx"
SecureGroup = "sg-xxx"
ClusterName = "default"
```

### 环境变量支持
所有配置项都支持环境变量覆盖：
```bash
export ECI_REGION=cn-shanghai
export ECI_SECURITY_GROUP=sg-123
export ECI_VSWITCH=vsw-123
export ECI_ACCESS_KEY=your-access-key
export ECI_SECRET_KEY=your-secret-key
```

## 调试和故障排除

### 日志级别设置
```bash
# 运行时设置日志级别
./bin/virtual-kubelet --log-level=debug
```

### 常见问题

#### 构建失败
- 检查Go版本要求（1.13+）
- 验证依赖完整性：`go mod tidy`
- 清理构建缓存：`make clean`

#### 运行时错误
- 检查配置文件路径和权限
- 验证阿里云凭证有效性
- 查看详细日志：`--log-level=debug`

#### ECI API调用失败
- 检查网络连接
- 验证区域配置
- 确认ECI服务已开通

## 代码规范

### Go代码规范
- 遵循Go官方代码规范
- 使用gofmt自动格式化
- 运行`make vet`和`make lint`检查

### 提交规范
- 提交前运行完整测试套件
- 确保代码通过静态分析
- 更新相关文档

## 性能优化

### 构建优化
- 使用静态编译减少运行时依赖
- 优化Docker镜像大小
- 启用编译优化标志

### 运行时优化
- 合理配置资源限制
- 优化API调用频率
- 实现连接池和缓存

## 贡献指南

### 提交Pull Request
1. Fork项目仓库
2. 创建功能分支
3. 实现功能并添加测试
4. 运行完整测试套件
5. 提交Pull Request

### 代码审查
- 确保代码符合项目规范
- 添加适当的测试用例
- 更新相关文档
- 性能影响评估

---

*此开发指南提供了完整的开发环境设置、构建流程和最佳实践，帮助开发者快速上手项目开发。*