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

项目结构

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 指南
   • 遵循 Go Code Review Comments
   • 使用 go vet 进行静态检查
   • 使用 golangci-lint 进行代码检查

2. 命名规范

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

3. 错误处理

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

4. 注释规范

   • 所有导出的类型、函数必须有注释
   • 注释以类型或函数名开头
   • 包注释放在 package 语句之前

非功能需求（起步阶段）

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

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

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

功能模块

已完成功能

客户端连接 (client/)

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

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

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

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

• 索引模板管理（Index Templates）

  • PutTemplate: 创建/更新索引模板
  • GetTemplate: 获取指定模板配置
  • DeleteTemplate: 删除索引模板
  • ListTemplates: 列出所有模板
  • 模板配置验证

• 索引生命周期策略管理（ISM/ILM）

  • PolicyManager 接口：统一的策略管理抽象
  • ISM 实现：AWS OpenSearch Index State Management
  • ILM 预留：未来支持 Elasticsearch Index Lifecycle Management
  • PutPolicy: 创建/更新策略
  • GetPolicy: 获取指定策略
  • DeletePolicy: 删除策略
  • ListPolicies: 列出所有策略
  • 策略配置验证

• 索引管理（Index Management）

  • CreateIndex: 创建索引（支持 Settings 和 Mappings 配置）
  • GetIndex: 获取索引信息
  • DeleteIndex: 删除索引
  • IndexExists: 检查索引是否存在
  • ListIndices: 列出匹配的索引
  • 索引名称验证和错误处理

• Mapping 管理（Dynamic Mapping）

  • PutMapping: 添加/更新字段映射
  • GetMapping: 获取索引映射信息
  • AddField: 便捷的单字段添加
  • FieldMapping 配置：Type、Index、Store、Analyzer、Format、IgnoreAbove

• 文档操作（Document CRUD）

  • IndexDocument: 索引文档（支持自动生成或指定 ID）
  • GetDocument: 根据 ID 获取文档
  • UpdateDocument: 部分更新文档
  • DeleteDocument: 删除文档
  • BulkIndexDocuments: 批量索引文档（NDJSON 格式）

• 全文搜索（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）

安装依赖

go mod download

配置

[配置说明待补充]

运行

go run main.go

测试

测试流水线（推荐）

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

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

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

手动测试

# 代码质量检查
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（测试驱动开发）流程。详细的开发指令请参考：

• 开发准则 - Go 最佳实践、TDD 流程、测试流水线要求
• Agent 执行协议 - Agent 工作流程和执行约束

开发路线图

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

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

第二阶段：核心功能（已完成）

• 集群运维操作（GetInfo）
• 索引模板管理（CRUD）
• ISM 策略管理（CRUD）
• 索引管理功能（创建、删除、查询、列表）
• Mapping 动态管理（添加字段、获取映射）
• 文档 CRUD 操作（包含批量索引）
• 全文搜索功能（多种查询类型）
• 完善测试覆盖（集成测试 + 单元测试）

第三阶段：高级功能

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

第四阶段：库化准备

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

贡献指南

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

许可证

[待定]

联系方式

[待补充]

---

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