Επένδυση API και στατική ανάλυση

1) Γιατί συνδέει το API

• Πρόληψη ασυμβίβαστων και σιωπηρών αλλαγών
• ενοποιούν τα καθεστώτα, τα σφάλματα, τη σελιδοποίηση, την ασφάλεια·
• καθιστούν προβλέψιμες τις προδιαγραφές επαληθεύσιμες από το μηχάνημα και τις ελευθερώσεις·
• μείωση του κόστους επανεξέτασης και του χρόνου επιβίβασης.

Αρχή: "οι συμβάσεις ελέγχονται αυτόματα· Οι δημόσιες σχέσεις χωρίς πράσινη επένδυση δεν ισχύουν"

2) Εγκαταστάσεις επένδυσης

1. Συμβάσεις: OpenAPI/AsyncAPI/GraphQL SDL, Protobuf/Avro/JSON Schema.
2. Εφαρμογή: στυλό REST/gRPC, μεσαίο λογισμικό, κωδικοί κατάστασης/κεφαλίδες.
3. Υποδομή: Κεφαλίδες ασφαλείας, όρια, πολιτικές για τη μνήμη.
4. Σχετικά αντικείμενα: παραδείγματα, συλλογές ταχυδρόμων, συστήματα σφαλμάτων.

3) Βασικοί κανόνες για το HTTP API (συνιστώμενο προφίλ)

3. 1 Συμβολισμός και URL

σε σώματα JSON, κεμπάμπ-περίπτωση σε μονοπάτια, ή ομοιόμορφη κεμπάμπ-περίπτωση/'/v1/... '.
Πόροι - πληθυντικός: '/v1/πληρωμές ', ένθετοι - '/v1/πορτοφόλια/{ id }/συναλλαγές'.
Αναγνωριστικά ως path-params: '/v1/payments/{ payment _ id} '(τύπος: συμβολοσειρά, μορφή: uuid).

3. 2 Μέθοδοι και καταστάσεις

"GET" - 200/206; " POST '- 201 (+' Τοποθεσία '), συγκρούσεις - 409; επικύρωση - 422· όρια - 429 (+ 'Retry-After').
Μη επιστρέφετε 200 για σφάλματα. Ερωτήσεις υπό όρους - 304 by 'If-No-Match'.

3. 3 Σφάλματα (ενιαίο μορφότυπο)

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

Απαιτείται: 'code', 'message', 'trace _ id'. locale - μέσω 'Content-Language'.

3. Pagination/φίλτρα

Με βάση τον δρομέα: 'page _ size', 'page _ token', ответ: 'next _ page _ token'.
Φίλτρα και διαλογή - λευκοί λίστες τεκμηριωμένοι σε «παραμέτρους».

3. 5 Ασφάλεια

Ενιαίο σύστημα ασφάλειας: OAuth2/OIDC πεδία εφαρμογής ή mTLS· αρνούνται το "http" (μόνο το "http ).
Μη επιστρέφετε ευαίσθητες κεφαλίδες, μάσκες σε παραδείγματα.

3. 6 Περιορισμοί και διαστάσεις

Όρια τίτλου/φορέα: 413/414/431· Τεκμηρίωση των μέγιστων επιτρεπόμενων τιμών.

4) Εργαλεία και οικοσύστημα

4. 1 OpenAPI

Spectral (JSON/YAML lint), Redocly linter, oas-diff/openapi-diff (semantic diff), schemathesis/dredd (έλεγχοι σε εξέλιξη).

4. 2 Protobuf/gRPC

buf (έλεγχος lint + θραύσης), protolint, γεννήτριες SDK· γνωστικό για ανάλυση.

4. 3 GraphQL

graphql-schema-linter, graphql-επιθεωρητής (breaking).

4. 4 Κωδικός Linters και SAST

ESLint, golangci-lint, Detekt/Ktlint, Pylint/Flake8, Semgrep (πρότυπα οσμής και ασφάλειας API).

5) Παραδείγματα κανόνων: Spectral/Redocly

5. 1 Φασματικό (παράδειγμα "φασματικό. yaml ')

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 ')

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: προφίλ buf

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 HTTP

• Αλλαγή τύπου πεδίου/υποχρεωτική
• Διαγραφή κατάστασης/διαδρομής/παραμέτρου
• στένωση enum/εύρους·
• αλλαγή του μορφοτύπου id (uuid → string).

• Προσθήκη προαιρετικών πεδίων
• Νέες καταστάσεις που δεν επηρεάζουν την ευχάριστη πορεία (για παράδειγμα, τεκμηριωμένη '422')
• επέκταση του enum.

7. 2 gRPC/Protobuf

Διαγραφή πεδίου χωρίς «περιορισμό »/επαναριθμηση - θραύση.
Αλλαγή τύπου (int32 → συμβολοσειρά) - θραύση.
Η προσθήκη μιας νέας ετικέτας ως προαιρετικής είναι συνήθως ασφαλής.

8) Σύνδεση συμβάσεων και κώδικα

1. Κωδικός σύμβασης: παραγωγή αποκόμματα SDK/διακομιστή, αρνητικά παραδείγματα δοκιμών.

2. Κωδικός σύμβασης: δοκιμές προδιαγραφών, αυτόματος έλεγχος κατάστασης/κεφαλίδων.

• απαγόρευση 'return 200' when 'error! = nil',
• υποχρεωτική «ταυτότητα-κλειδί» στις γραμμές πληρωμής με εγγραφή·
• συγκαλύπτοντας μάρκες σε κούτσουρα.

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'.
Πάντα 'ίχνος _ id'; ' Retry-After 'for 429/503.

Επαγρύπνηση

Μόνο δρομέας. Το max 'page _ size' είναι τεκμηριωμένο.

Ασφάλεια

Όλες οι πτητικές λειτουργίες - κατηγορία «ασφάλεια», περιγράφονται τα «πεδία».
No 'http:' links TLS 1. 2+.

Cache/idempotency

GET - 'ETag/Last-Modified', για εγγραφή - «Idempotency-Key» (κατά περίπτωση).

Τεκμηρίωση

«summary», «περιγραφή», παραδείγματα αιτήσεων/απαντήσεων (έγκυρα).

11) Παραδείγματα αυτοματοποιημένων ελέγχων

11. 1 Επαλήθευση των υποχρεωτικών κεφαλίδων ασφαλείας (Spectral)

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) Παρατηρησιμότητα των συμβάσεων ποιότητας

Μετρήσεις: μερίδιο των PR με σύνδεση σφαλμάτων, καθορισμός χρόνου, αριθμός προσπαθειών παραβίασης, «χρέη» σύμφωνα με τους κανόνες.
Dashboards: πρόοδος της μετανάστευσης στο ενοποιημένο σύστημα σφάλματος, κάλυψη με παραδείγματα, σταθερότητα έκδοσης.

13) Αντιπατερίδια

Το «Doc» ζει χωριστά από τον κώδικα → αποσυγχρονισμού. Κρατήστε το συμβόλαιο κοντά στην υπηρεσία και απελευθερώστε ένα εκδοθέν τεχνούργημα.
Linter μόνο με το χέρι. Χρειάζεστε μια σκληρή πύλη δημοσίων σχέσεων.
Τυχαία παραδείγματα (μη ντετερμινιστικά) - νιφάδες στους ελέγχους.
Δεν υπάρχουν αρνητικά παραδείγματα και κωδικοί σφάλματος.
Επανεφεύρεση του συστήματος σφάλματος για κάθε υπηρεσία.
Αγνοώντας τους ελέγχους θραύσης του Protobuf (αλλαγή ετικετών «με το μάτι»).

14) Ιδιαιτερότητες του iGaming/Finance

Νομισματικά πεδία - σταθερή κλίμακα/στρογγυλοποίηση· απαγόρευση επίπλευσης.
Υποχρεωτικές κεφαλίδες 'X-Tenant', 'X-Region' and trace 'traceparent'.
Χειριστήρια πληρωμής: έλεγχος για 'Idempotency-Key', 'Retry-After' και σωστή σημασιολογία 409/201.
Webhooks PSP/KYC: HMAC/mTLS περιγράφονται στο 'securitSchemes'. αντι-αναπαραγωγή ('X-Timestamp', παράθυρο).
Περιφερειακοί περιορισμοί και εντοπισμός σφαλμάτων ('Content-Language').

15) Κατάλογος ελέγχου ετοιμότητας Prod

• Τα προφίλ Spectral/Redocly είναι σχεδιασμένα και συνδεδεμένα σε προ-commit και PR-gate.
• Ενιαίο πρότυπο σφάλματος και καταστάσεις - δεσμευμένα και ελεγμένα.
• openapi-diff/επιθεωρητής GraphQL/buf - αλλαγές θραύσης μπλοκ.
• Τα παραδείγματα αιτήσεων/απαντήσεων είναι έγκυρα. τεκμηριωμένη σελιδοποίηση/φίλτρα.
• Συμπληρώνονται τα προγράμματα και τα πεδία εφαρμογής της SecuritySchemes. Δεν υπάρχουν σύνδεσμοι http.
• Για το Protobuf: «διατηρούνται» σε διαγραμμένες ετικέτες. νέα πεδία - προαιρετικά.
• Ενεργοποιημένα Semgrep/code linters· αποκρύπτοντας μυστικά σε κούτσουρα.
• Η ΚΚΠ δημοσιεύει συμβατικά αντικείμενα και αναφορές.
• Playbook: πώς να δράσετε όταν διακόπτετε-diffa (rollback, hotfix, ειδοποιήσεις σε integrators).

16) TL· DR

Εφαρμογή αυτόματης επένδυσης συμβάσεων (Spectral/Redocly, buf/GraphQL Inspector) και σημασιολογικού diff, καθορισμός ενιαίου συστήματος σφάλματος/κατάστασης/επισήμανσης/ασφάλειας, σύνδεση πύλης δημοσίων σχέσεων και δημοσίευση συμβάσεων ως τεχνουργήματα. Κάθε θραύση είναι φως πέδησης. Για χρήματα/πληρωμές - ειδικοί κανόνες (ταυτότητα, «Retry-After», HMAC/mTLS).