.cursorrules (deprecated)

1# Go API Development — Cursor Rules
2# Comprehensive rules for building APIs in Go
3 
4## Project Context
5You are working on a Go API application. The codebase follows Go idioms and conventions,
6uses the standard library where practical, and emphasizes simplicity, explicit error
7handling, and strong typing. The project uses Go modules for dependency management.
8 
9## Tech Stack
10- Go 1.22+ (latest stable)
11- Standard library `net/http` with `http.ServeMux` (Go 1.22+) or chi/gorilla for routing
12- `database/sql` with pgx driver for PostgreSQL
13- `encoding/json` for JSON marshaling
14- `slog` for structured logging (Go 1.21+)
15- `testing` package with table-driven tests
16- Docker for containerization
17 
18## Coding Style
19 
20### Naming Conventions
21- Packages: short, lowercase, single word (e.g., `user`, `order`, `auth`)
22- Exported types: PascalCase (e.g., `UserService`, `OrderHandler`)
23- Unexported: camelCase (e.g., `validateEmail`, `parseToken`)
24- Interfaces: describe behavior, often `-er` suffix (e.g., `Reader`, `UserStore`, `Authenticator`)
25- Errors: `Err` prefix for sentinel errors (e.g., `ErrNotFound`, `ErrUnauthorized`)
26- Constructors: `New` prefix (e.g., `NewUserService`, `NewRouter`)
27- HTTP handlers: verb-noun (e.g., `HandleCreateUser`, `HandleListOrders`)
28- Files: snake_case (e.g., `user_handler.go`, `order_service.go`)
29- Test files: `*_test.go` adjacent to the code being tested
30- Acronyms: all caps (e.g., `userID`, `httpClient`, `parseURL`)
31 
32### Project Structure
33```
34cmd/
35  api/
36    main.go              # Entry point
37internal/
38  config/                # Configuration loading
39    config.go
40  handler/               # HTTP handlers (transport layer)
41    user.go
42    order.go
43    middleware.go
44  service/               # Business logic
45    user.go
46    order.go
47  store/                 # Data access (repository pattern)
48    user.go
49    order.go
50    postgres.go          # Database connection setup
51  model/                 # Domain types
52    user.go
53    order.go
54  middleware/             # HTTP middleware
55    auth.go
56    logging.go
57    recovery.go
58pkg/                     # Public, reusable packages (if any)
59migrations/              # SQL migration files
60```
61 
62## Go Idioms
63 
64### Error Handling
65```go
66// Always handle errors explicitly. Never use _ for errors.
67user, err := s.store.GetUser(ctx, id)
68if err != nil {
69    if errors.Is(err, store.ErrNotFound) {
70        return nil, ErrUserNotFound
71    }
72    return nil, fmt.Errorf("get user %d: %w", id, err)
73}
74 
75// Define sentinel errors for expected conditions
76var (
77    ErrNotFound     = errors.New("not found")
78    ErrUnauthorized = errors.New("unauthorized")
79    ErrConflict     = errors.New("conflict")
80)
81 
82// Wrap errors with context using %w for unwrapping
83func (s *UserService) Delete(ctx context.Context, id int64) error {
84    if err := s.store.DeleteUser(ctx, id); err != nil {
85        return fmt.Errorf("delete user %d: %w", id, err)
86    }
87    return nil
88}
89```
90 
91### Interface Design
92```go
93// Define interfaces where they are USED, not where they are implemented.
94// Keep interfaces small — one or two methods.
95 
96// In handler package:
97type UserService interface {
98    GetUser(ctx context.Context, id int64) (*model.User, error)
99    CreateUser(ctx context.Context, input model.CreateUserInput) (*model.User, error)
100    ListUsers(ctx context.Context, opts model.ListOptions) ([]model.User, error)
101}
102 
103// In service package:
104type UserStore interface {
105    GetUser(ctx context.Context, id int64) (*model.User, error)
106    InsertUser(ctx context.Context, u *model.User) error
107    ListUsers(ctx context.Context, opts model.ListOptions) ([]model.User, int, error)
108}
109```
110 
111### HTTP Handler Pattern
112```go
113type UserHandler struct {
114    svc    UserService
115    logger *slog.Logger
116}
117 
118func NewUserHandler(svc UserService, logger *slog.Logger) *UserHandler {
119    return &UserHandler{svc: svc, logger: logger}
120}
121 
122func (h *UserHandler) HandleGetUser(w http.ResponseWriter, r *http.Request) {
123    id, err := strconv.ParseInt(r.PathValue("id"), 10, 64)
124    if err != nil {
125        writeError(w, http.StatusBadRequest, "invalid user ID")
126        return
127    }
128 
129    user, err := h.svc.GetUser(r.Context(), id)
130    if err != nil {
131        switch {
132        case errors.Is(err, service.ErrUserNotFound):
133            writeError(w, http.StatusNotFound, "user not found")
134        default:
135            h.logger.Error("get user", "error", err, "user_id", id)
136            writeError(w, http.StatusInternalServerError, "internal error")
137        }
138        return
139    }
140 
141    writeJSON(w, http.StatusOK, user)
142}
143 
144func writeJSON(w http.ResponseWriter, status int, v any) {
145    w.Header().Set("Content-Type", "application/json")
146    w.WriteHeader(status)
147    json.NewEncoder(w).Encode(v)
148}
149 
150func writeError(w http.ResponseWriter, status int, message string) {
151    writeJSON(w, status, map[string]string{"error": message})
152}
153```
154 
155### Middleware Pattern
156```go
157func LoggingMiddleware(logger *slog.Logger) func(http.Handler) http.Handler {
158    return func(next http.Handler) http.Handler {
159        return http.HandlerFunc(func(w http.ResponseWriter, r *http.Request) {
160            start := time.Now()
161            wrapped := &statusRecorder{ResponseWriter: w, status: http.StatusOK}
162            next.ServeHTTP(wrapped, r)
163            logger.Info("request",
164                "method", r.Method,
165                "path", r.URL.Path,
166                "status", wrapped.status,
167                "duration", time.Since(start),
168            )
169        })
170    }
171}
172```
173 
174## Concurrency
175- Use `context.Context` for cancellation and timeouts on all I/O operations
176- Prefer `sync.WaitGroup` and channels over raw goroutines
177- Use `errgroup.Group` for concurrent operations that can fail
178- Never start goroutines without a plan for shutdown
179- Use `sync.Once` for one-time initialization
180- Avoid goroutine leaks — always have a cancellation path
181 
182## Testing
183```go
184func TestUserService_GetUser(t *testing.T) {
185    tests := []struct {
186        name    string
187        id      int64
188        mock    func(*MockUserStore)
189        want    *model.User
190        wantErr error
191    }{
192        {
193            name: "existing user",
194            id:   1,
195            mock: func(s *MockUserStore) {
196                s.On("GetUser", mock.Anything, int64(1)).Return(&model.User{ID: 1, Name: "Alice"}, nil)
197            },
198            want: &model.User{ID: 1, Name: "Alice"},
199        },
200        {
201            name:    "user not found",
202            id:      999,
203            mock:    func(s *MockUserStore) { s.On("GetUser", mock.Anything, int64(999)).Return(nil, store.ErrNotFound) },
204            wantErr: service.ErrUserNotFound,
205        },
206    }
207 
208    for _, tt := range tests {
209        t.Run(tt.name, func(t *testing.T) {
210            store := new(MockUserStore)
211            tt.mock(store)
212            svc := service.NewUserService(store)
213            got, err := svc.GetUser(context.Background(), tt.id)
214            if tt.wantErr != nil {
215                assert.ErrorIs(t, err, tt.wantErr)
216                return
217            }
218            assert.NoError(t, err)
219            assert.Equal(t, tt.want, got)
220        })
221    }
222}
223```
224 
225## Performance Guidelines
226- Use `sync.Pool` for frequently allocated objects
227- Buffer channels when the producer/consumer rate is known
228- Use `strings.Builder` for string concatenation in loops
229- Profile with `pprof` before optimizing
230- Use connection pooling for database (pgx pool)
231- Set appropriate timeouts on HTTP server and clients
232- Use `json.Decoder` for streaming large JSON payloads
233 
234## Security
235- Validate all input at the handler layer
236- Use parameterized SQL queries (never concatenate user input)
237- Set timeouts on the HTTP server: `ReadTimeout`, `WriteTimeout`, `IdleTimeout`
238- Use TLS in production
239- Hash passwords with `golang.org/x/crypto/bcrypt`
240- Rate limit endpoints with middleware
241- Sanitize log output — never log passwords or tokens
242 
243## Common Pitfalls
244- Forgetting to check `err` — this is Go's most important convention
245- Not closing `resp.Body` after `http.Get` (use `defer resp.Body.Close()`)
246- Data races from sharing state between goroutines without synchronization
247- Using `json.Marshal` with unexported fields (they are silently omitted)
248- Nil pointer dereference — always check interface values and pointers
249- Forgetting to call `rows.Close()` in database queries (deferred or explicit)
250- Shadowing variables with `:=` in inner scopes
251- Using `time.Sleep` instead of proper synchronization
252