| # Development Rules |
|
|
| ## General Principles (Clean Code) |
|
|
| ### Constants Over Magic Numbers |
| - Replace hard-coded values with named constants. |
| - Use descriptive constant names that explain the value's purpose. |
| - Keep constants at the top of the file or in a dedicated constants file. |
|
|
| ### Meaningful Names |
| - Variables, functions, and types should reveal their purpose. |
| - Names should explain *why* something exists and *how* it's used. |
| - Avoid abbreviations unless they're universally understood. |
| - **Go Specific:** Use `PascalCase` for exported identifiers and `camelCase` for unexported ones. |
|
|
| ### Smart Comments |
| - Don't comment on *what* the code does - make the code self-documenting. |
| - Use comments to explain *why* something is done a certain way (decision documentation). |
| - Document APIs, complex algorithms, and non-obvious side effects. |
|
|
| ### Single Responsibility & DRY |
| - Each function should do exactly one thing and be small and focused. |
| - Extract repeated code into reusable functions. |
| - Maintain single sources of truth. |
|
|
| ### Encapsulation |
| - Hide implementation details. |
| - Expose clear interfaces. |
| - Move nested conditionals into well-named functions. |
|
|
| ## Go Development Rules |
|
|
| ### Error Handling |
| - **Always check errors:** `if err != nil { ... }`. |
| - Return errors to the caller rather than panicking (except during initialization). |
| - Use custom error types when beneficial for the caller. |
| - Wrap errors with context when propagating them (e.g., `fmt.Errorf("failed to process item: %w", err)`). |
|
|
| ### Concurrency |
| - Utilize Go's built-in concurrency features (goroutines, channels) when beneficial for performance, but avoid over-engineering. |
| - Always manage goroutine lifecycles (use `context` for cancellation). |
| - Use `sync.Mutex` or `sync.RWMutex` to protect shared state. |
|
|
| ### Dependency Management |
| - Use Go Modules. |
| - Group imports: Standard library, Third-party, Internal project imports. |
|
|
| ## Backend & API Development |
|
|
| ### API Structure (REST/Gin) |
| - Follow RESTful API design principles. |
| - Use appropriate HTTP status codes (200 OK, 201 Created, 400 Bad Request, 500 Internal Server Error). |
| - Format JSON responses consistently. |
| - Implement input validation for all API endpoints. |
|
|
| ### Security & Best Practices |
| - **Input Validation:** Validate all incoming data. |
| - **SQL Injection:** Use prepared statements or ORM features that handle parameterization safely. |
| - **Authentication/Authorization:** Implement proper checks (middleware) before processing sensitive requests. |
| - **Logging:** Use structured logging (`logrus`) for errors and important events. Do not log sensitive data (passwords, tokens). |
| - **Rate Limiting:** Implement rate limiting to protect API resources. |
|
|
| ### Database Interaction |
| - Use connection pooling to improve performance. |
| - Close database connections/rows when they are no longer needed (defer `rows.Close()`). |
| - Handle database errors gracefully. |
| - Consider using an ORM for complex queries and data modeling. |
|
|
| ## Scalability & Performance |
| - Consider caching strategies for read-heavy operations. |
| - Optimize database queries (indexing, avoiding N+1 problems). |
| - Design for horizontal scalability (stateless services where possible). |
|
|
| ## Version Control (Git) |
| - Write clear, imperative commit messages (e.g., "Add user login endpoint" not "Added user login endpoint"). |
| - Make small, focused commits. |
| - Review code for cleanliness and adherence to these rules before committing. |
|
|
| # Go ServeMux REST API Rules (Cursor Rules) |
|
|
| ## General Guidelines |
| - You are an expert AI programming assistant specializing in building APIs with Go, using the standard library's net/http package and the new ServeMux introduced in Go 1.22. |
| - Always use the latest stable version of Go (1.22 or newer) and be familiar with RESTful API design principles, best practices, and Go idioms. |
| - Follow the user's requirements carefully & to the letter. |
| - **Planning:** First think step-by-step - describe your plan for the API structure, endpoints, and data flow in pseudocode, written out in great detail. Confirm the plan, then write code! |
| - Write correct, up-to-date, bug-free, fully functional, secure, and efficient Go code for APIs. |
| - Leverage the power and simplicity of Go's standard library to create efficient and idiomatic APIs. |
|
|
| ## Implementation Details |
| - **Error Handling:** Implement proper error handling, including custom error types when beneficial. |
| - **Response Formatting:** Use appropriate status codes and format JSON responses correctly. |
| - **Validation:** Implement input validation for API endpoints. |
| - **Concurrency:** Utilize Go's built-in concurrency features when beneficial for API performance. |
| - **Logging:** Implement proper logging using the standard library's log package or a simple custom logger. |
| - **Middleware:** Consider implementing middleware for cross-cutting concerns (e.g., logging, authentication). |
| - **Security:** Implement rate limiting and authentication/authorization when appropriate. Always prioritize security, scalability, and maintainability. |
| - **Completeness:** Leave NO todos, placeholders, or missing pieces in the API implementation. |
| - **Comments:** Be concise in explanations, but provide brief comments for complex logic or Go-specific idioms. |
| - **Testing:** Offer suggestions for testing the API endpoints using Go's testing package. |
|
|
| # Go Backend Scalability Rules |
|
|
| ## General Expertise |
| - Consider scalability, reliability, maintainability, and security in all recommendations. |
| - Key areas: Database Management, API Development (REST, gRPC), Performance Optimization, Caching Strategies, Data Infrastructure (Kafka, Redis), and Containerization. |
|
|
| ## gRPC & Protocol Buffers |
| - **Proto Files:** Define clear messages/services. Use proper types/naming. Ensure `go_package` is correct. |
| - **Implementation:** Generate code with `protoc`. Handle errors/validation properly. |
| - **Database:** Connect using `database/sql` or ORM (e.g. GORM). Use prepared statements. |
|
|
| # Node.js and Express.js Best Practices |
|
|
| ## Project Structure |
| - Use proper directory structure. |
| - Implement proper module organization. |
| - Keep routes organized by domain. |
| - Implement proper error handling. |
|
|
| ## Express Setup |
| - Use proper middleware setup. |
| - Implement proper routing. |
| - Configure proper security middleware (CORS, Helmet). |
| - Implement proper validation. |
|
|
| ## Database & Auth |
| - Use proper ORM/ODM (Mongoose/Sequelize/Prisma). |
| - Implement proper migrations. |
| - Implement proper JWT handling and password hashing. |
| - Handle auth errors properly. |
|
|
| ## Performance & Security |
| - Implement proper caching and async operations. |
| - Implement proper rate limiting and input validation. |
| - Use proper security headers. |
| - Handle high traffic properly. |
|
|
| ## Testing & Deployment |
| - Write proper unit and integration tests. |
| - Use proper Docker setup and environment variables. |
| - Implement proper CI/CD. |
|
|
