https://github.com/luismr/spring-commander
Spring Commander is a lightweight framework for implementing the Command-Query Separation (CQS) pattern in Java Spring Boot, powered by a clean Mediator architecture.
https://github.com/luismr/spring-commander
clean-architecture cqs framework java java-21 mediator spring-autoconfiguration spring-boot
Last synced: about 2 months ago
JSON representation
Spring Commander is a lightweight framework for implementing the Command-Query Separation (CQS) pattern in Java Spring Boot, powered by a clean Mediator architecture.
- Host: GitHub
- URL: https://github.com/luismr/spring-commander
- Owner: luismr
- License: mit
- Created: 2025-04-09T13:32:25.000Z (about 2 months ago)
- Default Branch: main
- Last Pushed: 2025-04-09T15:28:04.000Z (about 2 months ago)
- Last Synced: 2025-04-09T15:31:48.434Z (about 2 months ago)
- Topics: clean-architecture, cqs, framework, java, java-21, mediator, spring-autoconfiguration, spring-boot
- Language: Java
- Homepage:
- Size: 23.4 KB
- Stars: 0
- Watchers: 1
- Forks: 0
- Open Issues: 0
-
Metadata Files:
- Readme: README.md
- License: LICENSE.md
Awesome Lists containing this project
README
# Spring Commander 🍮
Spring Commander is a lightweight framework for implementing the Command-Query Separation (CQS) pattern in Java Spring Boot, powered by a clean Mediator architecture.
## Features
- Command-Query Separation (CQS) pattern implementation
- Clean Mediator architecture
- Spring Boot auto-configuration
- Type-safe command and query handling
- Easy integration with Spring Boot applications
- Comprehensive test coverage
- GitHub Actions CI/CD pipeline
## Build Status
[](https://github.com/luismr/spring-commander/actions/workflows/maven.yml)
## GitHub Actions Setup
To enable automatic updates of code coverage badges, you need to configure GitHub Actions permissions:
1. Go to your repository settings
2. Navigate to "Actions" → "General"
3. Under "Workflow permissions", select:
- "Read and write permissions"
- Check "Allow GitHub Actions to create and approve pull requests"
4. Save the changes
This will allow the GitHub Actions workflow to:
- Update code coverage badges
- Commit changes to the repository
- Create and update pull requests
## Getting Started
### Prerequisites
- Java 21
- Maven 3.6+
- Spring Boot 3.4.4+
### Installation
#### Using Git
```bash
git clone [email protected]:luismr/spring-commander.git
```
#### Using Maven
1. First, configure your GitHub token in `~/.m2/settings.xml`:
```xml
github
YOUR_GITHUB_USERNAME
YOUR_GITHUB_TOKEN
```
> **Note:** If you don't have a GitHub token, you can request one by contacting me on [X (@luismachadoreis)](https://x.com/luismachadoreis) or [BlueSky (@luismachadoreis.bsky.social)](https://bsky.app/profile/luismachadoreis.bsky.social).
2. Add the GitHub Packages repository to your `pom.xml`:
```xml
github
Spring Commander GitHub Packages
https://maven.pkg.github.com/luismr/spring-commander
```
3. Add the dependency to your `pom.xml`:
```xml
dev.luismachadoreis.blueprint
spring-commander
0.0.3
```
### Gradle
1. First, configure your GitHub token in `~/.gradle/gradle.properties`:
```properties
gpr.user=YOUR_GITHUB_USERNAME
gpr.key=YOUR_GITHUB_TOKEN
```
2. Add the GitHub Packages repository to your `build.gradle`:
```groovy
repositories {
maven {
name = "GitHubPackages"
url = uri("https://maven.pkg.github.com/luismr/spring-commander")
credentials {
username = project.findProperty("gpr.user") ?: System.getenv("GITHUB_USERNAME")
password = project.findProperty("gpr.key") ?: System.getenv("GITHUB_TOKEN")
}
}
}
```
3. Add the dependency to your `build.gradle`:
```groovy
implementation 'dev.luismachadoreis.blueprint:spring-commander:0.0.3'
```
## Usage
### Commands
1. Create a command:
```java
public class CreateUserCommand implements Command {
private final String username;
private final String email;
public CreateUserCommand(String username, String email) {
this.username = username;
this.email = email;
}
// Getters
}
```
2. Create a command handler:
```java
@Component
public class CreateUserCommandHandler implements CommandHandler {
@Override
public User handle(CreateUserCommand command) {
// Implementation
return new User(command.getUsername(), command.getEmail());
}
}
```
3. Use the mediator in your service:
```java
@Service
public class UserService {
private final SpringCommanderMediator mediator;
public UserService(SpringCommanderMediator mediator) {
this.mediator = mediator;
}
public User createUser(String username, String email) {
return mediator.send(new CreateUserCommand(username, email));
}
}
```
### Queries
1. Create a query:
```java
public class GetUserQuery implements Query {
private String username;
// Getters and setters
}
```
2. Create a query handler:
```java
@Component
public class GetUserQueryHandler implements QueryHandler {
@Override
public User handle(GetUserQuery query) {
// Implementation
}
}
```
### Using the Mediator
```java
@Autowired
private SpringMediator mediator;
public void example() {
// Send a command
User user = mediator.send(new CreateUserCommand("username", "[email protected]"));
// Send a query
User foundUser = mediator.send(new GetUserQuery("username"));
}
```
## Development
### Prerequisites
- Java 21 or later
- Maven 3.8 or later
- Git
### Building
```bash
git clone https://github.com/luismr/spring-commander-java.git
cd spring-commander-java
mvn clean install
```
### Testing
```bash
mvn test
```
### Code Coverage
Code coverage reports are generated automatically during the build process. You can find the reports in the `target/site/jacoco` directory.
## Contributing
1. Fork the repository
2. Create your feature branch (`git checkout -b feature/amazing-feature`)
3. Commit your changes (`git commit -m 'Add some amazing feature'`)
4. Push to the branch (`git push origin feature/amazing-feature`)
5. Open a Pull Request
## GitHub Actions
The project uses GitHub Actions for continuous integration and deployment. The workflow includes:
- Building and testing on multiple Java versions
- Code coverage reporting
- Automatic updates of code coverage badges
- Deployment to GitHub Packages
## Maven Release Process
### Prerequisites
1. Configure GitHub authentication in your Maven settings (`~/.m2/settings.xml`):
```xml
github
YOUR_GITHUB_USERNAME
YOUR_GITHUB_TOKEN
```
2. Create a GitHub Personal Access Token (PAT) with the following permissions:
- `read:packages`
- `write:packages`
- `delete:packages`
### Performing a Release
1. Prepare the release:
```bash
mvn release:prepare
```
This will:
- Update version numbers
- Create a Git tag
- Update the SCM information
2. Perform the release:
```bash
mvn release:perform
```
This will:
- Checkout the tagged version
- Build and deploy to GitHub Packages
- Create source and Javadoc JARs
### Version Management
- SNAPSHOT versions are deployed to GitHub Packages automatically on each push to main
- Release versions are created manually using the release process
- Version format follows semantic versioning (MAJOR.MINOR.PATCH)
## License
This project is licensed under the MIT License - see the [LICENSE.md](LICENSE.md) file for details.
## Author
- **Luis Machado Reis** - [luismr](https://github.com/luismr)
## Acknowledgments
- Spring Boot team for the amazing framework
- Martin Fowler for the CQS pattern
- All contributors and users of this project