Амалисозии истинод

1) Ҳадафҳо, марзҳо ва принсипҳо

1. Протокол/характеристикаро яктарафа шарҳ диҳед.

2. Санҷиши мутобиқати мустақилро таъмин кунед.

3. Мисолҳои кории муштарӣ/сервер/веб-китобҳоро пешниҳод кунед.

4. Арзиши ҳамгироӣ ва амалисозиро коҳиш диҳед.

• RI на ба ҳадди аксар расонидани фаъолият, балки ба дурустии рафтор тамаркуз мекунад.
• Маҷмӯи ҳадди аққали танзимоти истеҳсолиро дар бар мегирад (TLS, воридшавӣ, ченакҳо, пайгирӣ, маҳдудкунандаҳо).
• Фурӯши тиҷоратӣ/маҳсулотро иваз намекунад, балки "сатри пасттар" -ро муқаррар мекунад.

• Spec-аввал: дуруст - дар мушаххасот (Open
• Муайянкунанда ва санҷидашуда: Ҷавобҳо ва афсонаҳои такроршаванда.
• Docs-as-Code: ҳама дар VCS, як версия бо рамз ва санҷишҳои мутобиқат.
• Қобилият: контейнерҳо, Ҳелм/композитсия, зуҳуроти тайёр.

2) Намудҳои татбиқи истинод

RI-Server: истинод ба сервер барои як тавсиф (REST/g

RI-Client/SDK: истинод ба мизоҷон (як ё ду платформаи маъмул) + намунаҳо.
Қабулкунандаи RI-Webhook: дастури имзошудаи webhook (санҷиши имзо, бозхонд).
RI-адаптерҳо: адаптерҳо ба брокерҳои паём/автобусҳои чорабинӣ (Avro/Proto/JSON, Registry Schema).
RI-Маълумот: маҷмӯи маълумотҳои истинод, профилҳои махфият, аксҳои тиллоӣ.

3) Меъмории репозиторияи RI

ri/
specs/        # OpenAPI/AsyncAPI/Proto/JSON-Schema server/       # эталонный сервер src/
config/
docker/
helm/
client/       # эталонный клиент/SDK + примеры js/ python/ go/
conformance/     # конформанс-раннер, тест-кейсы, золотые файлы cases/
fixtures/
golden/
samples/       # end-to-end сценарии, Postman/k6/Locust security/      # ключи тестовые, политики, пример подписи docs/        # руководство, ADR, runbook, FAQ ci/         # пайплайны, конфиги, матрица совместимости tools/        # генераторы, линтеры, проверяльщики схем

• Ҳар як релиз барчаспҳои 'VX' дорад. Y.Z 'ва артефактҳо (тасвирҳо, диаграммаҳо, SDK).
• Барои ҳар як нуқта - миқдор ва имзо (занҷири таъминот).
• CHANGELOG тағиротҳои "шикаста" -ро қайд кард.

4) Хусусиятҳо, шартномаҳо ва схемаҳо

Нақлиёт: Open

Семантика: рамзҳои хатогӣ, аблаҳӣ, курсор/пагинатсия, ретрай, депликатсия.
Ҳодисаҳо: намуд/версия, 'id', 'happened _ at _ utc', 'partition _ key', инвариантҳои фармоиш.
Имзоҳо/амният: маркаҳои OIDC/JWT, имзои webhook (HMAC/EDDSA), гардиши калидҳо.

5) Санҷиши мутобиқат

• мутобиқат бо доғҳо (тасдиқи схемаҳо),
• инвариантҳои рафторӣ (номутобиқатӣ, навъбандӣ, курсорҳо, TTL, сиёсати такрорӣ),
• амният (имзоҳо, мӯҳлатҳо, муҳофизати nonce/replay),
• ҷанбаҳои муваққатӣ (UTC, RFC3339, DST),
• ҳолатҳои манфӣ ва шароити сарҳадӣ.

Файлҳои тиллоӣ: Ҷавобҳо/рӯйдодҳои истинодии устувор, ки натиҷаҳо муқоиса карда мешаванд.

python def run_conformance(target_url, cases, golden_dir):
for case in cases:
req = build_request(case.input)
res = http_call(target_url, req)
assert match_status(res.status, case.expect.status)
assert match_headers(res.headers, case.expect.headers)
assert match_body(res.json, golden_dir / case.id, allow_extra_fields=True)
for invariant in case.invariants:
assert invariant.holds(res, case.context)

consumer/sdk-js 1.4server 1.6, 1.7server 2.0 consumer/sdk-go 0.9server 1.5–1.7   –
webhook-receiver 1.1events v1events v2 (deprecated fields removed)

6) Ҳадди аққали истеҳсолот (бе frills)

Амният: TLS бо нобаёнӣ, сарлавҳаҳои амният, маҳдудияти CORS, маҳдудкунандаҳо, зидди такрорӣ.
Мушоҳида: гузоришҳо (ниқобҳои сохторӣ + PD), ченакҳо (p50/p95/p99, сатҳи хатогӣ), пайгирӣ (таносуби 'дархост _ id').
Конфигуратсия: ҳама тавассути тағирёбандаҳои муҳит ва файлҳо, схемаи конфигуратсия тасдиқ карда мешавад.
Perf-basline: танзимоти умумии ҳавз, буҷаи танаффуси занҷир, кэш бо ҳамбастагӣ.
Устуворӣ: retrai бо jitter, breaker, backpressure.

7) CI/CD ва артефактҳо

1. Санҷишҳои линт/васл/воҳид.

2. Тасдиқи мушаххасот (Open

3. Насли SDK/stors аз характеристика.

4. Иҷрои мувофиқат: 'ri-server' дар муқобили 'ҳолатҳо' ва 'тилло'.

5. Сохтани тасвирҳо (SBOM, имзо), нашр кардан ба феҳрист.

6. E2E скриптҳо (docker-compose/number/Helm).

7. Нашри docksite ва намунаҳо.

• тасвирҳои контейнерӣ 'ri-server', 'ri-webhook',
• Бастаҳои SDK (npm/pypi/go),
• Диаграммаи Helm/эҷоди файлҳо,
• zip бо "файлҳои тиллоӣ" ва давандаи мувофиқ.

8) Намунаҳо, SDK ва чӣ гуна ба

Мини-барнома дар ду стекҳои маъмул (масалан, Гиреҳ. js/Go) бо қадамҳо: аутентификатсия → API занг → хатогӣ дар самти коркарди → бозсозӣ → webhook.
Чӣ тавр: idempotent POST, пагинатсияи курсӣ, имзои webhook, коркарди 429/503.
k6/JMeter профилҳо барои "дуд-перф" (на бор, балки саломатии асосӣ).

9) Версия ва эволютсия

Semver: шикастани тағйирот → MAJOR; Илова кардани MINOR-и шикастнопазир → PATCH →.
Нақшаи радкунӣ: эъломияҳо дар хусусиятҳо, парчамҳои махсус, давраи мувофиқати "соя", пас татбиқ карда мешаванд.
Мутобиқати ҳодисаҳо: Аз истеъмолкунандагон талаб карда мешавад, ки майдонҳои ношиносро нодида гиранд.

10) Амният ва махфият дар РИ

Калидҳои санҷишӣ ва асрори - танҳо барои стенд; дар докҳо - дастурҳои ивазкунӣ.
Пинҳон кардани PD дар гузоришҳо; Профилҳои беном кардани афсонавӣ (PII → синтетика).
Сиёсати ҳаёти артефактии муҳити зист (TTL, худкор тоза).

11) Мушоҳида ва SLO барои RI

SLI/SLO RI: p95 <250 ms дар лавҳаи истинод, сатҳи хатогӣ <0. 5%, таназзули дуруст ҳангоми нокомии вобастагӣ (дар намуна).
Панели панелҳо: ниҳонӣ/интиқол/хатогиҳо + натиҷаҳои мутобиқат.
Сабтҳои қарор барои имзои вебхукҳо/чекҳои токен (сабабҳои пайгирии нокомӣ).

12) Иҷро: заминаи "кофӣ"

Профилҳои 'wrk/ey/k6' дар роҳҳои гарм ва хунук.
Мавқеи возеҳ: RI дар ҳадди RPS рақобат намекунад, аммо бояд ба ҳадафи муқаррарӣ тоб оварад (масалан, 500 RPS дар t3). миёна бо p95 <200ms) - ҳамчун дастур барои интеграторҳо.

13) Дастури амалиётӣ (дафтарчаи корӣ)

Оғози маҳаллӣ: эҷод/' ороиш '.
K8s-deploy: Арзишҳои Helm, асрори, ingress, HPA.
Гардиши тугмаҳои имзошудаи webhook (давраи калиди дугона).
Траблотинг: хатогиҳои зуд-зуд ва сабабҳои онҳо (401, 403, 429, 503), чӣ гуна хондани гузоришҳо/роҳҳо.

14) Идоракунӣ ва моликият

Соҳибон: соҳиби маҳсулоти дона + платформа (таҷҳизот) + амният.
Барориши равзанаи тақвим ва таъғироти таъғирот.
RFC/ADR оид ба тағироти пурмазмуни протокол.

15) Мутобиқшавӣ ба забонҳо/платформаҳо

Ҳадди аққали тавсияшуда як сатҳи баланд (JS/TS) ва як система (Go/Java) мебошад.
Харитаи навъи: чӣ гуна санаҳо/форматҳои асъорӣ/маҷмӯи даҳӣ/байтӣ нишон дода мешаванд.
Тавсияҳо барои бозпас/вақт/танзимоти ҳавз дар ҳар як SDK.

16) Анти-намунаҳо

RI = "қуттии қуттӣ бидуни санҷиш": мувофиқат ва фоидае нест.
Спека аз рамз "алоҳида зиндагӣ мекунад" ва номутобиқатиро санҷидааст.
Набудани "файлҳои тиллоӣ" ва invariants → шикофҳо ва баҳсҳо дар бораи рафтор.
Чаҳорчӯбаи вобастагӣ: ҳатмии қатъӣ ба як китобхона/абр бидуни контейнеризатсия.
Гузоришҳо бе ниқоби PD, калидҳо дар анбор.
Перф ба ҷои рафтор омехта мешавад: кӯшиши чен кардани "кӣ тезтар аст" ба ҷои "кӣ дуруст аст".
Як бинари/тасвири азим бе модулият ва артефактҳо (SDK/диаграммаҳо/характеристика).

17) Рӯйхати назорати меъморон

1. Speka - каноникӣ ва тасдиқшуда? (Кушодан/API/Proto/AsyncAPI/JSON-Schema)

2. Оё RI-сервер ва ҳадди аққал як RI-муштарӣ/SDK бо намунаҳои пурра вуҷуд дорад?
3. Давандаи мувофиқат, ҳолатҳо, "файлҳои тиллоӣ", манфӣ ва ғайривариантҳо омодаанд?
4. CI/CD тасвирҳо, SDK, сайт, мувофиқат ва e2e -ро ҷамъ меорад?
5. Амнияти пешфарз: TLS, имзоҳо, маҳдудиятҳо, ниқоби PD?
6. Мушоҳидаҳо: Гузоришҳо/ченакҳо/роҳҳо, панелҳо ва SLO барои RI?
7. Perf-basline ҳуҷҷатгузорӣ ва такроршаванда аст?
8. Версияи Semver, матритсаи мутобиқат, тартиби радкунӣ?
9. Runbook ва роҳандозии маҳаллӣ/кластерӣ - дар як клик?
10. Соҳибон, тақвими озод, ҷараёни RFC/ADR муайян карда шуд?

18) Намунаи мини: webhook истинод (псевдокод)

python def verify_webhook(request, keys):
sig = request.headers["X-Signature"]
ts = int(request.headers["X-Timestamp"])
if abs(now_utc().epoch - ts) > 300: return 401 # replay window body = request.raw_body if not any(hmac_ok(body, ts, k, sig) for k in keys.active_and_previous()):
return 401 event = json.loads(body)
if seen(event["id"]): return 200 # idempotency handle(event)
mark_seen(event["id"])
return 200

Санҷиши ҳолати санҷиш: равзанаи вақт, дурустии имзо (калиди ҷорӣ ва қаблӣ), номутобиқатии ҳодиса. id ', манфӣ (имзои вайроншуда, мӯҳлати' ts ').

Хулоса

Амалисозии истинод канони рафтори система мебошад: як мушаххасоти ягона бо рамз, санҷишҳо ва артефактҳо тасдиқ карда шудааст. Ҳамгироии хуби RI ҳамгироиро суръат мебахшад, номуайянии протоколро бартараф мекунад, мутобиқати тасдиқшавандаро таъмин мекунад ва стандартҳои ҳадди аққали амният, мушоҳида ва иҷроишро муқаррар мекунад. Онро як қисми муҳандисии "скелет" -и худ созед - ва маҳсулот, шарикон ва экосистемаи шумо зудтар ва боэътимод ҳаракат хоҳанд кард.