Membina REST API dengan Lucee: Panduan Lengkap

Membina REST API dengan Lucee: Panduan Lengkap

REST ialah seni bina untuk pemindahan data tanpa keadaan melalui HTTP. Lucee membolehkan anda mentakrifkan perkhidmatan REST menggunakan komponen CFC dengan atribut khas, dan servlet RestServlet yang disertakan bersama Lucee mengendalikan penghalaan permintaan kepadanya. Artikel ini membimbing anda daripada pendaftaran perkhidmatan hingga menguji endpoint dengan curl, termasuk pengendalian ralat dan pengesahan asas.

Cara Lucee Menghidangkan REST

Permintaan REST dijalankan oleh servlet tambahan bernama RestServlet yang disertakan bersama Lucee dan sudah didayakan dalam Tomcat secara lalai. Ini bermakna anda tidak perlu membuat konfigurasi tambahan pada Tomcat. Yang perlu anda lakukan ialah mendaftarkan perkhidmatan REST dengan aplikasi anda, kemudian menulis komponen dengan fungsi remote. Lucee menghantar data REST dalam format JSON secara lalai.

Mendaftar Perkhidmatan REST

Ada dua cara mendaftar perkhidmatan. Cara pertama melalui pentadbir, di mana anda menambah pemetaan dalam bahagian Archives & Resources, Rest dengan nilai Virtual dan Physical. Cara kedua ialah secara programatik dalam Application.cfc menggunakan fungsi restInitApplication:

component {
    this.name = "apiKedai";

    restInitApplication(
        dirPath = getDirectoryFromPath(getCurrentTemplatePath()) & "rest",
        serviceMapping = "kedai",
        password = "kataLaluanPentadbir"
    );
}

Satu keperluan penting yang didokumenkan: Application.cfc tidak dijalankan oleh permintaan REST tulen, jadi anda mesti melawat satu templat .cfm dahulu untuk mencetuskan Application.cfc dan mendaftarkan pemetaan. Buat fail index.cfm kosong dan bukanya dalam pelayar sebelum menguji API. Untuk konfigurasi aplikasi lain, rujuk panduan memahami Application.cfc.

Komponen dan Fungsi Remote

Komponen REST ialah CFC biasa yang ditanda dengan atribut rest dan restpath. Fungsi di dalamnya ditanda dengan access="remote" supaya boleh dipanggil melalui HTTP. Contoh komponen Sistem daripada dokumentasi Lucee menunjukkan polanya:

component rest="true" restpath="/sistem" {

    remote struct function getOS() httpmethod="GET" restpath="os" {
        return server.os;
    }

}

Apabila didaftarkan dengan pemetaan kedai, endpoint ini boleh diakses pada /rest/kedai/sistem/os. Asas menulis CFC dibincangkan dalam panduan fungsi dan komponen CFC.

Atribut restPath dan httpMethod

restpath mentakrifkan laluan yang memanggil komponen atau fungsi, membolehkan anda memilih laluan sendiri dan bukannya menggunakan nama komponen. httpMethod menetapkan kata kerja HTTP yang diterima, dengan nilai lazim GET, POST, PUT, DELETE, HEAD dan OPTIONS. Sejak Lucee 6.1.0.155, satu fungsi boleh menerima berbilang kaedah, berguna untuk GET yang juga perlu menjawab permintaan HEAD:

remote string function status() httpmethod="GET,HEAD" restpath="status" {
    return "ok";
}

Kata kerja UPDATE juga disokong selain PUT dan POST. Pilih kata kerja yang selari dengan tindakan anda supaya API mengikut konvensyen REST.

Menerima Data Permintaan

Atribut restArgSource pada argumen fungsi menentukan dari mana nilai diambil. Nilai yang disokong termasuk Path, Query, Form, Header dan Cookie, dengan restArgName untuk menamakan pemboleh ubah permintaan. Ini membolehkan anda membaca parameter laluan dan rentetan query secara langsung:

component rest="true" restpath="/produk" {

    remote struct function cari(string kategori restArgsource="query")
        httpmethod="GET" restpath="/cari" {
        return { kategori = arguments.kategori };
    }

    remote struct function satu(string id restArgsource="path")
        httpmethod="GET" restpath="/{id}" {
        return { id = arguments.id };
    }

}

Perhatikan bahawa restpath khusus seperti /cari mesti diletakkan sebelum restpath generik seperti /{id}, kerana Lucee memadankan fungsi mengikut urutan takrifan.

returnformat json dan Format Pulangan

Untuk panggilan remote biasa di luar servlet REST, atribut returnformat pada cffunction menentukan format nilai pulangan kepada pemanggil, dengan nilai json, xml, plain, serialize, wddx dan java. Dalam perkhidmatan REST pula, JSON ialah format lalai, dan atribut produces mengawal jenis kandungan respons manakala consumes menetapkan jenis kandungan permintaan yang dijangkakan. Anda juga boleh menukar format dengan sambungan fail dalam URL, contohnya menambah .json atau .xml pada hujung endpoint.

Fungsi serializeJSON menukar objek CFML kepada rentetan JSON apabila anda perlu membina respons secara manual:

data = { nama = "Thalhah", peranan = "admin" };
json = serializeJSON(data);

Pengendalian Ralat dan Kod Status

API yang baik memulangkan kod status HTTP yang betul, bukan sentiasa 200. Tag cfheader dengan atribut statusCode menetapkan kod status, dan statusText menambah penerangan. Gabungkan dengan try dan catch untuk memulangkan ralat berstruktur:

remote struct function satu(string id restArgsource="path")
    httpmethod="GET" restpath="/{id}" {

    try {
        if (len(arguments.id) == 0) {
            throw("ID diperlukan");
        }
        return { id = arguments.id, nama = "Contoh" };
    } catch (any e) {
        cfheader(statuscode = 400, statustext = "Permintaan tidak sah");
        return { ralat = e.message };
    }

}

Gunakan 404 untuk sumber yang tidak wujud, 400 untuk input tidak sah, 401 untuk tidak disahkan dan 500 untuk kegagalan pelayan. Memulangkan struktur JSON yang konsisten memudahkan klien mengendalikan semua keadaan.

Pengesahan Asas

Endpoint sensitif perlu mengesahkan pemanggil. Pendekatan mudah ialah memerlukan token atau kunci API dalam pengepala permintaan dan menyemaknya pada awal fungsi, memulangkan 401 jika tidak sah. Untuk pengesahan berasaskan sesi, Lucee menyediakan fungsi getAuthUser yang memulangkan nama pengguna yang disahkan melalui cflogin. Tanpa mengira kaedah, jangan sekali-kali mendedahkan data sensitif sebelum pengesahan disahkan, dan hantar token melalui HTTPS.

remote struct function rahsia() httpmethod="GET" restpath="rahsia" {

    if (cgi.http_authorization != "Bearer tokenRahsia") {
        cfheader(statuscode = 401);
        return { ralat = "Tidak disahkan" };
    }
    return { data = "Maklumat sensitif" };

}

Pertahanan lanjut terhadap serangan web dibincangkan dalam panduan keselamatan aplikasi web CFML.

Contoh Hujung Titik Penuh

Contoh berikut menggabungkan semuanya: satu komponen produk dengan senarai, satu item dan penciptaan, disertakan pengendalian ralat. Simpan ia sebagai Produk.cfc dalam direktori rest yang dirujuk oleh restInitApplication:

component rest="true" restpath="/produk" {

    remote array function senarai() httpmethod="GET" restpath="" {
        return queryExecute(
            "SELECT id, nama FROM produk ORDER BY nama",
            {}, { datasource = "kedai" }
        );
    }

    remote struct function satu(required string id restArgsource="path")
        httpmethod="GET" restpath="/{id}" {
        var q = queryExecute(
            "SELECT id, nama FROM produk WHERE id = :id",
            { id = { value = arguments.id, cfsqltype = "cf_sql_integer" } },
            { datasource = "kedai" }
        );
        if (q.recordCount == 0) {
            cfheader(statuscode = 404);
            return { ralat = "Tidak dijumpai" };
        }
        return { id = q.id, nama = q.nama };
    }

    remote struct function cipta(required string nama restArgsource="form")
        httpmethod="POST" restpath="" {
        try {
            queryExecute(
                "INSERT INTO produk (nama) VALUES (:nama)",
                { nama = { value = arguments.nama, cfsqltype = "cf_sql_varchar" } },
                { datasource = "kedai" }
            );
            return { berjaya = true };
        } catch (any e) {
            cfheader(statuscode = 400);
            return { ralat = e.message };
        }
    }

}

Parameterisasi query dalam contoh ini mengikut amalan dalam panduan cfquery dan cfqueryparam, dan sambungan pangkalan data dirujuk melalui datasource yang dijelaskan dalam panduan konfigurasi datasource.

Menguji dengan curl

Selepas memetakan perkhidmatan dan melawat index.cfm sekali, anda boleh menguji endpoint dengan curl. Contoh untuk senarai produk dan mendapatkan satu item:

curl http://localhost:8888/rest/kedai/produk
curl http://localhost:8888/rest/kedai/produk/42

Untuk permintaan POST dengan data borang, tambah -d dan -X POST. Bendera -i memaparkan pengepala respons supaya anda dapat mengesahkan kod status:

curl -i -X POST -d "nama=Pensel" http://localhost:8888/rest/kedai/produk

Jika endpoint tidak ditemui, semak dahulu sama ada anda sudah melawat fail .cfm untuk mencetuskan pendaftaran, dan pastikan kata laluan pentadbir dalam restInitApplication betul.

Kod Status HTTP yang Lazim

API yang baik memulangkan kod status yang betul dan bukannya sentiasa 200. Tetapkan kod melalui cfheader dengan atribut statusCode.

Memulangkan kod yang tepat memudahkan klien mengendalikan setiap keadaan dengan betul.

Soalan Lazim (FAQ)

Bagaimana cara mendaftar perkhidmatan REST dalam Lucee?

Guna restInitApplication dalam Application.cfc dengan dirPath, serviceMapping dan password, atau tambah pemetaan Virtual dan Physical dalam pentadbir di bawah Archives & Resources, Rest.

Apakah fungsi returnformat json dalam API CFML?

Atribut returnformat pada fungsi remote menentukan format nilai pulangan, contohnya json. Dalam servlet REST, JSON ialah format lalai dan boleh ditukar dengan atribut produces atau sambungan fail dalam URL.

Bagaimana cara memulangkan kod status HTTP daripada endpoint?

Guna tag cfheader dengan atribut statusCode, contohnya cfheader(statuscode = 404) untuk sumber yang tidak wujud, dan sertakan statusText untuk keterangan.

Bagaimana cara membaca parameter laluan seperti /produk/42?

Tandakan argumen fungsi dengan restArgsource="path" dan letakkan penanda bernama dalam restpath, contohnya restpath="/{id}", supaya Lucee mengisi argumen id daripada laluan.

Bagaimana cara menguji REST API Lucee tanpa pelayar?

Guna curl, contohnya curl http://localhost:8888/rest/kedai/produk, dan tambah -i untuk melihat kod status dan pengepala respons.

Sumber

• REST Services with Lucee, docs.lucee.org
• cffunction, docs.lucee.org
• cfheader, docs.lucee.org
• GetAuthUser(), docs.lucee.org
• serializeJSON(), docs.lucee.org
• Lucee on GitHub