Українська
Моделі та служби HTTP
Крок 1. DTO як типи TypeScript
Навіщо. API повертає JSON, форму якого задають записи C# з тем 8–11 і 12. Якщо клієнт описує ті самі форми як типи TypeScript, компілятор перевіряє кожне поле, яке читають шаблони й сховища: помилка в написанні, як-от message.boddy, – це помилка компіляції, а не undefined на екрані. Типи TypeScript стираються під час виконання – вони нічого не коштують і не перевіряють відповідь сервера; це контракт, якому клієнт довіряє.
Типи написано вручну, а не згенеровано (з документа OpenAPI з теми 12), бо клієнтові потрібна лише частина поверхні API, а короткий читабельний файл легше вивчати. Ціна – зміну DTO доводиться дзеркально повторювати тут вручну.
Що зробити. Створіть моделі:
ts
/** DTOs of the Chatex API. Ids are GUID strings, dates are ISO strings, enums are camelCase strings. */
export type ChatType = 'direct' | 'group' | 'channel';
export type ChatMemberRole = 'owner' | 'admin' | 'member' | 'subscriber';
export interface MyProfileDto {
id: string;
userName: string;
email: string;
displayName: string;
bio?: string | null;
hasAvatar: boolean;
createdAt: string;
}
export interface UserDto {
id: string;
userName: string;
displayName: string;
bio?: string | null;
hasAvatar: boolean;
lastSeenAt?: string | null;
}
export interface UserSummaryDto {
id: string;
userName: string;
displayName: string;
hasAvatar: boolean;
}
export interface AuthResponse {
accessToken: string;
accessTokenExpiresAt: string;
user: MyProfileDto;
}
export interface ChatDto {
id: string;
type: ChatType;
title?: string | null;
description?: string | null;
publicHandle?: string | null;
hasAvatar: boolean;
createdAt: string;
memberCount: number;
/** Null when the caller is not a member (public chat preview). */
myRole?: ChatMemberRole | null;
isMuted: boolean;
peer?: UserSummaryDto | null;
}
export interface LastMessageDto {
id: string;
senderId: string;
body: string;
createdAt: string;
}
export interface ChatListItemDto {
id: string;
type: ChatType;
title?: string | null;
hasAvatar: boolean;
lastActivityAt: string;
myRole: ChatMemberRole;
isMuted: boolean;
lastMessage?: LastMessageDto | null;
unreadCount: number;
peer?: UserSummaryDto | null;
}
export interface ChatSummaryDto {
id: string;
type: ChatType;
title?: string | null;
description?: string | null;
publicHandle?: string | null;
hasAvatar: boolean;
}
export interface ChatMemberDto {
user: UserSummaryDto;
role: ChatMemberRole;
joinedAt: string;
}
export interface AttachmentDto {
id: string;
fileName: string;
contentType: string;
sizeBytes: number;
}
export interface MessageDto {
id: string;
chatId: string;
sender: UserSummaryDto;
/** Null when the message is deleted. */
body?: string | null;
replyToMessageId?: string | null;
createdAt: string;
editedAt?: string | null;
isDeleted: boolean;
attachments: AttachmentDto[];
}
export interface PageDto<T> {
items: T[];
nextCursor?: string | null;
}
// Requests
export interface RegisterRequest {
userName: string;
email: string;
password: string;
displayName: string;
}
export interface LoginRequest {
login: string;
password: string;
}
export interface UpdateProfileRequest {
displayName: string;
bio?: string | null;
}
export interface ChangePasswordRequest {
currentPassword: string;
newPassword: string;
}
export interface CreateChatRequest {
type: 'group' | 'channel';
title: string;
description?: string | null;
publicHandle?: string | null;
memberIds?: string[];
}
export interface UpdateChatRequest {
title: string;
description?: string | null;
publicHandle?: string | null;
}
export interface SendMessageRequest {
body?: string | null;
replyToMessageId?: string | null;
attachmentIds?: string[];
}
/** Display name of a chat: direct chats have no title, so they use the peer's name. */
export function chatTitle(chat: { title?: string | null; peer?: UserSummaryDto | null }): string {
return chat.title || chat.peer?.displayName || 'Chat';
}
export function canManageChat(role: ChatMemberRole | null | undefined): boolean {
return role === 'owner' || role === 'admin';
}
/** Channels accept posts from owners and admins only. */
export function canPost(type: ChatType, role: ChatMemberRole | null | undefined): boolean {
if (!role) {
return false;
}
return type !== 'channel' || canManageChat(role);
}
/** UUIDv7 ids sort by creation time, so comparing the canonical strings orders messages. */
export function compareIds(a: string, b: string): number {
return a < b ? -1 : a > b ? 1 : 0;
}interfaceописує форму об’єкта без класу за ним:JSON.parseстворює прості об’єкти, а інтерфейс повідомляє компілятору, що вони містять. Назви збігаються з DTO мовою C# (ChatDto,MessageDto).- Ідентифікатори –
string, дати –string. У JSON немає типу GUID чи дати: API надсилає GUID і часові мітки ISO 8601 як рядки, і клієнт зберігає їх так само.new Date(iso)перетворює дату, коли її треба показати. - Перелічення – це об’єднання рядкових літералів:
ChatType– це'direct' | 'group' | 'channel', саме ті рядки в camelCase, що їх записуєJsonStringEnumConverterв API (тема 12). field?: T | null–?означає, що властивості може не бути,| null– що вона може бутиnull. API нічого не пропускає, але надсилаєnullдля порожніх значень; прийняття обох варіантів зберігає чесність типів для об’єктів, створених у тестах.MessageDto.bodyмає значення null для видаленого повідомлення, як сказано в коментарі.PageDto<T>– це узагальнена сторінка з теми 7: елементи й непрозорийnextCursor.- Типи запитів (
LoginRequest,SendMessageRequest, …) віддзеркалюють записи запитів API. - Невеликі допоміжні функції, потрібні кільком функціям, лежать поруч із типами:
chatTitle(у прямого чату немає назви, тож він показує ім’я співрозмовника),canManageChatіcanPost– клієнтське віддзеркаленняChatPermissionsз теми 10, яке використовується лише для приховування кнопок; рішення все одно ухвалює сервер, – іcompareIds. Оскільки ідентифікатори API – це UUIDv7 (тема 4), порівняння рядків упорядковує повідомлення за часом створення.
Крок 2. Observable та HttpClient
Навіщо. HttpClient в Angular повертає Observable з RxJS. Observable – це лінивий потік: нічого не відбувається, доки хтось не підпишеться, а тоді він може видати будь-яку кількість значень і завершитися або завершитися помилкою. Для виклику HTTP він видає одну відповідь (або, з observe: 'events', кілька подій прогресу) і завершується.
Observable, Promise, Task
Task<T> у C# – гарячий: робота вже почалася, коли ви отримали завдання, і воно завершується один раз. Promise<T> у JavaScript такий самий. Observable<T> – холодний і може видати багато значень: http.get(url) нічого не надсилає, доки не викликано subscribe, а кожна підписка надсилає запит знову. Chatex використовує кожен там, де він доречний: служби HTTP повертають Observable (так робить HttpClient), сховища перетворюють поодинокі відповіді на Promise через firstValueFrom(observable) і користуються async/await, як у C#, а потоки багатьох значень – введення для пошуку, події хаба – лишаються Observable.
Крок 3. Одна служба на ресурс
Навіщо. Кожна кінцева точка API отримує один метод у тонкій службі: URL, метод HTTP і типи, більше нічого. Компоненти й сховища ніколи не будують URL самі. Групування відповідає групам маршрутів API (табл. 16.1).
Таблиця 16.1. Служби HTTP клієнта
| Служба | Маршрути | Де використовується |
|---|---|---|
AuthApi | /api/auth/register, login, refresh, logout, logout-all | AuthService (ця тема) |
ProfileApi | /api/me, /api/me/password, /api/me/avatar | сторінка налаштувань (тема 21) |
UsersApi | /api/users, /api/users/{id} | пошук користувачів (тема 18), профілі (тема 21) |
ChatsApi | /api/chats/…: список, створення, прямий чат, пошук, приєднання, вихід, учасники, ролі, вимкнення сповіщень, прочитане | сховище чатів і сторінки чатів (теми 18–21) |
MessagesApi | /api/chats/{id}/messages, /api/messages/{id} | сховище повідомлень (тема 19) |
AttachmentsApi | /api/attachments | поле введення повідомлення (тема 19) |
Що зробити. Створіть служби. Файл уже повний; пізніші теми його лише викликають.
ts
import { HttpClient, HttpEvent, HttpParams } from '@angular/common/http';
import { Injectable, inject } from '@angular/core';
import { Observable } from 'rxjs';
import {
AttachmentDto,
AuthResponse,
ChangePasswordRequest,
ChatDto,
ChatListItemDto,
ChatMemberDto,
ChatMemberRole,
ChatSummaryDto,
CreateChatRequest,
LoginRequest,
MessageDto,
MyProfileDto,
PageDto,
RegisterRequest,
SendMessageRequest,
UpdateChatRequest,
UpdateProfileRequest,
UserDto,
UserSummaryDto,
} from './models';
/** Builds query params, skipping null and undefined values. */
function params(values: Record<string, string | number | null | undefined>): HttpParams {
let result = new HttpParams();
for (const [key, value] of Object.entries(values)) {
if (value !== null && value !== undefined && value !== '') {
result = result.set(key, String(value));
}
}
return result;
}
function fileForm(file: File): FormData {
const form = new FormData();
form.append('file', file, file.name);
return form;
}
/** /api/auth: the refresh token travels in an HttpOnly cookie, see authInterceptor. */
@Injectable({ providedIn: 'root' })
export class AuthApi {
private readonly http = inject(HttpClient);
register(body: RegisterRequest): Observable<AuthResponse> {
return this.http.post<AuthResponse>('/api/auth/register', body);
}
login(body: LoginRequest): Observable<AuthResponse> {
return this.http.post<AuthResponse>('/api/auth/login', body);
}
refresh(): Observable<AuthResponse> {
return this.http.post<AuthResponse>('/api/auth/refresh', null);
}
logout(): Observable<void> {
return this.http.post<void>('/api/auth/logout', null);
}
logoutAll(): Observable<void> {
return this.http.post<void>('/api/auth/logout-all', null);
}
}
/** /api/me */
@Injectable({ providedIn: 'root' })
export class ProfileApi {
private readonly http = inject(HttpClient);
get(): Observable<MyProfileDto> {
return this.http.get<MyProfileDto>('/api/me');
}
update(body: UpdateProfileRequest): Observable<MyProfileDto> {
return this.http.put<MyProfileDto>('/api/me', body);
}
changePassword(body: ChangePasswordRequest): Observable<void> {
return this.http.put<void>('/api/me/password', body);
}
uploadAvatar(file: File): Observable<MyProfileDto> {
return this.http.put<MyProfileDto>('/api/me/avatar', fileForm(file));
}
deleteAvatar(): Observable<MyProfileDto> {
return this.http.delete<MyProfileDto>('/api/me/avatar');
}
}
/** /api/users */
@Injectable({ providedIn: 'root' })
export class UsersApi {
private readonly http = inject(HttpClient);
search(query: string, limit = 20): Observable<UserSummaryDto[]> {
return this.http.get<UserSummaryDto[]>('/api/users', { params: params({ query, limit }) });
}
get(id: string): Observable<UserDto> {
return this.http.get<UserDto>(`/api/users/${id}`);
}
}
/** /api/chats */
@Injectable({ providedIn: 'root' })
export class ChatsApi {
private readonly http = inject(HttpClient);
list(cursor?: string | null, limit = 30): Observable<PageDto<ChatListItemDto>> {
return this.http.get<PageDto<ChatListItemDto>>('/api/chats', {
params: params({ cursor, limit }),
});
}
create(body: CreateChatRequest): Observable<ChatDto> {
return this.http.post<ChatDto>('/api/chats', body);
}
direct(userId: string): Observable<ChatDto> {
return this.http.post<ChatDto>('/api/chats/direct', { userId });
}
search(query: string, limit = 20): Observable<ChatSummaryDto[]> {
return this.http.get<ChatSummaryDto[]>('/api/chats/search', {
params: params({ query, limit }),
});
}
get(id: string): Observable<ChatDto> {
return this.http.get<ChatDto>(`/api/chats/${id}`);
}
update(id: string, body: UpdateChatRequest): Observable<ChatDto> {
return this.http.put<ChatDto>(`/api/chats/${id}`, body);
}
delete(id: string): Observable<void> {
return this.http.delete<void>(`/api/chats/${id}`);
}
uploadAvatar(id: string, file: File): Observable<ChatDto> {
return this.http.put<ChatDto>(`/api/chats/${id}/avatar`, fileForm(file));
}
deleteAvatar(id: string): Observable<ChatDto> {
return this.http.delete<ChatDto>(`/api/chats/${id}/avatar`);
}
join(id: string): Observable<ChatDto> {
return this.http.post<ChatDto>(`/api/chats/${id}/join`, null);
}
leave(id: string): Observable<void> {
return this.http.post<void>(`/api/chats/${id}/leave`, null);
}
members(id: string, cursor?: string | null, limit = 50): Observable<PageDto<ChatMemberDto>> {
return this.http.get<PageDto<ChatMemberDto>>(`/api/chats/${id}/members`, {
params: params({ cursor, limit }),
});
}
addMembers(id: string, userIds: string[]): Observable<{ added: number }> {
return this.http.post<{ added: number }>(`/api/chats/${id}/members`, { userIds });
}
removeMember(id: string, userId: string): Observable<void> {
return this.http.delete<void>(`/api/chats/${id}/members/${userId}`);
}
setRole(id: string, userId: string, role: ChatMemberRole): Observable<void> {
return this.http.put<void>(`/api/chats/${id}/members/${userId}/role`, { role });
}
mute(id: string, muted: boolean): Observable<void> {
return this.http.put<void>(`/api/chats/${id}/mute`, { muted });
}
markRead(id: string, messageId: string): Observable<void> {
return this.http.post<void>(`/api/chats/${id}/read`, { messageId });
}
}
/** /api/chats/{id}/messages and /api/messages */
@Injectable({ providedIn: 'root' })
export class MessagesApi {
private readonly http = inject(HttpClient);
/**
* No cursor: the newest page, newest first. `before`: older pages, newest first.
* `after`: newer messages, oldest first (catching up after a reconnect).
*/
list(
chatId: string,
options: { before?: string | null; after?: string | null; limit?: number } = {},
): Observable<PageDto<MessageDto>> {
return this.http.get<PageDto<MessageDto>>(`/api/chats/${chatId}/messages`, {
params: params({ before: options.before, after: options.after, limit: options.limit ?? 50 }),
});
}
send(chatId: string, body: SendMessageRequest): Observable<MessageDto> {
return this.http.post<MessageDto>(`/api/chats/${chatId}/messages`, body);
}
edit(id: string, body: string): Observable<MessageDto> {
return this.http.put<MessageDto>(`/api/messages/${id}`, { body });
}
delete(id: string): Observable<void> {
return this.http.delete<void>(`/api/messages/${id}`);
}
}
/** /api/attachments: upload first, then send the ids with the message. */
@Injectable({ providedIn: 'root' })
export class AttachmentsApi {
private readonly http = inject(HttpClient);
upload(file: File): Observable<HttpEvent<AttachmentDto>> {
return this.http.post<AttachmentDto>('/api/attachments', fileForm(file), {
reportProgress: true,
observe: 'events',
});
}
}
export const avatarUrl = {
user: (id: string) => `/api/users/${id}/avatar`,
chat: (id: string) => `/api/chats/${id}/avatar`,
};
export const attachmentUrl = (id: string) => `/api/attachments/${id}`;private readonly http = inject(HttpClient)– служба отримуєHttpClientз кореневого інжектора. В Angular 22HttpClientтипово надається в корені;app.config.tsусе одно викликаєprovideHttpClient(розділ 4), щоб додати перехоплювач.this.http.post<AuthResponse>(url, body)серіалізуєbodyу JSON, надсилає його й розбирає відповідь якAuthResponse. Аргумент типу – це обіцянка компілятору, а не перевірка.params(...)будує рядки запиту й пропускаєnull,undefinedта порожні значення, тожlist(null)надсилає/api/chats?limit=30безcursor=.fileForm(file)загортає файл уmultipart/form-dataпід іменем поляfile, до якого кінцеві точки завантаження з теми 13 прив’язуються черезIFormFile file.MessagesApi.listприймає курсориbeforeіafterз теми 11 в одному об’єкті параметрів, тож виклик має виглядlist(chatId, { before: cursor }).AttachmentsApi.uploadпроситьobserve: 'events'зreportProgress: Observable тоді видає події запиту, а не лише остаточну відповідь, і поле введення повідомлення (тема 19) показує стан завантаження.avatarUrlіattachmentUrlбудують URL файлів. Браузер не може завантажити їх звичайним<img src>, бо їм потрібен токен носія; як їх завантажують, пояснює тема 18.
Перевірка
powershell
npm run buildзавершується успішно. Нове поки що ніхто не використовує, тож пакет не збільшується: збирання відкидає код, який ніхто не імпортує.