7.5 KiB
7.5 KiB
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 # 模板操作测试
开发原则
代码质量要求
-
遵循 Go 官方最佳实践
- 使用
gofmt格式化代码 - 遵循 Effective Go 指南
- 遵循 Go Code Review Comments
- 使用
go vet进行静态检查 - 使用
golangci-lint进行代码检查
- 使用
-
命名规范
- 包名：简短、小写、单数形式
- 接口名：单个方法接口以
-er结尾 - 变量名：驼峰命名，缩写词全大写（如
URL、ID） - 常量：驼峰命名或全大写下划线分隔
-
错误处理
- 所有错误必须处理
- 使用有意义的错误信息
- 适当时使用
errors.Is()和errors.As() - 可考虑使用
fmt.Errorf()包装错误
-
注释规范
- 所有导出的类型、函数必须有注释
- 注释以类型或函数名开头
- 包注释放在
package语句之前
非功能需求（起步阶段）
由于项目处于实验阶段，以下方面采用简化实现：
- 配置管理：使用全局变量，简单的配置结构
- 日志系统：基础的日志输出，可使用全局 logger
- 错误处理：基本的错误返回和处理，暂不需要复杂的错误链
- 性能优化：功能优先，性能问题后续优化
这些简化不影响代码的可读性和可维护性，为后续改进预留空间。
功能模块
已完成功能
客户端连接 (client/)
- OpenSearch 客户端初始化和连接管理
- AWS v4 签名认证
- 配置验证和错误处理
- 支持 .env 文件配置加载
集群运维操作 (operations/cluster/)
- 获取集群信息（GetInfo）
- 集群名称、版本、UUID
- 节点数、分片数统计
索引业务操作 (operations/index/)
- 索引模板管理（Index Templates）
- PutTemplate: 创建/更新索引模板
- GetTemplate: 获取指定模板配置
- DeleteTemplate: 删除索引模板
- ListTemplates: 列出所有模板
- 模板配置验证
待实现功能
以下功能将根据实际需求逐步实现：
- 索引管理（创建、删除、更新索引）
- 文档操作（CRUD）
- 搜索功能（基础查询、复杂查询）
- 聚合查询
- 批量操作
- 性能测试工具
快速开始
环境要求
- 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）
- 索引管理功能（创建、删除、更新索引）
- 文档 CRUD 操作
- 基础搜索功能
- 完善测试覆盖
第三阶段：高级功能
- 聚合查询
- 批量操作优化
- 性能测试工具
- 错误处理优化
- 重试和容错机制
第四阶段：库化准备
- API 设计优化
- 完整文档
- 示例代码
- 发布为可复用库
贡献指南
由于本项目主要用于个人实验，暂不接受外部贡献。但欢迎提出建议和问题。
许可证
[待定]
联系方式
[待补充]
注意: 本项目处于积极开发中，API 可能会发生变化。