CleanApi

🌟 English | 🌏 中文

This is a template for an API using a streamlined verison of Clean Architecture alongside .NET's Minimal APIs.

Prerequisites

• .NET 9 SDK - [required] This solution in built on it, you need to install it before building and running.

• Docker - [optional] If you want to build the Dockerfile you will need to install it.

• Docker-Compose - [optional] If you want to launch this solution quickly via the docker-compose.yml you will need to install it.

Installation

This is a .NET template and you can install it using the dotnet new cli.

Option 1: Install from NuGet (Recommended)

dotnet new install CleanApi.Solution.Template

Option 2: Install from source

# 1. clone this repository
git clone https://github.com/larymao/CleanApi.git cleanapi

# 2. navigate to the repository root
cd cleanapi

# 3. install the template
dotnet new install .

Usage

To scaffold a new solution with this template, execute one of the following commands:

# new solution with git initialized
dotnet new cleanapi --allow-scripts yes --name {YOUR_SOLUTION_NAMESPACE}

# new solution without git
dotnet new cleanapi --git false --name {YOUR_SOLUTION_NAMESPACE}

And then you could modify contents of docker-compose.yml, src/Web/Dockerfile and src/Web/Configs/*.json to suit your own business. Things you may wanna to modify are as follows:

• postgres configs in docker-compose.yml
• postgres connection string in config files
• dockerfile labels

Scripts

This template comes with several built-in commands to help you manage your project. You can run these commands using make:

# Restore project dependencies
make restore

# Build the project
make build

# Run all tests
make test

# Clean build outputs and test results
make clean

# Publish the application
make publish

# Run the application with watch mode (hot reload)
make watch

# Run the application
make run

# Add a new database migration
make migration name=YourMigrationName

These commands are designed to work consistently across Windows (WSL), macOS, and Linux environments. Before using them, make sure you have the following prerequisites:

• GNU Make installed
• .NET SDK installed
• Entity Framework Core tools installed (dotnet tool install --global dotnet-ef)

Database

This template is designed to work exclusively with PostgreSQL. The database integration offers several automated features:

• Auto Database Creation: The database is automatically created on first run if it doesn't exist
• Auto Migration: All pending migrations are automatically applied during application startup
• Code-First Approach: Uses Entity Framework Core's code-first pattern for database schema management

When you need to make changes to your database schema, you can create a new migration using the provided script:

make migration name=YourMigrationName

AI Assistant Integration

This template comes with pre-configured AI assistant instructions optimized for Cursor and GitHub Copilot. The default configuration sets English as the primary communication language and follows .NET development best practices.

To change the communication language to Chinese, locate the AI config file and modify the Code and Communication Standards section:

## Code and Communication Standards
- Code Writing Standards: All code elements must strictly use English to ensure international compatibility and maintainability of the code.
- Communication Language Requirements: All communication with users must be in Chinese, including explanations, suggestions, problem analysis, and technical discussions.
- Mixed Content Handling: When code snippets need to be referenced or displayed within Chinese responses, the code itself should still follow English writing standards, while code explanations and contextual descriptions should be in Chinese.

Uninstallation

To uninstall the template run the following command:

dotnet new uninstall CleanApi.Solution.Template

OR

If you installed this template from source code, enter the root directory of this repo, and run the following command:

dotnet new uninstall .

Features

There are plenty of handy implementations of features throughout this solution, in no particular order here are some that might interest you.

• Authentication using JWT Token
• Data Storage using Postgres
• Data accessing using EFCore with Code First Mode
• Object Mapping using Mapster
• Mediator Pattern using Mediator
• Validation using FluentValidation
• OpenApi using NSwag
• Logging using Serilog
• Testing using NUnit, Shouldly, Moq & Respawn