nextjs clean architecture

Arsitektur Bersih di Next.js

Repo ini adalah contoh cara mencapai arsitektur bersih di Next.js. Ada tutorial video yang melewati proyek ini. Klik gambar untuk memeriksanya di YouTube:

Anda dapat menjalankan proyek hanya dengan menjalankan npm install dan npm run dev .

Arsitektur bersih

Catatan

? Saya menggambar versi sederhana dari diagram arsitektur bersih asli ini. Saya menyederhanakannya dengan cara yang lebih masuk akal bagi saya, dan lebih mudah dipahami. Saya harap ini membantu Anda juga.

Saya sangat menyarankan Anda untuk membaca artikel asli oleh Paman Bob jika ini adalah pertama kalinya Anda mendengar tentang arsitektur bersih, tetapi saya akan mencoba meringkasnya untuk Anda di bawah ini.

Arsitektur yang bersih adalah seperangkat aturan yang membantu kami menyusun aplikasi kami sedemikian rupa sehingga lebih mudah dipelihara dan diuji, dan basis kode mereka dapat diprediksi. Ini seperti bahasa umum yang dipahami pengembang, terlepas dari latar belakang teknis dan preferensi bahasa pemrograman mereka.

Arsitektur bersih, dan arsitektur serupa/turunan, semuanya memiliki tujuan yang sama - pemisahan kekhawatiran . Mereka memperkenalkan lapisan yang menggabungkan kode serupa bersama -sama. "Layering" membantu kita mencapai aspek -aspek penting dalam basis kode kita:

• Independen dari UI - Logika bisnis tidak digabungkan dengan kerangka kerja UI yang digunakan (dalam hal ini Next.js). Sistem yang sama dapat digunakan dalam aplikasi CLI, tanpa harus mengubah logika atau aturan bisnis.
• Independen dari database - Implementasi/operasi basis data diisolasi di lapisan mereka sendiri, sehingga sisa aplikasi tidak peduli dengan database mana yang digunakan, tetapi berkomunikasi menggunakan model .
• Independen dari kerangka kerja - aturan bisnis dan logika tidak tahu apa -apa tentang dunia luar. Mereka menerima data yang ditentukan dengan JavaScript biasa, menggunakan JavaScript, layanan , dan repositori sederhana untuk menentukan logika dan fungsionalitas mereka sendiri. Ini memungkinkan kami untuk menggunakan kerangka kerja sebagai alat, alih -alih harus "membentuk" sistem kami ke dalam implementasi dan keterbatasan mereka. Jika kami menggunakan penangan rute di aplikasi kami, dan ingin refactor beberapa dari mereka ke tindakan server, yang perlu kami lakukan hanyalah memohon pengontrol spesifik dalam tindakan server alih -alih rute handler, tetapi logika bisnis inti tetap tidak berubah.
• Testable - Logika dan aturan bisnis dapat dengan mudah diuji karena tidak tergantung pada kerangka kerja UI, atau database, atau server web, atau elemen eksternal lainnya yang membangun sistem kami.

Arsitektur yang bersih mencapai hal ini melalui mendefinisikan hierarki ketergantungan - lapisan hanya bergantung pada lapisan di bawahnya , tetapi tidak di atas.

Struktur Proyek (hanya bit penting)

• app - Lapisan Kerangka & Pengemudi - Pada dasarnya semuanya selanjutnya.js (halaman, tindakan server, komponen, gaya dll ...) atau apa pun "mengkonsumsi" logika aplikasi
• di - Injeksi Ketergantungan - Folder tempat kami mengatur wadah DI dan modul
• drizzle - Semuanya DB - Menginisialisasi Klien DB, Menentukan Skema, Migrasi
• src - "root" sistem
  • application - Lapisan Aplikasi - Memegang Kasing dan Antarmuka Penggunaan untuk Repositori dan Layanan
  • entities - Entitas Lapisan - Memegang model dan kesalahan khusus
  • infrastructure - Lapisan Infrastruktur - Memegang implementasi repositori dan layanan, dan menarik antarmuka dari application
  • interface-adapters - Antarmuka Adapter Layer - Memegang pengontrol yang berfungsi sebagai titik masuk ke sistem (digunakan dalam Frameworks & Driver Layer untuk berinteraksi dengan sistem)
• tests - Tes Unit Langsung Di Sini - Struktur Subfolder unit cocok dengan src
• .eslintrc.json - di mana plugin eslint-plugin-boundaries didefinisikan - ini menghentikan Anda dari melanggar aturan ketergantungan
• vitest.config.ts - perhatikan bagaimana @ alias didefinisikan!

Penjelasan Lapisan

• Frameworks & Driver : Menyimpan semua fungsi kerangka kerja UI, dan segala sesuatu yang berinteraksi dengan sistem (ex. AWS Lambdas, Webhooks Stripe dll ...). Dalam skenario ini, itu penangan rute selanjutnya.js, tindakan server, komponen (server dan klien), halaman, sistem desain, dll ...
  • Lapisan ini seharusnya hanya menggunakan pengontrol , model , dan kesalahan , dan tidak boleh menggunakan kasus penggunaan , repositori , dan layanan .
• Adapter antarmuka : mendefinisikan pengontrol :
  • Pengontrol melakukan pemeriksaan otentikasi dan validasi input sebelum meneruskan input ke kasus penggunaan tertentu.
  • Pengontrol mengatur kasus penggunaan. Mereka tidak menerapkan logika apa pun, tetapi mendefinisikan seluruh operasi menggunakan kasus penggunaan.
  • Kesalahan dari lapisan yang lebih dalam digelembungkan dan ditangani di mana pengontrol digunakan.
  • Pengontrol menggunakan presenter untuk mengonversi data ke format ramah UI tepat sebelum mengembalikannya ke "konsumen". Ini membantu kami mengirimkan lebih sedikit javascript ke klien (logika dan perpustakaan untuk mengonversi data), membantu mencegah bocor setiap properti sensitif, seperti email atau kata sandi hash, dan juga membantu kami menurunkan jumlah data yang kami kirim kembali ke klien.
• Aplikasi : Di mana Logika Bisnis Hidup. Terkadang disebut inti . Lapisan ini mendefinisikan kasus penggunaan dan antarmuka untuk layanan dan repositori.
  • Gunakan kasus :
    • Mewakili operasi individu, seperti "Buat Todo" atau "Masuk" atau "Toggle Todo".
    • Terima input pra-divalidasi (dari pengontrol) dan menangani pemeriksaan otorisasi .
    • Gunakan repositori dan layanan untuk mengakses sumber data dan berkomunikasi dengan sistem eksternal.
    • Kasing penggunaan tidak boleh menggunakan kasus penggunaan lain . Itu bau kode. Ini berarti kasus penggunaan melakukan banyak hal dan harus dipecah menjadi beberapa kasus penggunaan.
  • Antarmuka untuk repositori dan layanan:
    • Ini didefinisikan dalam lapisan ini karena kami ingin mengeluarkan ketergantungan alat dan kerangka kerja mereka (driver basis data, layanan email dll ...), jadi kami akan mengimplementasikannya di lapisan infrastruktur .
    • Karena antarmuka hidup di lapisan ini, penggunaan kasus (dan secara transitif lapisan atas) dapat mengaksesnya melalui injeksi ketergantungan .
    • Injeksi ketergantungan memungkinkan kita untuk membagi definisi (antarmuka) dari implementasi (kelas) dan menyimpannya di lapisan (infrastruktur) yang terpisah, tetapi masih memungkinkan penggunaannya.
• Entitas : Di mana model dan kesalahan didefinisikan.
  • Model :
    • Tentukan bentuk data "domain" dengan javascript biasa, tanpa menggunakan teknologi "basis data".
    • Model tidak selalu terikat pada database - mengirim email memerlukan layanan email eksternal, bukan database, tetapi kami masih perlu memiliki bentuk data yang akan membantu lapisan lain berkomunikasi "mengirim email".
    • Model juga menentukan aturan validasi mereka sendiri, yang disebut "aturan bisnis perusahaan". Aturan yang biasanya tidak berubah, atau paling tidak mungkin berubah ketika sesuatu yang diubah eksternal (navigasi halaman, keamanan, dll ...). Contohnya adalah model User yang mendefinisikan bidang nama pengguna yang harus memiliki setidaknya 6 karakter dan tidak termasuk karakter khusus .
  • Kesalahan :
    • Kami menginginkan kesalahan kami sendiri karena kami tidak ingin menggelembungkan kesalahan khusus basis data, atau jenis kesalahan apa pun yang spesifik untuk perpustakaan atau kerangka kerja.
    • Kami catch kesalahan yang datang dari perpustakaan lain (misalnya gerimis), dan mengubah kesalahan itu menjadi kesalahan kami sendiri.
    • Begitulah cara kami dapat menjaga inti kami tetap independen dari kerangka kerja, perpustakaan, dan teknologi apa pun - salah satu aspek terpenting dari arsitektur bersih.
• Infrastruktur : Di mana repositori dan layanan sedang didefinisikan.
  • Lapisan ini menarik antarmuka repositori dan layanan dari lapisan aplikasi dan mengimplementasikannya di kelas mereka sendiri.
  • Repositori adalah cara kami mengimplementasikan operasi basis data. Mereka adalah kelas yang mengekspos metode yang melakukan operasi basis data tunggal - seperti getTodo , atau createTodo , atau updateTodo . Ini berarti bahwa kami hanya menggunakan pustaka / driver database di kelas -kelas ini. Mereka tidak melakukan validasi data apa pun, cukup jalankan kueri dan mutasi terhadap database dan baik melemparkan kesalahan yang ditentukan khusus atau hasil pengembalian.
  • Layanan adalah layanan bersama yang digunakan di seluruh aplikasi - seperti layanan otentikasi, atau layanan email, atau mengimplementasikan sistem eksternal seperti Stripe (buat pembayaran, validasi tanda terima dll ...). Layanan ini juga menggunakan dan bergantung pada kerangka kerja dan perpustakaan lainnya. Itu sebabnya implementasinya disimpan di sini bersama repositori.
  • Karena kami tidak ingin lapisan apa pun bergantung pada yang satu ini (dan secara transitif bergantung pada database dan semua layanan), kami menggunakan prinsip inversi ketergantungan . Ini memungkinkan kita untuk hanya bergantung pada antarmuka yang ditentukan dalam lapisan aplikasi , alih -alih implementasi di lapisan infrastruktur . Kami menggunakan inversi pustaka kontrol seperti ioctopus untuk mengabstraksikan implementasi di balik antarmuka dan "menyuntikkan" kapan pun kami membutuhkannya. Kami membuat abstraksi di direktori di . Kami "mengikat" repositori, layanan, pengontrol, dan menggunakan kasus untuk simbol, dan kami "menyelesaikan" mereka menggunakan simbol -simbol itu ketika kami membutuhkan implementasi yang sebenarnya. Begitulah cara kami dapat menggunakan implementasi, tanpa perlu secara eksplisit bergantung padanya (impor).

FAQ

Tip

Jika Anda memiliki pertanyaan yang tidak dicakup oleh FAQ, jangan ragu untuk membuka masalah dalam repo ini, atau bergabung dengan server Discord saya dan memulai percakapan di sana.

Apakah Arsitektur Bersih / Implementasi Ini Ramah Tanpa Server? Bisakah saya menggunakan ini ke Vercel?

Ya! Anda dapat menggunakannya dengan router halaman, router aplikasi, middleware, penangan API, tindakan server, apa pun! Biasanya, mencapai injeksi ketergantungan dalam proyek JavaScript sedang dilakukan dengan perpustakaan inversify.js, yang tidak sesuai dengan runtime lainnya kecuali node. Proyek ini mengimplementasikan Ioctopus, wadah IOC sederhana yang tidak bergantung pada reflect-metadata dan bekerja pada semua runtime.

Haruskah saya mulai menerapkan arsitektur bersih segera ketika saya membuat proyek berikutnya.js saya?

Saya akan mengatakan tidak . Jika Anda memulai proyek baru, saya menyarankan Anda untuk fokus untuk mencapai status MVP secepat mungkin (sehingga Anda dapat memvalidasi ide Anda / melihat apakah ada masa depan untuk proyek Anda). Ketika hal -hal mulai serius (lebih banyak fitur mulai diterapkan, basis pengguna Anda mengalami pertumbuhan yang signifikan, atau Anda sedang melakukan pengembang lain dalam proyek Anda), saat itulah Anda ingin menginvestasikan waktu untuk mengadaptasi arsitektur ini (atau arsitektur apa pun dalam hal ini).

Jika Anda sudah jauh di dalam gulma pada proyek, Anda (dan tim Anda) dapat merencanakan refactoring bertahap mulai dari sprint berikutnya. Dalam hal ini Anda sudah memiliki kode yang ditulis, Anda hanya perlu menata ulang sedikit, dan Anda dapat melakukan bagian berdasarkan bagian, route handler dengan rute handler, aksi server dengan tindakan server. Ngomong -ngomong, saya katakan dengan ringan "Anda hanya perlu menata ulang sedikit" , tetapi itu bisa jauh dari sesederhana itu. Selalu memperhitungkan "hal -hal yang salah" ketika Anda merencanakan refactoring. Dan luangkan waktu untuk menulis tes!

Ini terlihat seperti rekayasa berlebihan, dan mempersulit pengembangan fitur.

Jika Anda tidak menghabiskan lebih dari 3 menit untuk memikirkan hal ini, maka ya, itu memang terlihat seperti rekayasa berlebihan. Tetapi jika Anda melakukannya, Anda akan menyadari bahwa arsitektur = disiplin . Arsitekturnya adalah kontrak antara pengembang yang mendefinisikan apa yang pergi ke mana. Ini sebenarnya menyederhanakan pengembangan fitur karena membuat basis kode dapat diprediksi, dan itu membuat keputusan itu untuk Anda.

Anda tidak dapat menumbuhkan proyek secara berkelanjutan jika setiap pengembang yang mengerjakannya menulis kode di mana itu yang paling nyaman. Basis kode akan berubah menjadi mimpi buruk untuk dikerjakan, dan saat itulah Anda akan merasakan proses pengembangan fitur yang sangat rumit. Untuk melawan ini, akhirnya Anda akan meletakkan beberapa aturan. Aturan -aturan itu akan tumbuh saat tim Anda menghadapi dan memecahkan masalah baru. Masukkan semua aturan itu dalam dokumen, dan ada definisi arsitektur Anda sendiri. Anda masih menerapkan semacam arsitektur, Anda baru saja mencapai titik itu dengan sangat lambat dan menyakitkan.

Arsitektur yang bersih memberi Anda jalan pintas dan arsitektur yang telah ditentukan yang telah diuji. Dan ya, tentu saja, Anda perlu mempelajari semua ini, tetapi Anda melakukannya sekali di masa hidup Anda, dan kemudian cukup terapkan prinsip -prinsip dalam bahasa atau kerangka apa pun yang akan Anda gunakan di masa depan.

Haruskah saya menerapkan arsitektur bersih di semua proyek saya?

TIDAK . Tidak jika Anda tidak mengharapkan proyek tumbuh, baik dalam jumlah fitur, atau jumlah pengguna, atau jumlah pengembang yang mengerjakannya.

Apa arsitektur serupa lainnya dengan arsitektur bersih?

Seperti yang disebutkan dalam posting blog asli yang saya sebutkan di bagian atas readme, Anda dapat:

• Arsitektur Heksagonal (alias pelabuhan dan adaptor) oleh Alistair Cockburn
• Arsitektur Bawang oleh Jeffrey Palermo
• Screaming Architecture oleh Paman Bob (pria yang sama di balik arsitektur bersih)
• Dan beberapa lagi (lihat posting blog asli)