التفاوض على المحتوى عمليًا
التفاوض على المحتوى (Content Negotiation)، المحدَّد في RFC-9110، آلية أساسية تتيح للخوادم ووكلاء المستخدم الاتفاق معًا على أنسب تمثيل للمورد. يتناول هذا المقال مواصفته وينفّذه باستخدام Spring Boot، ويتحقق من مدى التزام Spring Boot بمعايير RFC.
يبرز التفاوض على المحتوى كآلية أساسية لجعل واجهات الويب البرمجية أكثر سهولة في الوصول. وتمنح هذه التقنية القوية القائمين على التكامل مع الواجهة حرية اختيار تمثيل البيانات الأنسب لهم، وفي الوقت نفسه تتيح لمزوّدي الواجهات تلبية طيف واسع من احتياجات التكامل. وتعتمد العملية على إجراءات موحّدة، موصوفة باستفاضة في RFC-9110، الذي يوفر أساسًا متينًا لتنفيذها.
ينقسم المقال إلى جزأين. يركّز الأول على نظرية التفاوض على المحتوى ويتناول أنماطه وآلياته. ويعرض الثاني أمثلة واقعية للتفاوض على المحتوى باستخدام إطار Spring Boot.
النظرية وراء التفاوض على المحتوى
كما ذُكر سابقًا، يوجد التفاوض على المحتوى كي يتفق الخادم ووكيل المستخدم على صيغة لمحتوى الطلب والاستجابة تناسب الطرفين. وقد وُحّدت العملية في RFC-9110، الذي يصف ثلاثة أنماط منفصلة.
نمطان لمحتوى الاستجابة
- التفاوض الاستباقي (التفاوض الذي يقوده الخادم) هنا تقع على الخادم مهمة اختيار التمثيل الأنسب، بناءً على ما يعرفه عن وكيل المستخدم. وقد تأتي هذه المعرفة من ترويسات تفاوض صريحة (Accept وAccept-Encoding وAccept-Charset وAccept-Language) أو من سمات ضمنية، مثل أجزاء من ترويسة User-Agent أو عنوان الشبكة.
- التفاوض التفاعلي (التفاوض الذي يقوده الوكيل) في هذا النهج يختار وكيل المستخدم التمثيل الأنسب بعد أن يتلقى استجابة أولية. فبدلًا من إرسال تمثيل أولي، يمكن للخادم أن يعيد قائمة بالتمثيلات المتاحة مع رمز الاستجابة 300 (خيارات متعددة) أو 406 (غير مقبول). ثم يستخدم وكيل المستخدم هذه المعلومات لإرسال طلب آخر للتمثيل الذي اختاره.
نمط واحد لمحتوى الطلب
- التفاوض على محتوى الطلب يمكن للخادم أن يشير إلى الصيغة التي يفضّلها لمحتوى الطلب. وللقيام بذلك قد يضيف ترويسات تفاوض إلى استجابته، يستطيع وكيل المستخدم بعد ذلك إعادة استخدامها في الطلبات اللاحقة.
ترويسات التفاوض على المحتوى
يحدد معيار التفاوض على المحتوى الترويسات التالية:
- Accept: تعبّر هذه الترويسة عن التفضيلات المتعلقة بنوع وسائط محتوى الرسالة. ففي الطلب تبيّن تفضيلات وكيل المستخدم لمحتوى الاستجابة. وفي الاستجابة تبيّن تفضيلات الخادم لمحتوى الطلب في الطلبات اللاحقة.
- Accept-Charset: تصنّفها إرشادات RFC على أنها مهجورة وينبغي تجنبها حيثما أمكن؛ لكنها كانت قبل هجرها تُستخدم للتعبير عن تفضيلات مجموعة المحارف. ويمكن لرمز بدل (wildcard) أن يمثل أي مجموعة محارف لم تُذكر في موضع آخر من الحقل.
- Accept-Encoding: هذه الترويسة مخصصة للتعبير عن تفضيلات ترميز المحتوى. وتتيح لوكلاء المستخدم تحديد ترميزات المحتوى التي يقبلونها في الاستجابة، كما تتيح للخوادم تحديد ترميز المحتوى الذي تفضّله في الطلبات اللاحقة. والرمز identity يعني ما يعنيه غياب الترميز.
- Accept-Language: تتيح لوكلاء المستخدم تحديد اللغات الطبيعية التي يفضلونها في الاستجابات. ويُعبَّر عن هذه التفضيلات بوسوم اللغة، فيستطيع المستخدمون ترتيب اللغات. وقد تحمل وسوم اللغة قيم جودة تعكس مدى تفضيل المستخدم لها.
- Vary: ترويسة استجابة تسرد أجزاء الطلب، غير الطريقة والهدف، التي تؤثر في كيفية اختيار الخادم لتمثيل الاستجابة. وقد تكون الرمز البدل * أو قائمة بأسماء حقول الطلب التي ربما أسهمت في اختيار تمثيل الاستجابة.
سنفتتح هذا الجزء بملخص موجز للقواعد الواجب اتباعها عند استخدام ترويسات التفاوض على المحتوى أو معالجتها.
قواعد عامة
- إذا غابت ترويسة تفاوض على المحتوى عن الطلب، فليس لدى المرسل تفضيلات في ذلك البعد من التفاوض.
- يمكن لكل حقل تفاوض على المحتوى أن يحمل عدة تفضيلات.
- يمكن ترتيب التفضيلات باستخدام قيم الجودة
“q”من النطاق0..1، بحد أقصى 3 أرقام بعد الفاصلة العشرية، حيث 1 تعني الأكثر تفضيلًا، و0.001الأقل تفضيلًا، و0 غير مقبول. - تأتي قيمة الجودة بعد التفضيل الذي تنطبق عليه ويفصلها عنه فاصلة منقوطة (مثل
application/json;q=0.8) - حين لا تُعطى قيمة جودة تُفترض قيمتها 1
- في معظم ترويسات التفاوض على المحتوى، يمكن لرمز بدل، حيث يُسمح به، أن يشير إلى قيمة غير محددة (مثل
Accept: text/*تشير إلى أي نوع mime نصي).
تنفيذ اختيار نوع الوسائط عبر التفاوض على المحتوى
لنوضح كيف يمكن أن يعمل التفاوض على المحتوى، سنبني خطوة بخطوة تطبيقًا بسيطًا يعيد أسعار الصرف. وسنكتبه بلغة Kotlin مع أحدث إصدار من Spring Boot.
إنشاء المشروع
نبدأ بتوليد مشروع باستخدام spring initializr.
سنعدّه كما يلي
- مشروع Gradle مع Kotlin DSL
- Kotlin كلغة
- أحدث إصدار مستقر من Spring Boot
- إصدار Java 17
- اعتمادية على Spring Web
بيانات وهمية
تكفي خدمة تعيد بيانات وهمية لإظهار كيفية عمل التفاوض على المحتوى
private val EUR = Currency.getInstance("EUR")
private val USD = Currency.getInstance("USD")
private val PLN = Currency.getInstance("PLN")
@Service
class ExchangeRatesService {
private val exchangeRates: ExchangeRates = ExchangeRates(
listOf(
ExchangeRate(
baseCurrency = EUR,
quotedCurrency = USD,
rate = BigDecimal.valueOf(1.10)
),
ExchangeRate(
baseCurrency = USD,
quotedCurrency = EUR,
rate = BigDecimal.valueOf(0.90)
)
),
Instant.now()
)
fun getAllExchangeRates(): ExchangeRates {
return exchangeRates
}
}
data class ExchangeRates(val exchangeRates: List<ExchangeRate>, val updatedAt: Instant)
data class ExchangeRate(val baseCurrency: Currency, val quotedCurrency: Currency, val rate: BigDecimal)
كشف نقطة نهاية تقدّم أول تمثيل للمورد بصيغة application/json
بعد ذلك يمكننا الانتقال إلى نقطة نهاية تقدّم التمثيل الأول (application/json) للاستجابة:
package com.example.contentnegotiation.controller
import com.example.contentnegotiation.domain.ExchangeRatesService
import org.springframework.http.MediaType
import org.springframework.web.bind.annotation.GetMapping
import org.springframework.web.bind.annotation.RequestMapping
import org.springframework.web.bind.annotation.RestController
@RestController
@RequestMapping("/exchange-rates")
class ExchangeRatesController(private val exchangeRatesService: ExchangeRatesService) {
@GetMapping(produces = [MediaType.APPLICATION_JSON_VALUE])
fun getAllExchangeRates(): ExchangeRatesResponse {
val exchangeRates = exchangeRatesService.getAllExchangeRates()
return ExchangeRatesResponse(
exchangeRates = exchangeRates.exchangeRates.map {
ExchangeRateResponseItem(
baseCurrency = it.baseCurrency,
quotedCurrency = it.quotedCurrency,
rate = it.rate
)
},
updatedAt = exchangeRates.updatedAt
)
}
}
الآن نشغّل التطبيق ونرسل طلبًا تجريبيًا
curl --location 'http://localhost:8080/exchange-rates'
هذه هي الاستجابة التي نحصل عليها:
HTTP/1.1 200
Content-Type: application/json
Transfer-Encoding: chunked
Date: Thu, 17 Aug 2023 09:38:43 GMT
{
"exchangeRates": [
{
"baseCurrency": "EUR",
"quotedCurrency": "USD",
"rate": 1.1
},
{
"baseCurrency": "USD",
"quotedCurrency": "EUR",
"rate": 0.9
}
],
"updatedAt": "2023-08-17T09:32:21.407251Z"
}
إضافة تمثيل آخر للمورد بصيغة application/xml
يتطلب تسلسل XML اعتمادية إضافية واحدة في ملف Gradle: com.fasterxml.jackson.dataformat:jackson-dataformat-xml.
بعد ذلك نوسّع نقطة النهاية الحالية بإضافة نوع وسائط آخر (MediaType.APPLICATION_XML_VALUE) إلى قسم ‘produces’.
@RestController
@RequestMapping("/exchange-rates")
class ExchangeRatesController(private val exchangeRatesService: ExchangeRatesService) {
@GetMapping(produces = [MediaType.APPLICATION_JSON_VALUE, MediaType.APPLICATION_XML_VALUE])
fun getAllExchangeRates(): ExchangeRatesResponse {
...
يمكننا بعدها إعادة تشغيل التطبيق والتحقق من أن تمثيل XML يبدو صحيحًا:
curl -i --location 'http://localhost:8080/exchange-rates' \
--header 'Accept: application/xml'
ينبغي أن تبدو الاستجابة هكذا
HTTP/1.1 200
Content-Type: application/xml
Transfer-Encoding: chunked
Date: Thu, 17 Aug 2023 10:12:28 GMT
<ExchangeRatesResponse>
<exchangeRates>
<exchangeRates>
<baseCurrency>EUR</baseCurrency>
<quotedCurrency>USD</quotedCurrency>
<rate>1.1</rate>
</exchangeRates>
<exchangeRates>
<baseCurrency>USD</baseCurrency>
<quotedCurrency>EUR</quotedCurrency>
<rate>0.9</rate>
</exchangeRates>
</exchangeRates>
<updatedAt>2023-08-17T10:12:23.792904Z</updatedAt>
</ExchangeRatesResponse>
إضافة تمثيل أكثر تقدمًا للمورد: text/html
هنا أريد أن أوضح التعامل مع تمثيل أكثر تعقيدًا – تمثيل لا يمكن تسلسله تلقائيًا. لنأخذ صيغة text/html. سنولّد محتوى HTML بمكتبة Kotlin توفر DSL لهذا الغرض تحديدًا: org.jetbrains.kotlinx:kotlinx-html-jvm.
بعد ذلك نكتب مُحوِّلًا (mapper) يبني تمثيل HTML لمورد أسعار الصرف
package com.example.contentnegotiation.controller
import com.example.contentnegotiation.domain.ExchangeRates
import kotlinx.html.*
import kotlinx.html.stream.appendHTML
import org.springframework.context.i18n.LocaleContextHolder
import org.springframework.stereotype.Component
import java.time.ZoneOffset
import java.time.format.DateTimeFormatter
private val DATE_TIME_FORMATTER = DateTimeFormatter.ofPattern("uuuu-MM-dd HH:mm:ss")
@Component
class HTMLMapper {
fun mapToHTML(exchangeRates: ExchangeRates): String {
val locale = LocaleContextHolder.getLocale()
return buildString {
appendHTML().html {
head {
title { +"Exchange rates" }
style {
unsafe {
+"""
h1, h2, p {
text-align: center;
}
table {
margin-left:auto;
margin-right:auto;
}
th, td {
text-align: center;
padding: 10px;
border:1px solid black;
}
""".trimIndent()
}
}
}
body {
h1 { +"Exchange rates" }
p {
h2 {
+"Updated at: ${DATE_TIME_FORMATTER.format(exchangeRates.updatedAt.atOffset(ZoneOffset.UTC))}"
}
table {
thead {
tr {
th { +"Base currency" }
th { +"Quoted currency" }
th { +"Rate" }
}
}
tbody {
exchangeRates.exchangeRates.map {
tr {
td { +"${it.baseCurrency}" }
td { +"${it.quotedCurrency}" }
td { +"${it.rate}" }
}
}
}
}
}
}
}
}
}
}
لاستخدامه في ExchangeRatesControler، نحتاج أولًا إلى إضافة صيغة جديدة من نقطة النهاية إلى المتحكم
package com.example.contentnegotiation.controller
import com.example.contentnegotiation.domain.ExchangeRatesService
import org.springframework.http.MediaType
import org.springframework.web.bind.annotation.GetMapping
import org.springframework.web.bind.annotation.RequestMapping
import org.springframework.web.bind.annotation.RestController
@RestController
@RequestMapping("/exchange-rates")
class ExchangeRatesController(
private val exchangeRatesService: ExchangeRatesService,
private val htmlMapper: HTMLMapper
) {
@GetMapping(produces = [MediaType.APPLICATION_JSON_VALUE, MediaType.APPLICATION_XML_VALUE])
fun getAllExchangeRates(): ExchangeRatesResponse {
val exchangeRates = exchangeRatesService.getAllExchangeRates()
return ExchangeRatesResponse(
exchangeRates = exchangeRates.exchangeRates.map {
ExchangeRateResponseItem(
baseCurrency = it.baseCurrency,
quotedCurrency = it.quotedCurrency,
rate = it.rate
)
},
updatedAt = exchangeRates.updatedAt
)
}
@GetMapping(produces = [MediaType.TEXT_HTML_VALUE])
fun helloHTML(): String {
return htmlMapper.mapToHTML(exchangeRatesService.getAllExchangeRates())
}
}
بعد ذلك نعيد تشغيل التطبيق ونتأكد من أن تمثيل HTML يعود بشكل صحيح
curl -i --location 'http://localhost:8080/exchange-rates' \
--header 'Accept: text/html'
ينبغي أن نحصل على
HTTP/1.1 200
Content-Type: text/html;charset=UTF-8
Content-Length: 1156
Date: Thu, 17 Aug 2023 11:56:35 GMT
<html>
<head>
<title>Exchange rates</title>
<style>h1, h2, p {
text-align: center;
}
table {
margin-left:auto;
margin-right:auto;
}
th, td {
text-align: center;
padding: 10px;
border:1px solid black;
}</style>
</head>
<body>
<h1>Exchange rates</h1>
<p>
<h2>Updated at: 2023-08-17 13:03:04</h2>
<table>
<thead>
<tr>
<th>Base currency</th>
<th>Quoted currency</th>
<th>Rate</th>
</tr>
</thead>
<tbody>
<tr>
<td>EUR</td>
<td>USD</td>
<td>1.1</td>
</tr>
<tr>
<td>USD</td>
<td>EUR</td>
<td>0.9</td>
</tr>
</tbody>
</table>
</p>
</body>
</html>
تقييم خوارزمية التفاوض على المحتوى في Spring Boot
أصبحت ثلاثة أنواع وسائط مدعومة الآن. حان وقت بعض التجارب لنرى كيف يستخدم Spring Boot التفاوض على المحتوى لاختيار نوع الوسائط الأنسب.
دعم قيم الجودة
بدايةً، سنتحقق مما إذا كان Spring Boot يحترم قيم “q” كما حددها RFC-9110. سنرسل عددًا من الطلبات لنعرف.
بالنسبة إلى هذا الطلب
curl -i --location 'http://localhost:8080/exchange-rates' \
--header 'Accept:text/html;q=0.9,application/xml;q=0.8,application/json;q=0.7'
نحصل على
HTTP/1.1 200
Content-Type: text/html;charset=UTF-8
Content-Length: 1225
Date: Thu, 17 Aug 2023 13:13:40 GMT
...
وبالنسبة إلى هذا الطلب
curl -i --location 'http://localhost:8080/exchange-rates' \
--header 'Accept:text/html;q=0.8,application/xml;q=0.9,application/json;q=0.7'
نحصل على
HTTP/1.1 200
Content-Type: application/xml
Transfer-Encoding: chunked
Date: Thu, 17 Aug 2023 13:17:58 GMT
...
وبالنسبة إلى هذا الطلب
curl -i --location 'http://localhost:8080/exchange-rates' \
--header 'Accept:text/html;q=0.7,application/xml;q=0.8,application/json;q=0.9'
نحصل على
HTTP/1.1 200
Content-Type: application/json
Transfer-Encoding: chunked
Date: Thu, 17 Aug 2023 13:20:04 GMT
...
من الواضح أن Spring Boot عالج قيمة ‘q’ بشكل صحيح في كل مرة، إذ اختار دائمًا التمثيل المدعوم صاحب أعلى قيمة ‘q’.
غياب ترويسة Accept
لنر الآن ما يحدث عندما لا تُرسل ترويسة ‘Accept’، أو عندما تُرسل بقيمة فارغة.
عندما تكون ترويسة Accept غائبة أو فارغة أو مضبوطة على */*، نحصل على الاستجابة التالية:
HTTP/1.1 200
Content-Type: application/json
Transfer-Encoding: chunked
Date: Thu, 17 Aug 2023 13:20:04 GMT
...
كيف يُحدَّد التمثيل في هذه الحالة؟
يوضح النظر في شيفرة Spring أن ترويسة Accept الغائبة أو الفارغة تعود إلى */*. وينتج عن ذلك ثلاثة تمثيلات ممكنة للمورد، لها جميعًا الأولوية نفسها. وعندما تتشارك عدة أنواع وسائط في قيمة الجودة نفسها، يُحسم ترتيبها بالدالة compareTo في الصنف MimeType. وببساطة، يحسم الترتيب الأبجدي لأنواع mime الأمر.
قيمة غير مدعومة في ترويسة Accept
لنر ما يحدث عندما تحمل ترويسة Accept قيمة لا يدعمها الخادم:
بالنسبة إلى text/plain نحصل على:
HTTP/1.1 406
Accept: application/json, application/xml, text/html
Content-Length: 0
Date: Thu, 17 Aug 2023 13:49:31 GMT
تأتي الاستجابة برمز الحالة 406 (Not Acceptable) وتتضمن ترويسة Accept تسرد كل أنواع الوسائط المدعومة (application/json, application/xml, text/html).
جلب أسعار الصرف من متصفح ويب
من اللافت أن جلب مورد أسعار الصرف من متصفح ويب يعطينا تمثيل HTML
وذلك لأن متصفحات الويب ترسل تفضيلاتها الخاصة للمحتوى الذي تجلبه. وكما نرى، فإن text/plain هو خيارها الأول
تنفيذ التدويل عبر التفاوض على المحتوى
لنوضح كيف يعمل التفاوض على لغة المحتوى في Spring، دعونا نضيف دعمًا للغات متعددة… محتوى HTML لدينا مرشح مثالي للتدويل.
لذلك سنستخدم صنف Spring المسمى MessageSource، القادر على حل النصوص بحسب سياق اللغة المحلية للطلب. لنغيّر HTMLMapper ليبدأ باستخدام MessageSource:
private const val EXCHANGE_RATES = "exchange-rates"
private const val UPDATED_AT = "updated-at"
private const val BASE_CURRENCY = "base-currency"
private const val QUOTED_CURRENCY = "quoted-currency"
private const val RATE = "rate"
private val DATE_TIME_FORMATTER = DateTimeFormatter.ofPattern("uuuu-MM-dd HH:mm:ss")
@Component
class HTMLMapper(private val messageSource: MessageSource) {
fun mapToHTML(exchangeRates: ExchangeRates): String {
val locale = LocaleContextHolder.getLocale()
return buildString {
appendHTML().html {
head {
title { +messageSource.getMessage(EXCHANGE_RATES, null, locale)}
...
table {
thead {
tr {
th { +messageSource.getMessage(BASE_CURRENCY, null, locale) }
th { +messageSource.getMessage(QUOTED_CURRENCY, null, locale) }
th { +messageSource.getMessage(RATE, null, locale)}
}
}
...
بعد ذلك نجهّز ملفات الترجمة. افتراضيًا تُستخدم ملفات الإعداد من حزمة الموارد التي تتبع اصطلاح التسمية messages_{language_code}.properties. ويوضع اللغة الافتراضية في الملف messages.properties.
سنضيف الآن ترجمات لثلاث لغات (الإنجليزية والألمانية والفرنسية)، مع جعل الإنجليزية الافتراضية
يحتوي كل ملف لغة الخصائص التالية، مترجمة وفقًا لذلك:
messages.properties
exchange-rates=Exchange rates
updated-at=Updated at
base-currency=Base currency
quoted-currency=Quoted currency
rate=Rate
ثم علينا ضبط اللغات المحلية المدعومة. نفعل ذلك بتوفير bean من النوع LocaleResolver
@Configuration
class LocaleConfiguration {
@Bean
fun localeResolver(): LocaleResolver {
val localeResolver = AcceptHeaderLocaleResolver()
localeResolver.setDefaultLocale(Locale.ENGLISH)
localeResolver.supportedLocales = listOf(Locale.ENGLISH, Locale.GERMANY, Locale.FRENCH)
return localeResolver
}
}
بعد ذلك يمكننا إعادة تشغيل التطبيق وإرسال بعض الطلبات
غياب ترويسة Accept-Language
طلب بلا ترويسة Accept-Language
curl -i --location 'http://localhost:8080/exchange-rates' \
--header 'Accept: text/html'
يعيد استجابة باللغة الافتراضية، أي الإنجليزية
HTTP/1.1 200
Content-Type: text/html;charset=UTF-8
Content-Length: 1225
Date: Fri, 18 Aug 2023 09:35:31 GMT
<html>
<head>
<title>Exchange rates</title>
<style>h1, h2, p {
text-align: center;
}
table {
margin-left:auto;
margin-right:auto;
}
th, td {
text-align: center;
padding: 10px;
border:1px solid black;
}</style>
</head>
<body>
<h1>Exchange rates</h1>
<p>
<h2>Updated at: 2023-08-18 09:27:59</h2>
<table>
<thead>
<tr>
<th>Base currency</th>
<th>Quoted currency</th>
<th>Rate</th>
</tr>
...
Accept-Language بقيمة غير مدعومة
إذا طلبت ترويسة Accept-Language الإسبانية، وهي غير مدعومة
curl -i --location 'http://localhost:8080/exchange-rates' \
--header 'Accept: text/html' \
--header 'Accept-Language: es'
تعود الاستجابة باللغة الافتراضية (على عكس ترويسة Accept، لا يُعاد هنا رمز 406)
HTTP/1.1 200
Content-Type: text/html;charset=UTF-8
Content-Length: 1225
Date: Fri, 18 Aug 2023 09:35:31 GMT
<html>
<head>
<title>Exchange rates</title>
<style>.....</style>
</head>
<body>
<h1>Exchange rates</h1>
<p>
<h2>Updated at: 2023-08-18 09:27:59</h2>
<table>
<thead>
<tr>
<th>Base currency</th>
<th>Quoted currency</th>
<th>Rate</th>
</tr>
...
قائمة لغات مع قيم جودة
إذا تضمّن الطلب قائمة لغات مع قيم q
curl -i --location 'http://localhost:8080/exchange-rates' \
--header 'Accept: text/html' \
--header 'Accept-Language: en;q=0.5,fr;q=0.7,de;q=0.6,es;0.9'
نحصل على اللغة المدعومة صاحبة أعلى قيمة q – الفرنسية في هذه الحالة
HTTP/1.1 200
Content-Type: text/html;charset=UTF-8
Content-Length: 1225
Date: Fri, 18 Aug 2023 09:42:44 GMT
<html>
<head>
<title>Kursy wymian</title>
<style>h1, h2, p {
text-align: center;
}
table {
margin-left:auto;
margin-right:auto;
}
th, td {
text-align: center;
padding: 10px;
border:1px solid black;
}</style>
</head>
<body>
<h1>Kursy wymian</h1>
<p>
<h2>Zaktualizowane: 2023-08-18 09:27:59</h2>
<table>
<thead>
<tr>
<th>Bazowa waluta</th>
<th>Notowana waluta</th>
<th>Kurs</th>
</tr>
...
جلب أسعار الصرف من متصفح ويب
تمامًا كما في نوع المحتوى، يرسل المتصفح أيضًا تفضيلاته للغة المحتوى
ويمكن ضبط هذه التفضيلات في إعدادات المتصفح. وهكذا يبدو الأمر في Google Chrome
وعاد المحتوى بلغة متصفحي الافتراضية
التفاوض على ترميز المحتوى
يتطلب ترميز المحتوى ضبط ثلاث خصائص في Spring Boot
server.compression.enabled: تفعّل ضغط المحتوى من جهة الخادمserver.compression.mime-types: تحدد أنواع المحتوى التي يجوز ضغطهاserver.compression.min-response-size: أصغر حجم استجابة، بالبايت، يُضغط.
لنضع هذه الخصائص في الملف application.properties
server.compression.enabled=true
server.compression.mime-types=text/html,application/json,application/xml
server.compression.min-response-size=1024
بعد ذلك نعيد تشغيل التطبيق ونرسل بعض الطلبات التجريبية
طلب بلا Accept-Encoding
إذا أرسلنا الطلب
curl -sI --location 'http://localhost:8080/exchange-rates' \
--header 'Accept: text/html'
نحصل على هذه الاستجابة
HTTP/1.1 200
vary: accept-encoding
Content-Type: text/html;charset=UTF-8
Content-Length: 1225
Date: Fri, 18 Aug 2023 12:42:37 GMT
الاستجابة غير مضغوطة، رغم أنها أكبر من الحد الأدنى للضغط الذي ضبطناه. ونرى أيضًا ترويسة Vary: Accept-Encoding، وهي تشير إلى أن ترويسة Accept-Encoding قد تؤخذ في الحسبان عند بناء الاستجابة.
طلب مع ترميز محتوى محدد
إذا حدد الطلب gzip كترميز مقبول
curl -sI --location 'http://localhost:8080/exchange-rates' \
--header 'Accept: text/html' \
--header 'Accept-Encoding: gzip'
تعود الاستجابة مضغوطة
HTTP/1.1 200
vary: accept-encoding
Content-Encoding: gzip
Content-Type: text/html;charset=UTF-8
Transfer-Encoding: chunked
Date: Fri, 18 Aug 2023 13:25:33 GMT
قيمة الجودة المستخدمة في ترميز المحتوى
إذا أرسلنا طلبًا تحمل ترويسة Accept-Encoding فيه قيمتين، gzip وidentity، مع إعطاء identity قيمة جودة أعلى:
curl -sI --location 'http://localhost:8080/exchange-rates' \
--header 'Accept: text/html' \
--header 'Accept-Encoding: gzip;q=0.1,identity;q=0.3'
فإننا ما زلنا نحصل على استجابة مضغوطة
HTTP/1.1 200
vary: accept-encoding
Content-Encoding: gzip
Content-Type: text/html;charset=UTF-8
Transfer-Encoding: chunked
Date: Fri, 18 Aug 2023 13:32:52 GMT
إذن في هذه الحالة لا تُستخدم قيمة ‘q’ الأعلى لتحديد الأولوية.
تفضيل ترميز بقيمة جودة تساوي صفرًا
إذا أرسلنا طلبًا
curl -sI --location 'http://localhost:8080/exchange-rates' \
--header 'Accept: text/html' \
--header 'Accept-Encoding: gzip;q=0'
تعود الاستجابة غير مضغوطة
HTTP/1.1 200
vary: accept-encoding
Content-Type: text/html;charset=UTF-8
Content-Length: 1225
Date: Fri, 18 Aug 2023 13:36:40 GMT
وهذا يبين أنه يمكن استخدام قيمة الجودة لاستبعاد صيغ ضغط معينة.
تعديلات ترويسة Vary
كما رأينا، أدى تفعيل ضغط الاستجابة إلى ظهور ترويسة Vary في الاستجابات. لكن هذا ليس ما نريده تمامًا. فالتفاوض على المحتوى لدينا يعتمد على ترويسات مثل Accept, Accept-Language وAccept-Encoding، وكل منها قادر على تغيير تمثيل الاستجابة.
للأسف، لا توجد في Spring خاصية مخصصة لتغيير هذا السلوك. لكن فلتر servlet يوفر حلًا بديلًا سهلًا:
@WebFilter("/exchange-rates")
class ExchangeRateFilter : Filter{
override fun doFilter(request: ServletRequest?, response: ServletResponse?, chain: FilterChain?) {
val httpServletResponse = response as HttpServletResponse
httpServletResponse.setHeader(HttpHeaders.VARY, "${HttpHeaders.ACCEPT}, ${HttpHeaders.ACCEPT_LANGUAGE}, ${HttpHeaders.ACCEPT_ENCODING}")
chain!!.doFilter(request, response)
}
}
ولكي يسري ذلك، يجب إضافة التعليق التوضيحي @ServletComponentScan أيضًا.
@SpringBootApplication
@ServletComponentScan
class ContentNegotiationApplication
fun main(args: Array<String>) {
runApplication<ContentNegotiationApplication>(*args)
}
ثم نعيد تشغيل التطبيق ونرسل طلبًا تجريبيًا
curl -I --location 'http://localhost:8080/exchange-rates'
ينبغي أن تتضمن الاستجابة الآن ترويسة Vary تسرد كل حقل يمكن أن يغيّر تمثيل الاستجابة
HTTP/1.1 200
Vary: accept,accept-language,accept-encoding
Content-Type: application/json
Transfer-Encoding: chunked
Date: Fri, 18 Aug 2023 14:31:51 GMT
الخلاصة
استكشف هذا المقال نظرية التفاوض على المحتوى كما هي موصوفة في RFC-9110. وبعد أن غطينا النظرية، بنينا مثالًا عمليًا باستخدام Spring Boot.
فيما يلي نظرة عامة على كيفية دعم Spring Boot للتفاوض على المحتوى، ومدى مطابقته للنظرية، وسلوكه في الحالات الحدّية:
| عنصر التفاوض | الترويسة | أخذ قيمة q في الحسبان | السلوك عند غياب الترويسة | قيم الترويسة غير المدعومة | مُدرجة في ترويسة Vary | نمط التفاوض على المحتوى |
|---|---|---|---|---|---|---|
| نوع الوسائط | Accept | نعم | يُعاد نوع الوسائط المدعوم الذي يأتي أولًا أبجديًا | يُعاد 406 (غير مقبول)؛ وتحمل الاستجابة ترويسة Accept تسرد أنواع الوسائط المدعومة | لا | استباقي، تفاعلي |
| اللغة | Accept-Language | نعم | تُستخدم اللغة الافتراضية | تُستخدم اللغة الافتراضية | لا | استباقي |
| الترميز | Accept-Encoding | لا | لا يُستخدم أي ترميز | لا يُستخدم أي ترميز | نعم | استباقي |
ومن الجدير إبراز أن Spring Boot يأتي بآلية تفاوض على المحتوى مدمجة ومرنة جدًا. ويمكن عدّها نوعًا من التفاوض الاستباقي على المحتوى، لا يظهر فيه رمز الاستجابة 406 إلا في الحالات النادرة التي لا يستطيع فيها الخادم تقديم تمثيل مقبول.
ومع ذلك، فهو لا يتبع مواصفة RFC-9110 بدقة في كل السيناريوهات. وقد ظهر ذلك بوضوح أكبر في التفاوض على الترميز وفي طريقة إلحاق ترويسة Vary، وكلاهما اضطررنا إلى تعديله.