Spetsifikatsiya asosida dasturlash: avval API kontrakti, keyin kod

Odatiy tartibda backend dasturchi API yozadi, frontend dasturchi esa uni kutadi, keyin integratsiya paytida «bu maydon boshqa nomda ekan» degan kelishmovchiliklar chiqadi. Spetsifikatsiya asosida dasturlash (spec-first yoki contract-first) bu tartibni o‘zgartiradi: avval API qanday ko‘rinishi rasmiy hujjatda yoziladi, keyin hamma shu hujjatga qarab ishlaydi.

Kontrakt nimani o‘z ichiga oladi

• Barcha manzillar va metodlar
• So‘rov parametrlari va tanasi: maydonlar, turlari, majburiyligi, cheklovlari
• Javoblar tuzilmasi har bir holat uchun: muvaffaqiyat, xato, topilmadi
• Xato kodlari va ularning ma’nosi
• Autentifikatsiya usuli
• Misollar

Kontrakt odatda mashina o‘qiy oladigan standart formatda yoziladi — REST uchun eng keng tarqalgani OpenAPI. Bu muhim: hujjatdan avtomatik ravishda boshqa narsalar yaratiladi.

Kontraktdan nima olinadi

1. Interaktiv hujjat — dasturchilar so‘rovlarni brauzerda sinab ko‘radi
2. Soxta server (mock) — frontend jamoasi haqiqiy backend tayyor bo‘lishidan oldin ishlay boshlaydi
3. Mijoz kodi — turli tillar uchun API bilan ishlash kutubxonalarini generatsiya qilish
4. Avtomatik tekshiruvlar — backend javoblari kontraktga mosligini testlar nazorat qiladi

Ish tartibi

1. Tahlilchi yoki arxitektor ssenariylar asosida kontrakt qoralamasini yozadi
2. Frontend, backend va mobil dasturchilar uni birga ko‘rib chiqadi
3. Kelishilgan versiya repozitoriyga qo‘yiladi
4. Jamoalar parallel ishlaydi: frontend mock bilan, backend haqiqiy amalga oshirish bilan
5. Kontraktdagi har qanday o‘zgarish muhokama qilinadi va versiyalanadi

Afzalliklar

• Parallel ishlab chiqish. Jamoalar bir-birini kutmaydi.
• Kamroq kelishmovchilik. Maydon nomlari va formatlar oldindan kelishilgan.
• Hujjat har doim dolzarb. U kodning manbai, keyingi qo‘shimcha emas.
• Tashqi hamkorlar bilan qulay. Integratsiya qiladigan kompaniyaga kontrakt beriladi va ular kutmasdan boshlaydi.

Qachon ayniqsa foydali

• Bir API bilan bir nechta mijoz ishlaydi: sayt, iOS va Android ilovalar, Telegram mini-ilova
• Turli kompaniyalar yoki pudratchilar bir loyihaning turli qismlarini yaratadi
• Tashqi hamkorlarga API beriladi
• Uzoq yashaydigan tizim, jamoalar vaqt o‘tishi bilan almashadi

Cheklovlar

• Boshida vaqt talab qiladi — kontraktni yozish va kelishish kerak
• Juda tez o‘zgaradigan prototipda kontraktni doimo yangilash og‘irlashadi
• Kontrakt faqat interfeysni tasvirlaydi, biznes mantiqni emas — uni alohida hujjatlashtirish kerak

Amaliy maslahatlar

• Maydon nomlash qoidasini bir marta tanlang va unga amal qiling
• Sanalar, pul summalari va telefon raqamlari formatini aniq belgilang
• Ro‘yxatlar uchun sahifalash usulini boshidan kiriting
• Xatolar uchun yagona tuzilma: kod, tushunarli matn, qaysi maydonda muammo
• Kontraktdagi o‘zgarishlarni eski mijozlarni buzmaydigan tarzda qiling: maydon qo‘shish mumkin, olib tashlash yoki ma’nosini o‘zgartirish — yangi versiya orqali