Migrasi ColdFusion ke Lucee: ralat yang paling biasa

Migrasi ColdFusion ke Lucee: ralat yang paling biasa

Kebanyakan kod Adobe ColdFusion berjalan terus di Lucee tanpa perubahan, tetapi tidak semuanya. Ralat yang muncul selepas migrasi hampir selalu berpunca daripada satu perkara: kod anda memanggil tag atau fungsi Adobe yang tidak wujud dalam teras Lucee, atau bergantung pada tetapan pelayan yang belum dipindahkan. Artikel ini menyenaraikan ralat paling kerap, dengan mesej ralat sebenar yang ditangkap pada enjin Lucee, dan pembetulan yang diuji. Untuk panduan langkah demi langkah keseluruhan proses, baca dahulu panduan migrasi dari ColdFusion ke Lucee.

Tag dan fungsi Adobe yang tiada dalam teras

Tiga tag yang paling kerap mengejutkan pembangun selepas migrasi ialah cfspreadsheet, cfchart dan cfwebsocket. Ketiga-tiganya wujud dalam Adobe ColdFusion, tetapi tiada dalam teras Lucee. Dua fungsi gaya Adobe yang turut tiada ialah spreadsheetNew() untuk Excel dan pdfMerge() untuk menggabungkan PDF. Kod yang memanggilnya tidak akan dikompil, dan enjin membalas dengan mesej yang jelas. Ujian berikut dijalankan pada Lucee 7.1, satu tag atau fungsi dalam satu fail supaya ralatnya tidak bercampur:

<!--- tag Adobe yang tiada dalam teras Lucee --->
<cfspreadsheet action="read" src="buku.xlsx" query="q">
<cfchart format="png">
    <cfchartseries type="pie">
        <cfchartdata item="A" value="10">
    </cfchartseries>
</cfchart>
<cfwebsocket name="soket" onMessage="pengendali">

<!--- fungsi Adobe yang tiada dalam teras Lucee --->
<cfscript>
    s = spreadsheetNew("buku");
    pdfMerge("gabung.pdf", ["a.pdf", "b.pdf"]);
</cfscript>

Mesej ralat sebenar yang dibalas oleh enjin untuk kelima-limanya, tidak disunting:

undefined tag [cfspreadsheet]
undefined tag [cfchart]
undefined tag [cfwebsocket]
No matching function [SPREADSHEETNEW] found
No matching function [PDFMERGE] found

cfchart ditangkap pada bekas bersih Lucee 7.1.0.204 tanpa sebarang sambungan. Satu catatan jujur: sesetengah imej Docker keluaran SNAPSHOT membundel Chart Extension, jadi cfchart kelihatan berjalan di situ, tetapi pemasangan teras biasa tidak menyertakannya. Sentiasa uji pada pelayan anda sendiri dan jangan anggap tag itu wujud hanya kerana satu imej tertentu memuatkannya.

Pembetulannya ialah memasang sambungan atau menukar pendekatan. Excel memerlukan pustaka cfsimplicity/spreadsheet-cfml; carta memerlukan Chart Extension (org.lucee:chart-extension); WebSocket memerlukan org.lucee:websocket-extension; dan manipulasi PDF lanjutan memerlukan sambungan PDF Lucee (org.lucee:pdf-extension). Panduan penuh pemasangan ada pada artikel cfspreadsheet dan Excel, cfchart dan carta graf dan cfwebsocket dan aplikasi masa nyata.

Alternatif yang berjalan dalam teras

Untuk membuktikan jalan keluar wujud tanpa sambungan, ketiga-tiga contoh berikut dijalankan dan lulus pada Lucee 7.1. Eksport Excel boleh digantikan dengan CSV, carta boleh digantikan dengan data JSON untuk Chart.js, dan PDF dijana terus dengan cfdocument yang memang ada dalam teras:

<!--- CSV: ganti cfspreadsheet untuk eksport mudah --->
<cfscript>
    q = queryNew("nama,harga", "varchar,decimal", [["Kopi", 12.5], ["Teh", 8.0]]);
    cfcontent(type = "text/csv; charset=utf-8", reset = true);
    writeOutput("nama,harga" & chr(10));
    cfloop(query = q) { writeOutput(q.nama & "," & q.harga & chr(10)); }
</cfscript>

<!--- JSON: ganti cfchart dengan Chart.js di hadapan --->
<cfscript>
    q = queryNew("kategori,nilai", "varchar,integer", [["A", 10], ["B", 20]]);
    cfheader(name = "Content-Type", value = "application/json; charset=utf-8");
    writeOutput(serializeJSON(q));
</cfscript>

<!--- PDF: cfdocument ada dalam teras --->
<cfdocument format="pdf" pagetype="A4">
    <h1>Dokumen ujian</h1>
    <p>Dijana oleh teras Lucee tanpa sambungan.</p>
</cfdocument>

Ketiga-tiganya membalas HTTP 200. CSV memulangkan nama,harga diikuti baris data, JSON memulangkan {"COLUMNS":["kategori","nilai"],"DATA":[["A",10],["B",20]]}, dan cfdocument memulangkan PDF sebenar sebesar 1,154 bait dengan pengepala %PDF.

cfdocument dan atribut yang berbeza

cfdocument memang ada dalam teras, tetapi set atributnya lebih kecil daripada Adobe. Perbezaan paling ketara ialah format: Adobe menyokong format="flashpaper" dan format="pdf", manakala Lucee hanya menyokong pdf. Kod lama yang menjana FlashPaper akan gagal serta-merta dengan mesej sebenar ini: invalid format [flashpaper], only the following format is supported [pdf].

Flash sudah mati sebagai teknologi pelayar, jadi pembetulannya mudah: tukar format kepada pdf. Semak juga atribut lain yang pernah bergantung pada ciri Flash dalam cfdocument, seperti pratonton, dan gantikan dengan paparan PDF biasa.

cfquery lawan queryExecute

cfquery dan queryExecute kedua-duanya berfungsi di Lucee, jadi perbezaannya bukan ralat maut tetapi perangkap halus. Kod yang ditulis dalam gaya tag memakai cfquery dengan atribut name, manakala kod skrip memakai queryExecute() yang memulangkan objek query terus. Masalahnya muncul apabila kod lama mencampur keduanya: contohnya memanggil queryExecute tetapi kemudian membaca hasil melalui pemboleh ubah cfquery, atau mengharapkan q.recordCount sedangkan pemboleh ubah itu tidak pernah diisi. Semasa migrasi, kekalkan satu gaya dalam satu fail dan pastikan nama pemboleh ubah hasil sepadan dengan cara ia dipanggil.

Application.cfc lama

Application.cfc ialah fail pertama yang perlu diaudit kerana ia memegang hampir semua tetapan aplikasi. Perkara yang berfungsi di Adobe tetapi perlu disemak semula di Lucee: tetapan this.datasource, this.sessionManagement, this.timeout, dan paling penting this.mailServers. Di Adobe, tetapan mel selalunya disimpan dalam ColdFusion Administrator, tetapi di Lucee ia lazimnya ditakrifkan terus dalam Application.cfc melalui this.mailServers. Jika fail lama tidak membawa tetapan mel, cfmail tanpa atribut server akan gagal kerana tiada pelayan SMTP ditakrifkan. Salin tetapan pelayan satu per satu ke dalam Application.cfc, dan jangan harap ia datang secara automatik.

Datasource dengan nama Adobe

Datasource tidak dipindahkan bersama kod. Ia didaftarkan dalam ColdFusion Administrator di Adobe, dan perlu didaftarkan semula dalam Lucee Administrator atau Application.cfc. Kod yang memanggil nama datasource lama akan gagal dengan mesej sebenar ini: Datasource [nama_adobe_lama] doesn't exist, diikuti baris yang menyenaraikan nama tersedia: datasource names are [app_db,mydb,luceemy,kedai,mydsn,kedaiDB,kita].

Mesej ini sebenarnya membantu: bahagian kedua menyenaraikan nama yang didaftarkan, jadi anda terus tahu nama mana yang perlu digunakan atau didaftarkan. Untuk panduan mendaftar datasource, baca artikel datasource tidak dijumpai.

requesttimeout dan permintaan lama

Permintaan yang lama berjalan, seperti laporan besar atau eksport, boleh tiba-tiba terputus selepas migrasi kerana requesttimeout. Kedua-dua enjin menetapkan masa tamat permintaan, tetapi nilainya tidak dipindahkan secara automatik: jika aplikasi Adobe anda bergantung pada this.requesttimeout yang tinggi, dan Application.cfc baharu tidak menyatakannya, Lucee memakai lalai yang lebih pendek. Semak tetapan this.requesttimeout dalam Application.cfc dan <cfsetting requesttimeout="..."> dalam halaman yang memerlukan masa lebih lama, kemudian naikkan nilainya mengikut keperluan sebenar aplikasi.

Enkod aksara

Ralat enkod aksara muncul sebagai aksara pelik pada output, bukan sebagai halaman ralat, jadi ia mudah terlepas pandang semasa ujian. Punca lazimnya ialah campuran enkod antara Adobe dan Lucee: fail sumber disimpan sebagai ISO-8859-1 tetapi Lucee membaca sebagai UTF-8, atau sebaliknya. Tetapkan satu enkod konsisten di seluruh aplikasi: simpan semua fail .cfm dan .cfc sebagai UTF-8, dan nyatakan charset=utf-8 pada cfcontent, cfheader dan borang. Untuk teks Melayu dengan aksara seperti é atau aksara Jawi, perbezaan satu bait ini cukup untuk merosakkan keseluruhan paparan.

cfmail dan pelayan SMTP

cfmail wujud dalam teras Lucee, tetapi ia memerlukan pelayan SMTP yang dikonfigurasi. Ralat paling kerap selepas migrasi bukanlah tag yang tiada, tetapi cfmail yang tidak menemui pelayan SMTP kerana tetapan Adobe tidak dibawa bersama. Daftar pelayan dalam this.mailServers pada Application.cfc, atau letak atribut server, port, username dan password terus pada tag. Perangkap kedua ialah spool: secara lalai Lucee menghantar e-mel melalui bebenang latar belakang, jadi ralat sambungan tidak dibuang kepada kod anda. Tetapkan spoolEnable="false" semasa ujian untuk melihat ralat serta-merta.

Jadual ralat biasa

Jadual berikut meringkaskan gejala yang anda lihat, puncanya, dan pembetulan:

Kesan ralat satu per satu dengan cftry

Apabila aplikasi besar gagal selepas migrasi, jangan teka punca daripada timbunan ralat yang panjang. Asingkan setiap bahagian dengan cftry supaya ralat ditangkap secara berasingan dan anda tahu tepat bahagian mana yang rosak:

<cfscript>
    try {
        // ganti dengan tag atau fungsi yang ingin diuji
        s = spreadsheetNew("buku");
        writeOutput("LULUS");
    } catch (any e) {
        writeOutput("GAGAL: " & e.message);
    }
</cfscript>

Corak ini menukar ralat yang menghentikan seluruh halaman kepada laporan ringkas yang boleh dibaca. Uji satu tag atau fungsi dalam satu fail setiap kali, kerana satu tag yang tidak dikenali menggagalkan kompilasi seluruh fail dan menyalahkan tag lain yang sebenarnya sihat. Mulakan dari tag yang paling khusus kepada aplikasi anda, catat mesej e.message untuk setiap satu, dan baiki mengikut jadual di atas.

Soalan Lazim

Adakah semua kod Adobe ColdFusion berfungsi di Lucee?

Kebanyakan berfungsi tanpa perubahan kerana Lucee mengekalkan keserasian tinggi dengan CFML, tetapi tag proprietari Adobe seperti cfspreadsheet, cfchart dan cfwebsocket tiada dalam teras dan memerlukan sambungan atau alternatif.

Kenapa saya mendapat mesej "undefined tag"?

undefined tag bermaksud tag itu tidak dikenali oleh enjin Lucee yang anda jalankan. Ia bukan ralat sintaks pada kod anda, tetapi tanda bahawa tag itu tiada dalam teras atau sambungannya belum dipasang.

Apakah ganti cfspreadsheet tanpa memasang pustaka?

Untuk eksport mudah, jana CSV dengan cfcontent dan cfloop seperti contoh di atas. Untuk membaca atau menulis fail Excel sebenar dengan pemformatan, pasang pustaka spreadsheet-cfml.

Bagaimana saya tahu datasource mana yang didaftarkan?

Ralat Datasource [nama] doesn't exist menyenaraikan nama datasource yang tersedia pada baris kedua. Gunakan senarai itu untuk memilih nama yang betul atau daftarkan nama baharu dalam Lucee Administrator.

Kenapa e-mel saya tidak keluar selepas migrasi walaupun cfmail wujud?

cfmail wujud dalam teras, tetapi pelayan SMTP tidak dipindahkan bersama kod. Daftar pelayan dalam this.mailServers pada Application.cfc, dan tetapkan spoolEnable="false" semasa ujian supaya ralat sambungan kelihatan serta-merta.

Sumber

• Migrating to Lucee from ColdFusion, Lucee Docs
• Lucee Language and Syntax Differences, Lucee Docs
• cfspreadsheet, Lucee Docs
• cfchart, Lucee Docs
• cfwebsocket, Lucee Docs
• cfdocument, Lucee Docs
• spreadsheet-cfml library, GitHub
• org.lucee:websocket-extension, Maven Central
• org.lucee:chart-extension, Maven Central