144 lines
2.8 KiB
Markdown
144 lines
2.8 KiB
Markdown
|
# phundrak.com Backend
|
||
|
|
|
||
|
|
The backend for [phundrak.com](https://phundrak.com), built with Rust and the [Poem](https://github.com/poem-web/poem) web framework.
|
||
|
|
|
||
|
|
## Features
|
||
|
|
|
||
|
|
- **RESTful API** with OpenAPI documentation
|
||
|
|
- **Type-safe routing** using Poem's declarative API
|
||
|
|
- **Structured logging** with `tracing`
|
||
|
|
- **Strict linting** for code quality and safety
|
||
|
|
- **Comprehensive testing** with integration test support
|
||
|
|
|
||
|
|
## Development
|
||
|
|
|
||
|
|
### Prerequisites
|
||
|
|
|
||
|
|
- Rust (latest stable version recommended)
|
||
|
|
- Cargo (comes with Rust)
|
||
|
|
|
||
|
|
### Running the Server
|
||
|
|
|
||
|
|
To start the development server:
|
||
|
|
|
||
|
|
```bash
|
||
|
|
cargo run
|
||
|
|
```
|
||
|
|
|
||
|
|
The server will start on the configured port (check your configuration for details).
|
||
|
|
|
||
|
|
### Building
|
||
|
|
|
||
|
|
For development builds:
|
||
|
|
|
||
|
|
```bash
|
||
|
|
cargo build
|
||
|
|
```
|
||
|
|
|
||
|
|
For optimized production builds:
|
||
|
|
|
||
|
|
```bash
|
||
|
|
cargo build --release
|
||
|
|
```
|
||
|
|
|
||
|
|
The compiled binary will be at `target/release/backend`.
|
||
|
|
|
||
|
|
## Testing
|
||
|
|
|
||
|
|
Run all tests:
|
||
|
|
|
||
|
|
```bash
|
||
|
|
cargo test
|
||
|
|
```
|
||
|
|
|
||
|
|
Run a specific test:
|
||
|
|
|
||
|
|
```bash
|
||
|
|
cargo test <test_name>
|
||
|
|
```
|
||
|
|
|
||
|
|
Run tests with output:
|
||
|
|
|
||
|
|
```bash
|
||
|
|
cargo test -- --nocapture
|
||
|
|
```
|
||
|
|
|
||
|
|
## Code Quality
|
||
|
|
|
||
|
|
### Linting
|
||
|
|
|
||
|
|
This project uses strict Clippy linting rules:
|
||
|
|
|
||
|
|
- `#![deny(clippy::all)]`
|
||
|
|
- `#![deny(clippy::pedantic)]`
|
||
|
|
- `#![deny(clippy::nursery)]`
|
||
|
|
|
||
|
|
Run Clippy to check for issues:
|
||
|
|
|
||
|
|
```bash
|
||
|
|
cargo clippy --all-targets
|
||
|
|
```
|
||
|
|
|
||
|
|
### Continuous Checking with Bacon
|
||
|
|
|
||
|
|
For continuous testing and linting during development, use [bacon](https://dystroy.org/bacon/):
|
||
|
|
|
||
|
|
```bash
|
||
|
|
bacon
|
||
|
|
```
|
||
|
|
|
||
|
|
This will watch your files and automatically run clippy or tests on changes.
|
||
|
|
|
||
|
|
## Code Style
|
||
|
|
|
||
|
|
### Error Handling
|
||
|
|
|
||
|
|
- Use `thiserror` for custom error types
|
||
|
|
- Always return `Result` types for fallible operations
|
||
|
|
- Use descriptive error messages
|
||
|
|
|
||
|
|
### Logging
|
||
|
|
|
||
|
|
- Use `tracing::event!` for logging
|
||
|
|
- Always set `target: "backend"`
|
||
|
|
- Use appropriate log levels (trace, debug, info, warn, error)
|
||
|
|
|
||
|
|
Example:
|
||
|
|
```rust
|
||
|
|
tracing::event!(target: "backend", tracing::Level::INFO, "Server started");
|
||
|
|
```
|
||
|
|
|
||
|
|
### Imports
|
||
|
|
|
||
|
|
Organize imports in three groups:
|
||
|
|
1. Standard library (`std::*`)
|
||
|
|
2. External crates
|
||
|
|
3. Local modules
|
||
|
|
|
||
|
|
Use explicit paths (e.g., `poem_openapi::ApiResponse` instead of wildcards).
|
||
|
|
|
||
|
|
### Testing
|
||
|
|
|
||
|
|
- Use `#[cfg(test)]` module blocks
|
||
|
|
- Leverage Poem's test utilities for endpoint testing
|
||
|
|
- Use random TCP listeners for integration tests to avoid port conflicts
|
||
|
|
|
||
|
|
## Project Structure
|
||
|
|
|
||
|
|
```
|
||
|
|
backend/
|
||
|
|
├── src/
|
||
|
|
│ ├── main.rs # Application entry point
|
||
|
|
│ ├── api/ # API endpoints
|
||
|
|
│ ├── models/ # Data models
|
||
|
|
│ ├── services/ # Business logic
|
||
|
|
│ └── utils/ # Utility functions
|
||
|
|
├── tests/ # Integration tests
|
||
|
|
├── Cargo.toml # Dependencies and metadata
|
||
|
|
└── README.md # This file
|
||
|
|
```
|
||
|
|
|
||
|
|
## License
|
||
|
|
|
||
|
|
See the root repository for license information.
|