zlei6/go-zero
1
0
Fork 0
mirror of https://github.com/zeromicro/go-zero.git synced 2026-05-14 02:10:00 +08:00
Code Issues Packages Projects Releases Wiki Activity

docs: enhance copilot instructions with detailed architecture patterns (#5313)

Browse Source 
Co-authored-by: Copilot <175728472+Copilot@users.noreply.github.com>
This commit is contained in:
Kevin Wan
2025-12-06 23:39:28 +08:00
committed by GitHub
parent 0a724447cd
commit 918a7be698
1 changed files with 71 additions and 27 deletions
Download Patch File Download Diff File Expand all files Collapse all files

98
.github/copilot-instructions.md vendored
View File

@@ -8,14 +8,16 @@ go-zero is a web and RPC framework with lots of built-in engineering practices d
### Key Architecture Components ### Key Architecture Components
- **REST API framework** (`rest/`) - HTTP service framework with middleware support - **REST API framework** (`rest/`) - HTTP service framework with middleware chain support
- **RPC framework** (`zrpc/`) - gRPC-based RPC framework with service discovery - **RPC framework** (`zrpc/`) - gRPC-based RPC framework with etcd service discovery and p2c_ewma load balancing
- **Core utilities** (`core/`) - Foundational components including: - **Gateway** (`gateway/`) - API gateway supporting both HTTP and gRPC upstreams with proto-based routing
- Circuit breakers, rate limiters, load shedding - **MCP Server** (`mcp/`) - Model Context Protocol server for AI agent integration via SSE
- Caching, stores (Redis, MongoDB, SQL) - **Core utilities** (`core/`) - Production-grade components:
- Concurrency control, metrics, tracing - Resilience: circuit breakers (`breaker/`), rate limiters (`limit/`), adaptive load shedding (`load/`)
- Configuration management - Storage: SQL with cache (`stores/sqlc/`), Redis (`stores/redis/`), MongoDB (`stores/mongo/`)
- **Code generation tool** (`tools/goctl/`) - CLI tool for generating code from API files - Concurrency: MapReduce (`mr/`), worker pools (`executors/`), sync primitives (`syncx/`)
- Observability: metrics (`metric/`), tracing (`trace/`), structured logging (`logx/`)
- **Code generation tool** (`tools/goctl/`) - CLI tool for generating Go code from `.api` and `.proto` files
## Coding Standards and Conventions ## Coding Standards and Conventions
@@ -25,18 +27,22 @@ go-zero is a web and RPC framework with lots of built-in engineering practices d
2. **Package naming**: Use lowercase, single-word package names when possible 2. **Package naming**: Use lowercase, single-word package names when possible
3. **Error handling**: Always handle errors explicitly, use `errorx.BatchError` for multiple errors 3. **Error handling**: Always handle errors explicitly, use `errorx.BatchError` for multiple errors
4. **Context propagation**: Always pass `context.Context` as the first parameter for functions that may block 4. **Context propagation**: Always pass `context.Context` as the first parameter for functions that may block
5. **Configuration structures**: Use struct tags with JSON annotations and default values 5. **Configuration structures**: Use struct tags with JSON annotations, defaults, and validation
Example configuration pattern: **Pattern**: All service configs embed `service.ServiceConf` for common fields (Name, Log, Mode, Telemetry)
```go ```go
type Config struct { type Config struct {
service.ServiceConf // Always embed for services
Host string `json:",default=0.0.0.0"` Host string `json:",default=0.0.0.0"`
Port int `json:",default=8080"` Port int // Required field (no default)
Timeout int `json:",default=3000"` Timeout int64 `json:",default=3000"` // Timeouts in milliseconds
Optional string `json:",optional"` Optional string `json:",optional"` // Optional field
Mode string `json:",default=pro,options=dev|test|rt|pre|pro"` // Validated options
} }
``` ```
**Service modes**: `dev`/`test`/`rt` disable load shedding and stats; `pre`/`pro` enable all resilience features
### Interface Design ### Interface Design
1. **Small interfaces**: Follow Go's preference for small, focused interfaces 1. **Small interfaces**: Follow Go's preference for small, focused interfaces
@@ -94,25 +100,33 @@ func TestSomething(t *testing.T) {
### REST API Development ### REST API Development
1. **API Definition**: Use `.api` files to define REST APIs 1. **API Definition**: Use `.api` files to define REST APIs with goctl codegen
2. **Handler pattern**: Separate business logic into logic packages 2. **Handler pattern**: Separate business logic into logic packages (handlers call logic layer)
3. **Middleware**: Use built-in middlewares (tracing, logging, metrics, recovery) 3. **Middleware chain**: Middlewares wrap via `chain.Chain` interface - use `Append()` or `Prepend()` to control order
4. **Response handling**: Use `httpx.WriteJson` for JSON responses - Built-in middlewares (all in `rest/handler/`): tracing, logging, metrics, recovery, breaker, shedding, timeout, maxconns, maxbytes, gunzip
5. **Error handling**: Use `httpx.Error` for HTTP error responses - Custom middleware: `func(http.Handler) http.Handler` - call `next.ServeHTTP(w, r)` to continue chain
4. **Response handling**: Use `httpx.WriteJson(w, code, v)` for JSON responses
5. **Error handling**: Use `httpx.Error(w, err)` or `httpx.ErrorCtx(ctx, w, err)` for HTTP error responses
6. **Route registration**: Routes defined with `Method`, `Path`, and `Handler` - wildcards use `:param` syntax
### RPC Development ### RPC Development
1. **Protocol Buffers**: Use protobuf for service definitions 1. **Protocol Buffers**: Use protobuf for service definitions, generate code with goctl
2. **Service discovery**: Integrate with etcd for service registration 2. **Service discovery**: Use etcd for dynamic service registration/discovery, or direct endpoints for static routing
3. **Load balancing**: Use built-in load balancing strategies 3. **Load balancing**: Default is `p2c_ewma` (power of 2 choices with EWMA), configurable via `BalancerName`
4. **Interceptors**: Implement interceptors for cross-cutting concerns 4. **Client configuration**: Support `Etcd`, `Endpoints`, or `Target` - use `BuildTarget()` to construct connection string
5. **Interceptors**: Implement gRPC interceptors for cross-cutting concerns (auth, logging, metrics)
6. **Health checks**: gRPC health checks enabled by default (`Health: true`)
### Database Operations ### Database Operations
1. **SQL operations**: Use `sqlx` package for database operations 1. **SQL operations**: Use `sqlx.SqlConn` interface - methods always end with `Ctx` for context support
2. **Caching**: Implement caching patterns with `cache` package 2. **Caching pattern**: `stores/sqlc` provides `CachedConn` for automatic cache-aside pattern
3. **Transactions**: Use proper transaction handling - `QueryRowCtx`: Query with cache key, auto-populate on cache miss
4. **Connection pooling**: Configure appropriate connection pools - `ExecCtx`: Execute and delete cache keys
3. **Transactions**: Use `sqlx.SqlConn.TransactCtx()` to get transaction session
4. **Connection pooling**: Managed automatically (64 max idle/open, 1min lifetime)
5. **Test helpers**: Use `redistest.CreateRedis(t)` for Redis, SQL mocks for DB testing
Example cache pattern: Example cache pattern:
```go ```go
@@ -192,6 +206,36 @@ Always implement proper resource cleanup using defer and context cancellation.
- Test: `go test ./...` - Test: `go test ./...`
- Test with race detection: `go test -race ./...` - Test with race detection: `go test -race ./...`
- Format: `gofmt -w .` - Format: `gofmt -w .`
- Generate code: `goctl api go -api *.api -dir .` - Code generation:
- REST API: `goctl api go -api *.api -dir .`
- RPC: `goctl rpc protoc *.proto --go_out=. --go-grpc_out=. --zrpc_out=.`
- Model from SQL: `goctl model mysql datasource -url="user:pass@tcp(host:port)/db" -table="*" -dir="./model"`
## Critical Architecture Patterns
### Resilience Design Philosophy
go-zero implements defense-in-depth with multiple protection layers:
1. **Circuit Breaker** (`core/breaker`): Google SRE breaker - tracks success/failure, opens on error threshold
2. **Adaptive Load Shedding** (`core/load`): CPU-based auto-rejection when system overloaded (disabled in dev/test/rt modes)
3. **Rate Limiting** (`core/limit`): Token bucket (Redis-based) and period limiters
4. **Timeout Control**: Cascading timeouts via context - set at multiple levels (client, server, handler)
### Middleware Chain Architecture
`rest/chain` provides middleware composition:
```go
// Middleware signature
type Middleware func(http.Handler) http.Handler
// Chain operations
chain := chain.New(m1, m2)
chain.Append(m3) // Adds to end: m1 -> m2 -> m3
chain.Prepend(m0) // Adds to start: m0 -> m1 -> m2 -> m3
handler := chain.Then(finalHandler)
```
### Concurrency Patterns
- **MapReduce** (`core/mr`): Parallel processing with worker pools - use for batch operations
- **Executors** (`core/executors`): Bulk/period executors for batching operations
- **SingleFlight** (`core/syncx`): Deduplicates concurrent identical requests
Remember to run tests and ensure all checks pass before submitting changes. The project emphasizes high quality, performance, and reliability, so these should be primary considerations in all development work. Remember to run tests and ensure all checks pass before submitting changes. The project emphasizes high quality, performance, and reliability, so these should be primary considerations in all development work.