текст перекладу

Створення надійних клієнтських бібліотек для вашого додатку: найкращі практики для JavaScript та TypeScript

При розробці масштабованих додатків надійна клієнтська бібліотека є необхідністю, а не просто зручністю. Така бібліотека абстрагує комунікацію з API, забезпечує контракти з сильною типізацією та сприяє повторному використанню по всьому додатку. У цій статті ми розглянемо практичний підхід до реалізації клієнтських бібліотек з використанням JavaScript та TypeScript, з акцентом на найкращі практики, які поєднують технічну суворість та зручність для розробників.

Налаштування основи: змінні середовища та екземпляри Fetch

В основі будь-якої клієнтської бібліотеки лежить здатність комунікувати з вашими бекенд-сервісами. Це починається з налаштування екземплярів fetch:

import { createFetch } from "@better-fetch/fetch";  

const BASE_SERVER_URL = process.env.BASE_SERVER_URL;  
const SERVER_IDENTITY = process.env.SERVER_IDENTITY;  

if (!BASE_SERVER_URL || !SERVER_IDENTITY) {  
 throw new Error("Missing environment variables");  
}  

export const serverFetch = createFetch({  
 baseURL: BASE_SERVER_URL,  
 headers: {  
 "Content-Type": "application/json",  
 "X-IDENTITY-KEY": SERVER_IDENTITY,  
 Origin: process.env.BASE_URL,  
 },  
});

Найкращі практики:

1. Перевірка змінних середовища: Завжди перевіряйте змінні середовища під час виконання. Відсутні змінні можуть призвести до тихих збоїв або неочікуваної поведінки.
2. Інкапсуляція: Використання бібліотеки, такої як @better-fetch/fetch, дозволяє інкапсулювати загальні налаштування (наприклад, базову URL-адресу та заголовки) і уникати повторення по всьому кодовому базі.
3. Безпека: Чутливі заголовки, такі як X-IDENTITY-KEY, повинні передаватися динамічно, якщо це можливо, щоб уникнути хардкодування секретів.

Визначення контрактів API за допомогою схем Zod

Ключовою частиною створення клієнтських бібліотек є забезпечення того, щоб дані, які передаються до та з ваших API, відповідали попередньо визначеним контрактам. Тут на допомогу приходить Zod — потужна бібліотека для валідації схем.

Приклад: Валідація даних студентів

import { z } from "zod";  

const studentsDataSchema = z.array(  
 z.object({  
 name: z.string(),  
 rollNo: z.string(),  
 gender: z.enum(["male", "female", "not_specified"]),  
 })  
);  
const rollNoSchema = z  
 .string()  
 .regex(/^\d{2}[a-z]{3}\d{3}$/i)  
 .refine((rollNo) => {  
 const numericPart = Number.parseInt(rollNo.slice(-3));  
 return numericPart >= 1 && numericPart <= 999;  
 }, {  
 message: "Invalid roll number",  
 });  
export function isValidRollNumber(rollNo: string): boolean {  
 return rollNoSchema.safeParse(rollNo).success;  
}

Найкращі практики:

1. Валідація, що керується схемами: Використовуйте бібліотеки, такі як Zod або Yup, для визначення та забезпечення відповідності навантажень API. Це гарантує безпеку типів та надає миттєвий зворотний зв'язок під час розробки.
2. Утиліти: Створюйте утиліти (наприклад, isValidRollNumber), щоб абстрагувати повторювану логіку валідації та зробити ваш код більш декларативним.
3. Описові повідомлення про помилки: Використовуйте повідомлення про помилки Zod, щоб надавати чіткий зворотний зв'язок під час невдачі валідації.

Організація API кінцевих точок: простори імен та модульний дизайн

Ваша клієнтська бібліотека повинна групувати пов'язані кінцеві точки в цілісні модулі.
текст перекладу
Цей підхід спрощує організацію коду та покращує його доступність.

Приклад: API результатів

const results = {  
 importFreshers: async (  
 payload: APITypes["results"]["importFreshers"]["payload"]  
 ) => {  
 return await serverFetch<  
 ApiResponse  
 >("/results/import-freshers", {  
 method: "POST",  
 body: payload,  
 });  
 },  
 getResultByRollNo: async (  
 payload: APITypes["results"]["getResultByRollNo"]["payload"]  
 ) => {  
 return await serverFetch<  
 ApiResponse  
 >("/results/:rollNo/get", {  
 method: "GET",  
 params: { rollNo: payload },  
 });  
 },  
} as const;

Найкращі практики:

1. Модульний дизайн: Організовуйте API за доменами (наприклад, results, hostels, faculties). Це відображає вашу архітектуру бекенду та робить бібліотеку інтуїтивно зрозумілою.
2. Інференція типів: Використовуйте конструкцію as const в TypeScript для визначення літеральних типів та запобігання випадковим змінам.
3. Обробка помилок: Реалізуйте узгоджені патерни обробки помилок (наприклад, обгортаючи виклики fetch у блоки try-catch або використовуючи глобальний обробник помилок).

Сильна типізація за допомогою TypeScript

TypeScript посилює можливості клієнтських бібліотек, забезпечуючи типову безпеку. Визначте спільні типи та інтерфейси для забезпечення узгодженості по всьому додатку.

Приклад: Спільний тип відповіді API

type ApiResponse = {  
 error: boolean;  
 message: string;  
 data: T;  
};

Найкращі практики:

1. Перевикористовувані типи: Визначте загальні типи відповідей (ApiResponse), щоб спростити обробку API.
2. Явні навантаження та відповіді: Для кожної кінцевої точки визначайте типи навантажень і відповідей, щоб виявляти невідповідності під час компіляції.

Експортування єдиного API

Наприкінці експортуйте єдиний об'єкт API, який буде виступати як єдине джерело правди для всіх ваших кінцевих точок.

const serverApis = {  
 results,  
 hostels,  
 faculties,  
 departments,  
} as const;

export default serverApis;

Найкращі практики:

1. Інкапсуляція: Експонуйте єдиний об'єкт serverApis, щоб запобігти прямому доступу до окремих модулів.
2. Незмінність: Використовуйте as const, щоб заблокувати структуру об'єкта та запобігти випадковим змінам.

Заключні думки

Створення клієнтської бібліотеки — це не лише підключення до API; це створення зручного досвіду для розробників. Перевіряючи вхідні дані, забезпечуючи сильну типізацію та ретельно організовуючи кінцеві точки, ви можете створити бібліотеку, яка без зусиль масштабуватиметься разом з потребами вашого додатку. Описані практики забезпечують підтримуваність, читабельність і надійність, створюючи міцну основу для будь-якого сучасного проекту на JavaScript/TypeScript.

Додаткові міркування

1. Документація: Всеосяжна документація є критично важливою. Використовуйте інструменти, такі як JSDoc або TypeDoc, для генерації чітких, зручних для розробників посилань на API.
2. Тестування: Реалізуйте юніт-тести для вашої клієнтської бібліотеки, використовуючи фреймворки, такі як Jest або Vitest, для забезпечення надійності та запобігання регресіям.
3. Версійність: Якщо ваша бібліотека використовується в різних проектах, використовуйте семантичну версійність (SemVer) для ефективного управління змінами.
4. Продуктивність: Оптимізуйте ваші виклики fetch за допомогою таких технік, як обробка запитів партіями та кешування, щоб зменшити затримки та покращити досвід користувача.
5. Зворотній зв'язок від спільноти: Спілкуйтеся з вашими розробниками або користувачами, щоб зібрати відгуки та покращити дизайн і функціональність вашої бібліотеки.

Дотримуючись цих найкращих практик, ви створите не лише функціональну клієнтську бібліотеку, але й таку, якою розробники будуть із задоволенням користуватися.
текст перекладу
Почніть будувати сьогодні, і нехай ваша клієнтська бібліотека стане основою безперешкодних інтеграцій API у ваших проектах.

Повний код можна подивитися тут:
-> Повний код

Не забудьте поставити зірочку на репозиторії тут:
-> Репозиторій

Не соромтесь підписатися на мене в соціальних мережах:
-> Github
-> Linkedin
-> X/Twitter
-> Instagram

Перекладено з: Building Robust Client Libraries for Your Application: Best Practices for JavaScript and TypeScript