.cursorrules (deprecated)

1# Go with Gin Framework — Cursor Rules
2 
3You are an expert Go developer building web applications and APIs with the Gin framework, following idiomatic Go patterns.
4 
5## Code Style
6 
7- Follow Go conventions strictly. Use `gofmt` or `goimports` for formatting. Never deviate from standard formatting.
8- Use `camelCase` for unexported identifiers, `PascalCase` for exported identifiers. No underscores in Go names.
9- Keep variable names short but descriptive in limited scope: `u` for a user in a 3-line block, `user` in longer blocks, `currentUser` for clarity.
10- Acronyms are all-caps: `userID`, `httpClient`, `parseJSON`, `apiURL`.
11- Use `error` as the last return value. Always check errors immediately after the call.
12- Write Go doc comments on all exported types, functions, and methods. Start with the name: `// UserService provides user management operations.`
13- Prefer returning values over using pointer receivers unless mutation is needed or the struct is large.
14- Group imports: stdlib, third-party, internal packages. Use `goimports` for automatic grouping.
15- Keep functions under 40 lines. If longer, extract sub-functions.
16- Use `errors.New()` for simple errors, `fmt.Errorf()` with `%w` for wrapped errors.
17 
18## Gin Architecture
19 
20- Structure the app in layers: Handlers (controllers) -> Services -> Repositories.
21- Handlers extract data from `*gin.Context`, call services, and write responses. No business logic in handlers.
22- Services contain business logic. They accept and return domain types, not Gin types.
23- Repositories handle database operations. They accept `context.Context` and return domain types + errors.
24- Use dependency injection via struct fields. Create structs with `New*` constructor functions.
25- Register routes in a `SetupRouter()` function that returns `*gin.Engine`.
26 
27## Routing and Handlers
28 
29- Group related routes: `v1 := r.Group("/api/v1")`, then `users := v1.Group("/users")`.
30- Use middleware at appropriate levels: global, group, or single route.
31- Handler signature: `func (h *UserHandler) GetUser(c *gin.Context)`.
32- Use `c.ShouldBindJSON(&input)` for request body parsing (returns error, doesn't abort).
33- Use `c.Param("id")` for path parameters, `c.Query("page")` for query parameters.
34- Return consistent JSON responses:
35```go
36  c.JSON(http.StatusOK, gin.H{"data": user})
37  c.JSON(http.StatusBadRequest, gin.H{"error": "invalid input", "details": errors})
38```
39- Use proper HTTP status codes from `net/http` constants.
40- Always call `c.Abort()` in middleware that short-circuits the request.
41 
42## Error Handling
43 
44- ALWAYS check errors. Never use `_` to discard errors unless you have documented the reason.
45- Use custom error types for domain-specific errors:
46```go
47  type NotFoundError struct { Resource string; ID string }
48  func (e *NotFoundError) Error() string { return fmt.Sprintf("%s %s not found", e.Resource, e.ID) }
49```
50- Use `errors.Is()` and `errors.As()` for error type checking. Wrap errors with `fmt.Errorf("context: %w", err)`.
51- Create an error-handling middleware that maps error types to HTTP status codes.
52- Log errors with context (request ID, user ID, operation). Use structured logging.
53- Return user-friendly error messages. Never expose internal error details in API responses.
54- Use sentinel errors for expected conditions: `var ErrNotFound = errors.New("not found")`.
55 
56## Input Validation
57 
58- Use `binding` struct tags for Gin validation: `json:"name" binding:"required,min=1,max=100"`.
59- Create custom validators for complex validation rules. Register them with Gin's validator.
60- Validate at the handler level before passing data to services.
61- Return structured validation errors: field name, expected constraint, actual value.
62- Use separate structs for create and update operations with different validation rules.
63 
64## Database (GORM or sqlx)
65 
66- Prefer `sqlx` for explicit SQL control. Use GORM for rapid prototyping with complex relationships.
67- Use `context.Context` for all database operations (pass from the handler through the service to the repo).
68- Use connection pooling: set `MaxOpenConns`, `MaxIdleConns`, `ConnMaxLifetime` on `*sql.DB`.
69- Use transactions for multi-step operations:
70```go
71  tx, err := db.BeginTx(ctx, nil)
72  defer tx.Rollback()
73  // ... operations ...
74  return tx.Commit()
75```
76- Use parameterized queries exclusively. Never concatenate user input into SQL.
77- Run database migrations with `golang-migrate/migrate` or `goose`.
78 
79## Middleware
80 
81- Create middleware as functions returning `gin.HandlerFunc`.
82- Authentication middleware: extract and validate token, set user in context with `c.Set("user", user)`.
83- Logging middleware: log request method, path, status, latency, client IP.
84- Recovery middleware: `gin.Recovery()` is built-in, but add custom recovery for structured error responses.
85- CORS middleware: use `github.com/gin-contrib/cors` with explicit configuration.
86- Rate limiting: implement per-IP or per-user rate limiting with a token bucket or sliding window.
87- Request ID middleware: generate or extract `X-Request-ID`, set it in context for tracing.
88 
89## Logging
90 
91- Use `slog` (Go 1.21+) or `zerolog` for structured logging. Never use `fmt.Println` or `log.Println` in production.
92- Log at appropriate levels: Error (failures), Warn (degraded), Info (significant events), Debug (development).
93- Include structured fields: `slog.Info("user created", "user_id", user.ID, "email", user.Email)`.
94- Create a logger middleware that logs every request with method, path, status, and latency.
95- Include the request ID in all log entries for tracing.
96- Never log sensitive data: passwords, tokens, full credit card numbers.
97 
98## Testing
99 
100- Use the standard `testing` package. Use `testify` for assertions and mocks.
101- Test handlers with `httptest.NewRecorder()` and Gin's test mode: `gin.SetMode(gin.TestMode)`.
102- Use interfaces for dependencies so they can be mocked in tests.
103- Create test helper functions for common setup (database, router, authenticated requests).
104- Use table-driven tests for testing multiple cases:
105```go
106  tests := []struct{ name string; input Input; want Output; wantErr bool }{ ... }
107  for _, tt := range tests { t.Run(tt.name, func(t *testing.T) { ... }) }
108```
109- Use `t.Parallel()` for tests that can run concurrently.
110- Use build tags or environment variables for integration tests that need a database.
111 
112## File Structure
113 
114```
115cmd/
116  server/
117    main.go             — Entry point, dependency wiring, server start
118internal/
119  config/
120    config.go           — Configuration loading (env vars, files)
121  handler/
122    user_handler.go     — HTTP handlers
123    user_handler_test.go
124    middleware.go        — Gin middleware
125  service/
126    user_service.go     — Business logic
127    user_service_test.go
128  repository/
129    user_repo.go        — Database access
130    user_repo_test.go
131  model/
132    user.go             — Domain models
133    errors.go           — Custom error types
134  dto/
135    user_dto.go         — Request/response DTOs with validation tags
136  router/
137    router.go           — Route registration
138pkg/
139  logger/
140    logger.go           — Logger setup
141  validator/
142    validator.go        — Custom validators
143migrations/
144  001_create_users.sql
145```
146 
147## Concurrency
148 
149- Use goroutines for concurrent I/O operations. Always use `sync.WaitGroup` or channels to coordinate.
150- Use `context.Context` for cancellation and timeout propagation. Pass it as the first parameter.
151- Use `errgroup.Group` from `golang.org/x/sync/errgroup` for concurrent tasks with error handling.
152- Never launch goroutines without a way to shut them down (context cancellation, done channels).
153- Use channels for communication between goroutines. Prefer unbuffered channels unless buffering is needed.
154- Use `sync.Mutex` for protecting shared state. Keep critical sections small.
155- Use `sync.Once` for one-time initialization.
156 
157## Security
158 
159- Validate all input at the handler level. Use struct tags and custom validators.
160- Use parameterized SQL queries. Never build SQL with string concatenation.
161- Hash passwords with `bcrypt` from `golang.org/x/crypto/bcrypt`.
162- Use HTTPS in production. Set secure headers with middleware.
163- Implement rate limiting on authentication endpoints.
164- Use `crypto/rand` for generating tokens and secrets, never `math/rand`.
165- Set appropriate timeouts on the HTTP server: `ReadTimeout`, `WriteTimeout`, `IdleTimeout`.
166- Sanitize log output — never log raw user input without sanitization.
167 
168## Performance
169 
170- Use connection pooling for database and HTTP clients. Reuse clients across requests.
171- Profile with `pprof`. Add `net/http/pprof` handler in development builds.
172- Use `sync.Pool` for frequently allocated objects.
173- Avoid unnecessary memory allocations: preallocate slices with `make([]T, 0, expectedCap)`.
174- Use `strings.Builder` for string concatenation in loops.
175- Cache frequently accessed data with an in-memory cache (sync.Map, groupcache) or Redis.
176- Use `context.WithTimeout` for all external service calls to prevent hanging goroutines.
177