Klasa kontrolująca (Controller)

O tym jak działa kontroler, czym powinien się zajmować i dlaczego nie powinien realizować zbyt wiele. W dzisiejszym wpisie powiem o tym dlaczego nie warto budować wielkich kontrolerów będących boskimi klasami.

Klasa kontrolująca

Zwykle mówi się, że zapytania użytkowników zawierające błędne dane rozbijają się o kontrolery. Jest w tym ziarno prawdy, jednak poprawniejszym określeniem będzie, że rozbijają się one o walidację wywoływaną przez klasę kontrolera. Po tych słowach wstępu może nam się w głowach kształtować pewien obraz, czym powinna być klasa kontrolująca. 

Przykład Controllera

W celu uniknięcia suchych regułek, posłużmy się przykładem z życia wziętym. Wyobraźmy sobie kierownika kadr działu księgowości w pewnej firmie. Owy kierownik ma za zadanie przydzielać zleconą pracę dla podlegających mu pracowników. Z wykonanych zadań jest następnie rozliczany na spotkaniach zarządu, dlatego musi być pewien, że rezultaty przedstawi w sposób czytelny dla swoich przełożonych.  Musi on także być pewien, że jest w stanie wraz ze swoimi podwładnymi zrealizować powierzone zadanie, np. upewnić się, że wraz ze zleceniem rozliczenia rocznego załączone zostały wszystkie wymagane dokumenty. Jest to kierownik, więc pracę sprawdzenia zleci odpowiedniemu pracownikowi, a sam zajmie się tym, co robi najlepiej - kontrolowaniem przydziału zadań na tym szczeblu.

Zobrazujmy sobie ten przykład poprzez jego implementację.

@Controller('incomes')
export class IncomesController {
  constructor(private readonly incomesService: IncomesService) {}

  @Post('calculate/year')
  async calculateYearIncome(@Body() request: CalculateYearIncomeRequest): Promise<YearIncomeResponse> {
    const yearIncome = await this.incomesService.calculateYearIncome(request as CalculateYearIncomeDTO);
    
    const response = YearIncomeResponseMapper.mapIncomeEntity(yearIncome);
    
    return response;
  }
}
Mamy tutaj przyjęcie i automatyczną walidację danych, wywołanie pewnej logiki biznesowej i użycie jej wyniku do sformatowania obiektu wyjściowego (ang. response object). Oczywistym jest także fakt, iż postać tej metody będzie się różnić w zależności od użytej technologii czy frameworka. Niejednokrotnie może okazać się, iż konieczne jest ręczne wywołanie pewnej metody walidującej, czy też sam obiekt wyjściowy może tworzyć się automatycznie. 

Controller bez magii frameworka

Spójrzmy więc na inny przykład kontrolera, gdzie framework nie pozwala na aż tyle magii. Idea jest ta sama, trzeba tylko pamiętać, że zadaniem klasy kontrolera jest kontrolowanie i nie ma znaczenia to, jaka będzie jego finalna forma. Delegowanie zadań, uruchomienie walidacji i sformatowanie wyjścia, to wszystko. Kontroler nie powinien być przepełniony logiką, co jest częstym błędem niedoświadczonych programistów, którzy upychają tutaj zadania nie nadające się dla kontrolerów.

@Controller('incomes')
export class IncomesController {
  constructor(private readonly incomesService: IncomesService) {}

  @Post('calculate/year')
  async calculateYearIncome(@Body() form: CalculateYearIncomeForm): Promise<YearIncomeResponse> {
    form.validate();
    
    const dto = CalculateYearIncomeDTOMapper.map(form.getData());
    
    const yearIncome = await this.incomesService.calculateYearIncome(dto);
    
    const response = YearIncomeResponseMapper.mapIncomeEntity(yearIncome);
    
    return response;
  }
}

Anty przykład - zły controller

Pomijając fakt złamania kilku innych zasad, to jest przykład, jak kontroler NIE POWINIEN wyglądać. Może kod jest w jakimś stopniu czytelny, ale w tym przypadku implementacja aż prosi się o wdrożenie warstwy serwisowej i przeniesienie tam logiki. O tym, jak wdrożyć warstwę serwisową porozmawiamy przy innej okazji. Dodatkowo brakuje tutaj mapowania do postaci obiektu wyjściowego i zwracana jest bezpośrednio encja / model, co nie jest dobrym pomysłem z uwagi na brak kontroli formy wyjściowej, o czym już wspominałem w ostatnim wpisie.

@Controller('incomes')
export class IncomesController {
  constructor(
    private readonly incomeRepository: IncomeRepository,
    private readonly invoiceRepository: InvoiceRepository
  ) {}

  @Post('calculate/year')
  async calculateYearIncome(@Body() request: YearIncomeRequest): Promise<Income> {
    const { year, companyId } = request;
    
    const invoices = await this.invoiceRepository.findByYearAndType( 
      year, 
      invoiceType: InvoiceTypeEnum.SELL,
      companyId
    );
    
    const incomeValue = invoices.reduce((income: number, invoice: Invoice) => 
      income += invoice.netValue, 0);
      
    let income = await this.incomeRepository.findYearIncome(year, companyId);
      
    if (income) {
       income.value = incomeValue;
       
       return this.incomeRepository.save(income);
    }  
      
    income = IncomeFactory.createYearIncome({ year, companyId });
    
    return this.incomeRepository.save(income);
  }
}

Podsumowując



Polecane wpisy:

DRY: Don't Repeat Yourself

Zasada DRY, to po przełożeniu na język polski: nie powtarzaj się. Brzmi bardzo banalnie, jednak dosyć często okazuje się, że mamy problem z jej stosowaniem w kodzie. Dziś dowiesz się, jak nie łamać tej reguły, a co za tym idzie nie powtarzać się.

Sprawdź ten wpis

YAGNI: You aren't gonna need it

YAGNI to kwintesencja zasad clean code. Dotyczy ona bezużyteczności kodu, a dokładniej, konieczności usuwania tych fragmentów, które nie są potrzebne. W myśl "You aren't gonna need it" nie powinniśmy tworzyć niczego więcej, niż to, co jest potrzebne.

Sprawdź ten wpis

KISS: keep it simple, stupid!

Zasada KISS: "Keep it simple, stupid", może zostać dosłownie przetłumaczona na: "rób to prosto, głupku". Mówi ona o tym, abyśmy tworzyli kod w jak najprostszy i najbardziej czytelny sposób. Już dziś sprawdź, czego się wystrzegać, aby spełniać KISS.

Sprawdź ten wpis

Wzorce projektowe

Wzorce projektowe zostały stworzone po to, aby nie wymyślać przysłowiowego koła na nowo. Znajomość wzorców projektowych i umiejętność ich stosowania pozwala na szybkie rozwiązywanie problemów. Wpis ten radzi, jakie wzorce zastosować u siebie.

Sprawdź ten wpis

Wzorzec singleton

Kolejny kreacyjny wzorzec projektowy omawiany na łamach tego bloga: singleton. Wzorzec dookoła którego narosło wiele mitów i legend. Dziś o tym dlaczego singleton jest antywzorcem, jakie problemy powoduje oraz kiedy warto po niego sięgnąć.

Sprawdź ten wpis

Autor wpisu:

Gabriel Ślawski

Fanatyk czystego i prostego kodu. Zwolennik podejść DDD oraz Modular Monolith. Na codzień pracuje jako programista i architekt. Po godzinach spełnia się w projektach open source, udziela się na blogach oraz czyta książki o kosmosie i astrofizyce.