Lucee extensions: pasang, kemas kini dan bina sendiri

Lucee extensions: pasang, kemas kini dan bina sendiri

Extension Lucee ialah pakej tambahan yang menambah fungsi, tag, pemacu JDBC, penyedia sumber atau plugin pentadbir kepada enjin Lucee, dan ia dihantar sebagai satu fail dengan sambungan .lex. Fail .lex itu sebenarnya arkib ZIP yang mengandungi fail manifest dan kod Java. Artikel ini menerangkan cara memasang extension dari Lucee Admin dan CommandBox, cara memasang tanpa UI menggunakan folder deploy, cara mengemas kini dan mengunci versi, cara membina extension sendiri dengan Java, dan cara mengesahkan extension itu benar-benar dimuatkan. Jika anda belum memasang enjinnya, mulakan dengan cara memasang Lucee.

Apa itu extension Lucee (.lex)

Extension menambah keupayaan yang tidak terbina dalam teras Lucee. Contoh biasa ialah pemacu JDBC seperti PostgreSQL dan MSSQL, penyedia sumber seperti S3 dan Redis, sokongan imej dan PDF, serta tag tambahan seperti cfchart. Fail extension menggunakan sambungan .lex, iaitu singkatan Lucee Extension, dan ia sebenarnya fail ZIP biasa. Di dalamnya terdapat folder META-INF dengan fail MANIFEST.MF yang menyimpan metadata seperti id, nama, versi dan versi teras yang diperlukan. Selain itu ada folder untuk fail JAR, folder components untuk CFC global, dan folder context untuk tag tersuai.

Struktur asas sebuah fail .lex kelihatan seperti ini:

my-extension.lex   (fail ZIP)
  META-INF/MANIFEST.MF
  META-INF/logo.png
  jars/            (JAR OSGi, cara lama)
  maven/           (repositori Maven, Lucee 7 dan ke atas)
  components/      (CFC yang boleh diakses global)
  context/         (tag tersuai)

Metadata dalam MANIFEST.MF ialah perkara yang dibaca Lucee untuk mengenal pasti extension, jadi ia mesti ada sebelum extension boleh dipasang.

Extension teras lawan extension Maven

Terdapat dua cara extension membawa kod Java, dan kedua-duanya masih disokong. Cara lama ialah OSGi, iaitu setiap JAR ialah bundle OSGi dengan classloader sendiri dan disimpan dalam folder jars. Cara baharu yang diperkenalkan dalam Lucee 7 ialah extension Maven, iaitu JAR disusun mengikut koordinat Maven groupId:artifactId:version dan Lucee menyelesaikan kebergantungan pada masa pemasangan. Pendekatan Maven lebih mudah dibina dan didebug, serta membetulkan masalah lama OSGi yang tidak dapat mengimport pakej JDK moden seperti java.time.

Jangan keliru extension teras dengan extension Maven. Extension teras bermaksud extension yang dibundel bersama fail JAR standard Lucee supaya tersedia terus selepas pemasangan, manakala extension Maven ialah cara extension itu dibina dan dimuatkan, iaitu menggunakan classloading Java standard dan bukannya OSGi.

Pasang dari Lucee Admin

Untuk pemasangan sekali sahaja atau penerokaan, buka Lucee Administrator dan pergi ke menu Extensions, kemudian Applications. Di situ anda boleh mencari extension daripada penyedia, memuat naik fail .lex, memasang, mengemas kini dan menyahpasang extension secara interaktif. Kaedah ini sesuai untuk ujian tetapi tidak sesuai untuk deployment automatik kerana ia memerlukan klik manual. Panduan penuh menu pentadbir ada dalam panduan tetapan Lucee Admin.

Pasang dari CommandBox

CommandBox mengurus contoh Lucee sendiri, dan extension boleh dipasang dengan meletakkan fail .lex ke dalam folder deploy konteks pelayan Lucee di dalam CLI:

~/.CommandBox/engine/cfml/cli/lucee-server/deploy

Lucee mengambil dan memasang fail itu dalam masa 60 saat jika CommandBox sedang berjalan, atau sebaik sahaja ia dimulakan semula. Jika anda menulis task runner, CommandBox juga menyediakan kaedah installExtension() untuk memasang extension daripada penyedia kemas kini mengikut id:

// MySQL JDBC Extension
installExtension( '7E673D15-D87C-41A6-8B5F1956528C605F' )

Pasang tanpa UI (folder deploy)

Pada pelayan sebenar, folder deploy terletak di bawah folder pemasangan Lucee pada laluan {lucee-installation}/lucee-server/deploy. Salin fail .lex ke situ dan Lucee memasangnya pada permulaan atau dalam masa satu minit, tanpa sebarang klik. Sesetengah extension memerlukan mulakan semula untuk berkuat kuasa.

# salin fail extension ke folder deploy
cp s3-extension-2.0.2.21.lex /opt/lucee/server/lucee-server/deploy/

Dalam imej Docker, anda boleh memuat turun extension pada masa bina supaya ia terbenam dalam imej. Ini menjadikan bekas baharu sedia terus tanpa langkah tambahan, dan diterangkan lebih lanjut dalam deploy Lucee dengan Docker.

Untuk pemasangan deklaratif tanpa fail tempatan, Lucee menyokong pemboleh ubah persekitaran LUCEE_EXTENSIONS dengan senarai dipisahkan koma. Sejak Lucee 7.0.1, koordinat Maven diterima terus:

LUCEE_EXTENSIONS=org.lucee:s3-extension:2.0.2.21,org.lucee:redis-extension:3.0.0.56

Kemas kini dan kunci versi

Apabila versi tidak dinyatakan, Lucee menyelesaikan versi keluaran terkini daripada Maven dan menulis semula versi itu ke fail konfigurasi pelayan. Mengunci versi amat digalakkan kerana extension yang tidak dikunci boleh memasang versi berbeza selepas naik taraf atau deploy semula, dan versi yang dikunci juga deploy lebih cepat kerana tiada carian jauh pada masa pemasangan.

Untuk konfigurasi sebagai kod, anda boleh menggunakan fail .CFConfig.json. Pada Lucee 7, extension dikenal pasti melalui id UUID, manakala Lucee 8 menggunakan koordinat Maven sebagai pengecam utama:

{
  "extensions": [
    { "id": "07082C66-510A-4F0B-B5E63814E2FDF7BE", "version": "1.0.0.11" }
  ]
}

Kemas kini versi dilakukan dengan menukar nombor versi pada koordinat atau id, kemudian memulakan semula. Sentiasa uji versi baharu di persekitaran staging dahulu kerana extension menyentuh lapisan rendah enjin.

Lucee 7.1: ciri teras dipisahkan ke extension

Perubahan paling penting dalam Lucee 7.1 ialah beberapa fungsi yang dahulu terbina dalam teras kini dipindahkan ke extension berasingan. SMTP (penghantaran e-mel), FTP dan Compress (zip dan gzip) semuanya dipindahkan keluar, manakala HSQLDB dikeluarkan terus daripada teras. Dalam edaran penuh yang dipanggil fat JAR, extension ini masih dibundel, tetapi dalam edaran Light dan Zero ia tidak disertakan langsung.

Akibatnya, pemasangan baharu edaran Light atau Zero boleh kehilangan ciri yang dahulu terbina dalam, seperti cfmail atau cfzip, sehingga extension yang sepadan dipasang semula. Perubahan penuh modular ini diterangkan dalam Lucee 7.1 extension modular. Jadual berikut meringkaskan extension utama dan cara memasangnya:

Jika aplikasi anda menghantar e-mel, pastikan extension Mail dipasang, jika tidak cfmail akan gagal. Cara mengkonfigurasi cfmail sendiri diterangkan dalam panduan cfmail dan SMTP.

Bina extension sendiri dengan Java

Anda boleh membina extension sendiri dengan menulis fungsi terbina dalam, dipanggil BIF, sebagai kelas Java. Kelas ini mewarisi lucee.runtime.ext.function.BIF dan melaksanakan kaedah invoke. Contoh ringkas sebuah fungsi yang mengucapkan salam:

package org.contoh.extension.functions;

import lucee.runtime.PageContext;
import lucee.runtime.exp.PageException;
import lucee.runtime.ext.function.BIF;

public class Salam extends BIF {
    private static final long serialVersionUID = 1L;

    public static String call(PageContext pc, String nama) {
        return "Salam, " + nama + "!";
    }

    @Override
    public Object invoke(PageContext pc, Object[] args) throws PageException {
        return call(pc, args[0].toString());
    }
}

Kelas itu didaftarkan melalui deskriptor fungsi, dipanggil FLD, yang memberitahu Lucee nama fungsi dalam CFML dan kelas pelaksananya:

<function>
  <name>salam</name>
  <class maven="{maven}">org.contoh.extension.functions.Salam</class>
  <description>Ucap salam dalam Bahasa Melayu</description>
  <argument>
    <name>nama</name>
    <type>string</type>
    <required>true</required>
  </argument>
  <return type="string"/>
</function>

Placeholder {maven} digantikan dengan koordinat Maven sebenar semasa pembungkusan. Akhir sekali, tulis fail manifest dan bungkus semuanya ke dalam fail ZIP yang dinamakan semula kepada .lex:

Manifest-Version: 1.0
version: "1.0.0.0"
id: "GANTI-DENGAN-UUID-ANDA"
name: "Extension Salam"
description: "Contoh extension ringkas"
start-bundles: false
lucee-core-version: "7.0.0.110"

zip -r salam.lex META-INF fld maven

Tag tersuai pula mengikut corak yang sama tetapi menggunakan deskriptor TLD dan kelas yang mewarisi TagImpl. Selepas dibungkus, fail .lex itu boleh dipasang melalui mana-mana kaedah di atas.

Sahkan extension benar-benar dimuatkan

Memasang tidak sama dengan berfungsi, jadi sahkan dahulu. Tiga cara paling mudah ialah:

1. Semak log pemasangan. Lucee menulis semua tindakan deploy, termasuk versi yang diselesaikan, ke fail {lucee-installation}/lucee-server/context/logs/deploy.log.

tail -f /opt/lucee/server/lucee-server/context/logs/deploy.log

2. Buka Lucee Admin di menu Extensions kemudian Applications dan sahkan extension tersenarai sebagai dipasang bersama versinya.

3. Uji tag atau fungsi terus daripada CFML. Buat fail kecil dan panggil fungsi baharu:

<!--- salam() hanya wujud selepas extension di atas dipasang dan enjin dimulakan semula --->
<cfoutput>#salam("Dunia")#</cfoutput>

Jika halaman memulangkan Salam, Dunia!, extension itu dimuatkan dan berfungsi. Jika ia membalas No matching function atau undefined tag, extension belum aktif dan anda perlu menyemak log deploy semula.

Soalan Lazim (FAQ)

Apakah fail .lex dalam Lucee?

Fail .lex ialah pakej extension Lucee, iaitu arkib ZIP yang dinamakan semula dan mengandungi fail META-INF/MANIFEST.MF serta kod Java untuk fungsi, tag atau pemacu tambahan.

Bagaimana cara memasang Lucee extension tanpa UI?

Salin fail .lex ke folder {lucee-installation}/lucee-server/deploy dan mulakan semula, atau tetapkan LUCEE_EXTENSIONS dengan senarai koordinat Maven. Lucee memasangnya secara automatik tanpa sebarang klik.

Kenapa cfmail tiada selepas memasang Lucee 7.1?

Dalam Lucee 7.1 fungsi SMTP dipindahkan ke extension Mail yang berasingan. Edaran Light dan Zero tidak membundelkannya, jadi anda perlu memasang org.lucee:mail-extension dahulu sebelum cfmail berfungsi.

Bagaimana cara mengunci versi extension?

Nyatakan versi penuh pada koordinat Maven atau id UUID dalam .CFConfig.json atau LUCEE_EXTENSIONS, contohnya org.lucee:s3-extension:2.0.2.21, supaya Lucee tidak menyelesaikan versi baharu secara automatik.

Bagaimana cara mengesahkan extension sudah dimuatkan?

Semak fail deploy.log dalam folder context/logs, sahkan senarai dalam Extensions di Lucee Admin, atau panggil tag atau fungsi baharu daripada fail CFML dan lihat ia memulangkan hasil.

Sumber

• Extension Installation, docs.lucee.org
• Lucee 7.1, docs.lucee.org
• Maven Based Extensions, docs.lucee.org
• Extensions in Lucee 5, docs.lucee.org
• Installing Lucee Extensions, CommandBox
• Lucee Extensions, docs.lucee.org

Senarai semak

• Tentukan extension mana yang aplikasi anda perlukan, terutamanya Mail, FTP dan Compress dalam Lucee 7.1.
• Pilih kaedah pemasangan: Lucee Admin untuk sekali sahaja, folder deploy untuk automasi, atau LUCEE_EXTENSIONS untuk kontena.
• Kunci versi setiap extension supaya deploy semula tidak mengubah tingkah laku secara senyap.
• Uji versi baharu di staging sebelum naik ke pengeluaran.
• Sahkan pemasangan melalui deploy.log, senarai Extensions di Admin, atau ujian tag.
• Bina extension sendiri hanya apabila fungsi itu tidak wujud dalam teras atau extension sedia ada.