feat: opensearch客户端初始化 feat: 索引模板接口 ai: 开发准则 chore: TDD流水线脚本
This commit is contained in:
mouseleee
256
README.md
Normal file
256
README.md
Normal file
@@ -0,0 +1,256 @@
|
||||
# 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 可能会发生变化。
|
||||
Reference in New Issue
Block a user