Українська
Як працювати з підручником
Маршрут
Chatex налічує близько 15 000 рядків коду на C# і TypeScript. Такий проєкт ніхто не пише від початку до кінця за один присід, і читати його так теж не варто. Підручник будує його в шести модулях і 24 темах у тому порядку, в якому частини залежать одна від одної (рис. 1.6).
Рис. 1.6. Маршрут підручника
Чому такий порядок – від бази даних угору, а не, скажімо, від екранів униз?
- Кожен рівень будується на тому, що вже працює. Сервісу потрібні репозиторії, кінцевій точці – сервіс, сторінці Angular – кінцева точка. Будуючи знизу вгору, ви ніколи не пишете код проти чогось уявного.
- Кожен рівень можна перевірити окремо. Рівень даних перевіряють тестами на справжній PostgreSQL; бізнес-рівень – тестами його сервісів; API – через Scalar, запити
.httpі HTTP-тести; клієнт – у браузері. Не потрібно чекати кінця, щоб побачити, як працює ваш код. - Він відповідає еталонному коду. Кожен рівень – окремий проєкт, тож на кожній контрольній точці ви можете порівняти свій проєкт з таким самим проєктом еталона.
Ціна цього – перший видимий екран з’являється лише в модулі 5. До того тести – це ваш екран: у модулях 2–4 кожна тема закінчується тестами, що доводять: новий код працює.
Шаблон кроку
Кожна тема – це етап побудови. Її розділи містять пронумеровані кроки, і кожен крок має одні й ті самі три частини:
Навіщо – проблема, яку розв’язує крок, і проєктне рішення за ним, разом з відкинутими альтернативами. Теорія, що заслуговує на ближчий погляд (патерни, принципи SOLID, подробиці HTTP чи безпеки), винесена в такі рамки:
Рамка з тлом
Такі рамки пояснюють поняття й дають посилання на курс C#, де його викладено докладно. Під час повторного читання їх можна пропускати.
Що зробити – файли, які треба створити чи змінити, і команди, які треба виконати. Перед кожним лістингом стоїть речення про те, що він додає.
Перевірка – як переконатися, що крок спрацював: команда й очікуваний результат, запуск тестів, запит у Scalar або клацання в браузері. Не йдіть далі, доки перевірка не пройде:
Перевірка
Ось так виглядає перевірка.
Типові помилки позначено рамкою-попередженням:
Типова помилка
Що йде не так, як це проявляється і як це виправити.
Як читати лістинги
Лістинг підписано шляхом до його файлу відносно кореня репозиторію, тож ви завжди знаєте, куди покласти код:
cs
namespace Chatex.Data.Entities;
public enum ChatType
{
/// <summary>One-to-one conversation between exactly two users.</summary>
Direct,
/// <summary>Many members, everyone can post.</summary>
Group,
/// <summary>Broadcast: only owner and admins post, everyone else subscribes.</summary>
Channel,
}Файл часто росте впродовж кількох тем. Коли тема додає рядки до файлу, створеного раніше, нові рядки підсвічено зеленим, а навколо них показано сусідні рядки, щоб ви знайшли потрібне місце:
cs
public class ChatMember : IHasCreatedAt
{
public Guid ChatId { get; set; }
// ...
public bool IsMuted { get; set; }
public Chat Chat { get; set; } = null!;
public User User { get; set; } = null!;
}У кількох лістингах клієнта Angular деякі рядки підсвічено жовтим, а заголовок лістингу закінчується приміткою (тимчасові рядки): ці рядки відрізняються від остаточного файлу лише наразі – наприклад, це заглушка, яку замінить одна з наступних тем, – а в тексті сказано, яка саме.
Коментар // ... (<!-- ... --> у HTML, # ... у YAML і скриптах оболонки) замінює рядки, які не показано, бо вони не змінилися або не важливі для кроку. Ніколи не друкуйте сам // ....
Команди написано для PowerShell 7 (pwsh), який працює у Windows, macOS і Linux. Кожен блок містить одну команду; виконуйте їх у показаному порядку з кореня репозиторію, якщо крок не каже іншого. Команди, що виконуються на сервері Ubuntu (теми 23–24), написано для bash.
Ваш репозиторій і еталон
Створіть власний репозиторій Git у темі 2 і робіть коміт на кожній контрольній точці з повідомленням, яке пропонує контрольна точка. Чиста історія дрібних комітів дає змогу повернутися до робочого стану, коли експеримент пішов не так:
powershell
git switch -c experimentpowershell
git switch mainЕталонний код (папка D:\Work\Chatex-Reference з розділу Запуск еталонної версії) – це остаточний стан проєкту. Коли крок не працює, порівняйте свій файл з еталонним:
powershell
git diff --no-index Source/Chatex.Data/Entities/Chat.cs D:\Work\Chatex-Reference\Source\Chatex.Data\Entities\Chat.csРядки з - є лише у вашому файлі, рядки з + – лише в еталонному. Пам’ятайте, що еталонний файл може вже містити рядки, які додає пізніша тема; лістинги підручника підказують, що належить до поточного кроку.
Кожна сторінка посилається на файли, які вона розглядає, у коміті 27c83c6 на GitHub, тож еталонний код можна читати й у браузері.
Скільки це триває
Тема займає від однієї до чотирьох годин зосередженої роботи залежно від її обсягу й від того, скільки з передісторії для вас нове. Плануйте одну-дві теми на тиждень і не пропускайте перевірок та питань для самоперевірки: саме вони перетворюють скопійований проєкт на зрозумілий.