داربست — خودآموز MLOps و مهندسی سامانه‌های هوش مصنوعی (پیشرفته)

فصل ۲ از ۹

پیشرفت ترم
۰٪

در این فصل چه یاد می‌گیری#

یک تغییرِ کوچک و کاملاً منطقی در پاسخِ سرویس می‌دهیم: به‌جای یک برچسب، فهرستی از برچسب‌ها برمی‌گردانیم. سرویس سالم‌تر می‌شود، تست‌های خودمان سبزند، و هر ۴۰ تماسِ کلاینتِ پارسالی می‌شکند — با کدِ وضعیتِ ۲۰۰.

بعد همان تغییر را روی یک مسیرِ نسخه‌دار منتشر می‌کنیم و می‌شماریم: صفر شکسته. آخرِ فصل هم یک عددِ ناراحت‌کننده می‌گیریم: از ۸ درخواست، کلاینت روی ۴ تایشان مهلتش تمام شد و رفت — ولی سرور هر ۸ تا را تا آخر انجام داد.

دو رابطِ مکانیکی، یکی جفت و یکی نیم‌پله جابه‌جا

آخر این فصل می‌توانی:

  • قراردادِ یک API را بنویسی و بگویی چه چیزهایی باید داخلش باشد
  • تغییرِ سازگار را از تغییرِ شکننده تشخیص بدهی و با عدد نشانش بدهی
  • نسخه را در مسیر بگذاری و نسخهٔ قدیمی را با آبرو بازنشسته کنی
  • تستِ قرارداد بنویسی که قبل از استقرار قرمز شود

قبل از شروع#

از فصلِ ۱: artifact با کد و وزن و پیکربندیِ جدا. از ژرفا ترمِ ۶ فصلِ ۶: ThreadingHTTPServer، مسیرِ /healthz، اعتبارسنجی در مرز، و اینکه هرگز str(exception) را به کاربر ندهی.

آن فصل سرویس را ساخت. این فصل دربارهٔ چیزی است که آن فصل جا نداشت: قرارداد. یک سرویس فقط کد نیست؛ یک وعده به کسانی است که صدایش می‌زنند، و شکستنِ آن وعده گران‌تر از هر باگی است.

📓 نوت‌بوک: نوت‌بوک این فصل را در Colab باز کن — همهٔ کدهای این فصل آماده و به‌ترتیب داخلش هست.

اجرا زمانِ تقریبی
کلِ نوت‌بوک روی CPU حدودِ یک دقیقه
GPU لازم نیست

۱. سرویس، در یک سلول#

سرور را سریع می‌سازیم چون قبلاً ساخته‌ایش. سه مسیر دارد: /v1/predict، /v2/predict و یک مسیرِ بی‌نسخه به نامِ /predict که قرار است درسِ بخشِ ۳ باشد.

import json
import threading
import time
import urllib.error
import urllib.request
from http.server import BaseHTTPRequestHandler, ThreadingHTTPServer

model = fit_model(TRAIN[:800])
LABELS = sorted(model.classes_)
MODEL_VERSION = "1.0.0"
STATE = {"unversioned": "v1", "v1_confidence": False, "delay": 0.0,
         "finished": 0, "delivered": 0, "dropped": 0}


def classify(texts):
    proba = model.predict_proba([normalise(t) for t in texts])
    labels = list(model.classes_)
    return [(labels[int(r.argmax())], round(float(r.max()), 4)) for r in proba]


def read_texts(payload):
    """مهربان با ورودی: هم «text» تکی را می‌پذیرد هم «texts» فهرستی."""
    if "texts" in payload:
        texts = payload["texts"]
    elif "text" in payload:
        texts = [payload["text"]]
    else:
        raise ValueError("کلیدِ text یا texts لازم است")
    if not isinstance(texts, list) or not texts or len(texts) > 32:
        raise ValueError("texts باید فهرستی بینِ ۱ تا ۳۲ رشته باشد")
    if any(not isinstance(t, str) or not t.strip() for t in texts):
        raise ValueError("هر عضو باید رشتهٔ ناتهی باشد")
    return texts


def shape_v1(pairs):
    body = {"label": pairs[0][0], "model_version": MODEL_VERSION}
    if STATE["v1_confidence"]:
        body["confidence"] = pairs[0][1]
    return body


def shape_v2(pairs):
    return {"labels": [p[0] for p in pairs],
            "confidences": [p[1] for p in pairs],
            "model_version": MODEL_VERSION}


class Handler(BaseHTTPRequestHandler):
    def log_message(self, *args):
        pass

    def _send(self, code, payload, extra=()):
        body = json.dumps(payload, ensure_ascii=False).encode("utf-8")
        try:
            self.send_response(code)
            self.send_header("Content-Type", "application/json; charset=utf-8")
            self.send_header("Content-Length", str(len(body)))
            for key, value in extra:
                self.send_header(key, value)
            self.end_headers()
            self.wfile.write(body)
            STATE["delivered"] += 1
        except OSError:
            STATE["dropped"] += 1        # کلاینت قبل از رسیدنِ جواب رفته بود

    def do_GET(self):
        if self.path == "/healthz":
            self._send(200, {"ok": True, "model_version": MODEL_VERSION})
        else:
            self._send(404, {"error": "not found"})

    def do_POST(self):
        routes = {"/v1/predict": "v1", "/v2/predict": "v2",
                  "/predict": STATE["unversioned"]}
        if self.path not in routes:
            return self._send(404, {"error": "not found"})
        raw = self.rfile.read(int(self.headers.get("Content-Length", 0)))
        try:
            texts = read_texts(json.loads(raw))
        except (json.JSONDecodeError, ValueError) as error:
            return self._send(400, {"error": str(error)})
        time.sleep(STATE["delay"])
        pairs = classify(texts)
        STATE["finished"] += 1           # کار انجام شد — مستقل از اینکه کسی منتظرش باشد
        shape = routes[self.path]
        extra = [("Sunset", "Sat, 31 Jan 2032 00:00:00 GMT"),
                 ("Deprecation", "true")] if self.path == "/v1/predict" else []
        self._send(200, shape_v1(pairs) if shape == "v1" else shape_v2(pairs), extra)


class Server(ThreadingHTTPServer):
    def handle_error(self, request, client_address):
        pass                             # کلاینتی که رفته، خطای سرور نیست


server = Server(("127.0.0.1", 0), Handler)
threading.Thread(target=server.serve_forever, daemon=True).start()
BASE = f"http://127.0.0.1:{server.server_address[1]}"


def post(path, payload, timeout=10):
    request = urllib.request.Request(
        BASE + path, data=json.dumps(payload, ensure_ascii=False).encode("utf-8"),
        headers={"Content-Type": "application/json"})
    try:
        with urllib.request.urlopen(request, timeout=timeout) as response:
            return response.status, json.loads(response.read()), dict(response.headers)
    except urllib.error.HTTPError as error:
        return error.code, json.loads(error.read()), dict(error.headers)


print("سلامت:", json.loads(urllib.request.urlopen(BASE + "/healthz").read()))
print("v1   :", post("/v1/predict", {"text": "رمز عبورم را فراموش کردم"})[1])
print("v2   :", post("/v2/predict", {"texts": ["بسته به دستم نرسیده"]})[1])
print("خراب :", post("/v1/predict", {"wrong": 1})[:2])
سلامت: {'ok': True, 'model_version': '1.0.0'}
v1   : {'label': 'حساب کاربری', 'model_version': '1.0.0'}
v2   : {'labels': ['ارسال'], 'confidences': [0.5181], 'model_version': '1.0.0'}
خراب : (400, {'error': 'کلیدِ text یا texts لازم است'})

دو تصمیم که در ژرفا نبودند و اینجا کلیدی‌اند:

handle_error را خالی کرده‌ایم. وقتی کلاینت وسطِ کار می‌رود، نوشتنِ پاسخ خطا می‌دهد و کتابخانه به‌طورِ پیش‌فرض یک traceback چاپ می‌کند. این خطای سرور نیست و اگر با خطاهای واقعی قاطی شود، سیاههٔ تولید بی‌فایده می‌شود.

و STATE["finished"] قبل از ارسالِ پاسخ زیاد می‌شود. تفاوتش با delivered در بخشِ ۷ عددِ اصلیِ فصل را می‌دهد.

🔧 اگر کار نکرد: اگر سلولِ کلاینت را بدونِ سلولِ سرور اجرا کنی، این را می‌گیری: urllib.error.URLError: <urlopen error [WinError 10061] No connection could be made because the target machine actively refused it> — روی لینوکس و Colab همان با [Errno 111] Connection refused. یعنی هیچ‌کس پشتِ آن پورت نیست. در نوت‌بوک تقریباً همیشه یک دلیل دارد: Restart session زده‌ای و سلولِ سرور دوباره اجرا نشده. BASE را چاپ کن؛ اگر تعریف نشده باشد، جوابت را گرفته‌ای.

۲. قرارداد چیست#

قرارداد آن چیزی است که صدازننده حق دارد رویش حساب کند. اگر ننویسی‌اش، باز هم وجود دارد — فقط کسی نمی‌داند کجاست، و هر رفتارِ اتفاقیِ سرویس بخشی از آن می‌شود.

یک قراردادِ کمینه شش چیز می‌گوید:

  • ۱) شکلِ درخواست و اینکه کدام فیلد اجباری است
  • ۲) شکلِ پاسخ در حالتِ موفق، با نامِ دقیقِ هر کلید
  • ۳) کدهای وضعیت و معنایشان: ۴۰۰ یعنی «دوباره نفرست»، ۵۰۰ یعنی «بعداً بزن»
  • ۴) مهلتِ زمانی: صدازننده چقدر باید صبر کند
  • ۵) محدودیت‌ها: بیشترین اندازهٔ ورودی، بیشترین نرخِ درخواست
  • ۶) سیاستِ نسخه: چه تغییری بدونِ اطلاع می‌آید و چه تغییری نه

بندِ ششم همانی است که همه فراموشش می‌کنند و همان است که این فصل دربارهٔ آن است.

ولی قبلش، یک بار ببینیم این «قرارداد» روی سیم چه شکلی است. تا اینجا با post() کار کرده‌ایم که همه‌چیز را قایم می‌کند. یک درخواستِ HTTP در واقع فقط متن است — و دیدنِ یک بارش، شش بندِ بالا را از انتزاع درمی‌آورد:

import socket

PORT = server.server_address[1]
SKIP = ("Server:", "Date:")            # این دو خط روی هر ماشین و هر لحظه فرق دارند


def raw_exchange(path, payload):
    body = json.dumps(payload, ensure_ascii=False).encode("utf-8")
    head = (f"POST {path} HTTP/1.1\r\n"
            f"Host: 127.0.0.1:{PORT}\r\n"
            "Content-Type: application/json\r\n"
            f"Content-Length: {len(body)}\r\n\r\n").encode("utf-8")
    with socket.create_connection(("127.0.0.1", PORT), timeout=5) as sock:
        sock.sendall(head + body)
        sock.shutdown(socket.SHUT_WR)
        chunks = []
        while True:
            piece = sock.recv(4096)
            if not piece:
                break
            chunks.append(piece)
    return (head + body).decode("utf-8"), b"".join(chunks).decode("utf-8")


def show(title, raw):
    print(title)
    for line in raw.replace("\r\n", "\n").split("\n"):
        if not line.startswith(SKIP):
            print("   ", line.replace(f":{PORT}", ":<پورت>"))


sent, got = raw_exchange("/v1/predict", {"text": "بسته به دستم نرسیده"})
show("— بایت‌هایی که کلاینت می‌فرستد —", sent)
show("— بایت‌هایی که سرور برمی‌گرداند —", got)
_, missing = raw_exchange("/v9/predict", {"text": "بسته به دستم نرسیده"})
show("— همان درخواست، روی مسیری که وجود ندارد —", missing)
— بایت‌هایی که کلاینت می‌فرستد —
    POST /v1/predict HTTP/1.1
    Host: 127.0.0.1:<پورت>
    Content-Type: application/json
    Content-Length: 47
    
    {"text": "بسته به دستم نرسیده"}
— بایت‌هایی که سرور برمی‌گرداند —
    HTTP/1.0 200 OK
    Content-Type: application/json; charset=utf-8
    Content-Length: 49
    Sunset: Sat, 31 Jan 2032 00:00:00 GMT
    Deprecation: true
    
    {"label": "ارسال", "model_version": "1.0.0"}
— همان درخواست، روی مسیری که وجود ندارد —
    HTTP/1.0 404 Not Found
    Content-Type: application/json; charset=utf-8
    Content-Length: 22
    
    {"error": "not found"}

کلِ HTTP در این چند خط است، و هر تکه‌اش یکی از شش بندِ بالاست:

  • خطِ اول فعل و مسیر و نسخهٔ پروتکل: POST /v1/predict. نسخهٔ API همان v1 داخلِ مسیر است — بندِ ششم، به‌شکلِ چهار نویسه.
  • سرآیندها (Content-Type، Content-Length، Sunset) هرکدام نام: مقدار در یک خط‌اند. Content-Length تعدادِ بایت‌های بدنه است، نه تعدادِ نویسه‌ها — کلِ بدنه ۳۱ نویسه است و ۴۷ بایت: خودِ «بسته به دستم نرسیده» ۱۹ نویسه و ۳۵ بایت است، چون هر حرفِ فارسی در UTF-8 دو بایت می‌گیرد و فاصله یک بایت، و ۱۲ بایتِ دیگر مالِ کلید و علامت‌های JSON است.
  • یک خطِ خالی سرآیند را از بدنه جدا می‌کند. همین و بس.
  • خطِ اولِ پاسخ کدِ وضعیت است و معنایش بندِ سوم است: 200 یعنی «انجام شد»، 400 یعنی «درخواستت خراب است، همان را دوباره نفرست»، 404 یعنی «چنین مسیری ندارم»، و 503 یعنی «الان نمی‌توانم، بعداً بزن».

و به 404 دقت کن: پاسخِ سرور همان بدنهٔ JSON را دارد، فقط کدش فرق می‌کند. کلاینتی که کد را نخواند و مستقیم سراغِ JSON برود، یک KeyError می‌گیرد و فکر می‌کند مدل خراب است. کدِ وضعیت اولین چیزی است که باید بخوانی، نه آخرین.

۳. تغییری که بی‌صدا می‌شکند#

فرض کن تیم تصمیم می‌گیرد پاسخ را بهتر کند: به‌جای یک label، فهرستِ labels با میزانِ اطمینان. تغییرِ درستی هم هست. فقط روی مسیرِ بی‌نسخه اعمالش می‌کنیم.

SAMPLE = [r["text"] for r in TEST[:40]]


def old_client(path):
    """کلاینتی که پارسال نوشته شده و «label» را می‌خواند."""
    ok, broken, codes = 0, 0, set()
    for text in SAMPLE:
        status, body, _ = post(path, {"text": text})
        codes.add(status)
        try:
            _ = body["label"]
            ok += 1
        except KeyError:
            broken += 1
    return ok, broken, sorted(codes)


print("قبل از ارتقا  /predict   :", old_client("/predict"))
STATE["unversioned"] = "v2"                       # «فقط شکلِ پاسخ را بهتر کردیم»
print("بعد از ارتقا  /predict   :", old_client("/predict"))
print("بعد از ارتقا  /v1/predict:", old_client("/v1/predict"))
قبل از ارتقا  /predict   : (40, 0, [200])
بعد از ارتقا  /predict   : (0, 40, [200])
بعد از ارتقا  /v1/predict: (40, 0, [200])

چهل از چهل شکست — و هر چهل پاسخ کدِ ۲۰۰ داشت.

عددِ سوم در هر سه‌تایی مجموعهٔ کدهای وضعیت است و در هر سه حالت فقط 200 است. از دیدِ سرور هیچ اتفاقی نیفتاده: هیچ خطایی، هیچ لاگی، هیچ هشداری. خرابی در سمتِ کسی افتاده که کدش را تو نمی‌بینی.

و این بدترین شکلِ خرابی است، چون پایشِ خودت سبز می‌ماند. نرخِ خطای سرویس صفر است، /healthz جواب می‌دهد، و تلفن‌ها از جای دیگری زنگ می‌خورند.

ولی خطِ سوم نجاتِ ماجراست: همان لحظه، همان سرور، /v1/predict هنوز چهل از چهل را درست جواب می‌دهد. نسخه در مسیر یعنی همین: قراردادِ قدیمی نمی‌میرد، فقط قدیمی می‌شود.

۴. «اضافه کن، برندار»#

قاعده‌ای که کلِ سازگاریِ رو به عقب را در سه کلمه خلاصه می‌کند. حالا به v1 یک فیلدِ تازه اضافه کنیم و همان کلاینتِ قدیمی را دوباره بیندازیم رویش.

STATE["v1_confidence"] = True
print("v1 با فیلدِ تازه:", old_client("/v1/predict"))
print("پاسخِ تازهٔ v1  :", post("/v1/predict", {"text": SAMPLE[0]})[1])
v1 با فیلدِ تازه: (40, 0, [200])
پاسخِ تازهٔ v1  : {'label': 'حساب کاربری', 'model_version': '1.0.0', 'confidence': 0.9693}

صفر شکسته. کلاینتِ قدیمی confidence را نمی‌شناسد و کاملاً نادیده‌اش می‌گیرد؛ کلاینتِ تازه می‌تواند بخواندش.

سه دسته تغییر، با سه پیامدِ کاملاً متفاوت:

  • ۱) امن — اضافه کردنِ فیلد به پاسخ، اضافه کردنِ فیلدِ اختیاری به درخواست، مسیرِ تازه.
  • ۲) شکننده — تغییرِ نام، حذفِ فیلد، تغییرِ نوع (رشته به فهرست)، اجباری کردنِ فیلدی که اختیاری بود، تغییرِ کدِ وضعیت.
  • ۳) موذی — همان نام و همان نوع، ولی معنای متفاوت. مثلاً confidence که تا دیروز بینِ صفر و یک بود و امروز بینِ صفر و صد. هیچ تستی این را نمی‌گیرد مگر آنکه بازه بخشی از قرارداد باشد.

✅ چک کن: به فهرستِ کلیدهای پاسخِ سرویسِ خودت نگاه کن و از هرکدام بپرس: «اگر فردا نامش را عوض کنم، از کجا می‌فهمم چه کسی شکسته؟» اگر جوابت «از شکایتِ کاربر» است، قرارداد نداری. جوابِ درست یا تستِ قرارداد است (بخشِ ۶) یا نسخه در مسیر.

۵. بازنشستگیِ باآبرو#

نسخهٔ قدیمی را نمی‌شود یک‌شبه خاموش کرد، ولی نمی‌شود تا ابد هم نگه داشت. راهِ استاندارد این است که خودِ پاسخ بگوید «من قدیمی‌ام و تا این تاریخ زنده‌ام».

headers = post("/v1/predict", {"text": SAMPLE[0]})[2]
print("Deprecation:", headers.get("Deprecation"))
print("Sunset     :", headers.get("Sunset"))
Deprecation: true
Sunset     : Sat, 31 Jan 2032 00:00:00 GMT

Deprecation می‌گوید «دیگر توسعه نمی‌شود» و Sunset تاریخِ خاموشی را اعلام می‌کند. هر دو سربرگِ استانداردِ HTTP هستند، نه اختراعِ ما.

و فایدهٔ واقعی‌شان چیزی است که در سیاهه می‌بینی: حالا می‌توانی بشماری چند درخواست در روز هنوز به v1 می‌آید. بدونِ آن عدد، خاموش کردنِ یک نسخه یک قمار است.

۶. تستِ قرارداد، به‌عنوان دروازه#

تست‌های ترمِ ۱ می‌گفتند «کد درست کار می‌کند». تستِ قرارداد چیزِ دیگری می‌گوید: «شکلِ پاسخ همانی است که وعده داده‌ایم». این تست به هیچ‌کدام از توابعِ داخلی نگاه نمی‌کند؛ فقط سرویس را از بیرون صدا می‌زند.

def contract_tests(path):
    status, body, _ = post(path, {"text": SAMPLE[0]})
    bad_status, _, _ = post(path, {"wrong": 1})
    return [
        ("کدِ وضعیتِ ۲۰۰", status == 200),
        ("کلیدِ label هست", "label" in body),
        ("label رشته است", isinstance(body.get("label"), str)),
        ("label برچسبِ شناخته‌شده است", body.get("label") in LABELS),
        ("model_version هست", "model_version" in body),
        ("ورودیِ خراب کدِ ۴۰۰ می‌گیرد", bad_status == 400),
    ]


for path in ("/v1/predict", "/predict"):
    checks = contract_tests(path)
    passed = sum(1 for _, ok in checks if ok)
    print(f"{path:<14} {passed} از {len(checks)} سبز",
          "·", ", ".join(name for name, ok in checks if not ok) or "همه سبز")
/v1/predict    6 از 6 سبز · همه سبز
/predict       3 از 6 سبز · کلیدِ label هست, label رشته است, label برچسبِ شناخته‌شده است

سه تست قرمز، و هر سه دقیقاً همان چیزی را می‌گویند که چهل کلاینت با شکستنشان گفتند.

تفاوت این است که این سه تست قبل از استقرار قرمز می‌شوند، در حالی که آن چهل کلاینت بعدش می‌شکنند. ترمِ ۶ اسمِ این را «دروازهٔ خودکار» می‌گذارد؛ فعلاً همین‌قدر بدان که چنین تستی در همان مخزنِ سرویس زندگی می‌کند و مثلِ تست‌های ترمِ ۱ کدِ خروج می‌دهد.

📏 اندازه بگیر: با چه چیزی مقایسه شد؟ با همان سرور، همان مدل و همان چهل ورودی — تنها متغیر مسیر بود. روی کدام داده؟ چهل تیکتِ اولِ مجموعهٔ آزمون، یکسان در هر سه اندازه‌گیری. با چند seed؟ seed اینجا معنا ندارد و این خودش نکته است: شکستنِ قرارداد یک ویژگیِ قطعیِ کد است، نه یک اثرِ آماری. یا کلیدِ label در پاسخ هست یا نیست؛ چهل از چهل، هر بار، روی هر ماشینی.

۷. مهلتِ زمانی — و کاری که سرور بعدش می‌کند#

هر تماسِ شبکه‌ای بدونِ مهلت یعنی «تا ابد صبر می‌کنم». حالا سرویس را عمداً کند می‌کنیم و کلاینت را با مهلتِ کوتاه می‌فرستیم.

STATE.update(finished=0, delivered=0, dropped=0)
served, timed_out = 0, 0
for i in range(8):
    STATE["delay"] = 0.0 if i < 4 else 0.6       # تأخیرِ ساختگی، تا نتیجه قابلِ تکرار بماند
    try:
        post("/v1/predict", {"text": SAMPLE[i]}, timeout=0.2)
        served += 1
    except (TimeoutError, urllib.error.URLError):
        timed_out += 1
STATE["delay"] = 0.0
print(f"۸ درخواست با مهلتِ ۰٫۲ ثانیه: {served} موفق، {timed_out} مهلت‌تمام")
time.sleep(2.0)
print("کارهایی که سرور تا آخر انجام داد:", STATE["finished"])
print("پاسخ‌هایی که واقعاً تحویل شد   :", STATE["delivered"])
print("پاسخ‌هایی که به دیوار خورد     :", STATE["dropped"])
۸ درخواست با مهلتِ ۰٫۲ ثانیه: 4 موفق، 4 مهلت‌تمام
کارهایی که سرور تا آخر انجام داد: 8
پاسخ‌هایی که واقعاً تحویل شد   : 4
پاسخ‌هایی که به دیوار خورد     : 4

سرور هر هشت کار را کامل انجام داد. چهار تای آن‌ها را هیچ‌کس نمی‌خواست.

⚠️ مواظب باش: این تنها جدولِ فصل است که عددهایش تضمین‌شده نیستند و عمداً به‌عنوان خروجیِ تقریبی علامت خورده. سطرِ دوم — «سرور هر ۸ کار را تمام کرد» — قطعی است، چون شمارنده‌اش پیش از ارسالِ پاسخ بالا می‌رود. ولی تقسیمِ ۴ به ۴ در دو سطرِ آخر به سیستم‌عامل بستگی دارد: نوشتن روی اتصالی که طرفِ مقابل بسته، در بعضی سیستم‌ها همان بار اول خطا می‌دهد و در بعضی دیگر بی‌صدا در بافر می‌نشیند و خطا یک نوشتن بعدتر می‌آید. سطرِ اول هم به سرعتِ ماشین بند است: روی ماشینِ خیلی کند، حتی چهار درخواستِ بی‌تأخیر هم می‌توانند از مهلتِ ۰٫۲ ثانیه رد شوند. چیزی که همه‌جا برقرار است این است: سرور هر ۸ کار را تا آخر می‌برد، در حالی که فقط ۴ کلاینت هنوز منتظرش بوده‌اند — و همین نابرابری، کلِ حرفِ این بخش است.

مهلتِ کلاینت فقط تصمیمِ کلاینت است که دیگر صبر نکند. سرور خبر ندارد، کار را تمام می‌کند، حافظه و پردازنده‌اش را خرج می‌کند، و آخرش پاسخ را به یک اتصالِ بسته می‌نویسد.

و اینجاست که یک سرویسِ کند به یک سرویسِ مرده تبدیل می‌شود: کلاینت‌هایی که مهلتشان تمام می‌شود معمولاً دوباره تلاش می‌کنند، پس بارِ سرور بالا می‌رود، پس کندتر می‌شود، پس مهلت‌های بیشتری تمام می‌شود. این حلقه اسم دارد و فصلِ ۷ با یک قطع‌کنندهٔ مدار می‌شکندش.

سه چیزی که همین حالا می‌شود کرد: مهلت را در قرارداد بنویس تا صدازننده عددِ درست را بگذارد، مهلتِ خودِ سرور را هم بگذار تا کاری که از بودجه گذشته را رها کند، و پیش از شروعِ کارِ گران بررسی کن که اتصال هنوز باز است.

🤖 از دستیارت بپرس: «تفاوتِ connect timeout و read timeout چیست و چرا معمولاً باید دو عددِ متفاوت باشند؟» بعد این را بپرس: «اگر سه سرویس پشتِ سرِ هم صدا زده شوند و هرکدام مهلتِ ۵ ثانیه داشته باشند، بدترین زمانِ انتظارِ کاربر چقدر است؟» — جوابش یک ضربِ ساده است و همان دلیلِ وجودِ «بودجهٔ زمانی» که در طولِ زنجیره کم می‌شود، نه اینکه در هر گام از نو شروع شود.

واژه‌های تازهٔ این فصل#

کلمه تلفظ به حروف فارسی یعنی چه
API contract ای‌پی‌آی کانترکت وعده‌ای که سرویس دربارهٔ شکلِ درخواست و پاسخ می‌دهد
backward compatible بک‌وارد کامپتیبل تغییری که کلاینت‌های قدیمی را نمی‌شکند
breaking change بریکینگ چنج تغییری که قرارداد را می‌شکند و نسخهٔ تازه می‌خواهد
deprecation دپریکیشن اعلامِ اینکه یک نسخه دیگر توسعه نمی‌شود
sunset سان‌ست تاریخِ اعلام‌شدهٔ خاموش شدنِ یک نسخه
contract test کانترکت تست تستی که فقط شکلِ پاسخ را از بیرون بررسی می‌کند
timeout budget تایم‌اوت باجت سقفِ زمانی که یک صدازننده حاضر است صبر کند

تمرین‌ها

اول خودت فکر کن یا امتحان کن — بعد اینجا را باز کن.

در فصل بعد#

سرویسِ این فصل قرارداد دارد ولی هنوز هر کسی می‌تواند هر چند بار که بخواهد صدایش بزند، و بندِ پنجمِ قرارداد («بیشترین نرخِ درخواست») فقط روی کاغذ است. فصلِ بعد همین سرویس را پشتِ یک مرز می‌گذارد: کلید، محدودکنندهٔ نرخ و کدِ ۴۲۹. یک اسکریپتِ رهاشده را رویش می‌اندازیم و می‌شماریم: ۳۰ درخواستِ آن رد می‌شود و اپلیکیشنِ بی‌گناه صفر بار رد می‌شود.

به آخر این فصل رسیدی!

اگر ساختی و جواب داد، این دکمه مال توست.