Мутобиқат ва навсозиҳои API
1) Асосҳои мутобиқат
Иловаи аввал: бе шикастани кӯҳна нав илова кунед (майдонҳои нави ихтиёрӣ/нуқтаҳои ниҳоӣ, арзишҳои нави энум).
Шартномаҳои устувор: "он чизе, ки дар мушаххасот ваъда дода шудааст;" рафтор ҳуҷҷатгузорӣ шудааст.
Ба қафо> Ба пеш: афзалияти мутобиқати қафо; ба пеш тавассути хонандагони таҳаммулпазир иҷозат дода мешавад.
Ҳуҷҷатҳо аввалиндараҷа мебошанд: ягона манбаи ҳақиқат нусхаи бақайдгирии схема мебошад (Open
Таҳаввулоти возеҳ: шикастан - танҳо тавассути нусхаи нави асосӣ ва роҳнамои муҳоҷират.
2) Таксономияи тағирот
2. 1 мувофиқ (MINOR/PATCH)
Илова кардани майдонҳо/сарлавҳаҳои ихтиёрӣ, нуқтаҳои охирин, параметрҳои дархост бо пешфарз.
Афзоиши маҳдудиятҳо ('page _ size', TTL), равшан кардани хатогиҳо бидуни тағир додани рамзҳо/семантика.
Агар мизоҷон "номаълум" (хонандаи таҳаммулпазир) -ро нодида гиранд, арзишҳои энумро илова кунед.
2. 2 номуайян (рафтор)
Тағйир додани пешфарзҳо, тартиби навъбандӣ, танаффусҳои лоғар, квотаҳо - мантиқи тиҷоратро "вайрон" карда метавонанд. RFC + эълон ва канарейкаҳоро талаб мекунад.
2. 3 шикаст (MAJOR)
Майдонҳоро тағир диҳед/нест кунед, намуд/форматро иваз кунед, рамзҳои хатогиро иваз кунед, номувофиқатии шартномаҳо/схемаҳои аутентификатсияро баръакс кунед.
3) Сиёсати версия
Стратегия: 'таҳвили роҳ' ('/v1 ', '/v2').
Ноболиғ/ячейка: "илова кунед, шикаста нашавед".
Сарлавҳаҳои санаи (ихтиёрӣ): 'X-API-Version-Date' барои тағироти мулоими афзоянда.
Намудҳои ВАО (Op.): 'Қабул кунед: ариза/внд. акме. v1 + json 'барои гранулясияи хуб.
4) Амортизатсия ва ғуруби офтоб
4. 1 Сарлавҳаҳои иртибот
Deprecation: true
Sunset: 2026-03-31T00:00:00Z
Link: </guides/reports-v2>; rel="successor-version"4. 2 Тартиби бозпас гирифтани
1. Эълон дар рӯйхати портал/почта/қайдҳои барориши SDK.
2. Равзанаи огоҳӣ 90-180 рӯз ≥.
3. Статусҳо дар панели фарзандхонӣ.
4. Пас аз ғуруби офтоб - 410 Ҳолати Gone ё "танҳо хондан" барои давраи имтиёзнок, агар мувофиқа карда шавад.
5) Муҳоҷират ва ҳамзистии версияҳо
Дучанд навиштан/дутарафа хондан дар давраи гузариш ва оштӣ бо гузоришҳо.
Адаптерҳо (муваққатӣ): табдилдиҳии дарвоза аз сарбории кӯҳна → схемаҳои нав; умри адаптер маҳдуд аст.
Кӯмаки SDK: релизҳое, ки ҳарду версияро дастгирӣ мекунанд, бо огоҳиҳои коҳиш (1 вақт дар як раванд).
Парчамҳои хусусият: дохил кардани семантикаи нав аз рӯи рӯйхати калидҳо/иҷорагирон.
6) Мутобиқати қафо ва пеш
6. 1 Ба ақиб (мизоҷони кӯҳна ↔ сервери нав)
Форматҳои намуди/ҳатмиро тағйир надиҳед.
Майдонҳои нав танҳо ихтиёрӣ мебошанд.
Хатогиҳо - кӯҳнаи 'code _ code', рамзҳои навро илова кунед, иваз накунед.
6. 2 Ба пеш (мизоҷони нав ↔ сервери кӯҳна)
Имкониятҳоро тавассути 'OPTIONS '/'/версияҳо' санҷед.
Рафтори файз: Мизоҷ бояд ба хусусиятҳои гумшуда таҳаммулпазир бошад.
7) Шартномаҳо ва чекҳои автоматӣ
Феҳрист: версияҳои схемаи мағоза; PR ҳисоботҳои шикастан/шикастанро кофтааст.
Линтер: номҳо/намудҳо, idempotency, pagination, рамзҳои устувор.
CDC (Шартномаҳои истеъмолкунанда): Санҷишҳои интегратор дар CI таъминкунанда (Паймон ва аналогҳо).
Дарвоза: PR ҳангоми шикастани бидуни 'major '/RFC баста мешавад.
yaml
- name: API Diff run: api-diff --from main --to $PR_SHA --fail-on=breaking --format junit --out diff. xml8) Тамдиди канарӣ ва баръакс
Канария: 10% → 25% → 50% → 100% трафик; худкор ба таназзули SLO (5xx/latency/429).
Калидҳои бета: дастрасӣ ба версияҳои нав аз рӯи рӯйхат.
Озодкунӣ: буҷаи хатогӣ ҳангоми сӯзишворӣ.
Таҳлили қабул: ҳиссаи трафик/муштариён дар версияи нав, вақти муҳоҷират.
9) Мутобиқат ба таври муфассал: хатогиҳо, бутпарастӣ, аблаҳӣ
9. 1 Хатогӣ
Ҳолати HTTP- ро дар скриптҳои мавҷуда тағйир надиҳед.
'error _ code' - устувор; рамзҳои нав танҳо илова мекунанд.
'application/problem + json' як формати ягона аст.
9. 2 Саҳифа
Гузариш ба курсор/keyset = MINOR агар 'offset/limit' -и кӯҳна пуштибонӣ шавад.
Ҳуҷҷатгузории навъи '(updated_at,id)' ва устувории курсор.
9. 3 Идемпотенция
Барои навиштан - 'Idempotency-Key' + '409 дар ҳолати муноқиша IDEMP_REPLAY'.
Муҳоҷират набояд семантикаи аблаҳиро тағйир диҳад.
10) Табдилдиҳии дарвоза (агар лозим бошад)
Харитаи майдонҳои v1 → v2, хатогиҳоро муқаррар кунед, форматҳои сана/пулро табдил диҳед.
Гвардияҳо: дигаргуниҳо шаффоф ва воридшаванда мебошанд; шикастанро пинҳон накунед, балки ҳамчун пули маҳдуд истифода баред.
11) Алоқа ва портал
Changelog s datami ('илова/тағир/фарсуда/хориҷ карда/собит').
Корти версия: ҳолат (бета/GA/фарсуда), санаи ғуруби офтоб, пайвандҳо ба роҳнамо.
Webhooks огоҳинома: 'фарсудашавӣ. аҳамият ',' версия. озод ',' нақша. тағир '.
SDK қайдҳо + баннерҳои порталиро нашр мекунад.
12) Нишондиҳандаҳои муваффақият
Меъёри қабули v2 (барои дархост/муштарӣ).
Ҳодисаҳои қафо-компат.
Омехтаи хатогӣ (саҳмияҳои 4xx/5xx/429) пеш аз/баъд аз озод шудан.
Вақт ба-қабул миёнаравӣ.
Сарбории дастгирӣ (чиптаҳо/ҳафта).
Арзиш барои хидмат.
13) Қолабҳо ва намунаҳо
13. 1 Унвонҳо ва коҳишҳои версия
X-API-Version: v1
Deprecation: true
Sunset: 2026-03-31T00:00:00Z
Link: </v2/reports>; rel="successor-version"13. 2 Сиёсати версия (порчаи YAML)
yaml versioning:
strategy: "path"
compatibility:
minor: "additive-only"
patch: "bugfix/perf, no schema change"
deprecation:
min_notice_days: 120 rollout:
canary_steps: [10,25,50,100]
rollback_checks: ["5xx_rate","p95_latency","429_rate","adoption"]13. 3 Замимаҳои саҳроии кушодаи API мувофиқ
yaml components:
schemas:
Report:
type: object required: [id, createdAt]
properties:
id: { type: string }
createdAt: { type: string, format: date-time }
cursor: { type: string, description: "optional for v1. 2+" } # additive14) Рӯйхати назоратӣ (MINOR/MAJOR)
MINOR
- DIFF: шикастан, сабзи сабз
- Ҳуҷҷатгузорӣ/SDK нав карда шуд (намунаҳо/кодекҳо)
- Бозгашти Canary + auto-SLO
- Нақшаи Comm, Саҳифаи Портал
- Панели қабул ва хатогӣ
MAJOR
- RFC/ADR, санаи ғуруби офтоб ва ≥ 90 тиреза -180 рӯз
- v1↔v2 пул ва роҳнамои муҳоҷират
- Дучанд навиштан/хондан ва оштӣ кардан
- SDK бо ҳарду огоҳиҳои API +
- Озмоишӣ бо интеграторҳои асосӣ
15) Нақшаи амалисозӣ (3 такрорӣ)
1. Бунёд (2 ҳафта):
Феҳристи схемаҳо, линтҳо ва худкор дар CI; сиёсати мутобиқат; Унвонҳои 'Амортизатсия/Ғуруби офтоб'.
2. Варақаҳои идорашаванда (3-4 ҳафта):
Канарейкаҳо, парчамҳои махсус, огоҳиҳои SLO; портали версия; SDK бо дастгирии 2 филиал баромад мекунад.
3. Автоматика ва миқёс (муттасил):
Санҷишҳои CDC истеъмолкунандагон дар CI, пешгӯии ғуруби офтоб дар бораи тамоюлҳои фарзандхонӣ, огоҳиномаҳо ва ёдраскуниҳои автоматӣ.
16) Мини-FAQ
Оё ман метавонам навъи майдонро бе ягон асосӣ иваз кунам?
Не, ин тавр нест. Ҳатто "stroka → chislo" шикаста истодааст. Майдони навро ворид кунед, кӯҳнааш фарсуда аст.
Enum: шумо метавонед арзишҳоро илова кунед?
Бале, агар мизоҷон хонандагони таҳаммулпазир бошанд. Вагарна - аввал ҳушёру бета.
Версияи кӯҳнаро чӣ қадар нигоҳ доштан мумкин аст?
То ҳол қабули ≥ нав 95% нигоҳ дошта шудааст. Мӯҳлатро дар сиёсат ислоҳ кунед.
Ҷамъ
Мутобиқати API як интизом аст: равиши иловагӣ, схемаҳои расмӣ ва дифҳо, релизҳои канарӣ, коҳишҳои возеҳ ва муҳоҷирати идорашаванда. Сиёсати тағиротро муттаҳид кунед, чекҳо ва иртиботро автоматӣ кунед, қабули онҳоро чен кунед - ва навсозиҳои шумо шикастани муштариёнро бозмедоранд ва суръати таҳаввулот бидуни гум кардани эътимод афзоиш хоҳад ёфт.