پوشش API و تجزیه و تحلیل استاتیک

1) چرا API لینک

• جلوگیری از تغییرات ناسازگار و ضمنی
• وضعیت ها، خطاها، صفحه بندی، امنیت را متحد کنید ؛
• مشخصات دستگاه قابل تایید و انتشار قابل پیش بینی ؛
• کاهش هزینه بررسی و زمان تحویل.

اصل: "قراردادها به طور خودکار بررسی می شوند ؛ روابط عمومی بدون پوشش سبز پایدار نیست"

2) امکانات خطوط

1. قراردادها: OpenAPI/AsyncAPI/GraphQL SDL، طرح Protobuf/Avro/JSON.
2. پیاده سازی: قلم REST/gRPC، میان افزار، کدهای وضعیت/هدر.
3. زیرساخت: هدر های امنیتی، محدودیت ها، سیاست های حافظه پنهان.
4. مصنوعات مرتبط: نمونه ها، مجموعه های پستچی، طرح های خطا.

3) قوانین اساسی برای API HTTP (مشخصات توصیه شده)

3. 1 نماد و URL

snake_case در بدنه JSON، کیس کباب در مسیرها یا کیس کباب یکنواخت/'/v1/... '.
منابع - جمع: '/v1/payments ', nested - '/v1/wallets/{ id }/transactions'.
شناسه ها به عنوان path-params: '/v1/payments/{ payment _ id} '(نوع: رشته، فرمت: uuid).

3. ۲ روشها و وضعیتها

«دریافت» - 200/206 ؛ POST '- 201 (+' محل ')، درگیری - 409 ؛ اعتبار سنجی - 422 ؛ محدودیت ها - 429 (+ 'Retry-After').
200 را برای اشتباهات برنگردانید. کوئری های شرطی - 304 توسط «If-None-Match».

3. 3 خطاها (فرمت تک)

json
{ "code":"validation_error", "message":"amount must be ≥ 1", "trace_id":"...", "details":[{"field":"amount","reason":"min:1"}] }

مورد نیاز: 'کد'، 'پیام'، 'ردیابی _ id' ؛ locale - از طریق «محتوا زبان».

3. 4 صفحه بندی/فیلتر

مبتنی بر مکان نما: 'page _ size'، 'page _ token'، ответ: 'next _ page _ token'.
فیلترها و مرتب سازی - لیست های سفید مستند در «پارامترها».

3. 5 ایمنی

طرح امنیتی یکنواخت: حوزه های OAuth2/OIDC یا mTLS ؛ انکار 'http' (فقط 'https').
هدر های حساس را باز نگردانید، نشانه های ماسک در نمونه ها.

3. 6 محدودیت ها و ابعاد

محدودیت عنوان/بدن: 413/414/431 ؛ حداکثر مقادیر مجاز را مستند کنید.

4) ابزار و اکوسیستم

4. 1 باز کردن API

Spectral (JSON/YAML lint)، Redocly linter، oas-diff/openapi-diff (تفاوت معنایی)، schemathesis/dredd (چک در حال انجام).

4. 2 Protobuf/gRPC

BUF (پرز + چک شکستن)، protolint، ژنراتور SDK ؛ Gnostic برای تجزیه و تحلیل.

4. 3 GraphQL

graphql-schema-linter, graphql-inspector (شکستن).

4. 4 خطوط کد و SAST

ESLint, golangci-lint, Detekt/Ktlint, Pylint/Flake8, Semgrep (بوی API و قالب های امنیتی).

5) مثال قانون: طیفی/قرمز

5. 1 طیفی (به عنوان مثال 'طیفی. یامل ')

yaml extends: ["spectral:oas", "spectral:asyncapi"]
rules:
openapi-tags: off info-contact: error no-http: error path-kebab-case:
description: "Paths must be kebab-case"
given: "$.paths[]~"
severity: error then:
function: pattern functionOptions: { match: "^/(?:[a-z0-9]+(?--[a-z0-9]+)/?)+$" }
response-error-schema:
description: "Error responses must use standard schema"
given: "$.paths[][].responses[?(@property >= '400')]"
then:
field: "content.application/json.schema.$ref"
function: truthy id-as-uuid:
given: "$..parameters[?(@.name =~ /.id$/i)]"
then:
field: schema.format function: enumeration functionOptions: { values: ["uuid"] }

5. 2 Redocly (قطعه '.redocly. یامل ')

yaml apis:
main: openapi.yaml lint:
extends:
- recommended rules:
no-ambiguous-paths: error operation-2xx-only: off operation-success-response:
severity: error where:
subject: response filterInParentKeys: ["200","201","204"]
operation-security-defined: error no-plain-http: error

6) Protobuf/gRPC: مشخصات بوف

6. 1 'BUF. من..

yaml version: v2 modules:
- path: proto lint:
use:
- DEFAULT except:
- PACKAGE_VERSION_SUFFIX # используем v1 в package breaking:
use:
- WIRE_JSON deps: []

• از اعداد فیلد استفاده مجدد نکنید ؛ حذف شده - در «حفظ».
• زمینه های جدید - «اختیاری» یا با پیش فرض ؛ نوع/معانی را تغییر ندهید.

7) تفاوت معنایی و تغییرات «شکستن»

7. 1 وب سایت

• تغییر نوع فیلد/اجباری
• حذف وضعیت/مسیر/پارامتر
• دامنه/محدوده باریک ؛
• تغییر فرمت id (uuid → string).

• اضافه کردن زمینه های اختیاری
• وضعیت های جدید که مسیر شاد را تحت تاثیر قرار نمی دهند (به عنوان مثال، مستند '422')
• پسوند enum.

7. 2 gRPC/Protobuf

حذف یک فیلد بدون «حفظ »/renumbering - شکستن.
تغییر نوع (int32 → رشته) - شکستن.
اضافه کردن یک برچسب جدید به عنوان اختیاری معمولا امن است.

8) قرارداد و پیوند کد

1. Contract → code: generation of SDK/server stubs, نمونه های منفی در آزمون.

2. قرارداد → کد: تست مشخصات، بررسی خودکار وضعیت/هدر.

• «بازگشت به 200» وقتی اشتباه! = صفر ؛
• «Idempotency-Key» اجباری در مسیرهای پرداخت نوشتن ؛
• ژتونها را در لاگها پنهان میکرد.

9) خط لوله CI/CD (مرجع)

pre-commit: spectral lint, redocly lint
PR gate:  openapi-diff (base..PR), buf breaking-check, graphql-inspector build:   schemathesis smoke, unit/integration linters (ESLint/golangci-lint)
release:  publish contracts (artifact/broker), sign & tag

• است شکستن تفاوت وجود دارد ؛
• قوانین اساسی نقض شده اند (وضعیت/امنیت/خطاها)
• هیچ مثال/توصیف پارامترها وجود ندارد.

10) کاتالوگ قوانین (قالب برای سازمان شما)

شناسه ها و انواع

'id' - 'string', 'format: uuid'.

زمینه های پول - «رشته »/« اعشاری» با مقیاس ؛ واحد پول - ISO-4217

اشتباه کردن

طرح یکپارچه (§ 3 را ببینید. 3)، کدهای: '400/401/403/404/409/422/429/5xx'.
همیشه 'ردیابی _ شناسه' ؛ بازگشت به عقب برای 429/503.

صفحه بندی

فقط مکان نما ؛ max 'page _ size' is مستند شده است.

امنیت و ایمنی

تمام عملیات - بلوک «امنیت» ؛ «حوزه» توصیف شده است.
بدون پیوندهای 'http:' ؛ TLS 1. 2+.

حافظه پنهان/قابلیت اطمینان

Для GET - «ETag/Last-Modified» ؛ برای نوشتن - 'Idempotency-Key' (در صورت لزوم).

مستند سازی

«تابستان»، «توضیحات»، نمونه هایی از درخواست ها/پاسخ ها (معتبر).

11) نمونه هایی از چک های خودکار

11. 1 تأیید سرصفحه های امنیتی اجباری (طیفی)

yaml security-headers:
given: "$.paths[][].responses['200'].headers"
then:
function: truthy

11. 2 openapi-diff (مرحله شبه CI)

openapi-diff --fail-on-incompatible base.yaml pr.yaml

11. 3 BUF شکستن چک

buf breaking --against '.git#branch=main'

12) قابل مشاهده بودن کیفیت قراردادها

معیارها: سهم روابط عمومی ها با خطاهای پیوند، زمان تعمیر، تعداد تلاش های شکستن، «بدهی ها» مطابق با قوانین.
داشبورد: پیشرفت مهاجرت به طرح خطای یکپارچه، پوشش با نمونه ها، ثبات نسخه.

13) ضد گلوله

«Doc» جدا از کد → desynchronization زندگی می کند. قرارداد را نزدیک به سرویس نگه دارید و یک مصنوع نسخه شده را آزاد کنید.
لینتر فقط با دست نیاز به روابط عمومی سخت دروازه.
نمونه های تصادفی (غیر قطعی) - لکه ها در چک.
بدون مثال های منفی و کدهای خطا.
بازسازی طرح خطا برای هر سرویس.
نادیده گرفتن چک های شکستن Protobuf (تغییر برچسب ها «توسط چشم»).

14) ویژگی های iGaming/امور مالی

زمینه های ارز - مقیاس ثابت/گرد کردن ؛ ممنوعیت شناور

سرآیندهای اجباری «X-Tenant»، «X-Region» و ردیابی «traceparent».
پرداخت نوشتن دسته: چک کردن «Idempotency-کلید», «تلاش مجدد پس از» و درست 409/201 semantics.
PSP/KYC Webhooks: HMAC/mTLS در «SecuritySchemes» شرح داده شده است ؛ ضد پخش («X-Timestamp»، پنجره).
محدودیت های منطقه ای و محلی سازی خطا («محتوا زبان»).

15) تولید لیست آمادگی

• پروفایل های طیفی/Redocly طراحی شده و متصل در قبل از متعهد و PR-دروازه.
• الگوی خطا و وضعیت تنها - متعهد و بررسی شده است.
• openapi-diff/GraphQL Inspector/buf - تغییرات شکستن بلوک.
• نمونه هایی از درخواست ها/پاسخ ها معتبر هستند ؛ صفحه بندی/فیلترها مستند شده است.
• طرح های امنیتی و حوزه ها پر می شوند ؛ هیچ لینک HTTP وجود ندارد.
• برای Protobuf: «رزرو شده» در برچسب های حذف شده ؛ زمینه های جدید - اختیاری
• پیوندهای Semgrep/کد فعال شده است. پنهان کردن اسرار در لاگ ها
• CI منتشر مصنوعات قرارداد و گزارش آستر.
• Playbook: نحوه عمل در هنگام شکستن دیفا (برگشت، hotfix، اطلاعیه ها به انتگرال ها).

16) TL ؛ دکتر متخصص

پیاده سازی پوشش خودکار قرارداد (Spectral/Redocly، buf/GraphQL Inspector) و تفاوت معنایی، رفع یک طرح خطا/وضعیت/صفحه بندی/امنیت، اتصال PR-gate و انتشار قراردادها به عنوان مصنوعات. هر اختلاف شکستن یک چراغ ترمز است. برای پول/پرداخت - قوانین خاص (idempotency، 'Retry-After'، HMAC/mTLS).