Type-safe API client
TypeScript'da type-xavfsiz API client: barcha endpoint'larni bitta Api xaritasida tavsiflash, URL'dan avtomatik body va javob type'i, TS ushlaydigan xatolar va real vositalar.
89-dars
Type-safe API client
Barcha endpoint'larni bitta type xaritasida tavsiflaysiz: qaysi URL, qaysi metod, nima yuboriladi, nima qaytadi. Keyin client funksiyasi shu xaritadan foydalanadi va siz URL yozishingiz bilan TS body va javob type'ini o'zi biladi.
Oddiy fetchJson<User>(...) (85-dars) dan farqi: u yerda type'ni har safar qo'lda yozasiz va xato qilishingiz mumkin. Bu yerda type URL'dan avtomatik chiqadi.
1. Endpoint xaritasi
type User = { id: number; name: string; email: string };
type Product = { id: number; title: string; price: number };
type Api = {
"GET /users": {
response: User[];
};
"GET /users/:id": {
params: { id: number };
response: User;
};
"POST /users": {
body: { name: string; email: string };
response: User;
};
"GET /products": {
query: { page?: number; search?: string };
response: Product[];
};
};
Butun API "shartnomasi" bitta joyda.
2. Client funksiyasi
type Route = keyof Api;
// endpointda bor maydonlarni majburiy qiladi
type Options<R extends Route> = Omit<Api[R], "response">;
async function api<R extends Route>(
route: R,
...[options]: {} extends Options<R> ? [Options<R>?] : [Options<R>]
): Promise<Api[R]["response"]> {
const [method, rawPath] = route.split(" ");
const opts = (options ?? {}) as {
params?: Record<string, unknown>;
query?: Record<string, unknown>;
body?: unknown;
};
// :id → 5
let path = rawPath.replace(/:(\w+)/g, (_, key) => String(opts.params?.[key]));
if (opts.query) {
const qs = new URLSearchParams();
for (const [k, v] of Object.entries(opts.query)) {
if (v !== undefined) qs.set(k, String(v));
}
path += `?${qs}`;
}
return fetchJson(`/api${path}`, {
method,
headers: { "Content-Type": "application/json" },
body: opts.body ? JSON.stringify(opts.body) : undefined,
});
}
Bu kodni bir marta yozasiz. Murakkab qismi faqat shu yerda. Ishlatadigan TS vositalari — keyof (54-dars), indexed access Api[R]["response"] (56-dars), generic constraint R extends Route (52-dars) — oldingi darslardan tanish.
3. Ishlatish (asosiy foyda shu yerda)
const users = await api("GET /users");
// users: User[] ← type'ni yozmadik, o'zi chiqdi
const user = await api("GET /users/:id", { params: { id: 5 } });
// user: User
const created = await api("POST /users", {
body: { name: "Ali", email: "[email protected]" },
});
const products = await api("GET /products", { query: { search: "telefon" } });
TS ushlaydigan xatolar
api("GET /user"); // ❌ bunday endpoint yo'q
api("GET /users/:id"); // ❌ params berilmadi
api("GET /users/:id", { params: { id: "5" } }); // ❌ id number bo'lishi kerak
api("POST /users", { body: { name: "Ali" } }); // ❌ email yo'q
api("GET /products", { query: { sort: "x" } }); // ❌ sort query'da yo'q
Editor'da api(" yozsangiz, barcha endpoint'lar ro'yxati avtokomplit bo'lib chiqadi.
Real loyihada
Bu g'oyani tayyor holatda beradigan vositalar bor:
- OpenAPI → TS generatorlar (
openapi-typescript+openapi-fetch): backend Swagger'idan xaritani avtomatik yasaydi. - tRPC: backend va frontend ham TS bo'lsa, xarita umuman yozilmaydi.
- Zod bilan birga ishlatilsa, javob runtime'da ham tekshiriladi.
Eslab qolish uchun
- Hamma endpoint'lar bitta
Apitype'ida. - Client generic:
R extends keyof Api. - Type URL'dan chiqadi, qo'lda
<User>yozilmaydi. - Endpoint o'zgarsa, ishlatilgan hamma joyda xato chiqadi, hech narsa unutilmaydi.