Axum API - Project Documentation

Overview

Proyek ini adalah backend API yang dibangun menggunakan:

• Rust
• Axum 0.8
• Tokio
• Async/Await
• Modular Architecture
• Integration Test menggunakan axum-test

Struktur ini dirancang agar scalable, mudah dibaca, mudah di-maintain, dan siap untuk development jangka panjang.

---

Project Structure

src/
 ├── config/        # Konfigurasi aplikasi & environment
 ├── db/            # Database connection, pooling, migration
 ├── handlers/      # Controller (fungsi yg menangani request)
 ├── middleware/    # Custom middleware (auth, logging, rate-limit)
 ├── models/        # Struct data, schema, DTO
 ├── routes/        # Routing per modul
 ├── services/      # Business logic
 ├── utils/         # Helper kecil (hash, token, dll)
 ├── lib.rs         # App builder untuk testing
 └── main.rs        # Entry point API server
tests/
 └── *.rs           # Integration tests (axum-test)
.env                # Environment variables
Cargo.toml

---

Tujuan Struktur Folder

1. config/ — Konfigurasi Aplikasi

Berisi konfigurasi environment dan setup seperti PORT, database URL, dll.

2. db/ — Setup Database

Berisi:

• Koneksi database
• Pooling (sqlx atau ORM lain)
• Migration jika diperlukan

3. handlers/ — HTTP Handler

Tempat semua fungsi endpoint, misalnya get_user(), create_user(), dll.

Handler hanya menerima request & return response.

4. routes/ — Routing API

Tempat grouping endpoint-route per modul:

• /hello
• /users
• /auth
• dll.

5. services/ — Business Logic

Berisi logika:

• Validasi
• Query database
• Perhitungan
• Token generator

Handler → memanggil service. Handler tidak boleh berisi business logic.

6. models/ — Data Model

Berisi struct:

• DTO (Data Transfer Object)
• JSON Schema using serde
• ORM model (sqlx/sea-orm)

7. middleware/ — Middleware

Berisi custom middleware seperti:

• Authentication
• Logging
• Rate limiting
• Request validation

8. utils/ — Helper

Tempat function kecil reusable:

• generate_uuid()
• hash_password()
• date utils
• error helper

9. lib.rs — App Builder

File ini menggabungkan semua router & component supaya bisa digunakan oleh:

• main.rs
• integration tests

10. main.rs — Entry Point

Menjalankan server:

• Membaca config
• Membuat listener
• Menjalankan Axum server
• Mendaftarkan router

11. tests/ — Integration Test (axum-test)

Semua test API berada di sini.

---

Menjalankan Integration Test

Jalankan:

cargo test

Untuk mencetak output test:

cargo test -- --nocapture

---

Development Workflow

Jalankan server (auto reload)

Gunakan cargo-watch:

cargo watch -q -c -x run

Jalankan test otomatis saat ada perubahan

cargo watch -q -c -w tests/ -x "test -- --nocapture"

---

Aturan Kode (Coding Rules)

• Handler hanya untuk request/response

• Tidak boleh ada business logic di dalam handler.

• Semua logic kompleks dipindah ke services/

• Semua query DB berada di db/ atau service layer

• Semua endpoint harus memiliki route di folder routes/

• Semua model data berada di models/

• Custom middleware wajib di folder middleware/

• Tidak boleh import handler antar modul

• Semua harus diekspor melalui router.

• Simpan utilitas kecil di folder utils/

---

Dependensi Utama

axum = "0.8"
tokio = { version = "1", features = ["full"] }
axum-test = "18"
serde = { version = "1.0", features = ["derive"] }

---

Menjalankan Server

cargo run

---

Contoh Menambah Modul Baru

Misal membuat /users endpoint:

1. Buat file:

src/handlers/users_handler.rs
src/routes/users.rs
src/services/users_service.rs
src/models/users.rs

2. Tambah router di src/routes/mod.rs:

pub mod users;

pub fn create_routes() -> Router {
    Router::new()
        .nest("/users", users::routes())
}

3. Tambah test di:

tests/users_test.rs

---

Kontribusi

Semua PR wajib:

• Mengikuti struktur folder
• Membuat test untuk endpoint baru
• Tidak menambah logic di handler
• Semua perubahan environment harus dicatat di README

---

by: arbath@teknohole.com