Писання документів з розширеного проектування систем англійською мовою
Освоєння мови документації по розширеному проектуванню систем: обробка компромісів, оцінка за задньою обкладинкою і словник проектних рішень для старших інженерів.
Документ проектування системи (також званий документом проектування, технічною специфікацією або RFC) є одним з найбільш послідовних письмових артефактів в інженерії програмного забезпечення. На просунутому рівні якість документа залежить не лише від самого проекту, але і від того, наскільки точно ви сформулюєте компроміси, обмеження і припущення.
Структура документа
Надійний документ з дизайном має передбачувану структуру, яку читачі зможуть швидко розшифрувати:
- ** Контекст і мотивація ** — чому цей дизайн потрібен зараз
- Цілі і не- цілі — що система буде робити і чого не буде робити
- ** Дизайн високого рівня ** — огляд архітектури
- ** Детальний дизайн ** — рішення на рівні компонентів
- Компроміси і альтернативи, які розглядалися — що ви відкинули і чому
- ** Оцінки збоку конверта** — обґрунтування потужності і вартості
- ** Відкритий запит ** — нерозв’ язані рішення
Запис розділу контексту
У розділі контексту відповіді на запитання: * Чому це важливо? * Використовуйте такі шаблони:
- «Існуючий ** підхід ** не масштабується за межі X запитів на секунду.»
- «Поточній системі не вистачає підтримки для переходу на багаторегіональний режим роботи»
- «Якщо команда ** зростає **, вручну забезпечення стало вузьким місцем.»
- Цей дизайн замінює пропозицію з Q3 і розглядає її обмеження
Уникайте нечітких фраз, наприклад, « нам потрібно поліпшити продуктивність ». Будьте конкретними: « Затримка P99 перевищує 200 мс під час максимального навантаження, що порушує нашу угоду про рівні обслуговування »
Цілі і не цілі
Цей розділ запобігає поширенню обсягу і вирівнює переглядачів. Використовувати чітку, паралельну структуру:
Цілі:
- Підтримка 10 000 одночасних з’єднань на вузол.
- Надати ** точно-один раз доставка ** гарантії для платіжних подій.
- Дозволити розгортання без перерв за допомогою синьо-зеленої стратегії.
Незавершені:
- Цей дизайн ** не розглядає ** кешування на стороні клієнта.
- ** За межами обсягу: ** Підтримка декількох користувачів — це відстежується окремо.
- Ми ** не оптимізуємо ** для завантажень з великим обсягом читання в цій ітерації.
Використовується для торгівлі
У розділі “Компроміси” старші інженери демонструють свої думки. Мова ключа:
Контрастні сполучення
- “Хоча Option A пропонує нижчу затримку, він вводить операційну складність.”
- «Варіант B спрощує модель розгортання за рахунок заблокованості постачальника»
- ”** Хоча ** кінцева послідовність зменшує затримку запису, це ** ускладнює ** логіку клієнта. “
Важливі фактори
- «Ми приоритизували простоту операцій над сирою пропускною здатністю»
- «Зважаючи на досвід нашої команди в Postgres, ми ** надали перевагу ** реляційному підходу.»
- «Маргінальний прибуток від продуктивності не виправдовує додану складність.»
- «Ця конструкція ** торгує ** вартістю зберігання для гнучкості запиту. “
Відкидаючи альтернативи
- «Ми оцінювали підхід, заснований на черзі повідомлень, але відкинули його, тому що…»
- «Варіант C був виключений через відсутність офіційної підтримки багатьох регіонів.»
- «Консенсус був таким, що додатковий операційний тягар переважив переваги.»
Оцінка за задньою обкладинкою
Обчислення зворотного обгортання (BOE) показують, що ваша конструкція може обробляти очікуване навантаження. Напишіть їх чітко:
Template
«Припускаючи 50 000 щоденних активних користувачів, кожен з яких генерує 10 подій за сеанс, ми оцінили 500 000 подій на день, або приблизно 6 подій на секунду в середньому. Під час піку (3× середнє), система повинна обробляти ~18 подій на секунду»
Ключові фрази
- «Припускаючи співвідношення читання-запису 10:1…»
- «При ** факторі реплікації ** 3, потреби в зберіганні потрійні.»
- Один вузол може обробляти X RPS під нашим спостереженням p95 затримки цілі
- Це дає нам ~Y GB/день необроблених даних подій перед стисненням
- «Ми бюджет 20% над піковими оцінками.»
Використовуйте ~ для наближень і чітко вкажіть ваші припущення. Рецензенти будуть спростовувати не підтверджені цифри.
Опис архітектурних споруд
Використовувати активні, специфічні дієслова:
| Instead of | Write |
|---|---|
| ”We will use Kafka" | "We route events through Kafka to decouple producers from consumers." |
| "The API is stateless" | "The API stores no session state, enabling horizontal scaling." |
| "We use caching" | "We cache responses at the edge with a 60-second TTL." |
| "The DB is sharded" | "We shard by user_id to distribute write load evenly.” |
Відкриті питання
Закривати документ з нерозв’ язаними рішеннями, а не з порожньою тишею:
- “TBD: Чи використовувати керовану службу Kafka або самостійний вузол. Залежить від аналізу витрат (див. квиток #1234).»
- Процитовано 2011-03-14. Under discussion: The retention policy for audit logs — legal review pending.
- «Рішення, необхідне перед реалізацією: SLA-рівень для асинхронного шляху запису.»
Реєстрація та реєстрація
Документація проекту є формальною, але не жорсткою. Використання:
- ** Ми ** (не “автор” або “я”) — дизайн є рішенням команди
- ** Теперішній час** для обраного дизайну: « Служба ** виставляє ** API REST. »
- ** Майбутній час** для запланованої роботи: « Впровадження версії 2 ** додасть ** підтримку потокових передачі даних. »
- Уникайте фраз типу “може бути можливо, що” - будьте прямими.
Ключеві моменти
- ** Контекст ** має бути конкретним, а не загальним. Показатели состояния, а не чувства.
- ** Цілі/ Не- цілі ** вирівнюють переглядачів і запобігають поширенню обсягу.
- Компроміси використовують контрастні сполучення: “while”, “at the cost of”, “although.”
- ** Оцінки BOE ** вимагають чітких припущень і чіткого сліду одиниць.
- ** Відкритий запит ** - це ознака зрілості, а не незавершеності.
- Використовуйте активні, точні дієслова: route, shard, cache, expose, decouple — не « use » або « do. »
Наприклад, англійська мова: англійська мова: англійська мова: англійська мова: англійська мова: англійська мова: англійська мова: англійська мова: англійська мова: англійська мова: англійська мова: англійська мова: англійська мова: англійська мова: англійська мова: англійська мова: англійська мова: англійська мова: англійська мова: англійська мова: англійська мова: англійська мова: англійська мова: англійська мова: англійська мова: англійська мова: англійська мова: англійська мова: англійська мова: англійська мова: англійська мова: англійська
Як ви занурюєтесь у створення більш складних документів проектування системи, ви швидко усвідомите, що це не просто * що * ви кажете, але * як * ви говорите. Точна мова є ключовою для передачі складних ідей чітко і спільно - особливо при роботі з компромісами і оцінками. Легко впасти в неясні терміни, але старші інженери очікують рівня артикуляції, який демонструє глибоке розуміння і здатність обґрунтовувати вибір дизайну. Однією з найпоширеніших помилок є припущення, що всі поділять ваше точне тлумачення терміну; завжди шукайте підтвердження. Наприклад, при обговоренні «масштабованості», не просто стверджуйте «ми потребуємо масштабованої архітектури». Замість цього, оформіть її так: «Для забезпечення довгострокової масштабованості, ми будемо пріоритизувати горизонтально масштабовані компоненти, використовуючи такі методи, як шардинг і балансування навантаження, визнаючи, що це вводить операційну складність»
Розглянемо сценарій під час перегляду коду. Рецензент може прокоментувати ваш опис PR так: « У цьому розділі не вистачає ясності щодо оцінених показників зростання користувачів, що впливає на масштабування бази даних. Чи могли б ви розібратися в припущеннях, що лежать в основі цих прогнозів? » Ключовим тут є не стати оборонним, а переформулювати своє твердження, використовуючи більш точну термінологію. Краще було б сказати: «Виявлено — моя початкова оцінка зростання користувачів була заснована на консервативному прогнозі 10% щорічно. Я переглянув розділ, щоб чітко вказати, що це припущення і включити аналіз чутливості, який описує, як продуктивність погіршиться за сценаріями 20%, 30% або навіть 50% зростання, разом з нашими запланованими стратегіями зменшення»
Інша поширена проблема виникає при представленні оцінок зворотного конверта. Замість того, щоб сказати «сервер буде обробляти X запитів за секунду», що відкрито для інтерпретації, прагніть до більш детального пояснення: «На основі очікуваного пікового навантаження 10 000 запитів за секунду і цільової затримки 200 мс, ми виділили [кількість ресурсів] для обчислювального рівня. Це обчислення включає оцінений час обробки за запитом — приблизно [одиницю часу], враховуючи мережеві витрати і механізми кешування. ” Акт кількісного визначення припущень відразу демонструє ретельність і дозволяє більш цілеспрямоване обговорення.
Нарешті, пам’ ятайте, що фраза безпосередньо впливає на сприйняття вашого дизайну. Використання таких термінів, як «надійний» або «допускається помилка» без подальшого контексту може ввести в оману. Замість цього, чітко сформулюйте * як * ви досягаєте стійкості – « Ми реалізуємо автоматичні вимкнення для ізоляції непрацездатних служб і багаторегіональну стратегію розгортання для відновлення після аварії. » Цей рівень деталізації створює впевненість у вашому дизайні і демонструє зріле розуміння архітектури системи.