Git untuk Projek CFML: Kawalan Versi dan Deploy Lucee

Git untuk Projek CFML: Kawalan Versi dan Deploy Lucee

Git ialah sistem kawalan versi yang membolehkan anda menjejak perubahan kod CFML, bekerja dalam cawangan, dan deploy ke pelayan dengan cara yang boleh diulang. Namun projek CFML membawa kerumitan tersendiri kerana Lucee menjana folder konfigurasi dan data yang tidak sepatutnya masuk ke dalam repositori. Artikel ini menerangkan apa yang perlu dikecualikan, struktur .gitignore, aliran kerja cawangan, dan perangkap deploy yang biasa berlaku.

Apa yang Jangan Masuk Repo

Peraturan pertama dalam projek CFML ialah memahami apa yang dijana oleh enjin dan bukannya ditulis oleh anda. Lucee meletakkan fail konfigurasi dan data konteks web dalam folder bernama WEB-INF di dalam root web setiap laman. Folder ini dicipta secara automatik apabila Lucee dipanggil untuk menghidangkan fail .cfm atau .cfml. Kerana ia dijana semula dan mengandungi tetapan khusus mesin, ia tidak sepatutnya dikomit ke dalam Git.

Selain WEB-INF, beberapa jenis fail lain juga tidak patut masuk repo. Fail muat naik pengguna seperti gambar dan dokumen yang dimuat naik melalui aplikasi adalah data, bukan kod. Rahsia seperti kata laluan pangkalan data dan kunci API juga tidak boleh dikomit. Fail log dan fail sementara IDE pula hanya menambah bising kepada repositori tanpa nilai.

Struktur .gitignore untuk Projek CFML

Fail .gitignore menentukan fail yang sengaja tidak dijejak oleh Git. Penting untuk diingat bahawa fail yang sudah dijejak tidak terjejas oleh .gitignore, jadi jika anda sudah mengkomit sesuatu fail secara tidak sengaja, anda perlu mengeluarkannya dengan git rm --cached terlebih dahulu. Berikut struktur .gitignore yang munasabah untuk projek Lucee:

# Konfigurasi Lucee yang dijana automatik
/WEB-INF/

# Rahsia dan konfigurasi persekitaran
.env
/Application.secrets.cfm
/config/local/

# Fail muat naik pengguna
/uploads/
/assets/muat-naik/

# Log dan fail sementara
/logs/
*.log

# IDE dan sistem operasi
.idea/
.vscode/
.DS_Store
Thumbs.db

Letakkan fail .gitignore di root repositori supaya ia terpakai kepada keseluruhan projek. Sesuaikan laluan dengan struktur aplikasi anda sendiri, contohnya nama folder muat naik sebenar.

Konfigurasi Lucee dan Persekitaran

Konfigurasi Lucee terbahagi kepada konfigurasi pelayan dan konfigurasi aplikasi. Konfigurasi aplikasi seperti Application.cfc sememangnya sepatutnya dikomit kerana ia sebahagian daripada kod anda. Tetapi konfigurasi pelayan yang disimpan dalam WEB-INF adalah khusus mesin dan tidak boleh dikomit.

Lucee membenarkan anda memindahkan folder WEB-INF ke luar root web dengan menetapkan parameter lucee-web-directory dalam fail web.xml enjin servlet. Ini memisahkan data konteks web daripada kod aplikasi, menjadikan repositori lebih bersih. Untuk memahami perbezaan antara konfigurasi aplikasi dan pelayan, rujuk panduan memahami Application.cfc.

Rahsia dan Pemboleh Ubah Persekitaran

Rahsia tidak boleh berada dalam Git, termasuk dalam fail yang kemudiannya dibuang, kerana ia kekal dalam sejarah repositori. Amalan yang betul ialah menyimpan rahsia dalam pemboleh ubah persekitaran atau sistem pengurusan rahsia, dan merujuknya daripada kod CFML. Lucee 7.1 menyediakan API SecretProvider untuk menguruskan rahsia, dan CommandBox membenarkan anda menghantar pemboleh ubah persekitaran kepada pelayan melalui fail server.json atau persekitaran shell.

Apabila bekerja dengan datasource, simpan kelayakan pangkalan data di luar kod dan rujuk melalui nama datasource yang dikonfigurasi dalam pentadbir, seperti yang diterangkan dalam panduan konfigurasi datasource.

Memulakan Repositori Git

Untuk mula menggunakan Git pada projek sedia ada, jalankan git init dalam folder projek, kemudian tambah fail dan buat komit pertama. Sebelum menambah fail, pastikan .gitignore sudah ada supaya fail yang tidak patut dikomit tidak masuk ke dalam sejarah repositori:

git init
git add .
git commit -m "Komit awal projek CFML"

Perintah git status menunjukkan keadaan semasa fail anda, sama ada ia belum dijejak, diubah atau sudah diadakan. Perintah git add mengadakan perubahan untuk komit seterusnya, dan git commit merakamnya ke dalam sejarah dengan mesej yang menerangkan perubahan itu. Ini ialah gelung kerja asas yang anda ulangi setiap kali menyelesaikan satu unit kerja, dan ia membentuk asas bagi semua aliran kerja yang lebih maju.

Cawangan dan Aliran Kerja Asas

Cawangan ialah ciri teras Git yang membolehkan anda bekerja pada ciri baharu tanpa mengganggu kod utama. Aliran kerja biasa ialah mengekalkan cawangan main yang sentiasa boleh deploy, dan mencipta cawangan berasingan untuk setiap ciri atau pembetulan:

git checkout -b ciri/pendaftaran-pengguna
git add .
git commit -m "Tambah borang pendaftaran pengguna"
git push -u origin ciri/pendaftaran-pengguna

Apabila ciri siap dan diuji, anda menggabungkannya kembali ke main melalui permintaan tarik (pull request) supaya perubahan disemak sebelum digabungkan. Aliran kerja ini mengurangkan risiko kod rosak masuk ke cawangan utama dan membolehkan berbilang pembangun bekerja selari.

Deploy melalui Git

Dengan kod dalam Git, deploy menjadi proses yang boleh diulang. Pendekatan paling mudah ialah menyimpan repositori pada pelayan atau perkhidmatan hosting, kemudian menarik perubahan terkini pada pelayan pengeluaran:

git pull origin main

Untuk aliran kerja yang lebih terkawal, gunakan saluran CI yang menjalankan ujian dan binaan apabila anda menolak ke cawangan tertentu. Anda boleh menyepadukan ujian TestBox dalam saluran ini, seperti yang diterangkan dalam panduan ujian unit CFML. Pendekatan lain ialah menandai versi dengan git tag supaya setiap keluaran boleh dikenal pasti dan dipulihkan dengan mudah. Jika sesuatu tidak kena selepas deploy, anda boleh berundur dengan cepat menggunakan git revert atau menyemak semula tag keluaran sebelumnya, kerana seluruh sejarah perubahan tersedia dalam repositori.

Perangkap Konfigurasi Lucee yang Tertimpa

Perangkap yang paling biasa ialah mengkomit folder WEB-INF secara tidak sengaja, kemudian apabila anda menarik pada pelayan lain, konfigurasi Lucee tempatan ditimpa oleh versi dari repositori. Ini menyebabkan datasource, pemetaan dan tetapan pentadbir hilang atau rosak. Gejalanya ialah aplikasi berfungsi pada satu mesin tetapi gagal pada mesin lain.

Perangkap kedua ialah menyimpan kelayakan dalam fail konfigurasi yang dikomit, kemudian kebocoran apabila repositori dikongsi. Perangkap ketiga ialah lupa bahawa fail yang sudah dijejak tidak boleh diabaikan hanya dengan menambahnya ke .gitignore. Anda perlu mengeluarkannya dari indeks terlebih dahulu dengan git rm --cached. Perangkap keempat ialah menarik perubahan terus ke pelayan pengeluaran tanpa ujian, yang boleh membawa kod rosak kepada pengguna. Untuk persekitaran pengeluaran yang menggunakan kontena, rujuk panduan deploy Lucee dengan Docker yang mengelakkan banyak masalah ini dengan imej yang tidak berubah.

Amalan Baik Git untuk CFML

Komit yang baik ialah komit kecil dan fokus pada satu perubahan, dengan mesej yang menerangkan sebab dan bukan hanya apa. Tulis mesej dalam bentuk imperatif, contohnya "Tambah pengesahan input" dan bukannya "menambah pengesahan". Ini memudahkan anda membaca sejarah dan mencari bila sesuatu pepijat diperkenalkan.

Gunakan tag untuk menandakan keluaran, dan pastikan cawangan utama sentiasa dalam keadaan boleh deploy dengan menggabungkan hanya perubahan yang sudah diuji. Semak juga status repositori sebelum deploy supaya anda tidak menghantar kod separuh siap. Apabila ragu sama ada sesuatu fail patut dikomit, tanya diri anda sama ada ia dijana oleh enjin, mengandungi rahsia, atau khusus kepada satu mesin. Jika ya, ia tidak sepatutnya berada dalam Git. Disiplin kecil ini menghalang kebanyakan masalah yang menyusahkan pasukan CFML pada kemudian hari.

Apa yang Patut dan Tidak Patut Masuk Repo

Komit kod dan konfigurasi aplikasi, dan kecualikan apa yang dijana enjin atau khusus mesin. Jadual ini meringkaskan keputusan itu.

Apabila ragu, semak sama ada fail itu dijana enjin, mengandungi rahsia, atau khusus satu mesin.

Soalan Lazim (FAQ)

Apakah fail yang tidak patut masuk repo projek CFML?

Folder WEB-INF yang dijana Lucee, fail muat naik pengguna, rahsia seperti kata laluan dan kunci API, fail log, dan fail sementara IDE. Semua ini khusus mesin atau data, bukan kod.

Bagaimana cara mengelakkan konfigurasi Lucee daripada dikomit?

Tambahkan /WEB-INF/ ke dalam fail .gitignore. Anda juga boleh memindahkan WEB-INF ke luar root web dengan parameter lucee-web-directory dalam web.xml.

Bagaimana cara mengeluarkan fail yang sudah dikomit secara tidak sengaja?

Guna git rm --cached nama-fail untuk mengeluarkannya dari indeks tanpa memadam fail, kemudian tambahkannya ke .gitignore dan buat komit baharu.

Bagaimana cara deploy projek CFML melalui Git?

Tolak perubahan ke repositori jauh, kemudian jalankan git pull origin main pada pelayan pengeluaran. Untuk kawalan lebih baik, gunakan saluran CI yang menjalankan ujian sebelum deploy.

Apakah perangkap biasa dalam Git untuk CFML?

Menimpa konfigurasi Lucee tempatan dengan WEB-INF dari repo, menyimpan rahsia dalam fail yang dikomit, dan menganggap menambah .gitignore sudah cukup untuk fail yang sudah dijejak.

Sumber

• gitignore documentation, git-scm.com
• Git Branching - Branches in a Nutshell, git-scm.com
• Git Basics - Recording Changes to the Repository, git-scm.com
• Securing /WEB-INF/ by moving it outside of the web root, docs.lucee.org