976 lines
24 KiB
Markdown
976 lines
24 KiB
Markdown
---
|
||
applyTo: '**/*.go'
|
||
---
|
||
# AI Agent 开发指令
|
||
|
||
本文档为 AI Agent（GitHub Copilot）提供开发本项目时的详细指令和指南。
|
||
|
||
## 项目背景
|
||
|
||
这是一个用于测试和实验 AWS OpenSearch Service 的 Go 项目。项目目标是创建生产级别的代码，并为未来转化为可复用的依赖库做准备。
|
||
|
||
## 核心原则
|
||
|
||
### 1. 代码质量要求（最高优先级）
|
||
|
||
**必须遵循 Go 官方最佳实践：**
|
||
|
||
- **Effective Go**: https://go.dev/doc/effective_go
|
||
- **Go Code Review Comments**: https://github.com/golang/go/wiki/CodeReviewComments
|
||
- **Go 标准库风格**: 参考标准库的代码风格和设计模式
|
||
|
||
**具体要求：**
|
||
|
||
```go
|
||
// ✅ 正确：导出的函数必须有文档注释，以函数名开头
|
||
// NewClient creates and initializes a new OpenSearch client with the provided configuration.
|
||
// It returns an error if the connection cannot be established.
|
||
func NewClient(cfg *Config) (*Client, error) {
|
||
// ...
|
||
}
|
||
|
||
// ❌ 错误：缺少注释或注释不以函数名开头
|
||
func NewClient(cfg *Config) (*Client, error) {
|
||
// ...
|
||
}
|
||
```
|
||
|
||
```go
|
||
// ✅ 正确：错误处理不能忽略
|
||
result, err := client.Search(ctx, query)
|
||
if err != nil {
|
||
return nil, fmt.Errorf("search failed: %w", err)
|
||
}
|
||
|
||
// ❌ 错误：忽略错误
|
||
result, _ := client.Search(ctx, query)
|
||
```
|
||
|
||
```go
|
||
// ✅ 正确：使用有意义的变量名
|
||
var maxRetryCount = 3
|
||
var connectionTimeout = 30 * time.Second
|
||
|
||
// ❌ 错误：使用无意义的缩写
|
||
var mrc = 3
|
||
var ct = 30 * time.Second
|
||
```
|
||
|
||
### 2. 命名规范
|
||
|
||
**包名：**
|
||
- 小写、简短、单数形式
|
||
- 避免使用下划线或驼峰命名
|
||
- 示例：`client`、`search`、`document`（不是 `opensearch_client`）
|
||
|
||
**接口名：**
|
||
- 单方法接口以 `-er` 结尾：`Reader`、`Writer`、`Searcher`
|
||
- 多方法接口使用描述性名称：`IndexManager`、`DocumentService`
|
||
|
||
**变量和函数名：**
|
||
- 驼峰命名（camelCase 或 PascalCase）
|
||
- 缩写词保持一致大写：`URL`、`HTTP`、`ID`、`JSON`（不是 `Url`、`Http`、`Id`、`Json`）
|
||
- 示例：`clientID`、`httpClient`、`parseURL`
|
||
|
||
**常量：**
|
||
```go
|
||
// ✅ 正确：使用驼峰命名
|
||
const DefaultTimeout = 30 * time.Second
|
||
const MaxRetries = 3
|
||
|
||
// 或者使用全大写（枚举类型）
|
||
const (
|
||
StatusPending = "PENDING"
|
||
StatusComplete = "COMPLETE"
|
||
)
|
||
```
|
||
|
||
### 3. 错误处理规范
|
||
|
||
**基本错误处理：**
|
||
|
||
```go
|
||
// ✅ 正确：包装错误，提供上下文信息
|
||
if err != nil {
|
||
return fmt.Errorf("failed to create index %q: %w", indexName, err)
|
||
}
|
||
|
||
// ✅ 正确：自定义错误类型（当需要时）
|
||
var ErrIndexNotFound = errors.New("index not found")
|
||
var ErrInvalidQuery = errors.New("invalid query syntax")
|
||
|
||
// ✅ 正确：错误检查使用 errors.Is 或 errors.As
|
||
if errors.Is(err, ErrIndexNotFound) {
|
||
// 处理索引不存在的情况
|
||
}
|
||
|
||
// ❌ 错误：吞掉错误信息
|
||
if err != nil {
|
||
return errors.New("something went wrong")
|
||
}
|
||
```
|
||
|
||
**Defer 中的错误处理：**
|
||
|
||
对于 `defer` 语句中的 Close() 等清理操作，**不能**完全忽略错误：
|
||
|
||
```go
|
||
// ✅ 正确：检查并记录 Close 错误
|
||
defer func() {
|
||
if closeErr := res.Body.Close(); closeErr != nil {
|
||
fmt.Fprintf(os.Stderr, "warning: failed to close response body: %v\n", closeErr)
|
||
}
|
||
}()
|
||
|
||
// ❌ 错误：完全忽略错误（虽然能通过 linter，但不是最佳实践）
|
||
defer func() { _ = res.Body.Close() }()
|
||
|
||
// ❌ 错误：不处理错误（errcheck 警告）
|
||
defer res.Body.Close()
|
||
```
|
||
|
||
**原因说明：**
|
||
- HTTP Response Body 的 Close() 错误虽然通常不影响业务逻辑（数据已读取）
|
||
- 但完全忽略错误不符合 Go 最佳实践
|
||
- 检查并记录到 stderr 便于调试和监控
|
||
- 这种方式既满足 linter 要求，又提供诊断信息
|
||
```
|
||
|
||
### 4. 注释规范
|
||
|
||
```go
|
||
// ✅ 正确：包注释（在 package 语句之前）
|
||
// Package client provides a high-level interface for interacting with AWS OpenSearch Service.
|
||
// It handles connection management, authentication, and request signing.
|
||
package client
|
||
|
||
// ✅ 正确：导出类型的注释
|
||
// Client represents an OpenSearch client that manages connections and operations.
|
||
type Client struct {
|
||
// ...
|
||
}
|
||
|
||
// ✅ 正确：导出方法的注释
|
||
// Search executes a search query against the specified index.
|
||
// It returns the search results or an error if the operation fails.
|
||
func (c *Client) Search(ctx context.Context, indexName string, query Query) (*SearchResult, error) {
|
||
// ...
|
||
}
|
||
|
||
// ✅ 正确：复杂逻辑的内部注释
|
||
func processResults(data []byte) error {
|
||
// Parse JSON response
|
||
var resp Response
|
||
if err := json.Unmarshal(data, &resp); err != nil {
|
||
return err
|
||
}
|
||
|
||
// Validate response structure
|
||
if resp.Total == 0 {
|
||
return ErrNoResults
|
||
}
|
||
|
||
// Transform results
|
||
// ...
|
||
}
|
||
```
|
||
|
||
### 5. 代码结构规范
|
||
|
||
**文件组织：**
|
||
```go
|
||
// 1. 包声明和包注释
|
||
// Package client provides...
|
||
package client
|
||
|
||
// 2. 导入语句（分组：标准库、第三方库、本地包）
|
||
import (
|
||
"context"
|
||
"fmt"
|
||
"time"
|
||
|
||
"github.com/opensearch-project/opensearch-go/v2"
|
||
|
||
"es-demo/config"
|
||
"es-demo/models"
|
||
)
|
||
|
||
// 3. 常量
|
||
const (
|
||
DefaultTimeout = 30 * time.Second
|
||
)
|
||
|
||
// 4. 变量
|
||
var (
|
||
ErrInvalidConfig = errors.New("invalid configuration")
|
||
)
|
||
|
||
// 5. 类型定义
|
||
type Client struct {
|
||
// ...
|
||
}
|
||
|
||
// 6. 构造函数
|
||
func NewClient(cfg *Config) (*Client, error) {
|
||
// ...
|
||
}
|
||
|
||
// 7. 方法（接收者方法）
|
||
func (c *Client) Connect(ctx context.Context) error {
|
||
// ...
|
||
}
|
||
|
||
// 8. 其他函数
|
||
func validateConfig(cfg *Config) error {
|
||
// ...
|
||
}
|
||
```
|
||
|
||
**接口设计：**
|
||
```go
|
||
// ✅ 正确：接口定义在使用方，而非实现方
|
||
// 在 operations/search 包中定义
|
||
type DocumentStore interface {
|
||
GetDocument(ctx context.Context, id string) (*Document, error)
|
||
PutDocument(ctx context.Context, doc *Document) error
|
||
}
|
||
|
||
// ✅ 正确：保持接口小而专注
|
||
type Searcher interface {
|
||
Search(ctx context.Context, query Query) (*Result, error)
|
||
}
|
||
|
||
type Indexer interface {
|
||
CreateIndex(ctx context.Context, name string, settings map[string]any) error
|
||
DeleteIndex(ctx context.Context, name string) error
|
||
}
|
||
```
|
||
|
||
### 6. 测试规范
|
||
|
||
**文件命名：**
|
||
- 测试文件：`client_test.go`（对应 `client.go`）
|
||
- 测试函数：`TestNewClient`、`TestClient_Search`
|
||
|
||
**测试结构：**
|
||
```go
|
||
func TestNewClient(t *testing.T) {
|
||
// 使用表驱动测试
|
||
tests := []struct {
|
||
name string
|
||
config *Config
|
||
want bool // 期望成功/失败
|
||
wantErr error
|
||
}{
|
||
{
|
||
name: "valid config",
|
||
config: &Config{
|
||
Endpoint: "https://example.com",
|
||
},
|
||
want: true,
|
||
wantErr: nil,
|
||
},
|
||
{
|
||
name: "nil config",
|
||
config: nil,
|
||
want: false,
|
||
wantErr: ErrInvalidConfig,
|
||
},
|
||
}
|
||
|
||
for _, tt := range tests {
|
||
t.Run(tt.name, func(t *testing.T) {
|
||
got, err := NewClient(tt.config)
|
||
if !errors.Is(err, tt.wantErr) {
|
||
t.Errorf("NewClient() error = %v, wantErr %v", err, tt.wantErr)
|
||
return
|
||
}
|
||
if (got != nil) != tt.want {
|
||
t.Errorf("NewClient() got = %v, want %v", got != nil, tt.want)
|
||
}
|
||
})
|
||
}
|
||
}
|
||
|
||
// 集成测试（需要真实环境）
|
||
func TestClient_Search_Integration(t *testing.T) {
|
||
if testing.Short() {
|
||
t.Skip("skipping integration test in short mode")
|
||
}
|
||
|
||
// 测试逻辑...
|
||
}
|
||
```
|
||
|
||
**辅助函数：**
|
||
```go
|
||
// 测试辅助函数以小写字母开头（不导出）
|
||
func setupTestClient(t *testing.T) *Client {
|
||
t.Helper()
|
||
|
||
cfg := &Config{
|
||
Endpoint: "http://localhost:9200",
|
||
}
|
||
client, err := NewClient(cfg)
|
||
if err != nil {
|
||
t.Fatalf("failed to create test client: %v", err)
|
||
}
|
||
return client
|
||
}
|
||
|
||
func cleanupTestIndex(t *testing.T, client *Client, indexName string) {
|
||
t.Helper()
|
||
|
||
if err := client.DeleteIndex(context.Background(), indexName); err != nil {
|
||
t.Logf("cleanup failed: %v", err)
|
||
}
|
||
}
|
||
```
|
||
|
||
## 项目阶段考虑
|
||
|
||
### 当前阶段（实验期）
|
||
|
||
**允许的简化：**
|
||
|
||
1. **配置管理**：可以使用全局变量
|
||
```go
|
||
// config/config.go
|
||
package config
|
||
|
||
var (
|
||
// Global configuration (acceptable in experimental phase)
|
||
Endpoint string
|
||
AccessKey string
|
||
SecretKey string
|
||
Region string
|
||
)
|
||
|
||
func Init() {
|
||
// Simple initialization from environment variables
|
||
Endpoint = os.Getenv("ES_ENDPOINT")
|
||
AccessKey = os.Getenv("AWS_ACCESS_KEY_ID")
|
||
SecretKey = os.Getenv("AWS_SECRET_ACCESS_KEY")
|
||
Region = os.Getenv("AWS_REGION")
|
||
}
|
||
```
|
||
|
||
2. **日志系统**：基础的 log 包使用
|
||
```go
|
||
// utils/logger.go
|
||
package utils
|
||
|
||
import "log"
|
||
|
||
var (
|
||
// Global logger (acceptable in experimental phase)
|
||
Logger = log.New(os.Stdout, "[ES-Demo] ", log.LstdFlags)
|
||
)
|
||
|
||
func Info(msg string, args ...any) {
|
||
Logger.Printf("INFO: "+msg, args...)
|
||
}
|
||
|
||
func Error(msg string, args ...any) {
|
||
Logger.Printf("ERROR: "+msg, args...)
|
||
}
|
||
```
|
||
|
||
**但必须保持：**
|
||
- 代码的可读性和可维护性
|
||
- 清晰的职责划分
|
||
- 完整的错误处理
|
||
- 充分的注释
|
||
|
||
## 代码质量检查
|
||
|
||
### 使用 Linter 进行自动化检查
|
||
|
||
本项目使用 `golangci-lint` 进行代码质量检查。在生成或修改代码后，**必须**确保代码通过 linter 检查。
|
||
|
||
**配置文件：** `.golangci.yml`
|
||
|
||
**运行 Linter：**
|
||
```bash
|
||
# 检查所有代码
|
||
golangci-lint run ./...
|
||
|
||
# 自动修复部分问题
|
||
golangci-lint run --fix ./...
|
||
```
|
||
|
||
**处理 Linter 输出：**
|
||
1. 认真阅读每一条 linter 警告和错误
|
||
2. 理解问题的根本原因
|
||
3. 按照 Go 最佳实践修复问题
|
||
4. 不要通过禁用 linter 规则来"修复"问题（除非有充分理由）
|
||
5. 如需禁用某个规则，必须在配置文件中注释说明原因
|
||
|
||
**常见 Linter 问题及解决方案：**
|
||
|
||
- `errcheck`: 错误未处理 → 添加错误处理逻辑
|
||
- `gofmt`: 格式不正确 → 运行 `go fmt ./...`
|
||
- `govet`: 可疑构造 → 重构代码
|
||
- `ineffassign`: 无效赋值 → 移除或修正赋值
|
||
- `staticcheck`: 静态分析问题 → 按建议修改
|
||
|
||
**集成到开发流程：**
|
||
- 在提交代码前，运行测试流水线（包含 linter 检查）
|
||
- 确保 linter 零警告、零错误
|
||
- CI/CD 流水线应包含 linter 检查步骤
|
||
|
||
## 常见模式和示例
|
||
|
||
### 客户端初始化模式
|
||
```go
|
||
// Config holds the configuration for the OpenSearch client.
|
||
type Config struct {
|
||
Endpoint string
|
||
Region string
|
||
AccessKey string
|
||
SecretKey string
|
||
Timeout time.Duration
|
||
}
|
||
|
||
// Client represents an OpenSearch client.
|
||
type Client struct {
|
||
config *Config
|
||
client *opensearch.Client
|
||
}
|
||
|
||
// NewClient creates a new OpenSearch client with the given configuration.
|
||
func NewClient(cfg *Config) (*Client, error) {
|
||
if cfg == nil {
|
||
return nil, fmt.Errorf("config cannot be nil")
|
||
}
|
||
|
||
if err := validateConfig(cfg); err != nil {
|
||
return nil, fmt.Errorf("invalid config: %w", err)
|
||
}
|
||
|
||
// Initialize OpenSearch client
|
||
osClient, err := opensearch.NewClient(opensearch.Config{
|
||
Addresses: []string{cfg.Endpoint},
|
||
// ... other settings
|
||
})
|
||
if err != nil {
|
||
return nil, fmt.Errorf("failed to create opensearch client: %w", err)
|
||
}
|
||
|
||
return &Client{
|
||
config: cfg,
|
||
client: osClient,
|
||
}, nil
|
||
}
|
||
|
||
func validateConfig(cfg *Config) error {
|
||
if cfg.Endpoint == "" {
|
||
return errors.New("endpoint is required")
|
||
}
|
||
if cfg.Region == "" {
|
||
return errors.New("region is required")
|
||
}
|
||
return nil
|
||
}
|
||
```
|
||
|
||
### 操作方法模式
|
||
```go
|
||
// SearchRequest represents a search query request.
|
||
type SearchRequest struct {
|
||
Index string
|
||
Query map[string]any
|
||
Size int
|
||
From int
|
||
}
|
||
|
||
// SearchResult represents the response from a search operation.
|
||
type SearchResult struct {
|
||
Hits []Document
|
||
Total int64
|
||
Took int64
|
||
}
|
||
|
||
// Search executes a search query against the specified index.
|
||
func (c *Client) Search(ctx context.Context, req *SearchRequest) (*SearchResult, error) {
|
||
if req == nil {
|
||
return nil, errors.New("search request cannot be nil")
|
||
}
|
||
|
||
if req.Index == "" {
|
||
return nil, errors.New("index name is required")
|
||
}
|
||
|
||
// Build and execute search
|
||
// ...
|
||
|
||
return result, nil
|
||
}
|
||
```
|
||
|
||
### Context 使用模式
|
||
```go
|
||
// 所有可能阻塞或需要超时控制的操作都应接受 context
|
||
func (c *Client) CreateIndex(ctx context.Context, name string, settings map[string]any) error {
|
||
// 使用 context 控制超时
|
||
req, err := http.NewRequestWithContext(ctx, "PUT", c.buildURL(name), body)
|
||
if err != nil {
|
||
return fmt.Errorf("failed to create request: %w", err)
|
||
}
|
||
|
||
// ...
|
||
}
|
||
|
||
// 调用示例
|
||
ctx, cancel := context.WithTimeout(context.Background(), 30*time.Second)
|
||
defer cancel()
|
||
|
||
err := client.CreateIndex(ctx, "my-index", settings)
|
||
```
|
||
|
||
## 版本和依赖管理
|
||
|
||
**依赖选择原则：**
|
||
1. 优先使用最新稳定版本
|
||
2. 使用官方推荐的库（如 opensearch-go）
|
||
3. 定期更新依赖（使用 `go get -u` 和 `go mod tidy`）
|
||
|
||
**更新依赖时检查：**
|
||
```bash
|
||
# 查看可用更新
|
||
go list -u -m all
|
||
|
||
# 更新特定依赖
|
||
go get -u github.com/opensearch-project/opensearch-go/v2@latest
|
||
|
||
# 整理依赖
|
||
go mod tidy
|
||
```
|
||
|
||
## 测试流水线
|
||
|
||
### 流水线脚本要求
|
||
|
||
项目**必须**包含自动化测试流水线脚本，用于执行完整的代码质量检查流程。
|
||
|
||
**脚本命名规范：**
|
||
- Windows (PowerShell): `test.ps1`
|
||
- Linux/Mac (Bash): `test.sh`
|
||
|
||
**流水线阶段（按顺序执行）：**
|
||
|
||
1. **Linting** - 代码质量检查
|
||
```bash
|
||
golangci-lint run ./...
|
||
```
|
||
|
||
2. **Build** - 编译验证
|
||
```bash
|
||
# 编译但不保留二进制文件
|
||
go build -o /dev/null . # Linux/Mac
|
||
go build -o NUL . # Windows
|
||
```
|
||
|
||
3. **Test** - 运行测试
|
||
```bash
|
||
go test -v -short -coverprofile=coverage.out ./...
|
||
```
|
||
|
||
4. **Cleanup** - 清理构建产物
|
||
```bash
|
||
# 删除编译输出、覆盖率文件等
|
||
rm -f *.exe *.test coverage.out coverage.html
|
||
```
|
||
|
||
### 流水线脚本检查
|
||
|
||
**在最终测试前，AI Agent 必须检查：**
|
||
|
||
1. 当前平台是否存在对应的流水线脚本
|
||
2. 如果不存在但有其他平台的脚本，则根据当前平台创建对应版本
|
||
|
||
**平台检测和脚本生成逻辑：**
|
||
|
||
```go
|
||
// 伪代码示例
|
||
if platform == "Windows" {
|
||
if !exists("test.ps1") {
|
||
if exists("test.sh") {
|
||
// 将 test.sh 翻译为 test.ps1
|
||
createWindowsScript()
|
||
} else {
|
||
// 创建新的 Windows 脚本
|
||
createDefaultWindowsScript()
|
||
}
|
||
}
|
||
} else if platform == "Linux" || platform == "Mac" {
|
||
if !exists("test.sh") {
|
||
if exists("test.ps1") {
|
||
// 将 test.ps1 翻译为 test.sh
|
||
createUnixScript()
|
||
} else {
|
||
// 创建新的 Unix 脚本
|
||
createDefaultUnixScript()
|
||
}
|
||
}
|
||
}
|
||
```
|
||
|
||
### PowerShell 脚本示例 (test.ps1)
|
||
|
||
```powershell
|
||
#!/usr/bin/env pwsh
|
||
# 测试流水线脚本 - Windows PowerShell
|
||
|
||
param(
|
||
[switch]$SkipLint,
|
||
[switch]$SkipBuild,
|
||
[switch]$SkipTest,
|
||
[switch]$Verbose
|
||
)
|
||
|
||
$ErrorActionPreference = "Stop"
|
||
|
||
# 1. Linting
|
||
if (-not $SkipLint) {
|
||
Write-Host "=== Linting ===" -ForegroundColor Yellow
|
||
golangci-lint run ./...
|
||
if ($LASTEXITCODE -ne 0) { exit 1 }
|
||
}
|
||
|
||
# 2. Build
|
||
if (-not $SkipBuild) {
|
||
Write-Host "=== Build ===" -ForegroundColor Yellow
|
||
go build -o NUL .
|
||
if ($LASTEXITCODE -ne 0) { exit 1 }
|
||
}
|
||
|
||
# 3. Test
|
||
if (-not $SkipTest) {
|
||
Write-Host "=== Test ===" -ForegroundColor Yellow
|
||
go test -v -short -coverprofile=coverage.out ./...
|
||
if ($LASTEXITCODE -ne 0) { exit 1 }
|
||
go tool cover -func=coverage.out | Select-String "total:"
|
||
}
|
||
|
||
# 4. Cleanup
|
||
Write-Host "=== Cleanup ===" -ForegroundColor Yellow
|
||
Remove-Item -Path "*.exe","*.test","coverage.out","coverage.html" -ErrorAction SilentlyContinue
|
||
|
||
Write-Host "✅ Pipeline PASSED" -ForegroundColor Green
|
||
```
|
||
|
||
### Bash 脚本示例 (test.sh)
|
||
|
||
```bash
|
||
#!/usr/bin/env bash
|
||
# 测试流水线脚本 - Linux/Mac Bash
|
||
|
||
set -euo pipefail
|
||
|
||
SKIP_LINT=false
|
||
SKIP_BUILD=false
|
||
SKIP_TEST=false
|
||
VERBOSE=false
|
||
|
||
# 解析参数
|
||
while [[ $# -gt 0 ]]; do
|
||
case $1 in
|
||
--skip-lint) SKIP_LINT=true; shift ;;
|
||
--skip-build) SKIP_BUILD=true; shift ;;
|
||
--skip-test) SKIP_TEST=true; shift ;;
|
||
--verbose) VERBOSE=true; shift ;;
|
||
*) echo "Unknown option: $1"; exit 1 ;;
|
||
esac
|
||
done
|
||
|
||
# 1. Linting
|
||
if [ "$SKIP_LINT" = false ]; then
|
||
echo "=== Linting ==="
|
||
golangci-lint run ./...
|
||
fi
|
||
|
||
# 2. Build
|
||
if [ "$SKIP_BUILD" = false ]; then
|
||
echo "=== Build ==="
|
||
go build -o /dev/null .
|
||
fi
|
||
|
||
# 3. Test
|
||
if [ "$SKIP_TEST" = false ]; then
|
||
echo "=== Test ==="
|
||
go test -v -short -race -coverprofile=coverage.out ./...
|
||
go tool cover -func=coverage.out | grep total:
|
||
fi
|
||
|
||
# 4. Cleanup
|
||
echo "=== Cleanup ==="
|
||
rm -f *.exe *.test coverage.out coverage.html
|
||
|
||
echo "✅ Pipeline PASSED"
|
||
```
|
||
|
||
### 使用流水线
|
||
|
||
**日常开发：**
|
||
```bash
|
||
# Windows
|
||
powershell -ExecutionPolicy Bypass -File .\test.ps1
|
||
|
||
# Linux/Mac
|
||
chmod +x test.sh
|
||
./test.sh
|
||
```
|
||
|
||
**跳过特定阶段：**
|
||
```bash
|
||
# Windows - 跳过 linting
|
||
powershell -ExecutionPolicy Bypass -File .\test.ps1 -SkipLint
|
||
|
||
# Linux/Mac - 跳过 build
|
||
./test.sh --skip-build
|
||
```
|
||
|
||
**CI/CD 集成：**
|
||
```yaml
|
||
# GitHub Actions 示例
|
||
- name: Run test pipeline
|
||
run: |
|
||
if [ "$RUNNER_OS" == "Windows" ]; then
|
||
pwsh -File test.ps1
|
||
else
|
||
./test.sh
|
||
fi
|
||
```
|
||
|
||
### 流水线最佳实践
|
||
|
||
1. **构建产物管理：**
|
||
- 编译时不保留二进制文件（输出到 `/dev/null` 或 `NUL`）
|
||
- 测试后自动清理所有临时文件
|
||
- 在 `.gitignore` 中排除所有构建产物
|
||
|
||
2. **失败快速原则：**
|
||
- 任何阶段失败立即终止流水线
|
||
- 返回非零退出码
|
||
- 提供清晰的错误信息
|
||
|
||
3. **可配置性：**
|
||
- 提供跳过特定阶段的选项
|
||
- 支持详细输出模式
|
||
- 允许自定义超时设置
|
||
|
||
4. **跨平台一致性：**
|
||
- 确保 Windows 和 Linux/Mac 脚本功能一致
|
||
- 使用等效的命令和选项
|
||
- 测试结果应该相同
|
||
|
||
## 文档要求
|
||
|
||
**代码文档：**
|
||
- 所有导出的标识符必须有文档注释
|
||
- 复杂的内部逻辑添加解释性注释
|
||
- 注释应解释"为什么"而不仅仅是"是什么"
|
||
|
||
**README 维护：**
|
||
- 添加新功能时更新功能列表
|
||
- 添加示例代码展示用法
|
||
- 更新配置说明
|
||
|
||
**示例代码：**
|
||
- 在 `examples/` 目录提供可运行的示例
|
||
- 示例代码必须可编译和运行
|
||
- 包含必要的错误处理
|
||
|
||
## AI Agent 工作流程（TDD 原则）
|
||
|
||
当收到开发任务时，**必须严格遵循 TDD（测试驱动开发）流程**：
|
||
|
||
### 1. Red（红灯阶段）- 编写失败的测试
|
||
|
||
**理解需求：**
|
||
- 明确要实现的功能和预期行为
|
||
- 确定输入、输出和边界条件
|
||
- 识别可能的错误场景
|
||
|
||
**设计 API：**
|
||
- 定义函数签名和类型
|
||
- 设计清晰的接口
|
||
- 确定错误返回值
|
||
|
||
**编写测试（先于实现）：**
|
||
```go
|
||
// 示例：先写测试
|
||
func TestNewClient(t *testing.T) {
|
||
tests := []struct {
|
||
name string
|
||
config *Config
|
||
wantErr error
|
||
}{
|
||
{
|
||
name: "valid config",
|
||
config: &Config{Endpoint: "https://example.com"},
|
||
wantErr: nil,
|
||
},
|
||
{
|
||
name: "nil config",
|
||
config: nil,
|
||
wantErr: ErrInvalidConfig,
|
||
},
|
||
}
|
||
|
||
for _, tt := range tests {
|
||
t.Run(tt.name, func(t *testing.T) {
|
||
got, err := NewClient(tt.config)
|
||
if !errors.Is(err, tt.wantErr) {
|
||
t.Errorf("NewClient() error = %v, wantErr %v", err, tt.wantErr)
|
||
}
|
||
})
|
||
}
|
||
}
|
||
```
|
||
|
||
**验证测试失败：**
|
||
- 运行测试，确认测试失败（因为功能还未实现）
|
||
- 确保测试失败的原因是正确的
|
||
|
||
### 2. Green（绿灯阶段）- 编写最小实现
|
||
|
||
**实现功能：**
|
||
- 编写最少的代码让测试通过
|
||
- 遵循本文档的所有规范
|
||
- 添加完整的文档注释
|
||
- 实现完整的错误处理
|
||
|
||
```go
|
||
// 示例：实现功能
|
||
func NewClient(cfg *Config) (*Client, error) {
|
||
if cfg == nil {
|
||
return nil, ErrInvalidConfig
|
||
}
|
||
|
||
// 最小实现
|
||
return &Client{config: cfg}, nil
|
||
}
|
||
```
|
||
|
||
**运行测试：**
|
||
- 确保所有测试通过
|
||
- 检查测试覆盖率
|
||
|
||
### 3. Refactor（重构阶段）- 优化代码
|
||
|
||
**代码重构：**
|
||
- 消除重复代码
|
||
- 改进命名和结构
|
||
- 优化性能（如需要）
|
||
- 确保代码可读性
|
||
|
||
**运行 Linter：**
|
||
```bash
|
||
golangci-lint run ./...
|
||
```
|
||
|
||
**修复所有 Linter 问题**
|
||
|
||
**再次运行测试：**
|
||
- 确保重构后测试仍然通过
|
||
- 验证代码行为未改变
|
||
|
||
### 4. 验证和文档
|
||
|
||
**运行测试流水线：**
|
||
```bash
|
||
# Windows
|
||
powershell -ExecutionPolicy Bypass -File .\test.ps1
|
||
|
||
# Linux/Mac
|
||
./test.sh
|
||
```
|
||
|
||
**更新文档：**
|
||
- 更新模块 README（如需要）
|
||
- 更新项目 README（如需要）
|
||
- 添加使用示例（如需要）
|
||
|
||
### TDD 循环总结
|
||
|
||
```
|
||
┌─────────────────────────────────────┐
|
||
│ 1. 编写失败的测试 (Red) │
|
||
│ - 定义预期行为 │
|
||
│ - 验证测试确实失败 │
|
||
└──────────────┬──────────────────────┘
|
||
↓
|
||
┌─────────────────────────────────────┐
|
||
│ 2. 编写最小实现 (Green) │
|
||
│ - 让测试通过 │
|
||
│ - 不过度设计 │
|
||
└──────────────┬──────────────────────┘
|
||
↓
|
||
┌─────────────────────────────────────┐
|
||
│ 3. 重构优化 (Refactor) │
|
||
│ - 改进代码质量 │
|
||
│ - 运行 Linter │
|
||
│ - 确保测试仍然通过 │
|
||
└──────────────┬──────────────────────┘
|
||
↓
|
||
┌─────────┐
|
||
│ 下一功能 │
|
||
└─────────┘
|
||
```
|
||
|
||
**重要提醒：**
|
||
- ❌ 不要先写实现再补测试
|
||
- ✅ 必须先写测试，然后写实现
|
||
- ✅ 每次只关注一个小功能
|
||
- ✅ 频繁运行测试，保持快速反馈
|
||
|
||
## 特殊指令
|
||
|
||
### 生成新模块时
|
||
1. 创建包目录和主文件
|
||
2. 创建对应的测试文件
|
||
3. 在 README 中更新项目结构
|
||
4. 在功能列表中标记进度
|
||
|
||
### 重构代码时
|
||
1. 确保向后兼容（除非明确要求破坏性变更）
|
||
2. 更新所有相关测试
|
||
3. 更新文档和注释
|
||
4. 运行完整测试套件
|
||
|
||
### 修复 Bug 时
|
||
1. 先编写复现 bug 的测试
|
||
2. 修复代码
|
||
3. 确保测试通过
|
||
4. 添加注释说明修复内容
|
||
|
||
## 禁止事项
|
||
|
||
**绝对不允许：**
|
||
- ❌ 忽略错误（使用 `_` 丢弃错误）
|
||
- ❌ 导出的标识符没有注释
|
||
- ❌ 使用 `panic` 处理常规错误（除非确实是不可恢复的错误）
|
||
- ❌ 在库代码中使用 `os.Exit`
|
||
- ❌ 硬编码配置值（应使用配置文件或环境变量）
|
||
- ❌ 使用全局可变状态（除了当前阶段允许的配置和日志）
|
||
|
||
**应当避免：**
|
||
- ⚠️ 过长的函数（超过 50 行考虑拆分）
|
||
- ⚠️ 过深的嵌套（超过 3 层考虑重构）
|
||
- ⚠️ 重复代码（提取为函数）
|
||
- ⚠️ 神秘的数字和字符串（使用命名常量）
|
||
|
||
## 参考资源
|
||
|
||
- [Effective Go](https://go.dev/doc/effective_go)
|
||
- [Go Code Review Comments](https://github.com/golang/go/wiki/CodeReviewComments)
|
||
- [Go 标准库文档](https://pkg.go.dev/std)
|
||
- [OpenSearch Go Client](https://github.com/opensearch-project/opensearch-go)
|
||
- [AWS SDK for Go v2](https://aws.github.io/aws-sdk-go-v2/)
|
||
|
||
---
|
||
|
||
**总结**: 作为 AI Agent，你的目标是生成生产级别的 Go 代码，遵循所有最佳实践，为将来转化为可复用库打下坚实基础。当有疑问时，参考 Go 标准库的实现方式。
|