# ES-Demo

OpenSearch/Elasticsearch 客户端实验项目，用于测试和验证 AWS OpenSearch Service 的各种功能和接口。

## 项目概述

这是一个用于实验 AWS OpenSearch Service 的 Go 项目。项目的主要目标是：

- 测试 OpenSearch 客户端的各种接口和功能
- 实现生产级别的代码质量
- 保持代码结构清晰、模块化
- 完备的测试覆盖
- 为未来转化为可复用的依赖库做准备

## 项目特点

- **生产级代码质量**：所有代码遵循 Go 官方最佳实践
- **模块化设计**：清晰的目录结构和职责划分
- **AI 辅助开发**：大部分代码由 AI 辅助生成，配合详细的指令文件
- **测试完备**：包含单元测试和集成测试
- **最新依赖**：使用最新版本的依赖库（除非有特殊需求）

## 技术栈

- **语言**: Go 1.25.3
- **OpenSearch 客户端**: opensearch-go/v2 v2.3.0
- **AWS SDK**: aws-sdk-go-v2 (config, aws/signer/v4)
- **环境变量**: godotenv v1.5.1
- **代码质量**: golangci-lint v1.64.8
- **测试框架**: Go 标准库 testing

## 项目结构

```text
es-demo/
├── README.md                 # 项目说明文档
├── .env.example              # 环境变量配置示例
├── .gitignore                # Git 忽略文件配置
├── .golangci.yml             # golangci-lint 配置
├── test.ps1                  # 测试流水线脚本（Windows）
├── go.mod                    # Go 模块依赖
├── go.sum                    # 依赖校验和
├── main.go                   # 程序入口
├── .github/
│   └── instructions/         # AI Agent 开发指令
│       ├── CLAUDE_GUIDELINE.instructions.md
│       └── DEV_GUIDELINE.instructions.md
├── config/                   # 配置相关
│   ├── config.go             # 全局配置，支持 .env 文件加载
│   └── config_test.go        # 配置测试（100% 覆盖率）
├── client/                   # OpenSearch 客户端封装
│   ├── client.go             # 客户端连接管理和 AWS 认证
│   └── client_test.go        # 客户端测试
└── operations/               # 业务操作实现
    ├── cluster/              # 集群级别运维操作
    │   ├── cluster.go        # 集群信息查询
    │   └── cluster_test.go   # 集群操作测试
    └── index/                # 索引级别业务操作
        ├── template.go       # 索引模板管理（CRUD）
        └── template_test.go  # 模板操作测试
```

## 开发原则

### 代码质量要求

1. **遵循 Go 官方最佳实践**
   - 使用 `gofmt` 格式化代码
   - 遵循 [Effective Go](https://go.dev/doc/effective_go) 指南
   - 遵循 [Go Code Review Comments](https://github.com/golang/go/wiki/CodeReviewComments)
   - 使用 `go vet` 进行静态检查
   - 使用 `golangci-lint` 进行代码检查

2. **命名规范**
   - 包名：简短、小写、单数形式
   - 接口名：单个方法接口以 `-er` 结尾
   - 变量名：驼峰命名，缩写词全大写（如 `URL`、`ID`）
   - 常量：驼峰命名或全大写下划线分隔

3. **错误处理**
   - 所有错误必须处理
   - 使用有意义的错误信息
   - 适当时使用 `errors.Is()` 和 `errors.As()`
   - 可考虑使用 `fmt.Errorf()` 包装错误

4. **注释规范**
   - 所有导出的类型、函数必须有注释
   - 注释以类型或函数名开头
   - 包注释放在 `package` 语句之前

### 非功能需求（起步阶段）

由于项目处于实验阶段，以下方面采用简化实现：

- **配置管理**：使用全局变量，简单的配置结构
- **日志系统**：基础的日志输出，可使用全局 logger
- **错误处理**：基本的错误返回和处理，暂不需要复杂的错误链
- **性能优化**：功能优先，性能问题后续优化

这些简化不影响代码的可读性和可维护性，为后续改进预留空间。

## 功能模块

### 已完成功能

#### 客户端连接 (client/)

- [x] OpenSearch 客户端初始化和连接管理
- [x] AWS v4 签名认证
- [x] 配置验证和错误处理
- [x] 支持 .env 文件配置加载

#### 集群运维操作 (operations/cluster/)

- [x] 获取集群信息（GetInfo）
  - 集群名称、版本、UUID
  - 节点数、分片数统计

#### 索引业务操作 (operations/index/)

- [x] 索引模板管理（Index Templates）
  - PutTemplate: 创建/更新索引模板
  - GetTemplate: 获取指定模板配置
  - DeleteTemplate: 删除索引模板
  - ListTemplates: 列出所有模板
  - 模板配置验证

### 待实现功能

以下功能将根据实际需求逐步实现：

- [ ] 索引管理（创建、删除、更新索引）
- [ ] 文档操作（CRUD）
- [ ] 搜索功能（基础查询、复杂查询）
- [ ] 聚合查询
- [ ] 批量操作
- [ ] 性能测试工具

## 快速开始

### 环境要求

- Go 1.25.3 或更高版本
- AWS 账号和 OpenSearch Service 实例
- AWS 访问凭证（Access Key ID 和 Secret Access Key）

### 安装依赖

```bash
go mod download
```

### 配置

[配置说明待补充]

### 运行

```bash
go run main.go
```

### 测试

#### 测试流水线（推荐）

使用自动化测试流水线，包含 Linting、Build、Test 和 Cleanup 四个阶段：

```powershell
# Windows PowerShell
powershell -ExecutionPolicy Bypass -File .\test.ps1

# 跳过特定阶段
powershell -ExecutionPolicy Bypass -File .\test.ps1 -SkipLint
powershell -ExecutionPolicy Bypass -File .\test.ps1 -SkipBuild
```

#### 手动测试

```bash
# 代码质量检查
golangci-lint run ./...

# 编译检查
go build -o NUL .

# 运行所有测试（跳过集成测试）
go test -v -short ./...

# 运行测试并显示覆盖率
go test -v -short -coverprofile=coverage.out ./...
go tool cover -func=coverage.out

# 生成 HTML 覆盖率报告
go tool cover -html=coverage.out -o coverage.html
```

**注意**: 使用 `-short` 标志跳过需要真实 OpenSearch 实例的集成测试。

## AI 辅助开发

本项目大量使用 AI 辅助开发，遵循严格的 TDD（测试驱动开发）流程。详细的开发指令请参考：

- [开发准则](./.github/instructions/DEV_GUIDELINE.instructions.md) - Go 最佳实践、TDD 流程、测试流水线要求
- [Agent 执行协议](./.github/instructions/CLAUDE_GUIDELINE.instructions.md) - Agent 工作流程和执行约束

## 开发路线图

### 第一阶段：基础设施（已完成）

- [x] 项目初始化
- [x] 基础项目结构（Client + Operations 架构）
- [x] OpenSearch 客户端封装（连接管理、AWS 认证）
- [x] 基本测试框架（单元测试、集成测试分离）
- [x] 测试流水线自动化（Lint → Build → Test → Cleanup）
- [x] 代码质量保障（golangci-lint 集成）

### 第二阶段：核心功能（进行中）

- [x] 集群运维操作（GetInfo）
- [x] 索引模板管理（CRUD）
- [ ] 索引管理功能（创建、删除、更新索引）
- [ ] 文档 CRUD 操作
- [ ] 基础搜索功能
- [ ] 完善测试覆盖

### 第三阶段：高级功能

- [ ] 聚合查询
- [ ] 批量操作优化
- [ ] 性能测试工具
- [ ] 错误处理优化
- [ ] 重试和容错机制

### 第四阶段：库化准备

- [ ] API 设计优化
- [ ] 完整文档
- [ ] 示例代码
- [ ] 发布为可复用库

## 贡献指南

由于本项目主要用于个人实验，暂不接受外部贡献。但欢迎提出建议和问题。

## 许可证

[待定]

## 联系方式

[待补充]

---

**注意**: 本项目处于积极开发中，API 可能会发生变化。