312 lines
9.8 KiB
Markdown
312 lines
9.8 KiB
Markdown
# 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 # 模板操作测试
|
||
├── ism.go # ISM 策略管理
|
||
├── policy.go # 统一策略接口
|
||
├── index.go # 索引 CRUD 操作
|
||
├── index_test.go # 索引操作测试
|
||
├── mapping.go # 索引 Mapping 管理
|
||
├── mapping_test.go # Mapping 操作测试
|
||
├── document.go # 文档 CRUD 操作
|
||
├── document_test.go # 文档操作测试
|
||
├── search.go # 全文搜索功能
|
||
└── search_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: 列出所有模板
|
||
- 模板配置验证
|
||
|
||
- [x] 索引生命周期策略管理（ISM/ILM）
|
||
- PolicyManager 接口：统一的策略管理抽象
|
||
- ISM 实现：AWS OpenSearch Index State Management
|
||
- ILM 预留：未来支持 Elasticsearch Index Lifecycle Management
|
||
- PutPolicy: 创建/更新策略
|
||
- GetPolicy: 获取指定策略
|
||
- DeletePolicy: 删除策略
|
||
- ListPolicies: 列出所有策略
|
||
- 策略配置验证
|
||
|
||
- [x] 索引管理（Index Management）
|
||
- CreateIndex: 创建索引（支持 Settings 和 Mappings 配置）
|
||
- GetIndex: 获取索引信息
|
||
- DeleteIndex: 删除索引
|
||
- IndexExists: 检查索引是否存在
|
||
- ListIndices: 列出匹配的索引
|
||
- 索引名称验证和错误处理
|
||
|
||
- [x] Mapping 管理（Dynamic Mapping）
|
||
- PutMapping: 添加/更新字段映射
|
||
- GetMapping: 获取索引映射信息
|
||
- AddField: 便捷的单字段添加
|
||
- FieldMapping 配置：Type、Index、Store、Analyzer、Format、IgnoreAbove
|
||
|
||
- [x] 文档操作（Document CRUD）
|
||
- IndexDocument: 索引文档（支持自动生成或指定 ID）
|
||
- GetDocument: 根据 ID 获取文档
|
||
- UpdateDocument: 部分更新文档
|
||
- DeleteDocument: 删除文档
|
||
- BulkIndexDocuments: 批量索引文档（NDJSON 格式）
|
||
|
||
- [x] 全文搜索（Search）
|
||
- Search: 主搜索函数（支持分页、排序、字段过滤）
|
||
- Query 构建器：
|
||
- MatchQuery: 全文匹配查询
|
||
- TermQuery: 精确词项查询
|
||
- RangeQuery: 范围查询
|
||
- BoolQuery: 布尔组合查询（Must、Should、MustNot、Filter）
|
||
- MultiMatchQuery: 多字段匹配
|
||
- WildcardQuery: 通配符查询
|
||
- PrefixQuery: 前缀查询
|
||
- MatchAllQuery: 匹配所有文档
|
||
|
||
### 待实现功能
|
||
|
||
以下功能将根据实际需求逐步实现：
|
||
|
||
- [ ] 聚合查询（Aggregations）
|
||
- [ ] 复杂查询组合（嵌套、父子文档）
|
||
- [ ] 索引别名管理
|
||
- [ ] 快照和恢复
|
||
- [ ] 性能测试工具
|
||
- [ ] 监控和指标
|
||
|
||
## 快速开始
|
||
|
||
### 环境要求
|
||
|
||
- 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）
|
||
- [x] ISM 策略管理（CRUD）
|
||
- [x] 索引管理功能（创建、删除、查询、列表）
|
||
- [x] Mapping 动态管理（添加字段、获取映射）
|
||
- [x] 文档 CRUD 操作（包含批量索引）
|
||
- [x] 全文搜索功能（多种查询类型）
|
||
- [x] 完善测试覆盖（集成测试 + 单元测试）
|
||
|
||
### 第三阶段：高级功能
|
||
|
||
- [ ] 聚合查询
|
||
- [ ] 批量操作优化
|
||
- [ ] 性能测试工具
|
||
- [ ] 错误处理优化
|
||
- [ ] 重试和容错机制
|
||
|
||
### 第四阶段：库化准备
|
||
|
||
- [ ] API 设计优化
|
||
- [ ] 完整文档
|
||
- [ ] 示例代码
|
||
- [ ] 发布为可复用库
|
||
|
||
## 贡献指南
|
||
|
||
由于本项目主要用于个人实验，暂不接受外部贡献。但欢迎提出建议和问题。
|
||
|
||
## 许可证
|
||
|
||
[待定]
|
||
|
||
## 联系方式
|
||
|
||
[待补充]
|
||
|
||
---
|
||
|
||
**注意**: 本项目处于积极开发中，API 可能会发生变化。
|