Введение
Друзья, всем привет!
Меня зовут Алексей и вот уже некоторое время я занимаюсь frontend-разработкой.
В этой статье я опишу один из способов реализации приложения, предоставляющего RESTfull API. Вкратце расскажу о том, как я писал подобное приложение на Typescript, а также приведу примеры кода. Существование такой статьи сильно облегчило бы мне жизнь при работе над проектом, надеюсь моя статья поможет и вам!
Немного предыстории
Для тестирования гипотез при развитии продукта требуется в короткие сроки реализовать прототип какого-нибудь приложения. В рамках рабочих задач мне довелось поработать над подобным прототипом. Это было backend-приложение предоставляющее RESTfull API и реализованное с применением технологий Nest.js и Swagger.
Выбор технологий
При выборе стека ключевым требованием стало использование Node.js, так как задача быстрой реализации RESTfull API легла на плечи команды frontend-разработки. При этом в качестве основного инструмента команда обычно использует фреймворк Angular.
Поэтому Nest.js оказался идеальным кандидатом, так как создатели этого фреймворка вдохновлялись подходами, используемыми в Angular. Здесь и привычный нам Dependency Injection, RxJS, Typescript, система модулей и мощный CLI. Полученный API решили задокументировать с помощью Swagger.
Вкратце о технологиях
Nest (NestJS) — фреймворк для разработки эффективных и масштабируемых серверных приложений на Node.js. Данный фреймворк использует прогрессивный (что означает текущую версию ECMAScript) JavaScript с полной поддержкой TypeScript (использование TypeScript является опциональным) и сочетает в себе элементы объектно-ориентированного, функционального и реактивного функционального программирования.
Под капотом Nest использует Express (по умолчанию), но также позволяет использовать Fastify.
Более подробно про Nest рекомендую почитать здесь.
Swagger — это набор инструментов, которые помогают описывать API. Благодаря ему пользователи и машины лучше понимают возможности REST API без доступа к коду. С помощью Swagger можно быстро создать документацию и отправить ее другим разработчикам или клиентам.
Более подробно про Swagger рекомендую почитать здесь.
Подготовка и настройка проекта
Как я уже отметил выше, Nest.js содержит в комплекте довольно мощный CLI. Начнем с его установки, убедившись при этом в том, что у нас на машине установлен Node.js и npm. Для установки выполним команду:
$ npm i -g @nestjs/cliПосле того как CLI установлен создадим с его помощью шаблон нашего приложения с именем rest-api-with-swagger:
$ nest new rest-api-with-swaggerВ Nest.js сущности, которые отвечают за обработку входящих HTTP-запросов и формирование ответов, называются контроллерами. Ниже приведен пример кода из контроллера (app.controller.ts), созданного по умолчанию при генерации шаблонного проекта:
import { Controller, Get } from '@nestjs/common';
import { AppService } from './app.service';
@Controller()
export class AppController {
constructor(private readonly appService: AppService) {}
@Get()
getHello(): string {
return this.appService.getHello();
}
}
В свою очередь, сущности, которые реализуют бизнес-логику приложения, называются сервисами:
import { Injectable } from '@nestjs/common';
@Injectable()
export class AppService {
getHello(): string {
return 'Hello World!';
}
}Сервисы и контроллеры (а также пайпы (Pipes), гарды (Guards) и другие сущности) объединяются в модули (Modules) - строительные блоки, из которых и формируется конечное приложение.
REST API
Пусть нашим ресурсом, доступ к которому мы хотим обеспечить посредством разрабатываемого API, будут заметки (notes). Для того, чтобы не тратить время на создание необходимых сущностей, воспользуемся следующей командой:
$ nest g resource notes # или nest generate resource notesДанная команда создаст модуль приложения, посвященный работе с заметками, и автоматически подключит его к нашему приложению. Структура файлов этого модуля будет иметь следующий вид:
src
notes
|-- dto
-- create-note.dto.ts
-- update-note.dto.ts
|-- entities
-- note.entity.ts
-- notes.controller.spec.ts
-- notes.controller.ts
-- notes.service.spec.ts
-- notes.service.ts
-- notes.module.ts
...Код контроллера, который будет обрабатывать запросы на выполнение операций над заметками, при этом выглядит примерно следующим образом:
import {
Controller, Get, Post,
Body, Patch, Param, Delete, Query
} from '@nestjs/common';
import { NotesService } from './notes.service';
import { CreateNoteDto } from './dto/create-note.dto';
import { UpdateNoteDto } from './dto/update-note.dto';
// Все запросы, содержащие в пути /notes, будут перенаправлены в этот контроллер
@Controller('notes')
export class NotesController {
constructor(private readonly notesService: NotesService) {}
@Post() // обработает POST http://localhost/notes?userId={userId}
create(
@Query('userId') userId: number, // <--- достанет userId из query строки
@Body() createNoteDto: CreateNoteDto
) {
return this.notesService.create(userId, createNoteDto);
}
@Get() // обработает GET http://localhost/notes?userId={userId}
findAll(@Query('userId') userId: number) {
return this.notesService.findAll(userId);
}
@Get(':noteId') // обработает GET http://localhost/notes/{noteId}
findOne(@Param('noteId') noteId: number) {
return this.notesService.findOne(noteId);
}
@Patch(':noteId') // обработает PATCH http://localhost/notes/{noteId}
update(@Param('noteId') noteId: number, @Body() updateNoteDto: UpdateNoteDto) {
return this.notesService.update(noteId, updateNoteDto);
}
@Delete(':noteId') // обработает DELETE http://localhost/notes/{noteId}
remove(@Param('noteId') noteId: number) {
return this.notesService.remove(noteId);
}
}Вот так вот просто мы получили готовый контроллер, работа которого соответствует всем необходимым правилам построения REST API. Далее, реализуем логику работы с нашими заметками в NotesService. Для упрощения, заметки будем хранить в массиве. В случае реального приложения, в данном сервисе потребовалось бы реализовать логику обращения к сервису работы с хранилищем заметок (например, БД), но это тема другой статьи. Подробнее можно почитать тут.
В первую очередь наполним модели (CreateNoteDto, UpdateNoteDto и Note), описывающие сами заметки и действия над ними. В результате код сервиса будет выглядеть следующим образом:
import { Injectable } from '@nestjs/common';
import { CreateNoteDto } from './dto/create-note.dto';
import { UpdateNoteDto } from './dto/update-note.dto';
import { Note } from './entities/note.entity';
@Injectable()
export class NotesService {
private _notes: Note[] = [];
create(userId: number, dto: CreateNoteDto) {
const id = this._getRandomInt();
const note = new Note(id, userId, dto.title, dto.content);
this._notes.push(note);
return note;
}
findAll(userId: number) {
return this._notes.filter(note => note.userId == userId);
}
findOne(noteId: number) {
return this._notes.filter(note => note.id == noteId);
}
update(noteId: number, dto: UpdateNoteDto) {
const index = this._notes.findIndex(note => note.id == noteId)
if (index === -1) {
return;
}
const { id, userId } = this._notes[index];
this._notes[index] = new Note(id, userId, dto.title, dto.content);
return this._notes[index];
}
remove(noteId: number) {
this._notes = this._notes.filter(note => note.id != noteId)
}
private _getRandomInt() {
return Math.floor(Math.random() * 100);
}
}Базовое приложение, реализующее CRUD-операции над заметками (ресурсом), получено. Теперь, перейдем к документированию API. Для этого установим Swagger-модуль для Nest.js:
$ npm install --save @nestjs/swagger swagger-ui-expressи подключим его к нашему приложению в файле main.ts:
import { NestFactory } from '@nestjs/core';
import { SwaggerModule, DocumentBuilder } from '@nestjs/swagger';
import { AppModule } from './app.module';
async function bootstrap() {
const app = await NestFactory.create(AppModule);
const config = new DocumentBuilder()
.setTitle('Notes API')
.setDescription('The notes API description')
.setVersion('1.0')
.build();
const document = SwaggerModule.createDocument(app, config);
SwaggerModule.setup('api', app, document);
await app.listen(3000);
}
bootstrap();Для того чтобы убедится в работоспособности нашего приложения, запустим его командой:
$ npm run start:devПосле запуска, по адресу http://localhost:3000/api/ отобразится следующая страница:
Уже что-то, но на полноценную документацию еще не похоже.
Во-первых, перенесем все методы работы с заметками в отдельную секцию Notes. Для этого повесим очередной декоратор на NotesController:
@ApiTags('Notes') // <---- Отдельная секция в Swagger для всех методов контроллера
@Controller('notes')
export class NotesController {
...
}Также, уберем из нашей документации метод работы с корневым маршрутом (/), повесив на него декоратор ApiExcludeEndpoint:
@Controller()
export class AppController {
constructor(private readonly appService: AppService) {}
@Get()
@ApiExcludeEndpoint() // <----- Скрыть метод контроллера в Swagger описании
getHello(): string {
...
}
}При этом, результат будет выглядеть следующим образом:
Во-вторых, добавим нашим эндоинтам описание, а также валидацию принимаемых параметров. В результате методы нашего контроллера приобретут следующий вид:
@ApiTags('Notes')
@Controller('notes')
export class NotesController {
...
@Patch(':noteId') // обработает PATCH http://localhost/notes/{noteId}
@ApiOperation({ summary: "Updates a note with specified id" })
@ApiParam({ name: "noteId", required: true, description: "Note identifier" })
@ApiResponse({ status: HttpStatus.OK, description: "Success", type: Note })
@ApiResponse({ status: HttpStatus.BAD_REQUEST, description: "Bad Request" })
update(
@Param('noteId', new ParseIntPipe()) noteId: number,
@Body() updateNoteDto: UpdateNoteDto
) {
return this.notesService.update(noteId, updateNoteDto);
}
...
}Полный код приложения можно найти в репозитории по ссылке. Список декораторов, позволяющих описать методы API, можно найти по тут. В примере выше для валидации входных параметров метода update используется пайп ParseIntPipe, более подробно с ним и другими встроенными пайпами можно ознакомится по ссылке.
Чтобы корректно сформировать Swagger описание, необходимо модифицировать наши dto, а также класс Note:
import { ApiProperty } from "@nestjs/swagger";
export class Note {
@ApiProperty({ description: "Note identifier", nullable: false })
id: number;
@ApiProperty({ description: "User identifier", nullable: true })
userId: number;
@ApiProperty({ description: "Note title", nullable: true })
title: string;
@ApiProperty({ description: "Note content", nullable: true })
content: string;
...
}В результате, наше Swagger описание будет выглядеть следующим образом:
API эндпоинты готовы, теперь защитим наш ресурс от несанкционированного доступа. В моем случае, согласно ТЗ требовалось использовать способ доступа с помощью API ключа (подробнее можно почитать здесь). Примеры авторизации с использованием JWT можно посмотреть тут, тут или тут.
Реализовывать авторизацию будем с помощью популярной библиотеки passport, для этого воспользуемся официальным модулем (оберткой) для Nest.js - @nestjs/passport. В первую очередь установим требуемый модуль:
$ npm install --save @nestjs/passport passport passport-headerapikeyДалее, создадим в нашем приложении отдельный модуль, отвечающий за авторизацию:
$ nest g mo authorization # nest generate module authorizationРабота с библиотекой passport основывается на использовании так называемых стратегий авторизации. Реализуем одну из них (api-key.strategy.ts):
import { Injectable, UnauthorizedException } from "@nestjs/common";
import { ConfigService } from "@nestjs/config";
import { PassportStrategy } from "@nestjs/passport";
import Strategy from "passport-headerapikey";
@Injectable()
export class ApiKeyStrategy extends PassportStrategy(Strategy, "api-key") {
constructor(private readonly _configService: ConfigService) {
super({ header: "X-API-KEY", prefix: "" },
true,
async (apiKey, done) => this.validate(apiKey, done)
);
}
public validate = (incomingApiKey: string, done: (error: Error, data) => Record<string, unknown>) => {
const configApiKey = this._configService.get("apiKey");
if (configApiKey === incomingApiKey) {
done(null, true);
}
done(new UnauthorizedException(), null);
};
}В примере выше в конструктор ApiKeyStrategy инжектируется сервис ConfigService. Данный сервис является частью пакета @nestjs/config и позволяет упростить работу с файлами, в которых содержатся переменные окружения (т.е. файлы вида .env). В нашем приложении ключ доступа к API является конфигурационным параметром и прописан в файле .env (см. код проекта). Более подробно о работе с модулем конфигурации можно ознакомится тут.
Теперь соберем воедино наш модуль авторизации (authorization.module.ts):
import { Module } from "@nestjs/common";
import { ConfigModule } from "@nestjs/config";
import { PassportModule } from "@nestjs/passport";
import { ApiKeyStrategy } from "./api-key.strategy";
@Module({
imports: [PassportModule, ConfigModule],
providers: [ApiKeyStrategy],
})
export class AuthorizationModule {}Модуль авторизации готов, но на данный момент методы нашего NotesController продолжат обрабатывать запросы, которые не содержат API ключа в заголовках HTTP-запросов. Для защиты API добавим еще несколько декораторов в контроллер:
@ApiTags('Notes')
@ApiSecurity("X-API-KEY", ["X-API-KEY"]) // <----- Авторизация через Swagger
@Controller('notes')
export class NotesController {
constructor(private readonly notesService: NotesService) {}
@Post() // обработает POST http://localhost/notes?userId={userId}
@UseGuards(AuthGuard("api-key")) // <---- Вернет 401 (unauthorized)
// при попытке доступа без корректного API ключа
...
create(
@Query('userId', new ParseIntPipe()) userId: number,
@Body() createNoteDto: CreateNoteDto
) {
return this.notesService.create(userId, createNoteDto);
}
}и модифицируем файл main.ts:
async function bootstrap() {
const app = await NestFactory.create(AppModule);
const config = new DocumentBuilder()
.setTitle('Notes API')
.setDescription('The notes API description')
.setVersion('1.0')
.addApiKey({ // <--- Покажет опцию X-API-KEY (apiKey)
type: "apiKey", // в окне 'Available authorizations' в Swagger
name: "X-API-KEY",
in: "header",
description: "Enter your API key"
}, "X-API-KEY")
.build();
...
}Конечное Swagger описание нашего API будет выглядеть следующим образом:
В заключении также рекомендую заглянуть в официальный репозиторий с примерами кода от разработчиков фреймворка.
Babayka_od
В чем смысл переписывать документацию?