Lucee Malaysia
EN Log masuk
Panduan Pasukan Lucee MY

CommandBox lanjutan: server.json, ForgeBox dan CI

CommandBox lanjutan untuk projek CFML: server.json, pemasangan pakej ForgeBox, tugasan berulang dan integrasi saluran CI tanpa mengejutkan pasukan anda.

Thalhah1 reputasi · disunting · 6 paparan · 8 min bacaan
CommandBox lanjutan: server.json, ForgeBox dan CI
0
Kandungan

CommandBox lanjutan: server.json, ForgeBox dan CI

CommandBox bukan sekadar arahan install dan start. Apabila projek CFML membesar, anda memerlukan konfigurasi pelayan yang boleh dikongsi seluruh pasukan, pemasangan pakej yang boleh diulang dengan tepat, tugasan berulang yang dijalankan dengan satu arahan, dan saluran CI yang gagal dengan jelas apabila kod rosak. Artikel ini menyambung panduan pengenalan CommandBox dan membincangkan empat perkara itu: fail server.json, pengurusan pakej ForgeBox secara lanjutan, task runner untuk tugasan berulang, dan integrasi saluran CI tanpa mengejutkan pasukan.

Kenapa server.json penting

Setiap kali anda memulakan pelayan dengan arahan start, CommandBox menyimpan tetapan yang digunakan ke dalam fail server.json di web root. Apa-apa parameter yang tidak dibekalkan kepada arahan start dibaca daripada fail ini sebagai lalai. Ini bermakna tetapan pelayan bukan lagi ingatan peribadi seorang pembangun, tetapi fail yang boleh dikomit ke dalam repositori.

Apabila server.json dikomit bersama kod, setiap pembangun mendapat pelayan yang sama tanpa perlu menghafal bendera baris arahan. Pelayan pementasan juga boleh menggunakan fail yang sama dengan tetapan berbeza untuk port dan profil, supaya tiada siapa tertanya-tanya kenapa aplikasi berkelakuan lain di mesin sendiri. Amalan mengkomit fail konfigurasi ini selari dengan apa yang diterangkan dalam panduan git untuk projek CFML: kod dan konfigurasi bergerak bersama, bukan berasingan.

Struktur server.json

Fail server.json ialah fail JSON biasa, jadi ia mudah dibaca dan boleh disahkan sebelum dikomit. Berikut contoh yang menetapkan enjin CFML, port, web root, alias maya, saiz timbunan JVM dan pemboleh ubah persekitaran:

{
    "name": "projek-lucee",
    "openBrowser": false,
    "profile": "production",
    "app": {
        "cfengine": "lucee@7"
    },
    "web": {
        "http": {
            "port": 8080
        },
        "webroot": "src/cfml",
        "aliases": {
            "/uploads": "../shared/uploads"
        }
    },
    "jvm": {
        "heapSize": 512,
        "minHeapSize": 256,
        "args": ["-XX:+UseG1GC"]
    },
    "env": {
        "APP_ENV": "production"
    }
}

Kunci app.cfengine menentukan enjin yang digunakan, sama ada lucee@7 atau enjin Adobe ColdFusion. Kunci web.webroot membolehkan anda meletakkan kod sumber dalam subfolder dan bukannya di akar folder projek, sementara web.aliases memetakan laluan maya ke folder di luar web root, berguna untuk folder muat naik yang dikongsi antara beberapa pelayan. Kunci jvm.heapSize dan jvm.minHeapSize menetapkan saiz timbunan memori dalam megabait, dan jvm.args menerima senarai argumen tambahan untuk JVM.

Ubah tetapan dengan server set, show dan clear

Anda tidak perlu mengedit fail server.json secara manual setiap kali. CommandBox menyediakan tiga arahan yang berfungsi seperti package set, show dan clear, iaitu server set, server show dan server clear. Ini penting kerana mengedit JSON secara manual mudah menyebabkan ralat sintaks yang hanya ditemui apabila pelayan gagal bermula.

server set web.http.port=8080
server show web.http.port
server show jq:web.http.port
server clear web.http.port

Arahan pertama menyimpan nilai port ke dalam fail server.json. Arahan kedua membaca semula satu nilai itu sahaja. Awalan jq: membolehkan anda membaca nilai menggunakan ungkapan JMESPath, berguna apabila anda mahu nilai bersarang atau menapis hasil dalam skrip. Arahan server clear pula membuang tetapan yang disimpan supaya lalai terbina dalam digunakan semula.

Pemasangan pakej dari ForgeBox dengan versi semantik

ForgeBox ialah repositori pakej CFML, dan CommandBox menyokong julat versi semantik semasa memasang pakej. Ini lebih daripada sekadar menentukan nombor versi tepat; ia membolehkan anda mengunci julat yang selamat supaya pakej boleh naik versi kecil tanpa perubahan besar yang memecahkan aplikasi.

install coldbox
install coldbox@^7.0.0
install "coldbox@>5.2 <=6.3.4"
install foo@4.x

Arahan install coldbox tanpa versi mengambil keluaran stabil terkini. Simbol karet dalam install coldbox@^7.0.0 membenarkan naik versi yang tidak mengubah digit bukan sifar paling kiri, iaitu naik versi minor dan patch dalam siri 7 tetapi bukan versi 8. Julat install "coldbox@>5.2 <=6.3.4" pula mengunci pakej dalam lingkungan yang lebih ketat, manakala install foo@4.x mengambil mana-mana versi utama 4. Untuk mencari pakej sebelum memasang, gunakan forgebox search diikuti kata kunci.

Kebergantungan pembangunan lawan pengeluaran

Tidak semua pakej patut dihantar ke pelayan pengeluaran. Rangka kerja ujian seperti TestBox diperlukan semasa menulis dan menjalankan ujian, tetapi tidak berguna malah menambah permukaan serangan di pengeluaran. CommandBox membezakan dua jenis kebergantungan ini dalam fail box.json.

install testbox --saveDev
install cborm --!save
install --production

Bendera --saveDev menyimpan pakej di bawah devDependencies dan bukannya dependencies. Bendera --!save memasang pakej tanpa menyimpannya ke dalam box.json langsung, berguna untuk pakej yang anda cuba sekali sahaja. Apabila anda menjalankan install --production, CommandBox melangkau semua kebergantungan pembangunan dan hanya memasang pakej yang benar-benar diperlukan aplikasi, jadi imej Docker atau binaan CI kekal kecil dan bersih.

Tugasan berulang dengan task runner

Tugasan yang anda jalankan berulang kali, seperti memindahkan skema pangkalan data, membersihkan fail sementara atau menjana dokumentasi, tidak patut bergantung pada ingatan. CommandBox menyediakan task runner, iaitu cara menulis tugasan automasi dalam CFML sebagai satu CFC dengan beberapa sasaran yang diisytiharkan sebagai kaedah awam.

task create --open
task run

Arahan task create menjana fail Task.cfc dan membukanya dalam editor lalai anda. Fail itu mengandungi kaedah run() yang menjadi sasaran lalai apabila anda menjalankan task run tanpa hujah. Setiap kaedah awam lain dalam CFC itu menjadi sasaran berasingan yang boleh dipanggil dengan nama, dan kaedah ini menerima argumen serta pembantu cetakan untuk output berwarna. Ini lebih fleksibel daripada skrip shell kerana anda boleh memanggil arahan CommandBox lain, membaca pangkalan data dan menghantar e-mel dari dalam tugasan yang sama.

Skrip pakej dengan run-script

Untuk perkara yang lebih ringkas daripada task runner, anda boleh menakrifkan skrip pakej terus dalam fail box.json dan menjalankannya dengan run-script. Skrip ini ialah koleksi arahan yang sering dijalankan bersama, dan boleh ditulis sebagai satu rentetan atau sebagai senarai arahan.

{
    "name": "Projek Lucee",
    "slug": "projek-lucee",
    "version": "1.0.0",
    "scripts": {
        "test": "testbox run",
        "build": [
            "!git describe --tags",
            "testbox run"
        ]
    }
}

Awalan tanda seru menandakan arahan sistem operasi, jadi !git describe --tags menjalankan binari git secara terus. Skrip yang ditulis sebagai senarai berhenti pada arahan pertama yang gagal, sama seperti rantaian dengan &&, jadi kegagalan ujian akan menghentikan binaan. Untuk menjalankan skrip ini, taip run-script test atau run-script build dari folder projek.

CommandBox dalam saluran CI

Keupayaan sebenar CommandBox terserlah apabila ia dimasukkan ke dalam saluran integrasi berterusan. Arahan CommandBox memulangkan kod keluar bukan sifar apabila sesuatu gagal, jadi pelari CI akan menandakan binaan sebagai gagal secara automatik tanpa perlu menulis logik pengesanan sendiri. Langkah asas dalam mana-mana pelari adalah sama: pasang kebergantungan, jalankan ujian, dan hentikan jika ujian gagal.

box install --production
box testbox run

Arahan pertama memasang kebergantungan pengeluaran sahaja supaya binaan pantas dan tidak membawa rangka kerja ujian yang tidak perlu. Arahan kedua menjalankan suite TestBox seperti yang diterangkan dalam panduan menulis ujian unit dengan TestBox. Pada GitHub Actions, langkah yang sama dipasang dengan satu action rasmi Ortus:

name: Ujian CFML
on: [push, pull_request]
jobs:
  ujian:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      - uses: Ortus-Solutions/setup-commandbox@v2.0.1
        with:
          installSystemModules: true
      - run: box install --production
      - run: box testbox run

Pilihan installSystemModules memasang modul commandbox-cfconfig dan commandbox-dotenv secara automatik, jadi tetapan datasource dan pemboleh ubah persekitaran boleh disuntik daripada CI tanpa menyentuh kod. Apabila binaan lulus, artefak boleh dihantar ke pelayan tanpa mematikan perkhidmatan, pendekatan yang dibincangkan dalam panduan deploy tanpa henti untuk CFML, atau dibungkus sebagai imej seperti dalam panduan deploy Lucee dengan Docker.

Rujukan ringkas arahan lanjutan

Jadual berikut meringkaskan arahan yang dibincangkan supaya mudah dirujuk semasa bekerja:

ArahanTujuanSituasi sesuai
server set web.http.port=8080Simpan tetapan pelayan tanpa edit failMenyeragamkan port seluruh pasukan
server show jq:web.http.portBaca satu nilai dalam skripMengambil port untuk langkah seterusnya
install testbox --saveDevPasang pakej sebagai kebergantungan devMenambah rangka kerja ujian
install --productionPasang tanpa kebergantungan devBinaan CI dan imej pengeluaran
task runJalankan tugasan berulangMigrasi, binaan, pembersihan
run-script buildJalankan skrip pakej dalam box.jsonGabungkan beberapa arahan

Soalan Lazim

Apakah perbezaan antara box.json dan server.json?

box.json menerangkan projek dan kebergantungannya serta skrip pakej, manakala server.json menyimpan tetapan pelayan seperti port, enjin CFML, saiz timbunan JVM dan alias maya. Kedua-duanya boleh dikomit ke repositori, tetapi yang pertama tentang pakej dan yang kedua tentang cara pelayan dijalankan.

Bagaimana cara mengunci versi pakej supaya tidak naik versi utama secara mengejut?

Gunakan julat versi semantik semasa install, contohnya install coldbox@^7.0.0 untuk kekal dalam siri 7, atau install "coldbox@>5.2 <=6.3.4" untuk lingkungan yang lebih ketat. Versi yang disimpan dalam box.json akan dipatuhi semula apabila ahli pasukan lain menjalankan install.

Bagaimana cara melangkau kebergantungan pembangunan dalam binaan pengeluaran?

Jalankan install --production. Bendera ini melangkau semua kebergantungan yang disimpan di bawah devDependencies, jadi pakej seperti TestBox tidak dihantar ke pelayan pengeluaran dan binaan menjadi lebih pantas.

Apakah task runner dan bila ia lebih sesuai daripada skrip pakej?

Task runner ialah CFC dengan kaedah awam sebagai sasaran, ditulis dalam CFML dan dijalankan dengan task run. Ia lebih sesuai untuk tugasan kompleks yang memerlukan logik, pangkalan data atau e-mel, manakala skrip pakej dengan run-script cukup untuk rantaian arahan yang ringkas.

Bagaimana CI tahu binaan gagal apabila ujian tidak lulus?

CommandBox memulangkan kod keluar bukan sifar apabila arahan seperti testbox run gagal, dan pelari CI mentafsir kod bukan sifar sebagai kegagalan binaan secara automatik. Tiada logik tambahan diperlukan untuk menandakan binaan merah.

Sumber

0 komen

0 komen

Log masuk untuk menjawab atau memberi komen.

Log masuk

Berkaitan