mirror of
https://github.com/twirl/The-API-Book.git
synced 2025-03-29 20:51:01 +02:00
fresh build
This commit is contained in:
parent
07f9c8cca1
commit
d213aa1ff3
BIN
docs/API.en.epub
BIN
docs/API.en.epub
Binary file not shown.
@ -2055,7 +2055,7 @@ or<br>
|
||||
<span class="hljs-attr">"longitude"</span>: <span class="hljs-number">0</span>
|
||||
}
|
||||
}
|
||||
→ <span class="hljs-number">404</span> Bad Request
|
||||
→ <span class="hljs-number">400</span> Bad Request
|
||||
{
|
||||
<span class="hljs-attr">"errors"</span>: [{
|
||||
<span class="hljs-attr">"type"</span>: <span class="hljs-string">"suspicious_coordinates"</span>,
|
||||
|
BIN
docs/API.en.pdf
BIN
docs/API.en.pdf
Binary file not shown.
BIN
docs/API.ru.epub
BIN
docs/API.ru.epub
Binary file not shown.
@ -1545,7 +1545,7 @@ app.<span class="hljs-title function_">display</span>(matchingCoffeeMachines);
|
||||
<li><code>place</code> — место (кафе, автомат, ресторан), где находится машина; мы не вводили эту сущность ранее, но, очевидно, пользователю потребуются какие-то более понятные ориентиры, нежели географические координаты, чтобы найти нужную кофемашину.</li>
|
||||
</ul>
|
||||
<p><strong>NB</strong>. Мы могли бы не добавлять новый эндпойнт, а обогатить существующий <code>/coffee-machines</code>. Однако такое решение выглядит менее семантично: не стоит в рамках одного интерфейса смешивать способ перечисления объектов по порядку и по релевантности запросу, поскольку эти два вида ранжирования обладают существенно разными свойствами и сценариями использования. К тому же, обогащение поиска «предложениями» скорее выводит эту функциональность из неймспейса «кофемашины»: для пользователя всё-таки первичен факт получения предложения приготовить напиток на конкретных условиях, и кофемашина — лишь одно из них, не самое важное.</p>
|
||||
<p><strong>NB</strong>. На самом деле, наличие идентификатора кофе-машины в интерфейсах само по себе нарушает принцип изоляции уровней абстракции. Эа функциональность должна быть организована более сложно: кофейни должны распределять поступающие заказы по свободным кофемашинам, и только тип кофемашины (если кофейня оперирует несколькими одновременно) является значимой частью предложения. Мы сознательно допускаем это упрощение (пользователь сам выбирает кофемашину), чтобы не перегружать наш учебный пример.</p>
|
||||
<p><strong>NB</strong>. На самом деле, наличие идентификатора кофе-машины в интерфейсах само по себе нарушает принцип изоляции уровней абстракции. Эта функциональность должна быть организована более сложно: кофейни должны распределять поступающие заказы по свободным кофемашинам, и только тип кофемашины (если кофейня оперирует несколькими одновременно) является значимой частью предложения. Мы сознательно допускаем это упрощение (пользователь сам выбирает кофемашину), чтобы не перегружать наш учебный пример.</p>
|
||||
<p>Вернёмся к коду, который напишет разработчик. Теперь он будет выглядеть примерно так:</p>
|
||||
<pre><code class="language-typescript"><span class="hljs-comment">// Ищем предложения,</span>
|
||||
<span class="hljs-comment">// соответствующие запросу пользователя</span>
|
||||
@ -2061,7 +2061,7 @@ strpbrk (str1, str2)
|
||||
<span class="hljs-attr">"longitude"</span>: <span class="hljs-number">0</span>
|
||||
}
|
||||
}
|
||||
→ <span class="hljs-number">404</span> Bad Request
|
||||
→ <span class="hljs-number">400</span> Bad Request
|
||||
{
|
||||
<span class="hljs-attr">"errors"</span>: [{
|
||||
<span class="hljs-attr">"type"</span>: <span class="hljs-string">"suspicious_coordinates"</span>,
|
||||
@ -2852,7 +2852,7 @@ X-Idempotency-Token: <токен>
|
||||
</ul>
|
||||
<p><strong>NB</strong>: важно, что перезапрос может случиться и по совершенно не техническим причинам: конечному пользователю может просто надоесть ждать, он вручную перезапустит приложение и вручную создаст повторный заказ.</p>
|
||||
<p>Математически вероятность получения ошибки выражается довольно просто: она равна отношению периода времени, требуемого для получения актуального состояния к типичному периоду времени, за который пользователь перезапускает приложение и повторяет заказ. (Следует, правда, отметить, что клиентское приложение может быть реализовано так, что даст вам ещё меньше времени, если оно пытается повторить несозданный заказ автоматически при запуске). Если первое зависит от технических характеристик системы (в частности, лага синхронизации, т.е. задержки репликации между мастером и копиями на чтение). А вот второе зависит от того, какого рода клиент выполняет операцию.</p>
|
||||
<p>Если мы говорим о приложения для конечного пользователя, то типично время перезапуска измеряется для них в секундах, что в норме не должно превышать суммарного лага синхронизации — таким образом, клиентские ошибки будут возникать только в случае проблем с репликацией данных / ненадежной сети / перегрузки сервера.</p>
|
||||
<p>Если мы говорим о приложениях для конечного пользователя, то типичное время перезапуска измеряется для них в секундах, что в норме не должно превышать суммарного лага синхронизации — таким образом, клиентские ошибки будут возникать только в случае проблем с репликацией данных / ненадежной сети / перегрузки сервера.</p>
|
||||
<p>Однако если мы говорим не о клиентских, а о серверных приложениях, здесь ситуация совершенно иная: если сервер решает повторить запрос (например, потому, что процесс был убит супервизором), он сделает это условно моментально — задержка может составлять миллисекунды. И в этом случае фон ошибок создания заказа будет достаточно значительным.</p>
|
||||
<p>Таким образом, возвращать по умолчанию событийно-консистентные данные вы можете, если готовы мириться с фоном ошибок или если вы можете обеспечить задержку получения актуального состояния много меньшую, чем время перезапуска приложения на целевой платформе.</p><h4>Примечания</h4><ul class="references"><li><p><a href="#ref-chapter-18-no-17-back" class="back-anchor" id="ref-chapter-18-no-17"><sup>1</sup> </a><span>Consistency Model. Eventual Consistency<br><a target="_blank" class="external" href="https://en.wikipedia.org/wiki/Consistency_model#Eventual_consistency">https://en.wikipedia.org/wiki/Consistency_model#Eventual_consistency</a></span></p></li>
|
||||
<li><p><a href="#ref-chapter-18-no-18-back" class="back-anchor" id="ref-chapter-18-no-18"><sup>2</sup> </a><span>Consistency Model. Read-Your-Writes Consistency<br><a target="_blank" class="external" href="https://en.wikipedia.org/wiki/Consistency_model#Read-your-writes_consistency">https://en.wikipedia.org/wiki/Consistency_model#Read-your-writes_consistency</a></span></p></li></ul><div class="page-break"></div><h3><a href="#api-patterns-async" class="anchor" id="api-patterns-async">Глава 19. Асинхронность и управление временем</a><a href="#chapter-19" class="secondary-anchor" id="chapter-19"> </a></h3>
|
||||
|
BIN
docs/API.ru.pdf
BIN
docs/API.ru.pdf
Binary file not shown.
Loading…
x
Reference in New Issue
Block a user