مقدمه هیلا: چارچوب جاوای تمام پشته

بر اساس Vaadin Fusion، Hilla یک بخش جلویی فعال جاوا اسکریپت را با یک انتهای پشتی جاوا Spring برای توسعه وب تمام پشته ترکیب می کند. بیایید با حله شروع کنیم.

Hilla یک پایانه پشتی جاوا ساخته شده در Spring را با یک قسمت جلویی TypeScript ساخته شده با Lit، سریع ترکیب می کند ، چارچوب واکنشی برای جاوا اسکریپت. Hilla، که بر اساس Vaadin Fusion ساخته شده است، یک حیوان منحصر به فرد در اکوسیستم جاوا است: چیزی شبیه به Next.js برای جاوا اسکریپت، اما با یک جاوا مبتنی بر Spring. این مقاله شما را با Hilla شروع می‌کند، از جمله نحوه داربست کردن یک برنامه وب پایه، ساخت قسمت جلویی و افزودن اجزای جدید.

حله و وادین

توسعه دهندگان Vaadin در ژانویه امسال اعلام کردند که نام Vaadin Fusion را به Hilla تغییر می دهند. برای توسعه دهندگانی که قبلاً با Fusion آشنا هستند، فقط نام آن تغییر کرده است. برای توسعه‌دهندگانی که به تازگی Hilla را کشف کرده‌اند، متوجه خواهید شد که نمونه‌های این مقاله از بسته‌ها و مؤلفه‌های نام‌گذاری شده برای Vaadin استفاده می‌کنند. بسته‌های Vaadin Fusion در نسخه بعدی به Hilla تغییر نام خواهند داد.

توسعه وب جاوا با بخش جلویی واکنشی

Hilla یک بخش جلویی جاوا اسکریپت واکنش‌پذیر و یک انتهای پشتی جاوا Spring را در یک ساخت واحد گرد هم می‌آورد. مثال‌های این مقاله به شما نشان می‌دهند که چگونه این مؤلفه‌ها با هم کار می‌کنند تا هیلا را به یک چارچوب تمام پشته تبدیل کنند. برای پیگیری، به Node.js (npm) و JDK اخیری که روی سیستم شما نصب شده است نیاز دارید. مطمئن شوید که هم node -v و هم java –version کار می کنند!

برای شروع، خط فرمان خود را باز کنید و یک پروژه جدید را از طریق npx، همانطور که در فهرست ۱ نشان داده شده است، داربست کنید.

npx @vaadin/cli init --hilla foundry-hilla

اکنون، cd را در فهرست راهنمای جدید وارد کنید و ./mvnw (یا mvnw را برای Windows) تایپ کنید. این دستور ساخت Maven را آغاز می کند. گزارش خروجی را برای هر دو قسمت پشتی و جلویی در حال ساخت مشاهده خواهید کرد. به زودی، برنامه در حالت توسعه دهنده راه اندازی می شود.

شکل ۱. از localhost:8080 دیدن کنید، و باید برنامه Hilla خود را در حال اجرا و اجرا ببینید.

اگر به فایل سیستمی که به تازگی ساخته اید نگاهی بیندازید، خواهید دید که ساختار به یک ساختار استاندارد Maven و یک فهرست جلویی تقسیم شده است:

• /project-root
  • /frontend
    • html
    • ts
    • ts
    • /stores
    • /موضوعات
    • /views
  • /src
  • /target

• /frontend
  • html
  • ts
  • ts
  • /stores
  • /موضوعات
  • /views
• /src
• /target

• html
• ts
• ts
• /stores
• /موضوعات
• /views

ریت پروژه حاوی فایل ساخت Maven (pom.xml) است که کد جاوا را از /src به /target می‌سازد و به ابزار ساخت جاوا اسکریپت فراخوانی می‌کند. (vite.js) برای ساخت برنامه front-end موجود در /frontend.

قسمت جلویی را بسازید

در Hilla، قسمت جلویی از مسیرهای /front-end/index.html، /front-end/index.ts و بوت استرپ شده است. فایل های .ts. این فایل ها با هم مسیریابی را تعیین می کنند و محتوا را روی صفحه مسیر داده شده تنظیم می کنند. آموزنده ترین این صفحات routes.ts است که در فهرست ۲ دیده می شود.

import { Route } from '@vaadin/router';
import './views/helloworld/hello-world-view';
import './views/main-layout';
export type ViewRoute = Route & {
 title?: string;
 icon?: string;
 children?: ViewRoute[];
};
export const views: ViewRoute[] = [
 // place routes below (more info https://vaadin.com/docs/latest/fusion/routing/overview)
 {
   path: '',
   component: 'hello-world-view',
   icon: '',
   title: '',
 },
 {
   path: 'hello',
   component: 'hello-world-view',
   icon: 'la la-globe',
   title: 'Hello World',
 },
 {
   path: 'about',
   component: 'about-view',
   icon: 'la la-file',
   title: 'About',
   action: async (_context, _command) => {
     await import('./views/about/about-view');
     return;
   },
 },
];
export const routes: ViewRoute[] = [
 {
   path: '',
   component: 'main-layout',
   children: [...views],
 },
];

کد موجود در فهرست ۲ یک مسیر را با یک جزء مرتبط می کند. مانند بسیاری از چارچوب‌های جاوا اسکریپت، Hilla از یک مؤلفه برای نمایش یک View استفاده می‌کند. در این حالت، وقتی کاربر به مسیر خالی می‌رود، مؤلفه hello-world-view را ارائه می‌کند. (توجه داشته باشید که مسیرهای دیگر اطلاعات اضافی مانند نماد، عنوان و اقدام را ارائه می دهند.)

طرح‌بندی اصلی توسط /frontend/views/main-layout.ts مدیریت می‌شود، در حالی که محتوای hello-world-view در / یافت می‌شود. frontend/views/helloworld/hello-world-view.ts، نشان داده شده در فهرست ۳. 

import '@vaadin/button';
import '@vaadin/notification';
import { Notification } from '@vaadin/notification';
import '@vaadin/text-field';
import { html } from 'lit';
import { customElement } from 'lit/decorators.js';
import { View } from '../../views/view';
@customElement('hello-world-view')
export class HelloWorldView extends View {
 name = '';
 connectedCallback() {
   super.connectedCallback();
   this.classList.add('flex', 'p-m', 'gap-m', 'items-end');
 }
 render() {
   return html`
     <vaadin-text-field label="Your name" @value-changed=${this.nameChanged}></vaadin-text-field>
     <vaadin-button @click=${this.sayHello}>Say hello</vaadin-button>
   `;
 }
 nameChanged(e: CustomEvent) {
   this.name = e.detail.value;
 }
 sayHello() {
   Notification.show(`Hello ${this.name}`);
 }
}

کد موجود در فهرست ۳ لیت را نشان می دهد که نمای را می سازد. اگر با اصطلاحات واکنشی جاوا اسکریپت آشنا هستید، منبع باید کاملا واضح باشد. اگر نه، به معرفی اخیر من به Lit مراجعه کنید. متد render() وظیفه خروجی‌گیری محتوای view را بر عهده دارد. ما در اینجا از آن به عنوان مکانی برای کشف چیزها استفاده خواهیم کرد. به طور خاص، می‌خواهیم ببینیم که چگونه این قسمت جلویی را با نقاط انتهایی جاوای خود متصل کنیم.

نقاط پایانی جاوا را ایجاد کنید

Hilla در بالای Spring Boot ساخته شده است، بنابراین ما می توانیم نقاط پایانی را با استفاده از Spring Web به طور معمول بسازیم. Hilla برای تولید خودکار TypeScript که در قسمت جلویی Lit مصرف می شود، عملکردهای اضافی ارائه می دهد.

با ایجاد یک فایل جدید در /src/java/main/com/example/application به نام MyEndpoint.java شروع کنید. محتوای فهرست ۴ را در این فایل جای‌گذاری کنید.

package com.example.application;

import com.vaadin.flow.server.auth.AnonymousAllowed;
import dev.hilla.Endpoint;
import dev.hilla.Nonnull;

@Endpoint
@AnonymousAllowed
Public @Nonnull class MyEndpoint {
   public String foo() {
       return "bar";
   }
}

حاشیه نویسی

Hilla @Endpoint به چارچوبی که این کلاس یک REST API است می گوید. کلاس همچنین با حاشیه نویسی @AnonymousAllowed حاشیه نویسی می شود زیرا Hilla به طور پیش فرض تمام نقاط پایانی را از طریق امنیت Spring ایمن می کند. حاشیه نویسی @Nonnull نوع اتصال مناسب را برای TypeScript جلویی ایجاد می کند.

پس از ذخیره این فایل کلاس، می توانید مشاهده کنید که Hilla یک فایل TypeScript جدید در /frontend/generated/MyEndpoint.ts ایجاد کرده است. ما از این ماژول برای ضربه زدن به نقطه پایانی از نمای استفاده خواهیم کرد.

توجه: در این فایل های تولید شده تغییراتی ایجاد نکنید. Hilla آنها را بر اساس تغییرات در فایل جاوا بازنویسی می کند.

اکنون، به frontend/views/helloworld/hello-world-view.ts برگردید، جایی که نقطه پایانی ساده خود را به کار می‌گیریم. در این مورد، ما می خواهیم محتوای فراخوانی نقطه پایانی foo() (که “bar” است) را خروجی بگیریم. فهرست ۵ اضافه‌هایی را نشان می‌دهد که باید در فایل hello-world-view.ts  ایجاد کنید. (توجه داشته باشید که من اکثر کدهای قبلی را حذف کرده ام و فقط موارد اضافه شده را برای این فهرست باقی گذاشته ام.) 

//...
import { customElement,property } from 'lit/decorators.js';
import { foo } from 'Frontend/generated/MyEndpoint';

@customElement('hello-world-view')
export class HelloWorldView extends View {
  //...
  @property()
  myString: string = "";
  constructor() {
    super();
    this.getString();
  }
  render() {
     return html`
     //...
     <div>${this.myString}</div>
   `;
 }

  async getString() {
     this.myString = await foo();
   }
}

نکته اصلی در اینجا این است که تابع foo() را از ماژول MyEndpoint وارد کنید، سپس از آن برای برقراری تماس با متد پشتیبان راه دور جاوا استفاده کنید. قبلاً تعریف شده است.

برای انجام این کار، یک ویژگی واکنش‌پذیر در کلاس با حاشیه‌نویسی Lit TypeScript @property، با نام string تعریف می‌کنیم. ما از این ویژگی برای ذخیره مقدار از سرور استفاده خواهیم کرد. برای پر کردن آن، متد async getString() را فراخوانی می‌کنیم که به سادگی تابع foo() را فراخوانی می‌کند و مقدار بازگشتی را در myString قرار می‌دهد. .

هیلا بیشتر کارها را انجام می دهد، از جمله ساخت واکشی از راه دور، بنابراین لازم نیست زیاد در مورد آن فکر کنیم.

استفاده از اجزای Vaadin در Hilla

همانطور که قبلاً اشاره کردم، Hilla Vaadin Fusion است، بنابراین برنامه های ساخته شده با Hilla می توانند مزیت همه  مولفه‌های خوب طراحی‌شده که ممکن است از آن چارچوب بشناسید. به عنوان مثال، اجازه دهید از یک جزء شبکه Vaadin برای بارگذاری مجموعه‌ای از رمان‌ها با عنوان و نویسندگانشان استفاده کنیم.

ابتدا، یک شی مدل ایجاد می کنیم که به سادگی دو رشته را نگه می دارد، همانطور که در لیست ۶ نشان داده شده است. این فایل یک شی داده معمولی جاوا است. آن را به عنوان /src/main/java/com/example/application/Novel.java ذخیره کنید.

package com.example.application;
import javax.validation.constraints.NotBlank;
public class Novel {
   @NotBlank
   private String title;
   @NotBlank
   private String author;
   public Novel(String title, String author){
     this.title = title;
     this.author = author;
   }
   public String getTitle() {
       return title;
   }
   public void setTitle(String title) {
       this.title = title;
   }
   public String getAuthor() {
       return author;
   }
   public void setAuthor(String author) {
       this.author = author;
   }
}

در فهرست ۷، فهرست از رمان‌های MyEndpoint ارائه می‌کنیم.

package com.example.application;
import java.util.*;
import java.util.ArrayList;
import java.util.List;
import com.vaadin.flow.server.auth.AnonymousAllowed;
import dev.hilla.Endpoint;
import dev.hilla.Nonnull;
@Endpoint
@AnonymousAllowed
public class MyEndpoint {
   private final List<Novel> novels = new ArrayList<Novel>();
   MyEndpoint(){
     Novel empireFalls = new Novel("Empire Falls", "Richard Russo");
     Novel reservationBlues = new Novel("Reservation Blues", "Sherman Alexie");
     Novel theAthenianMurders = new Novel("The Athenian Murders", "José Carlos Somoza");
     this.novels.add(empireFalls);
     this.novels.add(reservationBlues);
     this.novels.add(theAthenianMurders);
   }

   public @Nonnull List<Novel> getNovels() {
     return this.novels;
   }
}

در فهرست ۷، چند رمان با نویسندگان آنها آماده کردیم و آنها را در ویژگی novels قرار دادیم. سپس داده‌ها را در نقطه پایانی getNovels() قرار دادیم.

اکنون، اجازه دهید داده‌های جدید را همانطور که در فهرست ۸ مشاهده می‌شود، نمایش دهیم. (توجه داشته باشید که فهرست ۸ فقط بخش‌های تغییر یافته کد را نشان می‌دهد.) 

//...
import { foo, getNovels } from 'Frontend/generated/MyEndpoint';
import '@vaadin/grid/vaadin-grid';
@customElement('hello-world-view')
export class HelloWorldView extends View {
 @property()
 novels: object = {};
 constructor() {
   //...
   this.initNovels();
 }
 render() {
   return html`
     <vaadin-grid .items="${this.novels}" theme="row-stripes">
       <vaadin-grid-column path="title"></vaadin-grid-column>
       <vaadin-grid-column path="author"></vaadin-grid-column>
     </vaadin-grid>
   `;
 }
  async initNovels(){
     this.novels = await getNovels();
}

در این فهرست، ما شیء getNovels را از frontend/generated/MyEndpont وارد می‌کنیم که هیلا برای ما ایجاد کرده است. سپس از آن روش به عنوان منبع محتوای this.novels استفاده می کنیم.

بعد، از this.novels برای ارائه ویژگی .items به مؤلفه vaadin-grid وارد شده استفاده می کنیم. نتیجه نهایی یک جزء شبکه با قالب بندی زیبا با حداقل تلاش است.

نتیجه گیری

این مقاله هیلا را معرفی می‌کند، یک چارچوب فول پشته مبتنی بر Vaadin Fusion. Hilla یک تجربه خوب یکپارچه برای ساخت برنامه های وب جاوا با یک جلوی واکنشی ارائه می دهد. با تشکر از Vaadin، بسیاری از اجزای مفید آماده استفاده است. مثال‌های موجود در این مقاله باید به شما احساس کار با هیلا را بدهد.