From 748d9a862d8d0514fe47e012e2589c72170748cf Mon Sep 17 00:00:00 2001 From: Tyr Chen Date: Sat, 31 May 2025 11:48:14 -0700 Subject: [PATCH] chore: update readme --- README.md | 290 ++++++++++++++++++++++++++++++++++++++++++++++++++++++ 1 file changed, 290 insertions(+) diff --git a/README.md b/README.md index e69de29..f321b8e 100644 --- a/README.md +++ b/README.md @@ -0,0 +1,290 @@ +# 🦀 Cursor Rust Rules + +> **Production-tested Rust coding standards and best practices for Cursor IDE** + +A comprehensive collection of Rust development rules designed for use with Cursor IDE, providing opinionated guidelines for building production-ready Rust applications with modern patterns and industry best practices. + +## ✨ Features + +- 🏗️ **Modern Architecture Patterns** - Domain-driven design, subsystem organization, and clean architecture +- 🌐 **Web Development Standards** - Axum web framework, OpenAPI integration, authentication patterns +- 🗄️ **Database Best Practices** - SQLx patterns, migrations, connection pooling, and repository patterns +- ⚡ **Async & Concurrency** - Tokio patterns, async/await best practices, and concurrent data structures +- 🛠️ **Utility Libraries** - JWT authentication, CLI development, HTTP clients, and more +- 📦 **Workspace Organization** - Multi-crate workspace structure with clear subsystem boundaries +- 🔍 **Code Quality** - Comprehensive linting, error handling, testing, and documentation standards + +## 🚀 Quick Start + +### 1. Clone the Repository + +```bash +git clone https://github.com/your-username/cursor-rust-rules.git +cd cursor-rust-rules +``` + +### 2. Set Up Cursor Rules + +Copy the rules to your Cursor configuration: + +```bash +# Create cursor rules directory if it doesn't exist +mkdir -p ~/.cursor/rules/rust + +# Copy all rules +cp -r .cursor/rules/rust/* ~/.cursor/rules/rust/ +``` + +### 3. Use in Your Rust Project + +In your Rust project, create or update `.cursorrules`: + +```yaml +# .cursorrules +rules: + - "@rust/main" # Core Rust standards + - "@rust/axum" # Web development with Axum + - "@rust/database" # Database patterns with SQLx + - "@rust/concurrency" # Async and concurrency patterns + - "@rust/utilities" # Utility libraries and CLI tools + - "@rust/workspace" # Multi-crate workspace organization +``` + +Or for specific features only: + +```yaml +# .cursorrules - Minimal web API setup +rules: + - "@rust/core/code-quality" + - "@rust/features/axum" + - "@rust/features/database" +``` + +## 📁 Project Structure + +``` +cursor-rust-rules/ +├── .cursor/rules/rust/ # Cursor rule definitions +│ ├── main.mdc # Main rule loader and feature detection +│ ├── core/ # Core standards +│ │ └── code-quality.mdc # Code quality and best practices +│ ├── features/ # Feature-specific rules +│ │ ├── axum.mdc # Web framework standards +│ │ ├── database.mdc # Database patterns +│ │ ├── concurrency.mdc # Async/concurrency patterns +│ │ ├── utilities.mdc # Utility libraries +│ │ ├── http-client.mdc # HTTP client patterns +│ │ └── tools-and-config.mdc # Development tools +│ └── complex/ # Advanced patterns +│ └── workspace.mdc # Multi-crate workspace organization +└── README.md # This file +``` + +## 🎯 Rule Categories + +### Core Standards + +- **Code Quality** (`@rust/core/code-quality`) - Error handling, logging, testing, and code organization + +### Feature-Specific Rules + +- **Web Framework** (`@rust/features/axum`) - Axum 0.8+, OpenAPI, middleware, authentication +- **Database** (`@rust/features/database`) - SQLx patterns, migrations, connection pooling +- **Concurrency** (`@rust/features/concurrency`) - Tokio, async patterns, concurrent data structures +- **Utilities** (`@rust/features/utilities`) - JWT, CLI tools, builder patterns, validation +- **HTTP Client** (`@rust/features/http-client`) - Reqwest patterns, retry logic, authentication +- **Tools & Config** (`@rust/features/tools-and-config`) - Development tooling and configuration + +### Advanced Patterns + +- **Workspace** (`@rust/complex/workspace`) - Subsystem-based multi-crate organization + +## 🛠️ Usage Examples + +### Web API Development + +For building a web API with Axum: + +```rust +// Cargo.toml gets configured with these dependencies +[dependencies] +axum = { version = "0.8", features = ["macros", "multipart", "ws"] } +utoipa = { version = "5.0", features = ["axum_extras", "chrono", "uuid"] } +sqlx = { version = "0.8", features = ["runtime-tokio-rustls", "postgres"] } +tokio = { version = "1.45", features = ["macros", "rt-multi-thread"] } +``` + +Your project follows patterns like: + +```rust +// AppState with hot-reloadable config +#[derive(Clone)] +pub struct AppState { + pub config: Arc>, + pub db: PgPool, + pub http_client: reqwest::Client, +} + +// Route handlers with OpenAPI documentation +#[utoipa::path( + post, + path = "/api/v1/users", + request_body = CreateUserRequest, + responses( + (status = 201, description = "User created", body = User), + (status = 400, description = "Validation error", body = ApiError) + ), + tag = "users" +)] +pub async fn create_user( + State(state): State, + Json(request): Json, +) -> Result<(StatusCode, Json), ApiError> { + // Implementation follows validation and error handling patterns +} +``` + +### Database Integration + +For database operations with SQLx: + +```rust +// Repository patterns with proper error handling +#[async_trait] +pub trait UserRepository: Send + Sync { + async fn find_by_id(&self, id: UserId) -> Result, DatabaseError>; + async fn create(&self, user: CreateUserRequest) -> Result; + async fn update(&self, id: UserId, user: UpdateUserRequest) -> Result; +} + +// Migration and connection management +pub async fn setup_database(config: &DatabaseConfig) -> Result { + let pool = PgPoolOptions::new() + .max_connections(config.max_connections) + .connect(&config.url) + .await?; + + sqlx::migrate!("./migrations").run(&pool).await?; + Ok(pool) +} +``` + +### Multi-Crate Workspace + +For complex applications, organize as subsystems: + +``` +my-ecommerce-platform/ +├── shared/ # Cross-cutting infrastructure +│ ├── shared-types/ # Domain primitives +│ ├── shared-db/ # Database infrastructure +│ └── shared-events/ # Event definitions +├── subsystems/ # Business subsystems +│ ├── user-management/ # User & auth subsystem +│ ├── product-catalog/ # Product management +│ ├── order-management/ # Order processing +│ └── payment/ # Payment processing +└── services/ # Infrastructure services + ├── api-gateway/ # Unified API + └── admin-cli/ # Admin tools +``` + +## 🎮 Interactive Features + +The rules provide intelligent feature detection and suggestions: + +### Automatic Dependency Detection + +When you use certain patterns, Cursor will suggest appropriate dependencies: + +```rust +// Using async patterns triggers Tokio suggestions +async fn my_function() -> Result<(), Error> { + // Cursor suggests: Add tokio = "1.45" with appropriate features +} + +// Using database patterns triggers SQLx suggestions +sqlx::query!("SELECT * FROM users") + // Cursor suggests: Add sqlx with postgres features +``` + +### Smart Code Generation + +Rules include templates for common patterns: + +- **API Endpoints** - Complete handler with validation and OpenAPI docs +- **Database Repositories** - Repository trait and implementation +- **Error Types** - Structured error handling with proper HTTP status codes +- **Configuration** - Environment-based config with hot reload support + +## 📊 Rule Hierarchy + +Rules are loaded based on project complexity: + +1. **Simple Projects** - Core quality standards only +2. **Web APIs** - Core + Axum + Database rules +3. **Complex Systems** - All rules including workspace organization + +## 🔧 Customization + +### Override Specific Rules + +Create a local `.cursorrules` file to customize: + +```yaml +rules: + - "@rust/main" + +overrides: + # Use different web framework + web_framework: "warp" + + # Custom database configuration + database: + orm: "diesel" + features: ["mysql"] +``` + +### Add Project-Specific Rules + +Extend with your own patterns: + +```rust +// .cursor/rules/rust/project/custom.mdc +// Your project-specific patterns and standards +``` + +## 🤝 Contributing + +1. Fork the repository +2. Create a feature branch (`git checkout -b feature/amazing-rule`) +3. Add your rule with documentation and examples +4. Test with real projects +5. Submit a pull request + +### Rule Writing Guidelines + +- **Comprehensive Examples** - Show complete, working code +- **Production Patterns** - Based on real-world usage +- **Clear Documentation** - Explain why, not just what +- **Test Coverage** - Include testing patterns +- **Version Compatibility** - Specify crate versions + +## 📚 References + +- [Axum Documentation](https://docs.rs/axum/) +- [SQLx Documentation](https://docs.rs/sqlx/) +- [Tokio Documentation](https://docs.rs/tokio/) +- [Rust API Guidelines](https://rust-lang.github.io/api-guidelines/) + +## 📄 License + +MIT License - see LICENSE file for details. + +## 🚨 Disclaimer + +These rules represent opinionated best practices based on production experience. Adapt them to your specific project needs and constraints. + +--- + +**Happy Coding with Rust! 🦀**