Предлагаю вашему вниманию TypedAPI: библиотеку API клиента-сервера для проектов, в которых фронт и бэк написаны на TypeScript. Акцент делается на максимальной простоте использования. Суть такая: вы пишете API как обычный TypeScript класс с некоторыми ограничениями, потом автоматом из класса строится интерфейс, которым будет пользоваться клиентское приложение. Также генерируется некоторая служебная информация. Остается только настроить коннекторы (доступны HTTP и WebSocket). Валидацию, хранение подключений, и др. берет на себя TypedAPI. Есть поддержка событий.

Чтобы поиграться, есть два простеньких демонстрационных приложения: Hello, world! и Демо-чат.

Установка

TypedAPI состоит из нескольких библиотек, которые подключаются в зависимости от типа использования.

typedapi-core: ядро, подключается клиентом и сервером
typedapi-server: ядро сервера, подключается на сервере, включает в себя функционал HTTP сервера
typedapi-client: ядро клиента, подключается на клиенте
typedapi-server-ws — WebSocket сервер
typedapi-client-browser-http — HTTP клиент
typedapi-client-browser-ws — WebSocket клиент
typedapi-parser — Парсер для API класса и создания интерфейса. Подключается на сервере с флагом --dev
typedapi-redis-signaling — для проксирования событий из микросервисов во входной API

Пример, если мы хотим использовать WebSocket соединение:

# на сервере
npm install --save typedapi-core typedapi-server typedapi-server-ws
npm install --save-dev typedapi-parser
# на клиенте
npm install --save typedapi-core typedapi-client typedapi-client-browser-ws

Для HTTP соединения:

# for server
npm install --save typedapi-core typedapi-server
npm install --save-dev typedapi-parser
# for client
npm install --save typedapi-core typedapi-client typedapi-client-browser-http

Требования к API классу

Все методы должны возвращать Promise
Есть ограничения по типу данных, которые могут принимать и возвращать методы (см. ниже)
Класс может содержать дочерние свойства-объекты, построеные по тем же правилам

Дополнительно класс может содержать свойства типа Event и ParametricEvent для реализации событий, и есть заранее определенные инъекции для авторизации и хранения базовой информации о пользователе (см. ниже).

Пример класса для «Hello, world!»:

export class Api {
    async hello(name: string): Promise<string> {
        return `Hello, ${name}!`
    }
}

Ограничения по типам данных

Методы могут возвращать/принимать следующие типы данных:

Скалярные: number, string, boolean, Date, undefined, null
Array, Tuple, Enum, Union. Могут содержать только описанные здесь типы.
Объекты-структуры без методов
Индексированные объекты типа { [key: string | number]: SomeOtherType }

Прием/передача any, unknown запрещена.

Генерация интерфейса

Генерация интерфейса производится путем использования команды typedapi-parse из пакета typedapi-parser:

typedapi-parse [sourceFilename] [sourceObjectName] [outFilename] [reflectionOutFileName]

где:

sourceFilename: Путь к файлу, где хранится ваш API
sourceObjectName: Название класса в этом файле
outFilename: Путь к файлу, в который будет записан интерфейс для клиента
reflectionOutFileName: Путь к файлу, который будет хранить reflections для всех методов и данных. Он используется на сервере для валидации данных

Создание соединения

После того, как вы настроили API и сегенерировали интерфейсы, можно настраивать соединение. Пример как это может выглядеть для WebSocket:

Сервер

import { WebSocketServer } from "typedapi-server-ws"
import { buildMap } from "typedapi-server"
// файл, сгенерированный командой typedapi-parse для сервера
import { reflection } from "./apiReflection"
// Ваш API класс
import { Api } from "./Api"
new WebSocketServer({
    apiMap: buildMap(reflection, new Api),
    port: 8090
})

Клиент

import { WebSocketTransport } from "typedapi-client-browser-ws"
// файл, сгенерированный командой typedapi-parse для клиента
import { createClient } from "./apiReflection"
const api = createClient({ transport })
// теперь можно вызывать методы API
let result = await api.hello(name)

Настройка HTTP соединения происходит аналогичным способом, можно посмотреть в документации.

События

TypedAPI поддерживает события. При WebSocket соединении оповещение происходит обычным образом, отправкой данных через сокет. При HTTP соединении используется HTTP polling.

Пример cоздания события на сервере:

import { Event } from "typedapi-server"
export class Api {
    someEvent = new Event<string>()
}

// отправляем событие всем продписчикам
api.someEvent.fire(data)
// отправляем событие одному пользователю
api.someEvent.fireForUser(data, userId)
// Отправляем группе пользователей
api.someEvent.fireForGroup(data, groupName)
// отправляем конкретной сессии
api.someEvent.fireForSession(data, sessionId)
// Отправялем конкретному соединению
api.someEvent.fireForConnection(data, connectionId)

Обработка на клиенте:

// Подписываемся на событие
const subscription = await api.someEvent.subscribe(data => {
    // обработка события
})
// Отписка
await subscription.unsubscribe()

Параметрические события

Параметрические события это события, в которых у подписки могут быть определенные параметры, которые определяют, нужно ли оповещать пользователя о конкретном событии. Более подробно про параметрические события можно прочитать в документации.

Авторизация

Для того, чтобы реализовать авторизацию в вашем API, надо:

Реализовать SessionProviderInterface и передать его в конструктор сервиса. По умолчанию используется MemorySessionProvider, который будет сбрасываться при каждой перезагрузке сервера.
Реализовать методы, которые возвращают AuthDataResponse. Это специальный ответ метода, который обрабатывается по другому, нежели другие ответы.

Интерфейс AuthDataResponse выглядит так:

type AuthDataResponse = {
    newAuthData: {
        id?: string | number
        groups?: string[]
        name?: string
        email?: string
        phone?: string
    }
    // ответ, который будет отправлен пользователю
    // newAuthData используется только для внутренних нужд
    response: boolean
}

пример реализации API с авторизацией:

import { AuthDataResponse } from "typedapi-server"

export class ClientApi {
    /**
     * Проверяем логин и пароль, если подходит авторизуем
    **/
    async login(username: string, password: string): Promise<AuthDataResponse> {
        let user = await usersRepository.login(username, password)
        if(!user) {
            return {
                response: false,
                newAuthData: {}
            }
        } else {
            return {
                response: true,
                newAuthData: {
                    id: user.id,
                    groups: user.groups
                }
            }
        }
    }
    /**
    * Logout
    **/
    async logout(): Promise<AuthDataResponse> {
        return {
            response: true,
            newAuthData: {}
        }
    }
    /**
    * в apiUserID будет автоматически добавлен идентификатор пользователя.
    * Если пользватель не авторизован, он получит NotAuthorizedError
    **/
    async getUserData(apiUserId: number): Promise<SomeUserData> {
        let userData = await usersRespotory.getUserData(apiUserId)
        return userData
    }
}

Также помимо apiUserId можно получать и другие данные о пользователе, подробнее в документации.

Микросервисы

Для разбиения API на микросервисы используется следующая идея: на каждом микросервисе поднимается экземпляр API, и с помощью для каждого экземпляра устанавливается, какой сервис будет отвественен за обработку определенных методов. Для этого есть следующие инструменты:

HttpProxyClient —
Это объект проксирует вызовы методов со входного API на внутренний сервис
HttpTrustServer —
Этот объект принимает вызов от HttpProxyClient и вызывает запрашиваемый метод
RedisPublisher —
Присоединяется к API, слушает события, и перенаправляет их в Redis. Используется во внутренних сервисах.
RedisSubscriber —
Слушает события из Редиса, и запускает их на входном API

Архитектура может выглядеть примерно так:

Примеры кода можно найти в документации.

Заключение

Я описал ключевые особенности TypedAPI, для дополнительной информации можно почитать документацию. Я уже использую эту библиотеку в паре своих проектов, но пока она все же находится в режиме беты. Я активно ее развиваю, и надеюсь, что она будет полезна людям. Буду рад любой конструктивной критике.

Спасибо за внимание.

TypedAPI: клиент-сервер для TypeScript