{"id":16469411,"url":"https://github.com/kigawas/clean-axum","last_synced_at":"2025-07-27T13:17:04.147Z","repository":{"id":247163273,"uuid":"820466542","full_name":"kigawas/clean-axum","owner":"kigawas","description":"Axum scaffold with clean architecture","archived":false,"fork":false,"pushed_at":"2024-08-18T15:58:54.000Z","size":107,"stargazers_count":2,"open_issues_count":0,"forks_count":0,"subscribers_count":2,"default_branch":"main","last_synced_at":"2024-10-18T15:06:54.000Z","etag":null,"topics":["api","clean-architecture","rust","scaffold","web"],"latest_commit_sha":null,"homepage":"https://clean-axum.shuttleapp.rs/scalar","language":"Rust","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/kigawas.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":".github/FUNDING.yml","license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null},"funding":{"github":"kigawas"}},"created_at":"2024-06-26T14:19:28.000Z","updated_at":"2024-09-13T20:20:29.000Z","dependencies_parsed_at":"2024-08-16T19:03:52.685Z","dependency_job_id":null,"html_url":"https://github.com/kigawas/clean-axum","commit_stats":null,"previous_names":["kigawas/clean-axum"],"tags_count":0,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/kigawas%2Fclean-axum","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/kigawas%2Fclean-axum/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/kigawas%2Fclean-axum/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/kigawas%2Fclean-axum/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/kigawas","download_url":"https://codeload.github.com/kigawas/clean-axum/tar.gz/refs/heads/main","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":224197986,"owners_count":17271999,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["api","clean-architecture","rust","scaffold","web"],"created_at":"2024-10-11T12:07:21.204Z","updated_at":"2024-11-12T00:42:46.027Z","avatar_url":"https://github.com/kigawas.png","language":"Rust","funding_links":["https://github.com/sponsors/kigawas"],"categories":[],"sub_categories":[],"readme":"# clean-axum\n\nAxum scaffold with clean architecture.\n\nYou probably don't need [Rust on Rails](https://github.com/loco-rs/loco).\n\nRefer to [this post](https://kigawas.me/posts/rustacean-clean-architecture-approach/) for rationale and background.\n\n## Features\n\n- [Axum](https://github.com/tokio-rs/axum) framework\n- [SeaORM](https://github.com/SeaQL/sea-orm) domain models\n- Completely separated API routers and DB-related logic (named \"persistence\" layer)\n- Completely separated input parameters, queries and output schemas\n- OpenAPI documentation ([Swagger UI](https://clean-axum.shuttleapp.rs/docs) and [Scalar](https://clean-axum.shuttleapp.rs/scalar)) powered by [Utoipa](https://github.com/juhaku/utoipa)\n- Error handling with [Anyhow](https://github.com/dtolnay/anyhow)\n- Custom parameter validation with [validator](https://github.com/Keats/validator)\n- Optional [Shuttle](https://www.shuttle.rs/) runtime\n- Optional [prefork](https://docs.rs/prefork/latest/prefork/) workers for maximizing performance on Linux\n\n## Module hierarchy\n\n### API logic\n\n- `api::routers`: Axum endpoints\n- `api::error`: Models and traits for error handling\n- `api::extractor` Custom Axum extractors\n  - `api::extractor::json`: `Json` for bodies and responses\n  - `api::extractor::valid`: `Valid` for JSON body validation\n- `api::validation`: JSON validation model based on `validator`\n- `api::models`: Non domain model API models\n  - `api::models::response`: JSON error response\n\n### OpenAPI documentation\n\n- `doc`: Utoipa doc declaration\n\n### API-agonistic application logic\n\nMain concept: Web framework is replaceable.\n\nAll modules here should not include any specific API web framework logic.\n\n- `app::persistence`: DB manipulation (CRUD) functions\n- `app::config`: DB or API server configuration\n- `app::state`: APP state, e.g. DB connection\n- `app::error`: APP errors used by `api::error`. e.g. \"User not found\"\n\n### DB/API-agnostic domain models\n\nMain concept: Database (Sqlite/MySQL/PostgreSQL) is replaceable.\n\nExcept `models::domains` and `migration`, all modules are ORM library agnostic.\n\n- `models::domains`: SeaORM domain models\n- `models::params`: Serde input parameters for creating/updating domain models in DB\n- `models::schemas`: Serde output schemas for combining different domain models\n- `models::queries`: Serde queries for filtering domain models\n- `migration`: SeaORM migration files\n\n### Unit and integration tests\n\n- `tests::api`: API integration tests. Hierarchy is the same as `api::routers`\n- `tests::app::persistence`: DB/ORM-related unit tests. Hierarchy is the same as `app::persistence`\n\n### Others\n\n- `utils`: Utility functions\n- `main`: Tokio and Shuttle conditional entry point\n\n## Run\n\n### Start server\n\n```bash\ncp .env.example .env\n# touch dev.db\n# cargo install sea-orm-cli\n# sea-orm-cli migrate up\ncargo run\n\n# or for production\ncargo run --release\n```\n\n### Call API\n\n```bash\ncurl -X POST http://localhost:3000/users -H \"Content-Type: application/json\" -d '{\"username\":\"aaa\"}'\ncurl -X POST http://localhost:3000/users -H \"Content-Type: application/json\" -d '{\"username\":\"abc\"}'\ncurl http://localhost:3000/users\\?username\\=a\n```\n\n### OpenAPI doc (Swagger UI/Scalar)\n\n```bash\nopen http://localhost:3000/docs\nopen http://localhost:3000/scalar\n```\n\n## Start Shuttle local server\n\n```bash\n# cargo install cargo-shuttle\ncargo shuttle run\n```\n\nMake sure docker engine is running, otherwise:\n\n```bash\nbrew install colima docker\ncolima start\nsudo ln -sf $HOME/.colima/default/docker.sock /var/run/docker.sock\n```\n\n## Shuttle deployment\n\n```bash\ncargo shuttle login\ncargo shuttle deploy\n```\n\n## Benchmark\n\n```bash\n# edit .env to use Postgres\ncargo run --release\nwrk --latency -t20 -c50 -d10s http://localhost:3000/users\\?username\\=\n```\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fkigawas%2Fclean-axum","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fkigawas%2Fclean-axum","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fkigawas%2Fclean-axum/lists"}