NestJS-yritysbackendien API:t · Oppitunti

Nimitetty konfiguraatio registerAsilla

Ryhmittele toisiinsa liittyvät asetukset tyypitettyihin konfiguraationimiavaruuksiin ja injektoi ne ConfigService.getillä.

Oppitunti 2/413 vaihetta

Nimitetty konfiguraatio registerAsilla on ilmainen NestJS-yritysbackendien API:t-oppitunti CoddyKitissä. Tämä on oppitunti 2/4. Voit lukea koko oppitunnin alta ilmaiseksi ja harjoitella sen jälkeen käytännössä selaimessa sisäänrakennetulla koodieditorilla ja ympäri vuorokauden käytettävissä olevan tekoälytuutorin avulla. Oppitunti kuuluu NestJS-yritysbackendien API:t-oppimispolkuun, ja edistymisesi synkronoituu verkon ja CoddyKit-sovelluksen välillä. NestJS-yritysbackendien API:t-kurssilla on yhteensä 4 oppituntia.

Litteän konfiguraation ongelma

Kun API kasvaa, kaikkien asetusten kasaaminen yhteen valtavaan ConfigService-nimiavaruuteen muuttuu hallitsemattomaksi. Lopulta kutsut kuten config.get('DB_HOST'), config.get('REDIS_PORT') ja config.get('JWT_SECRET') ovat hajallaan eri puolilla koodia ilman ryhmittelyä tai tyypiturvallisuutta.

Ei rakennetta — tietokannan, välimuistin ja autentikoinnin avaimet ovat kaikki samalla litteällä tasolla.
Ei tyyppejä — get() palauttaa unknown-tyypin tai löyhästi tyypitetyn arvon.
Vaikea refaktoroida — avaimen uudelleennimeäminen tarkoittaa raakamerkkijonojen etsimistä eri puolilta koodikantaa.

NestJS ratkaisee tämän nimiavaruudellisen konfiguraation avulla käyttämällä @nestjs/config-paketin registerAs-apufunktiota.

registerAs-funktion esittely

registerAs(token, factory) luo konfiguraatiofactoryn, joka on sidottu nimiavaruuden tokeniin. Factory lukee arvot process.env-objektista ja palauttaa tyypitetyn objektin, joka ryhmittelee toisiinsa liittyvät asetukset.

Jokaisesta nimiavaruudesta tulee oma looginen kokonaisuutensa — database, jwt tai redis — jonka voit rekisteröidä, injektoida ja testata itsenäisesti.

import { registerAs } from '@nestjs/config';

export default registerAs('database', () => ({
  host: process.env.DB_HOST ?? 'localhost',
  port: parseInt(process.env.DB_PORT ?? '5432', 10),
  username: process.env.DB_USER ?? 'postgres',
  password: process.env.DB_PASSWORD ?? '',
  name: process.env.DB_NAME ?? 'app',
}));

Nimiavaruuden rekisteröiminen

Lataa nimiavaruudelliset factoryt ConfigModule.forRoot-funktion load-taulukon kautta. Jokainen alkio on registerAs-funktiolla luotu factory.

Merkitse moduuli asetuksella isGlobal: true, jotta ConfigService on käytettävissä kaikkialla ilman uudelleenimportointia.

import { Module } from '@nestjs/common';
import { ConfigModule } from '@nestjs/config';
import databaseConfig from './config/database.config';
import jwtConfig from './config/jwt.config';

@Module({
  imports: [
    ConfigModule.forRoot({
      isGlobal: true,
      load: [databaseConfig, jwtConfig],
    }),
  ],
})
export class AppModule {}

Nimiavaruuden lukeminen get()-funktiolla

Kun nimiavaruus on rekisteröity, koko nimiavaruus on käytettävissä tokeninsa alla. Kutsu configService.get('database') palauttaa koko ryhmitellyn objektin.

Voit myös käyttää yksittäistä sisäkkäistä arvoa pistepolun avulla: configService.get('database.host').

import { Injectable } from '@nestjs/common';
import { ConfigService } from '@nestjs/config';

@Injectable()
export class DbConnector {
  constructor(private readonly config: ConfigService) {}

  connect() {
    const host = this.config.get<string>('database.host');
    const port = this.config.get<number>('database.port');
    return `connecting to ${host}:${port}`;
  }
}

Nimiavaruuden tyypittäminen

Saadaksesi todellisen tyypiturvallisuuden johda tyyppi factorysta käyttämällä ConfigType-tyyppiä. Se päättelee registerAs-factoryn palauttaman tarkan rakenteen, joten erillistä synkronoitavana pidettävää rajapintaa ei tarvita.

ConfigType<typeof databaseConfig> antaa tyypin { host: string; port: number; ... }.
Automaattinen täydennys ja käännösaikaiset tarkistukset toimivat nyt jokaisella kentällä.

import { ConfigType } from '@nestjs/config';
import databaseConfig from './config/database.config';

// Inferred: { host: string; port: number; username: string; ... }
type DatabaseConfig = ConfigType<typeof databaseConfig>;

function describe(db: DatabaseConfig): string {
  return `${db.username}@${db.host}:${db.port}/${db.name}`;
}

Nimiavaruuden suora injektointi

Ergonomisin tapa on injektoida nimiavaruuden token suoraan sen sijaan, että käyttäisit ConfigService.get-kutsua kaikkialla. Käytä @Inject(databaseConfig.KEY)-decoratoria — registerAs liittää factoryyn tätä varten KEY-ominaisuuden.

Nyt kenttä on täysin tyypitetty ja riippuvuus näkyy eksplisiittisesti konstruktorissa.

import { Inject, Injectable } from '@nestjs/common';
import { ConfigType } from '@nestjs/config';
import databaseConfig from './config/database.config';

@Injectable()
export class UserRepository {
  constructor(
    @Inject(databaseConfig.KEY)
    private readonly db: ConfigType<typeof databaseConfig>,
  ) {}

  dsn(): string {
    return `postgres://${this.db.host}:${this.db.port}/${this.db.name}`;
  }
}

Miksi token kannattaa injektoida ConfigServicen sijaan

Molemmat lähestymistavat toimivat, mutta nimiavaruustunnisteen injektoinnilla on selviä etuja suuressa mittakaavassa:

Tyypityksen turvallisuus — injektoitu objekti on täysin tyypitetty; tarvitaan vähemmän get<T>-tyyppimuunnoksia, jotka voivat huomaamatta vanhentua.
Eksplisiittiset riippuvuudet — konstruktori ilmoittaa täsmälleen, mitä konfiguraatiota se tarvitsee.
Pienempi rajapinta — vain tietokantakonfiguraatiota käsittelevä luokka ei näe JWT- tai Redis-avaimia.
Helpommat testit — antakaa databaseConfig.KEY-avaimelle tavallinen objekti sen sijaan, että mockaisitte ConfigService-palvelua.

Useita nimiavaruuksia rinnakkain

Oikeissa yrityssovelluksissa on useita nimiavaruuksia. Jokainen niistä on oma tiedostonsa ja factorynsä, jotka rekisteröidään yhdessä load-taulukossa. Kun ne pidetään erillään, JWT-muutos ei voi vahingossa rikkoa tietokantakonfiguraatiota.

import { registerAs } from '@nestjs/config';

export const jwtConfig = registerAs('jwt', () => ({
  secret: process.env.JWT_SECRET ?? 'dev-secret',
  accessTtl: process.env.JWT_ACCESS_TTL ?? '15m',
  refreshTtl: process.env.JWT_REFRESH_TTL ?? '7d',
}));

export const redisConfig = registerAs('redis', () => ({
  host: process.env.REDIS_HOST ?? 'localhost',
  port: parseInt(process.env.REDIS_PORT ?? '6379', 10),
  ttl: parseInt(process.env.REDIS_TTL ?? '60', 10),
}));

Tyyppimuunnokset tehdään factoryssä

Ympäristömuuttujat ovat aina merkkijonoja. Nimiavaruuden factory on oikea paikka tehdä niille tyyppimuunnokset ja asettaa oletusarvot kerran, jotta kuluttajat saavat aina oikeantyyppiset arvot.

Tämä puhdas apufunktio näyttää tyyppimuunnoslogiikan, jonka sijoittaisitte registerAs-factoryyn — sen voi suorittaa itsenäisesti.

function buildDbConfig(env: Record<string, string | undefined>) {
  return {
    host: env.DB_HOST ?? 'localhost',
    port: parseInt(env.DB_PORT ?? '5432', 10),
    ssl: env.DB_SSL === 'true',
    poolSize: parseInt(env.DB_POOL_SIZE ?? '10', 10),
  };
}

const cfg = buildDbConfig({ DB_PORT: '6543', DB_SSL: 'true' });
console.log(cfg.port, typeof cfg.port); // 6543 'number'
console.log(cfg.ssl, typeof cfg.ssl);   // true 'boolean'
console.log(cfg.host);                  // localhost

Nimiavaruuden käyttäminen forRootAsync-metodissa

Muut moduulit voivat käyttää nimiavaruutta asynkronisesti. Injektoikaa nimiavaruustunniste inject-määrityksen kautta ja lukekaa tyypitetty objekti useFactory-funktiossa — esimerkiksi määrittämällä TypeORM käyttämään database-nimiavaruutta.

import { ConfigType } from '@nestjs/config';
import { TypeOrmModule } from '@nestjs/typeorm';
import databaseConfig from './config/database.config';

TypeOrmModule.forRootAsync({
  inject: [databaseConfig.KEY],
  useFactory: (db: ConfigType<typeof databaseConfig>) => ({
    type: 'postgres',
    host: db.host,
    port: db.port,
    username: db.username,
    password: db.password,
    database: db.name,
  }),
});

Yleiset sudenkuopat

Varokaa näitä virheitä työskennellessänne nimiavaruudellisen konfiguraation kanssa:

Factoryn lataamisen unohtaminen määrityksessä load: [...] — nimiavaruus on tällöin undefined.
Tunnisteiden ja polkujen sekoittaminen — get('database') palauttaa objektin, kun taas get('database.host') palauttaa lehtiarvon. Älkää sekoittako niitä keskenään.
Tyyppimuunnosten tekeminen uudelleen kuluttajissa — tehkää muunnos kerran factoryssä; kuluttajien tulee voida luottaa tyyppeihin.
process.env-arvon suora käyttäminen palveluissa nimiavaruuden injektoinnin sijaan heikentää tyypitystä ja testattavuutta.

Pikatarkistus

Testatkaa, miten hyvin ymmärrätte nimiavaruudellisen konfiguraation injektoinnin.

Vastaa interaktiivisessa oppitunnissa

Kertaus

Opitte ryhmittelemään asetuksia tyypitetyiksi konfiguraationimiavaruuksiksi registerAs-funktion avulla:

registerAs(token, factory) ryhmittelee toisiinsa liittyvät ympäristömuuttujat yhdeksi nimetyn ja tyypitetyn objektiksi.
Rekisteröikää factoryt kutsumalla ConfigModule.forRoot({ load: [...] }).
Lukekaa nimiavaruus kutsulla config.get('database') tai yksittäinen arvo kutsulla config.get('database.host').
Suosikaa @Inject(config.KEY)-ratkaisua yhdessä ConfigType<typeof config>-tyypin kanssa, jotta saavutatte täyden tyyppiturvallisuuden ja eksplisiittiset riippuvuudet.
Tehkää kaikki tyyppimuunnokset ja oletusarvojen asettaminen factoryn sisällä, jotta kuluttajat voivat luottaa tyyppeihin.

Tämä malli pitää konfiguraation rakenteisena, tyypitettynä ja testattavana yritystason rajapinnan kasvaessa.

Aloita maksutta

Opi TypeScript tekoälytuutorin avulla — ilmaiseksi

Kirjoita ja suorita oikeaa koodia selaimessa, saa välitöntä apua tekoälytuutorilta ympäri vuorokauden ja jatka siitä, mihin jäit, verkossa tai sovelluksessa.

Kurssit: 20
Oppitunnit: 76

Aloita opiskelu maksutta Näytä koko kurssi

Usein kysytyt kysymykset

Onko oppitunti ”Nimitetty konfiguraatio registerAsilla” ilmainen?

Kyllä – oppitunnin ”Nimitetty konfiguraatio registerAsilla” koko tekstin voi lukea täällä verkossa ilmaiseksi. Jos haluat harjoitella interaktiivisesti sisäänrakennetulla koodieditorilla ja ympäri vuorokauden käytettävissä olevan tekoälytuutorin avulla sekä avata koko NestJS-yritysbackendien API:t-kurssin, päivitä CoddyKit PROhon. NestJS-yritysbackendien API:t-kurssilla on yhteensä 4 oppituntia.

Mitä opin oppitunnilla ”Nimitetty konfiguraatio registerAsilla”?

Ryhmittele toisiinsa liittyvät asetukset tyypitettyihin konfiguraationimiavaruuksiin ja injektoi ne ConfigService.getillä. Harjoittelet NestJS-yritysbackendien API:t-aihetta koodilla, jonka suoritat suoraan selaimessa. Ympäri vuorokauden käytettävissä oleva tekoälytuutori vastaa kysymyksiisi oppitunnin aikana.

Tarvitsenko kokemusta aloittaakseni NestJS-yritysbackendien API:t-opiskelun?

Aiempi kokemus ei ole tarpeen. CoddyKitin NestJS-yritysbackendien API:t-oppimispolku sopii vasta-alkajista edistyneisiin, joten voit aloittaa tästä tai alusta ja edetä omaan tahtiisi. Tämä on oppitunti 2/4.

Kuinka kauan ”Nimitetty konfiguraatio registerAsilla”-oppitunnin suorittaminen kestää?

Useimmat CoddyKitin oppitunnit kestävät noin 5–10 minuuttia. Jokainen oppitunti on lyhyt ja interaktiivinen, joten edistyt tasaisesti ja voit jatkaa siitä, mihin jäit – sekä verkossa että sovelluksessa.

Voinko kirjoittaa ja suorittaa koodia tällä NestJS-yritysbackendien API:t-oppitunnilla?

Kyllä. Jokainen NestJS-yritysbackendien API:t-oppitunti sisältää sisäänrakennetun koodieditorin, joten voit kirjoittaa ja suorittaa oikeaa koodia suoraan selaimessa ja saada välitöntä palautetta tekoälyltä – paikallista asennusta ei tarvita.

Kaikki tämän kurssin oppitunnit

Skeemalla validoitu ympäristö Joi:lla ja forRootilla
Nimitetty konfiguraatio registerAsilla
Salaisuuksien lataaminen HashiCorp Vaultista ja AWS SSM:stä
Ympäristökohtainen konfiguraatio ja turvalliset oletukset

← Takaisin: NestJS-yritysbackendien API:t