Теперь, когда мы выпустили бета-версию Vapor 5, пришло время посмотреть, что на самом деле изменилось! В этом посте мы расскажем о том, как работает Vapor 5, какие изменения мы внесли и как будет выглядеть ваш новый код. Этот пост — часть серии публикаций, посвящённых Vapor Week. Подробнее читайте в основном посте блога.
Как выглядит Vapor 5
Вот простой маршрут в Vapor 5:
app.get("hello") { req in "Hello, world!" }
Знакомо? На самом деле это то же самое, что и в Vapor 4! А как насчёт работы с JSON через Content:
app.post("user") { req in let userData = try await req.content.decode(UserData.self) return UserMessage(message: "Hello \(userData.name), you are \(userData.age)") }
Опять же, очень знакомо! Вы могли заметить добавленный await в вызове decode — поскольку Vapor 5 теперь по умолчанию использует потоковую передачу, тело запроса не собирается, если в этом нет необходимости, поэтому вызов стал асинхронным.
Наконец, давайте посмотрим, как использовать Fluent:
// dbPool — это тип `Databases`, определённый при конфигурации приложения app.get("todos") { req in let todos = try await Todo.query(on: dbPool.database).all() return todos }
Вероятно, это самое заметное отличие, которое обратит внимание большинство людей. Причины объясняются в следующем разделе, но, будем надеяться, для большинства это небольшое изменение, которое легко автоматизировать.
Примечание: API для Fluent всё ещё дорабатывается, поэтому названия могут измениться.
Различия, которые вы можете заметить
Простые вещи выглядят очень похоже. И действительно, если вы полностью перешли на асинхронные API с использованием await, то переход должен пройти гладко. Но кое-что изменилось.
Прощайте, блокировки
Работа Vapor 4 по внедрению Sendable увенчалась огромным успехом — мы перешли от ежемесячных сообщений на GitHub о трудно диагностируемой гонке данных к нулю сообщений о сбоях из-за гонки данных! Это было невероятное достижение. Однако, чтобы сделать систему действительно безопасной, нам пришлось внедрить блокировки повсеместно, что препятствовало любой оптимизации производительности. Теперь, когда у нас есть API, который мы можем ломать (Application немного изменился, Request и Response теперь являются структурами, а некоторые свойства стали неизменяемыми), мы наконец можем их убрать! Думаю, я убрал из кодовой базы более 50 блокировок и добавил лишь несколько Mutex в тех местах, где нам действительно нужен какой-то изменяемый тип.
Больше никакого Storage
Вероятно, это одно из самых значительных изменений, но если вы не пишете пакеты для Vapor, то вряд ли его заметите. Однако вы заметите изменения в работе сервисов, о которых мы поговорим далее.
В Vapor 3 и Vapor 4 всё, что было связано с Request, было привязано к EventLoop. Это обеспечивало некоторую безопасность, поскольку, по сути, всё было привязано к одному потоку, а также повышало производительность, поскольку при обработке запросов не происходило переключения между потоками. Однако это привело к необходимости введения Storage, чтобы мы могли хранить фабрики и кэшировать типы, привязанные к нужному event loop. В Swift Concurrency эта модель не используется, и решение о том, где будет выполняться ваш код, зависит от пула задач (не считая пользовательских исполнителей). Это избавляет от необходимости привязывать логгер, клиент и базу данных к одному и тому же event loop и позволяет удалить Storage.
Настоящее внедрение зависимостей для сервисов
Поскольку нам больше не нужно следить за тем, чтобы сервисы использовали тот же event loop, что и Application и Request, сервисы претерпели значительные изменения, и именно это изменение повлияет на вас больше всего. Расширения и вычисляемые свойства ушли в прошлое, уступив место простому внедрению зависимостей. В Application в Vapor есть несколько типов, таких как ViewRenderer и Client, которые создаются при инициализации, но если вам нужен Databases (по сути, пул соединений с базой данных), просто передайте его в сервис! Я большой поклонник такого понятного и прямого внедрения зависимостей, потому что оно чётко показывает, какие из ваших типов, например контроллеры, нуждаются в той или иной зависимости, например в клиенте или базе данных, и его легко тестировать с помощью протоколов. Если вы предпочитаете свой любимый фреймворк для внедрения зависимостей, ничто не мешает вам использовать его для передачи типов в контроллеры и сервисы.
Потоковая передача (Streaming)
Вам больше не нужно указывать метод сбора тела при объявлении маршрутов, поскольку все маршруты по умолчанию используют потоковую передачу. Если вы используете какой-либо из вспомогательных методов для сбора тела (например, .collect() или функции, созданные на их основе, такие как content.decode()), то будет использоваться параметр maxBodySize. В противном случае, если вы сами вызываете потоковый API, вы сами решаете, сколько данных собирать (поскольку в большинстве случаев, когда это требуется, вы обрабатываете каждый фрагмент отдельно). Вы можете просто прочитать тело запроса с помощью:
app.post("upload") { req -> UploadResult in var bytesReceived = 0 try await req.body.forEachChunk { chunk in bytesReceived += chunk.count // Обработайте или сохраните фрагмент здесь, прежде чем запрашивать следующий. } return UploadResult(bytesReceived: bytesReceived) }
В данном случае каждый чанк — это Span<UInt8>. Поскольку мы указываем время жизни, компилятор не позволяет выйти за его пределы. Чтение тела также автоматически поддерживает обратное давление.
Тела ответов получают writer для записи:
app.get("events") { req in Response( headers: [.contentType: "text/event-stream"], body: .init(stream: { writer in for count in 1...5 { try await writer.write("data: \(count)\n\n") try await Task.sleep(for: .seconds(1)) } }) ) }
Опять же, это автоматически поддерживает противодавление (через await в вызове write), и мы используем гарантии времени жизни в Swift, чтобы гарантировать, что writer никогда не будет освобождён.
Макросы
Мы представили экспериментальный продукт VaporMacros, который вы можете добавить в качестве зависимости. Он позволяет определять маршруты и контроллеры с помощью макросов:
@Controller struct UserController { @GET("users") func index(req: Request) async throws -> [User] { // Fetch the users from your repository. } @GET("users", UUID.self) func show(req: Request, id: UUID) async throws -> User { // `id` has already been extracted and decoded for us. User(id: id, name: "Vapor") } @POST("users") func create(req: Request) async throws -> User { let input = try await req.content.decode(CreateUser.self) return User(id: UUID(), name: input.name) } }
Что действительно круто в этом подходе, так это то, что он обеспечивает типобезопасную маршрутизацию! То есть, если вы определяете маршрут с помощью @GET("users", UUID.self), вы должны привязать его к функции с параметром типа UUID. Если вы используете неправильный тип или забудете указать параметр id, вы получите ошибку компиляции. Это должно существенно изменить ситуацию для тех, кто, как и я, никогда не был в восторге от использования строк для всех маршрутов.
У нас также есть макросы для аутентификации:
@GET("account", "me") @AuthMiddleware(User.self, TokenAuthMiddleware()) func me(req: Request, user: User) async throws -> User { // You have a guaranteed user here! }
Опять же, если обработчик маршрута определён неправильно, вы получите ошибки компиляции, и у вас будет пользовательская модель с проверкой типов. Если вам нужно только проверить, существует ли пользователь, сделайте параметр необязательным, и тогда вместо 401 Unauthorized в случае, если пользователь не существует, запрос будет пропущен! Этот макрос меня особенно радует!
Обратите внимание, что эта функция всё ещё активно дорабатывается. У нас есть прототип для определения промежуточного программного обеспечения, и в настоящее время мы работаем над тем, чтобы компилятор мог передавать зависимости в промежуточное ПО. Следите за релизами, чтобы узнать о новых улучшениях.
Частичные параметры маршрута
Одна из новых функций нашего маршрутизатора, довольно специфическая, но очень важная для тех, кому она нужна (например, для реестров пакетов!), — это частичные параметры маршрута! Теперь это работает:
app.get("files", ":{file}.json") { req -> String in let file = try req.parameters.require("file") return "Requested JSON file: \(file)" }
Это должно избавить вас от необходимости подбирать строки и писать собственный код для решения этой задачи.
Более глубокая интеграция с экосистемой
Наконец, как и в случае с каждым крупным релизом, мы можем в полной мере воспользоваться преимуществами расширенной экосистемы и лучше интегрироваться с ней. Например, ConsoleKit теперь предлагает только высокопроизводительный LogHandler. Вся работа с командами передана Swift Argument Parser. Что касается логов, то теперь мы используем Logger.current везде, что значительно упрощает доступ к логгеру в любом месте ваших сервисов или маршрутов. А поскольку теперь мы поддерживаем эту функцию, к любому вызову логгера внутри запроса автоматически добавляется идентификатор запроса в метаданных.
Теперь мы используем Swift Configuration для настройки вашего сервера, то есть вы можете использовать любой формат конфигурации: файлы YAML, файлы .env, переменные среды, аргументы командной строки — и мы всё это подхватим, если вы укажете провайдера. Все типы, которые мы предоставляем для запросов и ответов, теперь основаны на Swift HTTP Types, и вам больше не нужно преобразовывать их в типы NIO и обратно!
Наконец, мы обеспечиваем интеграцию с Swift Service Lifecycle. Во-первых, если у вас есть другие сервисы Service, которые вы хотите использовать в своём приложении Vapor, вы можете передать их в своё приложение, и Vapor запустит их при запуске приложения и остановит при его завершении с помощью одной простой команды:
app.addService(MyWorker())
Если вы сами управляете несколькими сервисами и хотите просто добавить своё приложение Vapor в группу, Application соответствует Service и позволяет это сделать:
let app = try await Application() let services = ServiceGroup( configuration: .init( services: [ .init( service: app, successTerminationBehavior: .gracefullyShutdownGroup ), .init( service: MyWorker(), successTerminationBehavior: .gracefullyShutdownGroup ), ], gracefulShutdownSignals: [.sigterm, .sigint], logger: Logger.current ) ) try await services.run()
Лучший Vapor
Все эти изменения делают Vapor более удобным в использовании, более производительным, лучше интегрирующимся в экосистему и позволяющим создавать более качественные и безопасные приложения! Нам не терпится увидеть, что у вас получится!
