refactor: streamline onboarding modal by removing unnecessary slide preparation logic and enhancing loading state management for improved user experience
This commit is contained in:
278
.cursor/rules/neo4j.mdc
Normal file
278
.cursor/rules/neo4j.mdc
Normal file
@@ -0,0 +1,278 @@
|
||||
---
|
||||
description: This rule provides guidelines for best practices and coding standards when developing applications with Neo4j. It covers aspects from code organization and performance to security and testing.
|
||||
globs: *.cypher
|
||||
---
|
||||
# Neo4j Development Best Practices
|
||||
|
||||
This document outlines best practices and coding standards for developing applications using Neo4j. These guidelines are designed to promote maintainability, performance, and security.
|
||||
|
||||
Library Information:
|
||||
- Name: neo4j
|
||||
- Tags: database, graph, nosql, relationships
|
||||
|
||||
## 1. Code Organization and Structure
|
||||
|
||||
### 1.1 Directory Structure
|
||||
|
||||
Organize your project with a clear directory structure that separates concerns. A recommended structure is as follows:
|
||||
|
||||
|
||||
project_root/
|
||||
├── data/ # Contains data files for import/export
|
||||
├── queries/ # Stores Cypher queries
|
||||
├── src/ # Source code for the application
|
||||
│ ├── models/ # Defines data models and graph schemas
|
||||
│ ├── services/ # Contains business logic and Neo4j interactions
|
||||
│ ├── utils/ # Utility functions and helper classes
|
||||
│ ├── config/ # Configuration files
|
||||
│ └── app.js # Main application file
|
||||
├── tests/ # Unit, integration, and end-to-end tests
|
||||
├── .env # Environment variables
|
||||
├── package.json # Node.js project configuration
|
||||
├── requirements.txt # Python project dependencies
|
||||
└── README.md
|
||||
|
||||
|
||||
### 1.2 File Naming Conventions
|
||||
|
||||
* **Cypher Queries:** Use descriptive names (e.g., `get_user_friends.cypher`).
|
||||
* **Models:** Name files according to the entity they represent (e.g., `user.js`, `movie.py`).
|
||||
* **Services:** Use a service-based naming convention (e.g., `user_service.js`, `movie_service.py`).
|
||||
* **Tests:** Match test file names to the source file names (e.g., `user_service.test.js`).
|
||||
|
||||
### 1.3 Module Organization
|
||||
|
||||
Break down your application into modules based on functionality. Use well-defined interfaces and avoid circular dependencies.
|
||||
|
||||
* **Node.js:** Use ES modules (`import`, `export`) or CommonJS (`require`, `module.exports`).
|
||||
* **Python:** Utilize packages and modules for organizing code.
|
||||
|
||||
### 1.4 Component Architecture
|
||||
|
||||
Design a component architecture that promotes reusability and maintainability. Consider using patterns like Model-View-Controller (MVC) or a layered architecture.
|
||||
|
||||
* **Models:** Define data structures and interact with the Neo4j database.
|
||||
* **Services:** Implement business logic and handle data manipulation.
|
||||
* **Controllers (or equivalent):** Handle user requests and orchestrate interactions between models and services.
|
||||
|
||||
### 1.5 Code Splitting
|
||||
|
||||
For large applications, use code splitting to improve initial load times. Load modules and components on demand when they are needed.
|
||||
|
||||
* **Node.js:** Use dynamic imports (`import()`) for on-demand loading.
|
||||
* **Frontend Frameworks (if applicable):** Use framework-specific code-splitting techniques (e.g., React.lazy, Vue.js's async components).
|
||||
|
||||
## 2. Common Patterns and Anti-patterns
|
||||
|
||||
### 2.1 Design Patterns
|
||||
|
||||
* **Repository Pattern:** Abstract data access logic behind a repository interface. This makes it easier to switch database implementations or mock data access for testing.
|
||||
* **Unit of Work:** Group multiple database operations into a single transaction to ensure atomicity.
|
||||
* **Data Mapper:** Transfer data between domain objects and the database.
|
||||
* **Graph Traversal Pattern:** Encapsulate common graph traversal logic into reusable functions or classes.
|
||||
|
||||
### 2.2 Recommended Approaches for Common Tasks
|
||||
|
||||
* **Creating Nodes and Relationships:** Use Cypher queries with parameters to avoid SQL injection and improve performance.
|
||||
* **Querying Data:** Use Cypher's `MATCH` clause for efficient graph traversal. Leverage indexes and constraints for optimal query performance.
|
||||
* **Data Validation:** Validate data before inserting it into the database. Use constraints to enforce data integrity at the database level.
|
||||
* **Error Handling:** Implement robust error handling to gracefully handle database errors and prevent application crashes.
|
||||
|
||||
### 2.3 Anti-patterns and Code Smells
|
||||
|
||||
* **Over-fetching Data:** Avoid retrieving unnecessary data from the database. Use projections in Cypher queries to select only the required properties.
|
||||
* **Long Cypher Queries:** Break down complex Cypher queries into smaller, more manageable queries.
|
||||
* **Lack of Indexing:** Ensure that frequently queried properties are indexed to improve query performance.
|
||||
* **Ignoring Constraints:** Define and enforce constraints to maintain data integrity and consistency.
|
||||
* **Hardcoding Values:** Avoid hardcoding values in Cypher queries. Use parameters instead.
|
||||
* **Excessive Relationship Traversal in Application Code:** Prefer to execute complex relationship traversals within Cypher rather than in application code which reduces the amount of data transported and is significantly faster.
|
||||
|
||||
### 2.4 State Management
|
||||
|
||||
* **Stateless Services:** Design services to be stateless to improve scalability and testability.
|
||||
* **Session Management:** Use appropriate session management techniques for web applications.
|
||||
* **Caching:** Implement caching to reduce database load and improve response times.
|
||||
|
||||
### 2.5 Error Handling
|
||||
|
||||
* **Centralized Error Handling:** Implement a centralized error handling mechanism to handle exceptions consistently.
|
||||
* **Logging:** Log errors and warnings to help with debugging and monitoring.
|
||||
* **Retry Logic:** Implement retry logic for transient database errors.
|
||||
* **Custom Exceptions:** Define custom exceptions for specific error conditions.
|
||||
* **Graceful Degradation:** Design the application to degrade gracefully in case of database failures.
|
||||
|
||||
## 3. Performance Considerations
|
||||
|
||||
### 3.1 Optimization Techniques
|
||||
|
||||
* **Indexing:** Create indexes on frequently queried properties.
|
||||
* **Constraints:** Use constraints to enforce data integrity and improve query performance.
|
||||
* **Query Optimization:** Analyze Cypher query execution plans and optimize queries for performance.
|
||||
* **Connection Pooling:** Use connection pooling to reuse database connections and reduce connection overhead.
|
||||
* **Batch Operations:** Use batch operations to insert or update multiple nodes and relationships in a single transaction.
|
||||
* **Profile Queries:** Use `PROFILE` or `EXPLAIN` to understand query performance.
|
||||
* **Use `apoc.periodic.iterate` for batch processing** When dealing with large datasets, `apoc.periodic.iterate` allows for batch processing and avoids exceeding memory limits.
|
||||
|
||||
### 3.2 Memory Management
|
||||
|
||||
* **Limit Result Set Size:** Use `LIMIT` in Cypher queries to restrict the number of returned results.
|
||||
* **Stream Data:** Stream data from the database to avoid loading large amounts of data into memory.
|
||||
* **Garbage Collection:** Monitor garbage collection and tune JVM settings for optimal performance (Java-based implementations).
|
||||
|
||||
### 3.3 Bundle Size Optimization
|
||||
|
||||
* **Tree shaking** remove unused code
|
||||
* **Minification:** Minify code to reduce bundle size.
|
||||
* **Compression:** Compress bundles to reduce transfer size.
|
||||
|
||||
### 3.4 Lazy Loading
|
||||
|
||||
* **On-Demand Loading:** Load data and components on demand when they are needed.
|
||||
* **Pagination:** Use pagination to load data in smaller chunks.
|
||||
|
||||
## 4. Security Best Practices
|
||||
|
||||
### 4.1 Common Vulnerabilities
|
||||
|
||||
* **Cypher Injection:** Prevent Cypher injection by using parameterized queries.
|
||||
* **Authentication Bypass:** Secure authentication mechanisms and avoid relying on client-side authentication.
|
||||
* **Data Exposure:** Protect sensitive data by encrypting it at rest and in transit.
|
||||
* **Authorization Flaws:** Implement robust authorization mechanisms to control access to resources.
|
||||
|
||||
### 4.2 Input Validation
|
||||
|
||||
* **Sanitize Inputs:** Sanitize user inputs to prevent Cross-Site Scripting (XSS) attacks.
|
||||
* **Validate Inputs:** Validate user inputs to ensure they conform to expected formats and values.
|
||||
* **Parameterize Queries:** Always use parameterized queries to prevent Cypher injection.
|
||||
|
||||
### 4.3 Authentication and Authorization
|
||||
|
||||
* **Secure Authentication:** Use strong authentication mechanisms such as OAuth 2.0 or JWT.
|
||||
* **Role-Based Access Control (RBAC):** Implement RBAC to control access to resources based on user roles.
|
||||
* **Least Privilege Principle:** Grant users only the minimum necessary permissions.
|
||||
* **Neo4j's built-in security:** Utilize Neo4j's built-in authentication and authorization mechanisms for database access.
|
||||
|
||||
### 4.4 Data Protection
|
||||
|
||||
* **Encryption at Rest:** Encrypt sensitive data at rest using Neo4j's encryption features or third-party encryption solutions.
|
||||
* **Encryption in Transit:** Use HTTPS to encrypt data in transit.
|
||||
* **Data Masking:** Mask sensitive data in logs and reports.
|
||||
* **Regular Backups:** Perform regular backups to protect against data loss.
|
||||
* **Database Auditing:** Enable database auditing to track access and modifications to data.
|
||||
* **Avoid Storing Sensitive Data:** Only store necessary sensitive data. Consider tokenization or anonymization where applicable.
|
||||
|
||||
### 4.5 Secure API Communication
|
||||
|
||||
* **HTTPS:** Use HTTPS for all API communication.
|
||||
* **API Keys:** Use API keys to authenticate API requests.
|
||||
* **Rate Limiting:** Implement rate limiting to prevent abuse.
|
||||
* **Input Validation:** Validate API requests to prevent malicious input.
|
||||
|
||||
## 5. Testing Approaches
|
||||
|
||||
### 5.1 Unit Testing
|
||||
|
||||
* **Test Individual Components:** Unit test individual components in isolation.
|
||||
* **Mock Dependencies:** Use mocking to isolate components from external dependencies.
|
||||
* **Test Edge Cases:** Test edge cases and boundary conditions.
|
||||
* **Test Data Validation** Unit tests should cover data validation logic.
|
||||
|
||||
### 5.2 Integration Testing
|
||||
|
||||
* **Test Interactions:** Test the interactions between different components.
|
||||
* **Test Database Interactions:** Test the interactions between the application and the Neo4j database.
|
||||
* **Use Test Databases:** Use separate test databases for integration tests.
|
||||
|
||||
### 5.3 End-to-End Testing
|
||||
|
||||
* **Test Full Workflows:** Test the complete end-to-end workflows of the application.
|
||||
* **Automate Tests:** Automate end-to-end tests to ensure consistent results.
|
||||
|
||||
### 5.4 Test Organization
|
||||
|
||||
* **Organize Tests:** Organize tests in a clear and logical manner.
|
||||
* **Use Test Suites:** Use test suites to group related tests together.
|
||||
* **Naming Convention:** Follow a clear naming convention for test files and test methods.
|
||||
|
||||
### 5.5 Mocking and Stubbing
|
||||
|
||||
* **Mock Neo4j Driver:** Mock the Neo4j driver to isolate components from the database.
|
||||
* **Stub Responses:** Stub database responses to control the data returned by the database.
|
||||
* **Verify Interactions:** Verify that components interact with the database as expected.
|
||||
|
||||
## 6. Common Pitfalls and Gotchas
|
||||
|
||||
### 6.1 Frequent Mistakes
|
||||
|
||||
* **Lack of Planning:** Failing to properly plan the graph schema and data model.
|
||||
* **Ignoring Performance:** Neglecting to optimize Cypher queries and database configuration.
|
||||
* **Poor Security:** Failing to implement proper security measures.
|
||||
* **Insufficient Testing:** Insufficient testing leading to bugs and regressions.
|
||||
* **Not Utilizing Indexes:** Neglecting to create indexes on frequently queried properties.
|
||||
|
||||
### 6.2 Edge Cases
|
||||
|
||||
* **Large Graphs:** Handling very large graphs with millions or billions of nodes and relationships.
|
||||
* **Concurrent Access:** Managing concurrent access to the database.
|
||||
* **Transaction Management:** Properly managing transactions to ensure data consistency.
|
||||
* **Handling Null Values:** Understanding how Neo4j handles null values and handling them appropriately.
|
||||
|
||||
### 6.3 Version-Specific Issues
|
||||
|
||||
* **API Changes:** Be aware of API changes between different versions of the Neo4j driver and database.
|
||||
* **Cypher Syntax:** Be aware of changes to the Cypher syntax in different versions of Neo4j.
|
||||
* **Deprecated Features:** Avoid using deprecated features.
|
||||
|
||||
### 6.4 Compatibility Concerns
|
||||
|
||||
* **Driver Compatibility:** Ensure that the Neo4j driver is compatible with the version of the Neo4j database.
|
||||
* **Operating System Compatibility:** Ensure that the application is compatible with the target operating system.
|
||||
* **Java Version Compatibility:** Ensure the Java version is compatible (if using Java-based drivers).
|
||||
|
||||
### 6.5 Debugging Strategies
|
||||
|
||||
* **Logging:** Use logging to track the execution of the application and identify errors.
|
||||
* **Debuggers:** Use debuggers to step through the code and inspect variables.
|
||||
* **Neo4j Browser:** Use the Neo4j Browser to visualize the graph and execute Cypher queries.
|
||||
* **Cypher Profiler:** Use the Cypher profiler to analyze the performance of Cypher queries.
|
||||
* **APOC Procedures:** Use APOC Procedures to aid with debugging and monitoring.
|
||||
|
||||
## 7. Tooling and Environment
|
||||
|
||||
### 7.1 Recommended Development Tools
|
||||
|
||||
* **Neo4j Browser:** A web-based interface for interacting with the Neo4j database.
|
||||
* **Neo4j Desktop:** A desktop application for managing Neo4j databases.
|
||||
* **IntelliJ IDEA/PyCharm:** IDEs with excellent support for Neo4j development.
|
||||
* **VS Code:** Popular code editor with Neo4j extensions.
|
||||
* **APOC Library:** Provides many helpful stored procedures.
|
||||
|
||||
### 7.2 Build Configuration
|
||||
|
||||
* **Dependency Management:** Use a dependency management tool (e.g., npm, pip) to manage project dependencies.
|
||||
* **Environment Variables:** Use environment variables to configure the application for different environments.
|
||||
* **Build Scripts:** Use build scripts to automate the build process.
|
||||
|
||||
### 7.3 Linting and Formatting
|
||||
|
||||
* **ESLint/Pylint:** Use linters to enforce coding standards and identify potential errors.
|
||||
* **Prettier/Black:** Use formatters to automatically format code.
|
||||
* **Consistent Style:** Maintain a consistent coding style throughout the project.
|
||||
|
||||
### 7.4 Deployment Best Practices
|
||||
|
||||
* **Containerization:** Use containerization (e.g., Docker) to package the application and its dependencies.
|
||||
* **Cloud Deployment:** Deploy the application to a cloud platform (e.g., AWS, Azure, GCP).
|
||||
* **Load Balancing:** Use load balancing to distribute traffic across multiple instances of the application.
|
||||
* **Monitoring:** Monitor the application to detect and respond to issues.
|
||||
* **Immutable Infrastructure:** Treat servers as immutable; rebuild instead of modifying.
|
||||
|
||||
### 7.5 CI/CD Integration
|
||||
|
||||
* **Automated Builds:** Automate the build process using a CI/CD pipeline.
|
||||
* **Automated Tests:** Run automated tests as part of the CI/CD pipeline.
|
||||
* **Automated Deployments:** Automate the deployment process using a CI/CD pipeline.
|
||||
* **Version Control:** Use version control (e.g., Git) to manage the codebase.
|
||||
* **Trunk-Based Development:** Consider trunk-based development for faster feedback cycles.
|
||||
|
||||
By following these best practices, developers can build robust, scalable, and secure Neo4j applications.
|
||||
Reference in New Issue
Block a user