101 lines
3.4 KiB
Markdown
101 lines
3.4 KiB
Markdown
# k-template
|
|
|
|
A production-ready, modular Rust template for K-Suite applications, following Hexagonal Architecture principles.
|
|
|
|
## 🌟 Features
|
|
|
|
- **Hexagonal Architecture**: Clear separation of concerns between Domain, Infrastructure, and API layers.
|
|
- **Modular & Swappable**: Vendor implementations (databases, message brokers) are behind feature flags and trait objects.
|
|
- **Feature-Gated Dependencies**: Compile only what you need. Unused dependencies are not included in the build.
|
|
- **Cargo Generate Ready**: Pre-configured for `cargo-generate` to easily scaffold new services.
|
|
- **Testable**: Domain logic is pure and easily testable; Infrastructure is tested with integration tests.
|
|
|
|
## 🏗️ Project Structure
|
|
|
|
The workspace consists of three main crates:
|
|
|
|
- **`template-domain`**: The core business logic.
|
|
- Contains Entities, Value Objects, Repository Interfaces (Ports), and Services.
|
|
- **Dependencies**: Pure Rust only (no I/O, no heavy frameworks).
|
|
|
|
- **`template-infra`**: The adapters layer.
|
|
- Implements the Repository interfaces defined in `template-domain`.
|
|
- Content is heavily feature-gated (e.g., `sqlite`, `postgres`, `broker-nats`).
|
|
|
|
- **`template-api`**: The application entry point (Driving Adapter).
|
|
- Wires everything together using dependency injection.
|
|
- Handles HTTP/REST/gRPC interfaces.
|
|
|
|
## 🚀 Getting Started
|
|
|
|
### Prerequisites
|
|
|
|
- Rust (latest stable)
|
|
- `cargo-generate` (`cargo install cargo-generate`)
|
|
|
|
### Creating a New Project
|
|
|
|
Use `cargo-generate` to scaffold a new project from this template:
|
|
|
|
```bash
|
|
cargo generate --git https://github.com/your-org/k-template.git
|
|
```
|
|
|
|
You will be prompted for:
|
|
1. **Project Name**: The name of your new service.
|
|
2. **Database**: Choose between `sqlite` (default) or `postgres`.
|
|
|
|
The template will automatically clean up unused repository implementations based on your choice.
|
|
|
|
### Running Tests
|
|
|
|
```bash
|
|
# Run all tests
|
|
cargo test
|
|
|
|
# Run tests for a specific feature (e.g., postgres)
|
|
cargo test -p template-infra --no-default-features --features postgres
|
|
```
|
|
|
|
## ⚙️ Configuration & Feature Flags
|
|
|
|
This template uses Cargo features to control compilation of infrastructure adapters.
|
|
|
|
| Feature | Description | Crate |
|
|
|---------|-------------|-------|
|
|
| `sqlite` | Enables SQLite repository implementations and dependencies | `template-infra`, `template-api` |
|
|
| `postgres` | Enables PostgreSQL repository implementations and dependencies | `template-infra`, `template-api` |
|
|
| `broker-nats`| Enables NATS messaging support | `template-infra` |
|
|
|
|
|
|
### Switching Databases
|
|
|
|
To switch from the default SQLite to PostgreSQL in an existing project, update `Cargo.toml`:
|
|
|
|
**`template-api/Cargo.toml`**:
|
|
```toml
|
|
[features]
|
|
default = ["postgres"]
|
|
# ...
|
|
```
|
|
|
|
**`template-infra/Cargo.toml`**:
|
|
```toml
|
|
[features]
|
|
default = ["postgres"]
|
|
# ...
|
|
```
|
|
|
|
## 📐 Architecture Guide
|
|
|
|
### Adding a New Feature
|
|
|
|
1. **Domain**: Define the Entity, Value Objects, and Repository Interface in `template-domain`.
|
|
2. **Infra**: Implement the Repository Interface in `template-infra`.
|
|
- **Important**: Wrap your implementation in a feature flag (e.g., `#[cfg(feature = "my-feature")]`).
|
|
3. **API**: Wire the new service in `template-api/src/main.rs` or a dedicated module.
|
|
|
|
### Vendor Isolation
|
|
|
|
All external dependencies (SQLx, NATS, etc.) should stay within `template-infra` or `template-api`. The `template-domain` crate should remain agnostic to specific technologies.
|