# 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 可能会发生变化。