144 lines
7.0 KiB
Markdown
144 lines
7.0 KiB
Markdown
# FastAPI Backend - TA Alumni
|
|
|
|
Repositori ini adalah bagian Backend dari proyek **TA-PROJEK**, yang dibangun menggunakan **FastAPI** dengan struktur folder yang mengadopsi pola **Clean Architecture** (mirip dengan arsitektur enterprise pada **Node.js** seperti Express/NestJS).
|
|
|
|
Struktur ini dibuat sangat terstruktur untuk memudahkan kolaborasi tim, terutama bagi developer junior, agar kode tetap rapi, mudah diuji, dan memiliki pemisahan tanggung jawab (Separation of Concerns) yang jelas.
|
|
|
|
---
|
|
|
|
## 📂 Struktur Folder & Fungsi
|
|
|
|
Berikut adalah penjelasan fungsi dari setiap folder di dalam `app/`:
|
|
|
|
```text
|
|
Backend/
|
|
├── .env # Variabel lingkungan aktif (lokal) - JANGAN di-commit ke Git!
|
|
├── .env.example # Template variabel lingkungan untuk anggota tim baru
|
|
├── requirements.txt # Daftar dependensi library Python
|
|
├── README.md # Dokumentasi panduan developer (file ini)
|
|
└── app/
|
|
├── main.py # Entry point utama aplikasi (mirip server.js atau app.js di Node.js)
|
|
│
|
|
├── config/ # Konfigurasi aplikasi & koneksi database
|
|
│ ├── config.py # Schema pembacaan & validasi file .env menggunakan Pydantic Settings
|
|
│ └── database.py # Setup engine SQLAlchemy, Session, dan koneksi ke database
|
|
│
|
|
├── models/ # Definisi skema tabel Database (SQLAlchemy Models)
|
|
│ ├── base.py # Base class SQLAlchemy yang membagikan metadata tabel
|
|
│ ├── user.py # Model untuk tabel 'users'
|
|
│ └── alumni.py # Model untuk tabel 'alumni'
|
|
│
|
|
├── schemas/ # Data Transfer Object (DTO) / Validasi Request & Response (Pydantic)
|
|
│ ├── user.py # Validasi input/output data User
|
|
│ └── alumni.py # Validasi input/output data Alumni
|
|
│
|
|
├── repositories/ # Layer akses database (Data Access Object / DAO)
|
|
│ ├── base.py # Generic Repository yang berisi fungsi CRUD dasar (Get, Create, Update, Delete)
|
|
│ └── alumni.py # Operasi database spesifik untuk entitas Alumni
|
|
│
|
|
├── services/ # Layer Logika Bisnis (Business Logic)
|
|
│ ├── auth.py # Logika registrasi, verifikasi password, login, dan pembuatan token JWT
|
|
│ └── alumni.py # Logika bisnis seputar validasi dan pengolahan data alumni
|
|
│
|
|
├── controllers/ # Pengendali HTTP (Request & Response handler)
|
|
│ ├── auth.py # Menangani input request auth, memanggil auth service, mengembalikan HTTP response
|
|
│ └── alumni.py # Menangani input request alumni, memanggil alumni service, mengembalikan HTTP response
|
|
│
|
|
├── routers/ # Pendefinisian Endpoint / Route API (sama seperti routes/ di Node.js)
|
|
│ ├── api.py # Central router registry (menggabungkan semua router dengan prefix API)
|
|
│ ├── auth.py # Endpoint untuk registrasi dan login (/api/v1/auth)
|
|
│ └── alumni.py # Endpoint untuk CRUD data alumni (/api/v1/alumni)
|
|
│
|
|
├── middleware/ # Fungsi penengah/filter request (seperti Auth Guards)
|
|
│ └── auth_middleware.py # Dependency injection untuk proteksi route menggunakan token JWT
|
|
│
|
|
└── utils/ # Helper fungsi utilitas umum
|
|
├── security.py # Fungsi enkripsi/hashing password dan generator JWT
|
|
└── helpers.py # Utilitas pembantu lainnya
|
|
```
|
|
|
|
---
|
|
|
|
## 🔄 Aliran Data (Data Flow)
|
|
|
|
Saat aplikasi menerima request dari frontend, aliran datanya adalah sebagai berikut:
|
|
|
|
```mermaid
|
|
graph TD
|
|
Client[Klien/Frontend] -->|1. Kirim HTTP Request| Router[Routers]
|
|
Router -->|2. Validasi dengan Pydantic| Schema[Schemas]
|
|
Router -->|3. Teruskan parameter| Controller[Controllers]
|
|
Controller -->|4. Panggil logika bisnis| Service[Services]
|
|
Service -->|5. Minta operasi DB| Repository[Repositories]
|
|
Repository -->|6. Manipulasi data| Model[Models/Database]
|
|
Model -->|7. Kembalikan data| Repository
|
|
Repository -->|8. Kembalikan entitas| Service
|
|
Service -->|9. Kembalikan hasil proses| Controller
|
|
Controller -->|10. Format Output & Status Code| Router
|
|
Router -->|11. Kirim HTTP Response| Client
|
|
```
|
|
|
|
1. **Routers** (`app/routers/`): Menerima HTTP Request, mencocokkan path, menerapkan proteksi middleware jika perlu, dan memvalidasi tipe data input menggunakan **Schemas** (Pydantic).
|
|
2. **Controllers** (`app/controllers/`): Mengambil data dari request yang sudah tervalidasi, mengelola status code HTTP, dan memanggil **Services**.
|
|
3. **Services** (`app/services/`): Tempat utama menulis logika bisnis (seperti verifikasi aturan bisnis, perhitungan, integrasi AI/ML, enkripsi password). Memanggil **Repositories**.
|
|
4. **Repositories** (`app/repositories/`): Melakukan operasi database langsung menggunakan **Models** (SQLAlchemy). Layer ini memisahkan logika kueri SQL/ORM dari logika bisnis.
|
|
|
|
---
|
|
|
|
## 🛠️ Cara Memulai & Menjalankan Proyek
|
|
|
|
Langkah-langkah berikut ditujukan untuk developer junior agar dapat menjalankan backend di lokal dengan cepat:
|
|
|
|
### 1. Buat Virtual Environment
|
|
Buka terminal di folder `Backend/` dan jalankan perintah berikut:
|
|
|
|
**Windows (PowerShell):**
|
|
```powershell
|
|
python -m venv venv
|
|
.\venv\Scripts\Activate
|
|
```
|
|
|
|
**Linux/macOS:**
|
|
```bash
|
|
python3 -m venv venv
|
|
source venv/bin/activate
|
|
```
|
|
|
|
### 2. Install Dependensi
|
|
```bash
|
|
pip install -r requirements.txt
|
|
```
|
|
|
|
### 3. Konfigurasi Environment File
|
|
Secara default, file `.env` sudah dikonfigurasi menggunakan database SQLite lokal bernama `ta_database.db`. Anda tidak perlu menginstal database server tambahan untuk memulai development.
|
|
|
|
### 4. Jalankan Aplikasi
|
|
Jalankan development server menggunakan Uvicorn:
|
|
```bash
|
|
uvicorn app.main:app --reload
|
|
```
|
|
Aplikasi akan berjalan di alamat `http://127.0.0.1:8000`.
|
|
|
|
### 5. Akses Dokumentasi Swagger API
|
|
Buka browser dan arahkan ke alamat berikut untuk melihat & menguji API secara interaktif:
|
|
👉 **`http://127.0.0.1:8000/docs`**
|
|
|
|
---
|
|
|
|
## 📝 Panduan Menambahkan Fitur Baru (Untuk Junior Team)
|
|
|
|
Jika Anda ingin menambahkan modul/fitur baru (misalnya fitur **Dosen**):
|
|
|
|
1. **Buat Model Database**:
|
|
Buat file `app/models/dosen.py` yang mendefinisikan skema tabel database. Registrasikan ke database engine jika diperlukan.
|
|
2. **Buat Pydantic Schema**:
|
|
Buat file `app/schemas/dosen.py` untuk validasi data request masuk (`DosenCreate`, `DosenUpdate`) dan data response keluar (`DosenResponse`).
|
|
3. **Buat Repository**:
|
|
Buat file `app/repositories/dosen.py`. Warisi dari `BaseRepository` untuk mendapatkan fitur CRUD bawaan secara instan.
|
|
4. **Buat Service**:
|
|
Buat file `app/services/dosen.py` untuk mengolah logika bisnis Dosen.
|
|
5. **Buat Controller**:
|
|
Buat file `app/controllers/dosen.py` untuk memetakan request ke service dan menyusun output response.
|
|
6. **Buat & Daftarkan Router**:
|
|
Buat file `app/routers/dosen.py`. Daftarkan file router ini ke dalam file registry utama di `app/routers/api.py`.
|