Black Lives Matter. Support the Equal Justice Initiative.

Bu doküman ingilizce dokümana göre eski olabilir. Son güncellemeler için lütfen İngilizce Dokümanı. ziyaret edin

Express uygulamalarında kullanılacak ara yazılım yazmak

Genel bakış

Ara yazılım fonksiyonları uygulamanın istek-yanıt döngüsünde (req) istek objesi, (res) yanıt objesi, ve next metoduna sahip fonksiyonlardır. Express yönlendiricisinde bir fonksiyon olan nextçağrıldığında şimdiki ara yazılımın ardından gelen ara yazılımı çalıştırır.

Ara yazılım fonksiyonları aşağıdaki görevleri yerine getirebilir:

Eğer şimdiki ara yazılım fonksiyonu istek-yanıt döngüsünü sonlandırmazsa, bir sonraki ara yazılım fonksiyonuna kontrolü vermek için next fonksiyounu çağrılmalı. Aksi takdirde, istek havada kalır.

Aşağıdaki şekil bir ara yazılım fonksiyon çağrısının öğelerini gösterir:

Ara yazılım fonsiyonunu uyglandığı HTTP metodu.
Ara yazılım fonksiyonunun uygulandığı yol (rota).
Ara yazılım fonksiyonu.
Ara yazılım için geri çağırma argümanı, ortak anlayışa göre "next" olarak adlandırıldı.
Ara yazılım fonksiyonuna HTTP yanıtı argümanı, ortak anlayışa göre "res" olarak adlandırıldı.
Ara yazılım fonksiyonuna HTTP isteği argümanı, ortak anlayışa göre "req" olarak adlandırıldı.

Express 5 ile başlayarak, Promise döndüren ara yazılım fonksiyonları reddettiklerinde veya hata fırlattıklarında next(value) fonksiyonunu çağırırlar. next, fırlatılan hata veya ret edilen değer ile çağrılacak.

Örnek

Aşağıdaki basit bir “Merhaba Dünya” Ekspres uygulaması örneği. Bu yazının kalanında uygulamaya üç ara yazılım fonksiyonu tanımlanıp eklenecektir: basit bir log mesajı yazdıran myLogger, HTTP isteğinin zaman damgasını (timestamp) gösteren requestTime, ve gelen çerezleri doğrulayan validateCookies.

const express = require('express')
const app = express()

app.get('/', (req, res) => {
  res.send('Merhaba Dünya!')
})

app.listen(3000)

myLogger ara yazlım fonksiyonu

İşte “myLogger” adında basit bir ara yazılım fonksiyonu. Uygulamaya gelen bir istek bu fonksiyondan geçtiğinde sadece “LOGGED” yazdırır. Bu ara yazılım fonksiyonu, myLogger adında bir değişkene atanmıştır.

const myLogger = function (req, res, next) {
  console.log('LOGGED')
  next()
}

Yukarıdaki örnekte next() çağrısına dikkat edin. Bu fonksiyonu çağırmak, uygulamadaki bir sonraki ara yazılım fonksiyonunu çağırır. next() fonskiyonu Express API veya Node.js’in bir parçası değil, ara yazılım fonksiyonuna geçilen üçüncü argümandır. next() fonksiyonu herhangi bir şekilde adlandırılabilir, ancak orta anlayışa göre her zaman “next” olarak adlandırıldı. Karışıklıktan kaçınmak için her zaman bu şekilde kullanın.

Ara yazılım fonksiyonunu yüklemek için, ara yazılım fonksiyonunu belirterek app.use() metodunu çağırın. Örneğin, aşağıdaki kod (/) kök yoluna yönlendirme yapılmadan önce myLogger ara yazılım fonksiyonunu yükler.

const express = require('express')
const app = express()

const myLogger = function (req, res, next) {
  console.log('LOGGED')
  next()
}

app.use(myLogger)

app.get('/', (req, res) => {
  res.send('Hello World!')
})

app.listen(3000)

Uygulama ne zaman bir istek aldığında, “LOGGED” mesajını terminale yazdırır.

Ara yazılımları yükleme sırası önemlidir: ilk olarak yüklenen ara yazılım fonksiyonları yine ilk olarak çalışacaklardır.

myLogger kök yoluna yönlendirme yapıldıktan sonra yüklenirse, istek hiç ulaşmaz ve uygulama “LOGGED” mesajını yazdırmaz, çünkü kök yolu rota işleyicisi istek-yanıt döngüsünü sonlandırır.

myLogger ara yazılım fonksiyonu basit bir şekilde bir mesaj yazdırır, ve daha sonra next() metodunu çağırarak isteği yığındaki bir sonraki ara yazılım fonksiyonuna geçer.

requestTime ara yazılım fonksiyonu

Bir sonraki örnekte, “requestTime” adında bir ara yazılım fonksiyonu yaratıp requestTime adında bir özelliği istek objesine ekleyeceğiz.

const requestTime = function (req, res, next) {
  req.requestTime = Date.now()
  next()
}

Uygulama şimdi requestTime ara yazılım fonksiyonunu kullanıyor. Ayrıca, kök yol rotasının geri çağırma fonksiyonu, ara yazılımın req istek objesine eklediği özelliği kullanıyor.

const express = require('express')
const app = express()

const requestTime = function (req, res, next) {
  req.requestTime = Date.now()
  next()
}

app.use(requestTime)

app.get('/', (req, res) => {
  let responseText = 'Hello World!<br>'
  responseText += `<small>Requested at: ${req.requestTime}</small>`
  res.send(responseText)
})

app.listen(3000)

Uygulamanın kök yoluna bir istek yaptığınızda, uygulama şimdi tarayıcıda isteğinizin zaman damgasını yazdırıyor.

validateCookies ara yazılım fonksiyonu

Son olarak, gelen çerezleri doğrulayan ve çerezler geçersiz olduğunda 400 yanıtı gönderen bir ara yazılım fonksiyonu yaratacağız.

Harici bir asenkron servisiyle çerezleri doğrulayan bir fonksiyonu örneği.

async function cookieValidator (cookies) {
  try {
    await externallyValidateCookie(cookies.testCookie)
  } catch {
    throw new Error('Geçersiz çerezler')
  }
}

Burada req objesinden gelen çerezleri ayrıştırmak ve onları bizim cookieValidator fonksiyonuna geçmek için cookie-parser ara yazılım fonksiyonunu kullanıyoruz. validateCookies ara yazılımı, ret durumunda otomatik olarak bizim hata işleyicisini tetikleyen bir Promise döndürür.

const express = require('express')
const cookieParser = require('cookie-parser')
const cookieValidator = require('./cookieValidator')

const app = express()

async function validateCookies (req, res, next) {
  await cookieValidator(req.cookies)
  next()
}

app.use(cookieParser())

app.use(validateCookies)

// hata işleyicisi
app.use((err, req, res, next) => {
  res.status(400).send(err.message)
})

app.listen(3000)

next() fonksiyonunun await cookieValidator(req.cookies) çağrısından sonra çağrıldığına bakınız. Bu, cookieValidator çözümlendiğinde yığındaki bir sonraki ara yazılımının çağrılmasını sağlar. next() fonksiyonuna 'route' veya 'router' karakter dizinleri dışında herhangi bir şey geçerseniz Express şimdiki isteği bir hata olarak değerlendirip arda kalan hata olmayan yönlendirme ve ara yazılım fonksiyonlarını es geçer.

İstek objesine, yanıt objesine, yığındaki bir sonraki ara yazılım fonksiyonuna, ve bütün Node.js API’sine erişme imkanına sahip olduğunuzdan, ara yazılım fonksiyonlarının imkanları sınırsızdır.

Express ara yazılımı ile ilgili daha fazla bilgi için, bakınız: Express ara yazılımı kullanmak.

Yapılandırılabilir ara yazılım

Ara yazılımınızın yapılandırılabilir olmasını istiyorsanız, seçenekler objesi veya diğer parametreleri kabul eden ve girdi parametrelerine göre ara yazılım implementasyonunu döndüren bir fonksiyon dışarıya aktarın.

Dosya: my-middleware.js

module.exports = function (options) {
  return function (req, res, next) {
    // "options" objesine göre ara yazılım fonksiyonunu yaz
    next()
  }
}

Bu ara yazılım şimdi aşağıdaki gibi kullanılabilir.

const mw = require('./my-middleware.js')

app.use(mw({ option1: '1', option2: '2' }))

Yapılandırılabilir ara yazılım örnekleri için bakınız: cookie-session ve compression.