Գնահատել նախագիծը
← Բոլոր հրապարակումները

Content negotiation գործնականում

Content Negotiation-ը, որը սահմանված է RFC-9110-ում, կարևոր մեխանիզմ է, որը թույլ է տալիս սերվերներին և user agent-ներին համատեղ ընտրել ռեսուրսի ամենահարմար ներկայացումը։ Այս հոդվածում քննարկվում է դրա սպեցիֆիկացիան, այն իրագործվում է Spring Boot-ով, և ստուգվում է, թե որքան ճշգրիտ է Spring Boot-ը հետևում RFC ստանդարտներին։

16 րոպե
JavaAPIԾրագրավորումSpring BootKotlin

Content negotiation-ը վեբ API-ները առավել հասանելի դարձնելու առանցքային մեխանիզմ է։ Այս հզոր տեխնիկան API-ի ինտեգրատորներին ազատություն է տալիս ընտրել իրենց համար առավել հարմար տվյալների ներկայացումը, իսկ API-ի մատակարարներին՝ միաժամանակ սպասարկել ինտեգրման բազմազան կարիքներ։ Գործընթացը հիմնվում է ստանդարտացված ընթացակարգերի վրա, որոնք մանրամասն նկարագրված են RFC-9110-ում և իրագործման համար ամուր հիմք են տալիս։

Հոդվածը երկու մասից է բաղկացած։ Առաջինը կենտրոնանում է Content Negotiation-ի տեսության վրա և դիտարկում է դրա օրինաչափություններն ու մեխանիզմները։ Երկրորդը ներկայացնում է content negotiation-ի իրական օրինակներ Spring Boot ֆրեյմվորքով։

Content Negotiation-ի տեսությունը

Ինչպես նշվեց վերևում, content negotiation-ը գոյություն ունի, որպեսզի սերվերը և user agent-ը կարողանան համաձայնության գալ հարցման և պատասխանի բովանդակության այնպիսի ձևաչափի շուրջ, որը հարմար է երկուսին էլ։ Գործընթացը ստանդարտացված է RFC-9110-ում, որը նկարագրում է երեք առանձին օրինաչափություն։

Երկու օրինաչափություն պատասխանի բովանդակության համար

  • Proactive content negotiation (սերվերի կողմից կառավարվող negotiation) Այստեղ սերվերի գործն է ընտրել ամենահարմար ներկայացումը՝ հիմնվելով user agent-ի մասին իր գիտելիքների վրա։ Այդ գիտելիքը կարող է գալ content negotiation-ի բացահայտ header-ներից (Accept, Accept-Encoding, Accept-Charset, Accept-Language) կամ անուղղակի հատկանիշներից, օրինակ՝ User-Agent header-ի մասերից կամ ցանցային հասցեից։
  • Reactive content negotiation (user agent-ի կողմից կառավարվող negotiation) Այս մոտեցման դեպքում user agent-ն ընտրում է ամենահարմար ներկայացումը՝ սկզբնական պատասխանը ստանալուց հետո։ Սկզբնական ներկայացում ուղարկելու փոխարեն սերվերը կարող է վերադարձնել հասանելի ներկայացումների ցանկ՝ 300 (multiple choices) կամ 406 (not acceptable) պատասխանի կոդով։ Այնուհետև user agent-ն այս տեղեկատվությունն օգտագործում է ընտրված ներկայացման համար նոր հարցում ուղարկելու համար։

Մեկ օրինաչափություն հարցման բովանդակության համար

  • Request content negotiation Սերվերը կարող է ազդանշանել, թե որ ձևաչափն է նախընտրում հարցման բովանդակության համար։ Դրա համար այն իր պատասխանին կարող է ավելացնել negotiation header-ներ, որոնք user agent-ը հետո կարող է կրկին օգտագործել հաջորդ հարցումներում։

Content negotiation-ի header-ները

Content negotiation-ի ստանդարտը սահմանում է հետևյալ header-ները՝

  • Accept: Այս header-ը արտահայտում է նախապատվություններ հաղորդագրության բովանդակության media type-ի վերաբերյալ։ Հարցման մեջ այն նշում է user agent-ի նախապատվությունները պատասխանի բովանդակության համար։ Պատասխանի մեջ այն նշում է սերվերի նախապատվությունները հետագա հարցումներում հարցման բովանդակության համար։
  • Accept-Charset: RFC-ի ուղեցույցները այն նշում են որպես deprecated, և հնարավորության դեպքում պետք է խուսափել դրանից. սակայն deprecated դառնալուց առաջ այն ծառայում էր charset-ի նախապատվություններն արտահայտելու համար։ Wildcard-ը կարող է փոխարինել ցանկացած charset, որը այլ տեղ նշված չէ դաշտում։
  • Accept-Encoding: Այս header-ը նախատեսված է բովանդակության կոդավորման (content coding) նախապատվություններն արտահայտելու համար։ Այն թույլ է տալիս user agent-ներին ասել, թե որ content coding-ներն են ընդունում պատասխանում, ինչպես նաև թույլ է տալիս սերվերներին նշել այն content coding-ը, որը նախընտրում են հետագա հարցումների համար։ Identity token-ը նշանակում է նույնը, ինչ կոդավորման բացակայությունը։
  • Accept-Language: թույլ է տալիս user agent-ներին նշել, թե որ բնական լեզուները նախընտրում են պատասխաններում։ Այս նախապատվությունները արտահայտվում են լեզվի թեգերով, ուստի օգտատերերը կարող են լեզուները դասակարգել։ Լեզվի թեգերը կարող են ունենալ quality արժեքներ, որոնք արտացոլում են, թե որքան ուժեղ է օգտատերը նախընտրում դրանք։
  • Vary: պատասխանի header, որը թվարկում է, թե հարցման որ մասերը, մեթոդից և թիրախից բացի, ազդում են այն բանի վրա, թե ինչպես է սերվերն ընտրում պատասխանի ներկայացումը։ Դա կարող է լինել wildcard * կամ հարցման դաշտերի անունների ցանկ, որոնք կարող էին ներդրում ունենալ պատասխանի ներկայացման ընտրության մեջ։

Այս մասը կսկսենք content negotiation-ի header-ներն օգտագործելիս կամ մշակելիս պահպանվող կանոնների համառոտ ամփոփմամբ։

Ընդհանուր կանոններ

  1. Եթե content negotiation header-ը բացակայում է հարցումից, ուղարկողը negotiation-ի այդ հարթության մեջ նախապատվություններ չունի։
  2. Յուրաքանչյուր content negotiation դաշտ կարող է պարունակել մի քանի նախապատվություն։
  3. Նախապատվությունները կարելի է դասակարգել quality արժեքներով “q” 0..1 միջակայքից՝ մինչև 3 թվանշան ստորակետից հետո, որտեղ 1-ը նշանակում է առավել նախընտրելի, 0.001-ը՝ ամենաքիչ նախընտրելի, իսկ 0-ն՝ չընդունվող։
  4. Quality արժեքը հետևում է այն նախապատվությանը, որին վերաբերում է, և բաժանվում է դրանից կետ-ստորակետով (օրինակ՝ application/json;q=0.8)
  5. Երբ quality արժեք նշված չէ, ենթադրվում է 1
  6. Content negotiation-ի header-ների մեծ մասում wildcard-ը, եթե թույլատրվում է, կարող է նշանակել չճշտված արժեք (օրինակ՝ Accept: text/*-ը նշանակում է ցանկացած text mime type)։

Media type-ի ընտրության իրագործում content negotiation-ով

Ցույց տալու համար, թե ինչպես կարող է աշխատել content negotiation-ը, քայլ առ քայլ կկառուցենք պարզ հավելված, որը վերադարձնում է փոխարժեքներ։ Այն կգրենք Kotlin-ով՝ Spring Boot-ի ամենանոր տարբերակով։

Նախագծի գեներացիա

Սկսում ենք նախագիծ գեներացնելով spring initializr-ով։

Այն կկարգավորենք այսպես

  • Gradle նախագիծ Kotlin DSL-ով
  • Kotlin՝ որպես լեզու
  • Spring Boot-ի ամենանոր կայուն տարբերակը
  • Java 17 տարբերակ
  • Spring Web dependency

Stub տվյալներ

Կեղծ տվյալներ վերադարձնող սերվիսը բավական է ցույց տալու համար, թե ինչպես է աշխատում content negotiation-ը

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)

Endpoint, որը ծառայում է ռեսուրսի առաջին ներկայացումը application/json ձևաչափով

Սրանով հետո կարող ենք անցնել endpoint-ին, որը առաջարկում է պատասխանի առաջին ներկայացումը (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 սերիալիզացիան պահանջում է ևս մեկ dependency Gradle ֆայլում՝ com.fasterxml.jackson.dataformat:jackson-dataformat-xml։

Այնուհետև ընդլայնում ենք գոյություն ունեցող endpoint-ը՝ ‘produces’ բաժնին ավելացնելով ևս մեկ media type (MediaType.APPLICATION_XML_VALUE)։

@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-ում օգտագործելու համար նախ պետք է controller-ին ավելացնել endpoint-ի նոր տարբերակ

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-ի content negotiation ալգորիթմի գնահատում

Արդեն աջակցվում են երեք տարբեր media type-եր։ Ժամանակն է մի քանի փորձ կատարել՝ տեսնելու, թե ինչպես է Spring Boot-ն content negotiation-ով ընտրում ամենահարմար media type-ը։

Quality արժեքների աջակցություն

Սկզբի համար կստուգենք՝ արդյոք 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 header-ի բացակայություն

Այժմ տեսնենք, թե ինչ է լինում, երբ ‘Accept’ header չի ուղարկվում կամ ուղարկվում է դատարկ արժեքով։

Երբ Accept header-ը բացակայում է, դատարկ է կամ */* է, ստանում ենք հետևյալ պատասխանը՝

HTTP/1.1 200
Content-Type: application/json
Transfer-Encoding: chunked
Date: Thu, 17 Aug 2023 13:20:04 GMT

...

Ինչպե՞ս է ներկայացումը որոշվում այս իրավիճակում

Spring-ի կոդին հայացք գցելը պարզ է դարձնում, որ Accept header-ի բացակայության կամ դատարկ լինելու դեպքում այն վերածվում է */*-ի։ Դա տալիս է ռեսուրսի երեք հնարավոր ներկայացում՝ բոլորն էլ հավասար առաջնահերթությամբ։ Երբ մի քանի media type-եր ունեն նույն quality արժեքը, դրանց հերթականությունը որոշվում է MimeType դասի compareTo մեթոդով։ Պարզ ասած՝ վճռում է mime type-երի այբբենական կարգը։

Accept header-ում չաջակցվող արժեք

Տեսնենք, թե ինչ է լինում, երբ Accept header-ը պարունակում է արժեք, որը սերվերը չի աջակցում՝

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 header, որը թվարկում է բոլոր աջակցվող media type-երը (application/json, application/xml, text/html)։

Փոխարժեքների ստացում վեբ բրաուզերից

Հետաքրքիր է, որ փոխարժեքների ռեսուրսը վեբ բրաուզերից ստանալիս ստանում ենք HTML ներկայացումը

Դա պայմանավորված է նրանով, որ վեբ բրաուզերները ուղարկում են իրենց սեփական նախապատվությունները այն բովանդակության համար, որը ստանում են։ Ինչպես տեսնում ենք, text/plain-ը նրանց առաջին ընտրությունն է

Ինտերնացիոնալիզացիայի իրագործում content negotiation-ով

Ցույց տալու համար, թե ինչպես է աշխատում բովանդակության լեզվի negotiation-ը Spring-ում, ավելացնենք մի քանի լեզվի աջակցություն… Մեր HTML բովանդակությունը ինտերնացիոնալիզացիայի հիանալի թեկնածու է։

Դրա համար կօգտագործենք Spring-ի MessageSource դասը, որը կարող է տեքստը որոշել տվյալ հարցման locale համատեքստի համաձայն։ Փոխենք 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)}
                               }
                           }
...

Այնուհետև պատրաստում ենք թարգմանության ֆայլերը։ Լռելյայն օգտագործվում են resource bundle-ի կոնֆիգուրացիոն ֆայլերը, որոնք հետևում են messages_{language_code}.properties անվանակարգին։ Լռելյայն լեզուն պետք է լինի messages.properties ֆայլում։

Հիմա կավելացնենք թարգմանություններ երեք լեզվով (անգլերեն, գերմաներեն, ֆրանսերեն)՝ անգլերենը դարձնելով լռելյայն

Յուրաքանչյուր լեզվի ֆայլ պարունակում է հետևյալ property-ները՝ համապատասխանաբար թարգմանված՝

messages.properties

exchange-rates=Exchange rates
updated-at=Updated at
base-currency=Base currency
quoted-currency=Quoted currency
rate=Rate

Այնուհետև պետք է կարգավորենք, թե որ locale-ներն են աջակցվում։ Դա անում ենք LocaleResolver bean տրամադրելով

@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 header-ի բացակայություն

Accept-Language header չունեցող հարցումը

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 header-ը պահանջում է իսպաներեն, որը չի աջակցվում

curl -i --location 'http://localhost:8080/exchange-rates' \
--header 'Accept: text/html' \
--header 'Accept-Language: es'

պատասխանը գալիս է լռելյայն լեզվով (ի տարբերություն Accept header-ի, այստեղ 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>
...

Լեզուների ցանկ quality արժեքներով

Եթե հարցումը ներառում է լեզուների ցանկ 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-ում դա այսպես է երևում

Բովանդակությունը եկավ իմ բրաուզերի լռելյայն լեզվով

Բովանդակության կոդավորման negotiation

Բովանդակության կոդավորումը պահանջում է կարգավորել Spring Boot-ի երեք property

  • server.compression.enabled: միացնում է բովանդակության սեղմումը սերվերի կողմից
  • server.compression.mime-types: սահմանում է, թե բովանդակության որ տեսակները կարող են սեղմվել
  • server.compression.min-response-size: պատասխանի նվազագույն չափը բայթերով, որից սկսած այն սեղմվում է։

Այս property-ները դնենք 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 header-ը, որը ազդանշանում է, որ պատասխանը կառուցելիս Accept-Encoding header-ը կարող է հաշվի առնվել։

Հարցում՝ նշված բովանդակության կոդավորմամբ

Եթե հարցումը որպես ընդունվող կոդավորում նշում է 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

Quality արժեքը բովանդակության կոդավորման մեջ

Եթե ուղարկենք հարցում, որի Accept-Encoding header-ը երկու արժեք ունի՝ gzip և identity, ընդ որում identity-ին տրված է ավելի բարձր quality արժեք՝

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’ արժեքը առաջնահերթության համար չի օգտագործվում։

Կոդավորման նախապատվություն զրոյին հավասար quality արժեքով

Եթե ուղարկենք հարցում

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

Սա ցույց է տալիս, որ quality արժեքը կարելի է օգտագործել որոշակի սեղմման ձևաչափեր բացառելու համար։

Vary header-ի ճշգրտումներ

Ինչպես տեսանք, պատասխանի սեղմման միացումը հանգեցրեց նրան, որ Vary header-ը հայտնվեց պատասխաններում։ Սակայն դա լրիվ այն չէ, ինչ մենք ուզում ենք։ Մեր content negotiation-ը հիմնվում է այնպիսի header-ների վրա, ինչպիսիք են Accept, Accept-Language և Accept-Encoding, և նրանցից յուրաքանչյուրը կարող է փոխել պատասխանի ներկայացումը։

Ցավոք, Spring-ը այս վարքագիծը փոխելու համար առանձին property չունի։ Սակայն servlet filter-ը հեշտ լուծում է տալիս՝

@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 annotation-ը։

@SpringBootApplication
@ServletComponentScan
class ContentNegotiationApplication

fun main(args: Array<String>) {
runApplication<ContentNegotiationApplication>(*args)
}

Այնուհետև վերագործարկում ենք հավելվածը և ուղարկում օրինակելի հարցում

curl -I --location 'http://localhost:8080/exchange-rates'

Պատասխանը հիմա պետք է ներառի Vary header, որը թվարկում է բոլոր դաշտերը, որոնք կարող են փոխել պատասխանի ներկայացումը

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

Ամփոփում

Այս հոդվածում քննարկեցինք content negotiation-ի տեսությունը, ինչպես նկարագրված է RFC-9110-ում։ Տեսությունը ծածկելուց հետո Spring Boot-ով կառուցեցինք գործնական օրինակ։

Ստորև ամփոփված է, թե ինչպես է Spring Boot-ն աջակցում content negotiation-ը, որքանով է համապատասխանում տեսությանը և ինչպես է իրեն պահում եզրային դեպքերում՝

Negotiation-ի տարր Header q արժեքը հաշվի է առնվում Վարքագիծ, երբ header-ը բացակայում է Չաջակցվող header արժեքներ Ներառված է Vary header-ում Content negotiation-ի օրինաչափություն
Media type Accept Այո Վերադարձվում է աջակցվող այն media type-ը, որը այբբենական կարգով առաջինն է Վերադարձվում է 406 (Not acceptable). պատասխանը պարունակում է Accept header՝ աջակցվող media type-երի ցանկով Ոչ Proactive, Reactive
Լեզու Accept-Language Այո Օգտագործվում է լռելյայն լեզուն Օգտագործվում է լռելյայն լեզուն Ոչ Proactive
Կոդավորում Accept-Encoding Ոչ Կոդավորում չի օգտագործվում Կոդավորում չի օգտագործվում Այո Proactive

Արժե ընդգծել, որ Spring Boot-ը գալիս է ներկառուցված, շատ ճկուն content negotiation մեխանիզմով։ Այն կարելի է համարել proactive content negotiation-ի մի տեսակ, որտեղ 406 պատասխանի կոդը հայտնվում է միայն այն հազվադեպ իրավիճակներում, երբ սերվերը չի կարող առաջարկել ընդունելի ներկայացում։

Այդուհանդերձ, այն միշտ չէ, որ խստորեն հետևում է RFC-9110 սպեցիֆիկացիային բոլոր սցենարներում։ Սա առավել պարզ երևաց կոդավորման negotiation-ում և Vary header-ի կցման եղանակում, որոնք երկուսն էլ ստիպված եղանք ճշգրտել։