2.1.1.1 BFF Core Modülü#
BFF Core modülü form group, form geçerlilik kontrolü (form validation), hata yakalama, temel servisler ve temel modelleri içeren paketlerden oluşur. Bunlar şunlardır:
Form#
Form alt modülü HvlFormGroup angular bileşenini içerir. HvlFormGroup veri giriş ekranlarında angular form desteğini genişleten bir bileşendir. Bu bileşen ile bff ile sağlanan form geçerlilik kontrolleri kolay bir şekilde kullanılabilir.
Global Error Handler#
Uygulama genelinde ele alınmayan hatalarla ilgili işlem yapılmasını sağlayan HvlGlobalErrorHandler
sınıfı bu modülde yer alır. HvlGlobalErrorHandler sınıfı aşağıda açıklanan işlemleri yapar:
- Uygulama konfigürasyonunda core.errorHandling.backendToastEnabled ayarı true verilmişse servis çağrıları sonucu hata kodu içeren bir hata (beklenen bir hata) alınması durumunda toast mesajı şeklinde son kullanıcıya hata mesajının gösterilmesi sağlanır.
- Uygulama konfigürasyonunda core.errorHandling.backendGenericToastEnabled ayarı true verilmişse servis çağrıları sonucu herhangi bir hata alınması durumunda toast mesajı şeklinde son kullanıcıya gösterilmesi sağlanır.
- Uygulama konfigürasyonunda core.errorHandling.jsToastEnabled ayarı true olarak verilmişse uygulamada alınan herhangi bir hata durumunda (servis çağrısı olmak zorunda değil) hatanın toast mesajı şeklinde son kullanıcıya gösterilmesi sağlanır. Bu konfigürasyonun canlı ortamda açılması tavsiye edilmez.
- Uygulama konfigürasyonunda core.errorHandling.routingEnabled ayarı true verilmişse beklenen servis hataları dışında oluşan hatalar için uygulamanın hata sayfasına yönlendirilmesi sağlanır.
- Alınan tüm hatalar browser konsoluna loglanır. Eğer uygulama konfigürasyonunda core.errorHandling.ngxLoggerEnabled ayarının değeri true verilmişse loglama ngxlogger üzerinde yapılır, değilse loglama direk konsolun log metodları (console.log, console.error gibi) ile yapılır.
HvlGlobalErrorHandler sınıfının projelerde kullanımı#
HvlGlobalErrorHandler sınıfını projenizde kullanmak için ana modül tanımında aşağıdaki gibi providers'a eklemeniz gerekir.
import { ErrorHandler, NgModule } from '@angular/core';
import { HvlGlobalErrorHandler, HvlNgCoreModule } from '@hvlng/framework-bff/core';
@NgModule({
declarations: [
....
],
imports: [
....
],
providers: [
{provide: ErrorHandler, useClass: HvlGlobalErrorHandler},
...
],
...
})
export class AppModule {}
Service#
Bff modülü uygulama konfigürasyonu, loglama ve loader (yürütülen bir işlemin devam ettiğini kullanıcıya animasyonla gösteren servis) işlemleri için servisler sağlar. Bu servisler aşağıda açıklanmıştır.
HvlConfigurationService#
Eksen ile geliştirilen uygulamaların önyüz (frontend) ile ilgili konfigürasyonunun projede assets/config/config.json dosyasında yer alması beklenir. HvlConfigurationService servisi bu konfigürasyonun uygulama açılırken birkez alınmasını ve herhangi bir bileşende konfigürasyon bilgisine ihtiyaç duyulduğunda erişilebilmesini sağlar.
Örnek kullanım:
import { HvlConfigurationService } from '@hvlng/framework-bff/core';
@Component({selector: 'app-example', templateUrl: './example.component.html'})
export class ExampleComponent {
constructor(
private configurationService: HvlConfigurationService,
)
getCustomerLogo(){
if(this.configurationService.config.custom.customerLogo) {
return this.configurationService.config.custom.customerLogo
} else {
return 'assets/default/default-logo.png'
}
}
}
Yukarıdaki örnekteki this.configurationService.config nesnesi hvlng/framework-bff/core/model modülündeki Configuration interface'i tipindedir. Bu interface Eksen altyapısında tanımlanmış temel konfigürasyon bilgilerini içerir. Siz de kendi projenize ait ayarları bir interface ile tanımlayıp config nesnesini bu interface'e cast ederek kullanabilirsiniz. Aşağıdaki örneği inceleyiniz:
//@hvlng/framework-bff/core/model içersinde yer alan Configuration'ın cast edilebilmesi için extend edilmesi önemli
export interface MyAppConfiguration extends Configuration {
custom: CustomConfiguration;
}
export interface CustomConfiguration {
customerLogo: string;
}
import { HvlConfigurationService } from '@hvlng/framework-bff/core';
@Component({selector: 'app-example', templateUrl: './example.component.html'})
export class ExampleComponent {
constructor(
private configurationService: HvlConfigurationService,
)
getCustomerLogo(){
const config = this.configurationService.config as MyAppConfiguration;
if(config.custom.customerLogo) {
return this.configurationService.config.custom.customerLogo
} else {
return 'assets/default/default-logo.png'
}
}
}
Yukarıdaki kullanım şekli size daha okunur ve yönetilebilir kod yazma imkanı sağlar.
Önemli Temelde configurationModel core, theme ve application olarak 3 ana ayar aralığına bölünmüştür. ilk ikisi (core ve theme) alt yapıdan sağlanan ayarları temsil ederken, application kısmı any tipinde olup projelerin custom ayarları girebilmeleri için ayrılmıştır. örnek kullanım:
"application": { "keysys": { "reportUrlInfo": { "roleOwnerRoleGroups": "/reports/keysys_report/roleOwnerRoleGroups" }, "reportExportDateFormat": "dd.MM.YYYY HH:mm", "proxyStartDateMinuteLatency": "2" } }
Önemli
Gerçek ortamlarda proje konfigürasyonunun assets/config/config.json dosyasında değil de konfigürasyon sunucusunda yer alması beklenir. Bu sebeple gerçek ortamda konfigürasyonun alınabilmesi için konfigürasyon sunucusunun adresi ve diğer erişim bilgileri gibi ayarlar config_prod.json dosyasında yer almalıdır.
HvlLoaderService#
HvlLoaderService rest servis çağrısı gibi asenkron işlemlerde son kullanıcıya asenkron iş boyunca işlemin devam ettiğini ve beklemesi gerektiğini ifade eden 'yükleniyor' animasyonunun gösterilmesini sağlar. Aşağıdaki örneği inceleyiniz:
import { HvlLoaderService } from '@hvlng/framework-bff/core';
@Component({selector: 'app-example', templateUrl: './example.component.html'})
export class ExampleComponent {
constructor(
private loaderService: HvlLoaderService,
private myService: MyService,
)
callService(){
this.loaderService.set('show');
this.myService.getSomeData().subscribe({
next: (data) => {
...
}
}).add(() => {
this.loaderService.set('hide');
})
}
}
Önemli
PrimeNG (ya da benzeri bileşen kütüphaneleri) genellikle sundukları bileşenlerde 'yükleniyor' işlevini bir özellik ile sağlarlar. Bu sebeple HvlLoaderService yerine bu özellikleri kullanmak da bir alternatiftir ve tercih edilebilir.
HvlLoggerService#
HvlLoggerService uygulama genelinde client loglarını tek bir yerden yönetmek amacı geliştirilmiştir. Bu servis ile info, warn, error ve debug metodları sağlanmaktadır. Bu metodlar adlarından da anlaşılacağı üzere farklı seviyelerde log yazılmasını sağlamaktadır.
HvlLoggerService NGXLogger kütüphanesini kullanmaktadır. HvlLoggerService aşağıdaki konfigürasyonlara sahiptir:
- core.logging.level: Öntanımlı log seviyesini ayarlar. Şu değerleri alabilir: TRACE, DEBUG, INFO, LOG, WARN, ERROR, FATAL, OFF
- core.logging.disableConsoleLogging: Konsola log yazmayı kapatmak için kullanılabilir
- core.logging.colorScheme: NGXLogger için renk şemasını belirtir.
HvlBuildInfoService#
Uygulama sürümü ile ilgili bilgiler dönen servistir. Sürüm bilgilerinin projede assets/build/build.json dosyasında olması beklenir. HvlBuildInfoService bu dosyadaki bilgilerin elde edilmesini sağlar.
Notation#
Form geçerlilik kontrolleri ile ilgili notasyonlar sunan modüldür. Aşağıda sunulan notasyonlar açıklanmıştır:
Notation | Açıklama |
---|---|
@Min | Kontrol değerinin verilen bir minimum değere eşit olması yada verilen değerden küçük olmaması gerektiği belirtir |
@MinLength | Kontrol uzunluğunun (basamak sayısının) verilen bir minimum uzunluğa eşit olması yada verilen uzunluktan küçük olmaması gerektiği belirtir |
@Max | Kontrol değerinin verilen bir maksimum değere eşit olması yada verilen değerden büyük olmaması gerektiği belirtir |
@MaxLength | Kontrol uzunluğunun (basamak sayısının) verilen bir maksimum uzunluğa eşit olması yada verilen uzunluktan büyük olmaması gerektiği belirtir |
@EmptyControl | Eğer kontrol herhangi bir geçerlilik kontrolü içermiyorsa bu anotasyon kullanılmalıdır. İsminden dolayı @NotBlank yada @Required anotasyonları ile karıştırılabilmektedir, dikkat edilmelidir. Bu anotasyon kontrolün değeri ile ilgili değildir. |
@Future | Kontrol değerinin gelecek bir tarih (şuanki zamandan daha ileride bir tarih) olması gerektiğini belirtir |
@Nested | Kontolün primitive bir alan değil bir nesne içerdiğini ve bu nesnenin kendi elemanları için kendi geçerilik kuralları içerebileceğini belirtir |
@NestedArray | Kontolün primitive bir alan değil bir dizi içerdiğini ve bu dizinin içindeki elemanların kendi geçerilik kuralları içerebileceğini belirtir |
@NotBlank | Kontrol değerinin (boşluk karakterleri de kırpıldıktan sonra) boş olamayacağını belirtir. |
@Past | Kontrol değerinin geçmiş bir tarih (şuanki zamandan daha geride bir tarih) olması gerektiğini belirtir |
@Pattern | Kontrol değerinin veilen RegEx ifadeye uygun olması gerektiğini belirtir. |
@Required | Kontrol değerinin boş olamayacağını belirtir. |
@RequiredTrue | Kontrol değerinin true değeri olması gerektiğini belirtir. Genellikle checkbox'larla kullanılır. |
Model#
Model alt modülü bff core modülünde sağlanan servis ve bileşenler tarafından kullanılan model sınıflarını ve interface'leri içeren alt modüldür. Sağlanan model sınıflar aşağıda açıklanmıştır:
Model | Açıklama |
---|---|
HvlBaseModel | Bu sınıf Eksen altyapısı ile geliştirilen tüm model sınıflarının ata sınıfıdır. Tüm model sınıfların bu sınıfı extend etmesi beklenir. İçerdiği alanlar şunlardır: id, uuid, version, dateCreated, dateUpdated, createdBy, updatedBy, deleted, deletedDate. Bu alanlar Eksen backend'i ile uyumlu geliştirim yapılmasını sağlar. |
BuildInfo | HvlBuildInfoService döndüğü interface'tir. |
Configuration | HvlConfigurationService döndüğü konfigürasyonla ilgili temel interface'tir. Bu interface'in referans ettiği diğer alt veritipleri (Core, Theme vb.) de aynı pakette yer almaktadır. |
HvlError | Eksen ile uyumlu geliştirilmiş backend'lerden dönen hatayı ifade eden Model sınıftır. |
HvlLanguageModel | Client'ta tutulan son kullanıcının giriş yaptığı dili ifade eden interface'tir. |
HvlPage | Sayfalı veri dönen Eksen uyumlu backend servislerin veri dönüş tipini ifade eden sınıftır. Generic bir tiptir. |
HvlPageable | Sayfalı veri dönen Eksen uyumlu backend servislerin sayfalama ile ilgili aldığı parametreyi ifade eden sınıftır. |
HvlQueryModel | Eksen uyumlu genel sorgulama backend servislerin aldığı sorgu parametre sınıflarının ata sınıfıdır. Sorgu parametrelerinin bu sınıfı extend etmedi beklenir. |
HvlResponse | Eksen uyumlu backend servislerin dönen verisini ifade eden sınıftır. Generic bir tiptir. |