Cara Membina Papan Pemuka Masa Nyata dengan Encore.ts dan React

Papan pemuka masa nyata amat berguna dalam pelbagai aplikasi, daripada menjejak analitis tapak web kepada memantau data kewangan secara langsung atau memerhatikan peranti IoT.

? Dalam tutorial ini, kami akan menunjukkan kepada anda cara membina satu menggunakan React dan Encore.ts. Anda akan belajar membuat papan pemuka dinamik yang menstrim kemas kini serta-merta, memperkasakan anda untuk membuat keputusan yang cepat dan termaklum.

Untuk mendapatkan gambaran tentang perkara yang akan kami bina, lihat GIF produk siap dan kod sumber ini di sini. Mari selami!

Prasyarat

Sebelum kami bermula, pastikan anda memasang perkara ini pada komputer anda

• Node.js (v18 atau lebih baru)
• Npm (v10 atau lebih baru)

Apa dan Mengapa Encore

Encore.ts ialah rangka kerja sumber terbuka yang membantu anda membina hujung belakang dengan TypeScript, memastikan keselamatan jenis. Ia ringan dan pantas kerana ia tidak mempunyai sebarang kebergantungan NPM.

Apabila membangunkan sistem bahagian belakang teragih, selalunya sukar untuk meniru persekitaran pengeluaran secara tempatan, yang membawa kepada pengalaman pembangun yang lemah. Anda mungkin akhirnya berhadapan dengan banyak kerumitan hanya untuk menjalankan sesuatu secara tempatan dengan cara yang munasabah, yang mengambil masa daripada memfokuskan pada membina aplikasi sebenar. Encore.ts menangani perkara ini dengan menyediakan set alat lengkap untuk membina sistem teragih, termasuk:

• Persekitaran setempat sepadan dengan awan
• Keselamatan jenis silang perkhidmatan
• Infrastruktur sedar jenis
• Dokumen & pelanggan API automatik
• Pengesanan ujian tempatan
• Dan banyak lagi

Baiklah, kami bercakap tentang Encore dan cara ia membantu kami membina perkhidmatan bahagian belakang. Dalam bahagian seterusnya, mari pasang Encore secara setempat dan mula membina.

Memasang Encore

Untuk bekerja dengan Encore, kami perlu memasang CLI, yang menjadikannya sangat mudah untuk mencipta dan mengurus persekitaran setempat.

# macOS
brew install encoredev/tap/encore

# Windows
iwr https://encore.dev/install.ps1 | iex

# Linux
curl -L https://encore.dev/install.sh | bash

Mencipta aplikasi Encore

Membuat aplikasi Encore adalah sangat mudah, anda hanya perlu menjalankan arahan.

encore app create

Anda akan ditanya soalan berikut, jadi pilih jawapan anda dengan sewajarnya.

Select language for your applicatio : TypeScript
Template: Empty app
App Name : real-time-dashboard

Setelah Apl dibuat maka anda boleh mengesahkan konfigurasi aplikasi dalam encore.app

{
    "id":   "real-time-dashboard-<random-id>",
    "lang": "typescript"
}

Baiklah, kami telah mencipta aplikasi Encore. Mari kita bincangkan tentang API Penstriman dalam Encore dalam bahagian seterusnya.

Apakah itu API Penstriman dalam Encore

Sebelum kita bercakap tentang API penstriman, mari kita bincangkan API dalam Encore. Mencipta titik akhir API dalam Encore adalah sangat mudah kerana ia menyediakan fungsi api daripada modul encore.dev/api untuk menentukan titik akhir API dengan keselamatan jenis. Encore juga mempunyai pengesahan terbina dalam untuk permintaan masuk. Pada terasnya, API ialah fungsi async ringkas dengan struktur skema permintaan dan tindak balas. Encore menghuraikan kod dan menjana boilerplate pada masa penyusunan, jadi anda hanya perlu menumpukan pada mentakrifkan API.

API Penstriman ialah API yang membolehkan anda menghantar dan menerima data ke dan dari aplikasi anda, membenarkan komunikasi dua hala.

Encore menawarkan tiga jenis strim, setiap satu untuk arah aliran data yang berbeza:

• StreamIn: Gunakan ini untuk menstrim data ke dalam perkhidmatan anda.
• StreamOut: Gunakan ini untuk menstrim data keluar daripada perkhidmatan anda.
• StreamInOut: Gunakan ini untuk menstrim data masuk dan keluar dari perkhidmatan anda.

Apabila anda menyambung ke titik akhir API penstriman, pelanggan dan pelayan melakukan jabat tangan menggunakan permintaan HTTP. Jika pelayan menerima permintaan ini, strim dibuat untuk kedua-dua klien dan pengendali API. Strim ini sebenarnya ialah WebSocket yang membenarkan menghantar dan menerima mesej.

Baiklah, sekarang setelah kami mengetahui API dan API Penstriman dalam Encore, mari buat perkhidmatan papan pemuka kami di bahagian seterusnya dengan titik akhir API Penstriman untuk menyimpan dan mendapatkan data dalam masa nyata.

Mencipta perkhidmatan papan pemuka

Mari kita cipta perkhidmatan papan pemuka di mana kami akan menentukan API jualan kami untuk menstrim data ke dan dari papan pemuka jualan kami.

Buat folder pada peringkat akar dipanggil papan pemuka dan kemudian tambah fail encore.service.ts. Fail ini akan memberitahu Encore untuk merawat folder papan pemuka dan subfoldernya sebagai sebahagian daripada perkhidmatan.

# macOS
brew install encoredev/tap/encore

# Windows
iwr https://encore.dev/install.ps1 | iex

# Linux
curl -L https://encore.dev/install.sh | bash

Kemudian tambah kod berikut pada fail encore.service.ts. Kami mengimport kelas Perkhidmatan daripada encore.dev/service dan mencipta contoh daripadanya dengan menggunakan "papan pemuka" sebagai nama perkhidmatan.

encore app create

Sekarang mari buat fail papan pemuka.ts dan sediakan API jualan.

Select language for your applicatio : TypeScript
Template: Empty app
App Name : real-time-dashboard

Sebelum menyediakan API, kami akan menyediakan pangkalan data terlebih dahulu untuk menyimpan data jualan. Kami akan menggunakan SQLDatabase daripada modul encore.dev/storage/sqldb untuk mencipta pangkalan data PostgreSQL yang disokong oleh Encore.

Kita perlu mentakrifkan SQL sebagai migrasi, yang Encore akan ambil apabila kita melaksanakan perintah encore run.

Buat folder bernama migrasi di dalam folder papan pemuka, kemudian buat fail bernama 1_first_migration.up.sql. Pastikan anda mengikuti konvensyen penamaan, bermula dengan number_ dan berakhir dengan up.sql.

# macOS
brew install encoredev/tap/encore

# Windows
iwr https://encore.dev/install.ps1 | iex

# Linux
curl -L https://encore.dev/install.sh | bash

Di sini, kami sedang mencipta jadual yang dipanggil jualan dengan empat lajur:

• id: dinaikkan secara automatik dan berfungsi sebagai kunci utama
• jualan: tajuk jualan
• jumlah: jumlah jualan
• tarikh: tarikh jualan

Seterusnya, tambahkan kod berikut pada fail papan pemuka.ts.

encore app create

Di sini, kami mencipta contoh SQLDatabase dengan memberikannya papan pemuka nama dan menentukan laluan ke folder migrasi.

Kami menggunakan pakej postgres untuk mendengar dan memaklumkan perubahan dalam pangkalan data.

?

Seterusnya, tambahkan jenis ini dan peta dalam memori untuk memegang strim yang disambungkan (sambungan soket web).

Select language for your applicatio : TypeScript
Template: Empty app
App Name : real-time-dashboard

Seterusnya, mari sediakan titik akhir penstriman jualan untuk menghantar kemas kini apabila jualan baharu berlaku.

{
    "id":   "real-time-dashboard-<random-id>",
    "lang": "typescript"
}

Di sini kami menggunakan fungsi api.streamOut untuk mentakrifkan API, yang mengambil dua hujah:

• Pilihan Strim:
  • dedahkan: Tetapkan kepada benar untuk menjadikan titik akhir umum, jika tidak palsu
  • auth: Tetapkan kepada benar untuk melindungi titik akhir dengan pengesahan, jika tidak palsu
  • laluan: /jualan
• Fungsi: Ia memerlukan dua hujah
  • jabat tangan: Digunakan untuk mewujudkan sambungan strim
  • strim: Objek strim

Kami mengekalkan sambungan dalam peta ConnectStreams dan mendengar saluran new_sale menggunakan pelanggan Postgres. Apabila jualan baharu berlaku, kami menghantar kemas kini kepada semua strim yang disambungkan.

Seterusnya, kami akan mentakrifkan titik akhir API jualan tambah, di mana kami mendapatkan data jualan daripada badan permintaan dan menggunakan tika db untuk memasukkan rekod jualan baharu.

# create dashboard folder
mkdir dashboard

# switch to dashboard folder
cd dashboard

# create encore.service.ts file inside dashboard folder
touch encore.service.ts

Di sini, selepas menambah rekod jualan baharu pada pangkalan data, kami menggunakan pelanggan Postgres untuk menghantar pemberitahuan kepada saluran new_sale dengan data jualan. Dengan cara ini, pendengar saluran new_sale akan dimaklumkan dan boleh mengambil tindakan.

Akhir sekali, mari kita sediakan titik akhir API untuk mengembalikan senarai rekod jualan.

import { Service } from 'encore.dev/service';

export default new Service('dashboard');

Di sini, kami menggunakan pertanyaan kaedah contoh db untuk mendapatkan data dan kemudian memprosesnya untuk kembali sebagai senarai.

Bagus, kami kini mempunyai semua titik akhir API yang ditentukan. Mari terokai papan pemuka pembangunan Encore dalam bahagian seterusnya.

Meneroka papan pemuka pembangunan

Kami mempunyai titik akhir API dengan persediaan pangkalan data, tetapi bagaimanakah kami hendak menguji dan nyahpepijat perkhidmatan? Jangan risau, kerana Encore menyediakan papan pemuka Pembangunan Tempatan untuk menjadikan kehidupan pembangun lebih mudah dan meningkatkan produktiviti.

Ia termasuk beberapa ciri untuk membantu anda mereka bentuk, membangunkan dan nyahpepijat aplikasi anda:

• Katalog Perkhidmatan dan Penjelajah API untuk membuat panggilan API dengan mudah ke bahagian belakang setempat anda
• Penjejakan Teragih untuk penyahpepijatan yang mudah dan berkuasa
• Dokumentasi API Automatik untuk berkongsi pengetahuan dan menjawab soalan
• Encore Flow untuk menggambarkan seni bina perkhidmatan mikro anda

Semua ciri ini dikemas kini dalam masa nyata semasa anda menukar aplikasi anda.

Untuk mengakses papan pemuka, mulakan aplikasi Encore anda dengan larian encore, dan ia dibuka secara automatik.

# macOS
brew install encoredev/tap/encore

# Windows
iwr https://encore.dev/install.ps1 | iex

# Linux
curl -L https://encore.dev/install.sh | bash

Beginilah rupa papan pemuka dan anda boleh menguji segala-galanya secara tempatan sebelum pergi ke pengeluaran. Ini menjadikannya lebih mudah untuk menguji seni bina perkhidmatan mikro tanpa memerlukan alat luaran.

Berikut ialah contoh menambah jualan baharu menggunakan penjelajah API. Apabila anda mengklik butang Call API, anda akan mendapat respons dan log. Di sebelah kanan, anda boleh melihat kesan permintaan.

Apabila anda mengklik pada pautan jejak, anda mendapat butiran seperti pertanyaan pangkalan data, respons dan log.

Baiklah, itu sahaja tentang papan pemuka pembangunan tempatan. Anda boleh meneroka pilihan lain seperti Katalog Perkhidmatan, aliran dan banyak lagi. Dalam bahagian seterusnya, kami akan menjana pelanggan dengan keselamatan jenis TypeScript untuk digunakan dalam perkhidmatan Frontend (React Application) untuk berkomunikasi dengan API perkhidmatan papan pemuka.

Menjana pelanggan

Encore boleh menjana pelanggan permintaan bahagian hadapan dalam TypeScript atau JavaScript, mengekalkan jenis permintaan/tindak balas dalam penyegerakan dan membantu anda memanggil API tanpa usaha manual.

Buat folder bernama frontend dalam direktori akar dan jalankan arahan berikut untuk menyediakan projek React menggunakan Vite.

encore app create

Seterusnya, buat folder lib di dalam direktori src, tambahkan fail baharu bernama client.ts, dan biarkan ia kosong.

Select language for your applicatio : TypeScript
Template: Empty app
App Name : real-time-dashboard

Kemudian, dalam fail package.json, tambahkan skrip baharu yang dipanggil gen-client.

{
    "id":   "real-time-dashboard-<random-id>",
    "lang": "typescript"
}

Seterusnya, jalankan skrip untuk mencipta klien dalam src/lib/client.ts.

# create dashboard folder
mkdir dashboard

# switch to dashboard folder
cd dashboard

# create encore.service.ts file inside dashboard folder
touch encore.service.ts

Fail src/lib/client.ts hendaklah mengandungi kod yang dijana.

import { Service } from 'encore.dev/service';

export default new Service('dashboard');

Seterusnya, buat fail bernama getRequestClient.ts dalam direktori lib dan tambahkan kod berikut. Ini akan mengembalikan tika Klien berdasarkan persekitaran.

# make sure you are in dashboard folder
touch dashboard.ts

Baiklah, kini kami mempunyai pelanggan untuk digunakan dalam aplikasi React untuk memanggil API papan pemuka. Dalam bahagian seterusnya, mari buat perkhidmatan bahagian hadapan dan bina UI untuk papan pemuka jualan masa nyata.

Mencipta perkhidmatan bahagian hadapan

Dalam bahagian sebelumnya, kami menyediakan folder bahagian hadapan dengan aplikasi React, dan kini kami mahu menjadikannya sebagai perkhidmatan. Mari buat fail encore.service.ts dan tambahkan kod berikut untuk memberitahu Encore untuk merawat folder bahagian hadapan sebagai perkhidmatan "penghulu".

# macOS
brew install encoredev/tap/encore

# Windows
iwr https://encore.dev/install.ps1 | iex

# Linux
curl -L https://encore.dev/install.sh | bash

Kami ada dua pilihan:

• Layankan perkhidmatan papan pemuka dan bahagian hadapan secara berasingan
• Hidangkan semuanya sebagai satu berkas (kami akan menggunakan pendekatan ini untuk tutorial ini)

Untuk menyediakan aplikasi React, kami perlu membina dan menyediakannya sebagai aset statik dalam Encore. Mari sediakan fail static.ts dalam folder bahagian hadapan.

Menyajikan fail statik dalam Encore.ts adalah serupa dengan titik akhir API biasa, tetapi sebaliknya kami menggunakan fungsi api.static.

encore app create

Berikut ialah dua perkara penting yang perlu diberi perhatian: kami melepasi laluan dan pilihan dir.

• laluan: /!path memastikan ia bertindak sebagai laluan sandaran dan tidak bercanggah dengan titik akhir yang lain.
• dir: ./dist ialah direktori versi binaan aplikasi React.

Bagus, titik akhir statik disediakan. Sekarang, mari pasang beberapa kebergantungan untuk aplikasi React kami

• react-router-dom
• uuid
• css tailwind

Select language for your applicatio : TypeScript
Template: Empty app
App Name : real-time-dashboard

Kemudian kemas kini main.tsx dengan kod di bawah.

{
    "id":   "real-time-dashboard-<random-id>",
    "lang": "typescript"
}

Seterusnya, mari sediakan CSS Tailwind dan kemas kini beberapa fail.

# create dashboard folder
mkdir dashboard

# switch to dashboard folder
cd dashboard

# create encore.service.ts file inside dashboard folder
touch encore.service.ts

Tukar bahagian kandungan dalam tailwind.config.js

import { Service } from 'encore.dev/service';

export default new Service('dashboard');

Dan index.css dengan kod berikut.

# make sure you are in dashboard folder
touch dashboard.ts

Sekarang mari kita buat beberapa komponen untuk papan pemuka jualan.

• Jadual Jualan: untuk memaparkan data jualan dalam format jadual.

# 1_first_migration.up.sql

CREATE TABLE sales (
    id BIGSERIAL PRIMARY KEY,
    sale VARCHAR(255) NOT NULL,
    total INTEGER NOT NULL,
    date DATE NOT NULL
);

Di sini, kami mengimport jenis daripada klien yang dijana untuk memadankan jenis perkhidmatan papan pemuka dan memastikan keselamatan jenis.

• Metrik Jualan: untuk menunjukkan beberapa nombor jualan seperti jumlah jualan, terendah dan purata.

# dashboard.ts

import { SQLDatabase } from 'encore.dev/storage/sqldb';
import postgres from 'postgres';

const db = new SQLDatabase('dashboard', {
  migrations: './migrations',
});

const client = postgres(db.connectionString);

• RoleSelector: Untuk membenarkan pengguna memilih peranan untuk papan pemuka, kami akan menunjukkan dua pilihan:
  • Penonton: Boleh melihat papan pemuka jualan
  • Pengurus: Boleh melihat dan mencipta jualan baharu

# dashboard.ts

...

// Map to hold all connected streams
const connectedStreams: Map<string, StreamOut<Sale>> = new Map();

interface HandshakeRequest {
  id: string;
}

interface Sale {
  sale: string;
  total: number;
  date: string;
}

interface ListResponse {
  sales: Sale[];
}

• Jana Jualan: untuk memaparkan butang jana jualan dan mengandungi logik untuk menjana jualan.

Untuk menjana jualan, kami memerlukan beberapa data olok-olok, jadi mari buat fail src/constant.ts dan tambah data olok-olok

# dashboard.ts
...

import { api, StreamOut } from 'encore.dev/api';
import log from 'encore.dev/log';

...

export const sale = api.streamOut<HandshakeRequest, Sale>(
  { expose: true, auth: false, path: '/sale' },
  async (handshake, stream) => {
    connectedStreams.set(handshake.id, stream);

    try {
      await client.listen('new_sale', async function (data) {
        const payload: Sale = JSON.parse(data ?? '');

        for (const [key, val] of connectedStreams) {
          try {
            // Send the users message to all connected clients.
            await val.send({ ...payload });
          } catch (err) {
            // If there is an error sending the message, remove the client from the map.
            connectedStreams.delete(key);
            log.error('error sending', err);
          }
        }
      });
    } catch (err) {
      // If there is an error reading from the stream, remove the client from the map.
      connectedStreams.delete(handshake.id);
      log.error('stream error', err);
    }
  }
);

# dashboard.ts
...
...

export const addSale = api(
  { expose: true, method: 'POST', path: '/sale/add' },
  async (body: Sale & { id: string }): Promise<void> => {
    await db.exec`
      INSERT INTO sales (sale, total, date)
      VALUES (${body.sale}, ${body.total}, ${body.date})`;

    await client.notify(
      'new_sale',
      JSON.stringify({ sale: body.sale, total: body.total, date: body.date })
    );
  }
);

Di sini, kami mengimport getRequestClient dan kemudian memanggil titik akhir addSale daripada perkhidmatan papan pemuka. Ia sangat mudah dan addSale selamat jenis, jadi jika anda cuba menghantar sebarang atribut yang tidak dibenarkan, anda akan mendapat ralat.

Seterusnya, mari buat komponen SalesDashboard untuk menunjukkan paparan papan pemuka dengan metrik jualan, jualan terkini dan jualan sepanjang masa.

# macOS
brew install encoredev/tap/encore

# Windows
iwr https://encore.dev/install.ps1 | iex

# Linux
curl -L https://encore.dev/install.sh | bash

SalesDashboard mengambil satu prop yang dipanggil peranan, yang menentukan sama ada ia akan menunjukkan komponen GenerateSales.

SalesStream akan memegang rujukan strim aktif dan ditaip dengan kuat.

encore app create

Apabila komponen dipasang, kami membuat sambungan strim menggunakan titik akhir jualan perkhidmatan papan pemuka. Kami kemudian mendengar acara buka dan tutup soket dan menjalankan logik yang sesuai berdasarkan peristiwa ini.

Kami membaca data jualan daripada saleStream.current dan menyimpannya dalam keadaan baru-baru iniSalesData.

Apabila komponen dinyahlekap, kami membersihkan dan menutup aliran semasa.

Select language for your applicatio : TypeScript
Template: Empty app
App Name : real-time-dashboard

Kod ini mendapatkan jualan yang disimpan menggunakan titik akhir listSales daripada perkhidmatan papan pemuka dan menyimpannya dalam keadaan salesData.

{
    "id":   "real-time-dashboard-<random-id>",
    "lang": "typescript"
}

Kod ini mengira jualan terkini dan data jualan sepanjang masa.

# create dashboard folder
mkdir dashboard

# switch to dashboard folder
cd dashboard

# create encore.service.ts file inside dashboard folder
touch encore.service.ts

Akhir sekali, kemas kini fail App.tsx dengan kod ini.

import { Service } from 'encore.dev/service';

export default new Service('dashboard');

Di sini, kami menunjukkan komponen SalesDashboard dan RoleSelector berdasarkan sama ada parameter pertanyaan peranan tersedia atau tidak.

Sekarang, mari bina aplikasi React dengan menjalankan arahan di bawah dalam akar bahagian hadapan.

# make sure you are in dashboard folder
touch dashboard.ts

Setelah anda berjaya menjalankan arahan, folder dist akan dibuat di dalam direktori bahagian hadapan.

Bagus, sekarang dalam bahagian seterusnya, mari jalankan aplikasi dan ujinya dari awal hingga akhir.

Menjalankan aplikasi

Menjalankan aplikasi encore adalah mudah; hanya gunakan arahan di bawah.

# 1_first_migration.up.sql

CREATE TABLE sales (
    id BIGSERIAL PRIMARY KEY,
    sale VARCHAR(255) NOT NULL,
    total INTEGER NOT NULL,
    date DATE NOT NULL
);

Sebaik sahaja anda menjalankan arahan dengan jayanya, anda akan melihat log dalam terminal seperti ini:

# dashboard.ts

import { SQLDatabase } from 'encore.dev/storage/sqldb';
import postgres from 'postgres';

const db = new SQLDatabase('dashboard', {
  migrations: './migrations',
});

const client = postgres(db.connectionString);

Lawati http://127.0.0.1:4000 dalam penyemak imbas anda, dan anda akan melihat skrin seperti di bawah.

Seterusnya, pilih Pemapar dalam satu tab dan Pengurus dalam tab lain.

• Penonton

• Pengurus

Semasa menyemak papan pemuka pembangunan, kami mencipta rekod jualan dan ia disimpan dalam pangkalan data, jadi ia juga boleh dilihat dalam UI.

Sekarang, dari paparan pengurus, klik pada butang Jana Jualan dan lihat kedua-dua tab pada papan pemuka dikemas kini dalam masa nyata.

Ringkasan

Dalam tutorial ini, kami mencipta papan pemuka jualan masa nyata menggunakan React dan Encore.ts. Apl dikemas kini serta-merta dengan item jualan dan inventori baharu, membantu dengan keputusan pantas. Kami menggunakan Encore.ts, rangka kerja sumber terbuka, untuk membina bahagian belakang dengan TypeScript untuk pengekodan yang selamat dan lancar. Ciri utama Encore ialah:

1. Keselamatan Jenis: Pastikan semua titik akhir API dan struktur data selamat, mengurangkan kesilapan dan menjadikan kod lebih dipercayai.
2. API Penstriman: Membenarkan penstriman data masa nyata dengan StreamIn, StreamOut dan StreamInOut, membolehkan komunikasi dua hala antara klien dan pelayan.
3. Papan Pemuka Pembangunan Setempat: Menawarkan alatan untuk ujian dan penyahpepijatan, seperti Katalog Perkhidmatan, Penjelajah API dan Pengesanan Teragih, meningkatkan produktiviti.
4. Penjanaan Pelanggan Automatik: Mencipta pelanggan permintaan bahagian hadapan dalam TypeScript atau JavaScript, memastikan jenis permintaan/tindak balas sejajar.
5. Perkhidmatan Mikro Ringkas: Membolehkan anda membina apl dengan berbilang perkhidmatan tanpa kerumitan biasa, menyediakan cara yang lebih mudah untuk mengendalikan perkhidmatan mikro.

Ciri-ciri ini bersama-sama menjadikannya lebih mudah untuk membina dan mengurus apl yang kompleks, menawarkan pengalaman pembangun yang hebat.

Pautan yang berkaitan

• Star Encore di GitHub
• Cari Kod Sumber untuk contoh ini
• Sertai Komuniti Discord kami

Atas ialah kandungan terperinci Cara Membina Papan Pemuka Masa Nyata dengan Encore.ts dan React. Untuk maklumat lanjut, sila ikut artikel berkaitan lain di laman web China PHP!