# فصل ۰۲ — از تابع تا سرویس

<div dir="rtl">

# فصل ۰۲ — از تابع تا سرویس

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

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

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

![دو رابطِ مکانیکی، یکی جفت و یکی نیم‌پله جابه‌جا](/lesson-assets/t4-s02-service-design/prompt/01-image-two-couplings.png)

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

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

## قبل از شروع

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

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

> 📓 **نوت‌بوک:** [نوت‌بوک این فصل را در Colab باز کن](/notebooks/darbast/term-4-deployment/session-02-service-design.ipynb) — همهٔ کدهای این فصل آماده و به‌ترتیب داخلش هست.

</div>

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

<div dir="rtl">

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

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

</div>

```python
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])
```

```text
سلامت: {'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 لازم است'})
```

<div dir="rtl">

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

`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 در واقع فقط متن است** — و دیدنِ یک بارش، شش بندِ بالا را از انتزاع درمی‌آورد:

</div>

```python
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)
```

```text
— بایت‌هایی که کلاینت می‌فرستد —
    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"}
```

<div dir="rtl">

**کلِ 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` با میزانِ اطمینان. **تغییرِ درستی هم هست.** فقط روی مسیرِ بی‌نسخه اعمالش می‌کنیم.

</div>

```python
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"))
```

```text
قبل از ارتقا  /predict   : (40, 0, [200])
بعد از ارتقا  /predict   : (0, 40, [200])
بعد از ارتقا  /v1/predict: (40, 0, [200])
```

<div dir="rtl">

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

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

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

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

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

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

</div>

```python
STATE["v1_confidence"] = True
print("v1 با فیلدِ تازه:", old_client("/v1/predict"))
print("پاسخِ تازهٔ v1  :", post("/v1/predict", {"text": SAMPLE[0]})[1])
```

```text
v1 با فیلدِ تازه: (40, 0, [200])
پاسخِ تازهٔ v1  : {'label': 'حساب کاربری', 'model_version': '1.0.0', 'confidence': 0.9693}
```

<div dir="rtl">

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

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

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

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

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

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

</div>

```python
headers = post("/v1/predict", {"text": SAMPLE[0]})[2]
print("Deprecation:", headers.get("Deprecation"))
print("Sunset     :", headers.get("Sunset"))
```

```text
Deprecation: true
Sunset     : Sat, 31 Jan 2032 00:00:00 GMT
```

<div dir="rtl">

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

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

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

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

</div>

```python
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 "همه سبز")
```

```text
/v1/predict    6 از 6 سبز · همه سبز
/predict       3 از 6 سبز · کلیدِ label هست, label رشته است, label برچسبِ شناخته‌شده است
```

<div dir="rtl">

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

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

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

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

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

</div>

```python
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"])
```

```text-approx
۸ درخواست با مهلتِ ۰٫۲ ثانیه: 4 موفق، 4 مهلت‌تمام
کارهایی که سرور تا آخر انجام داد: 8
پاسخ‌هایی که واقعاً تحویل شد   : 4
پاسخ‌هایی که به دیوار خورد     : 4
```

<div dir="rtl">

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

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

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

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

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

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

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

</div>

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

<div dir="rtl">

## تمرین‌ها

قبل از تمرین، بدونِ نگاه به بالا جواب بده: چرا شکستنِ کلاینت با کدِ ۲۰۰ خطرناک‌تر از شکستن با کدِ ۵۰۰ است؟

**تمرینِ اجباری:** یک `v3` اضافه کن که به‌جای `confidences` یک فیلدِ `scores` با **درصد** (بینِ صفر و صد) برمی‌گرداند — یعنی همان تغییرِ «موذی» بخشِ ۴، این بار به‌شکلِ درست انجام‌شده. حالا **سه عدد** بده: تستِ قراردادِ `v1` روی `v3` چند از شش سبز می‌شود، همان تست وقتی `v3` را روی مسیرِ بی‌نسخه بگذاری چند، و اگر فقط نامِ فیلد را عوض کنی و بازه را دست نزنی چند. **بعد جواب بده: کدام‌یک از این سه تغییر را تستِ قرارداد نمی‌گیرد و چرا؟**

**تمرینِ ستاره‌دار ⭐:** به سرور یک **مهلتِ سمتِ خودش** بده: اگر کار از بودجه گذشت، کدِ ۵۰۳ با سربرگِ `Retry-After` برگردان به‌جای اینکه تا آخر ادامه بدهی. بعد **اثبات کن که کار کرده**، با همان دو شمارنده: تعدادِ کارهایی که سرور تا آخر رفت باید **کم** شود، نه فقط تعدادِ پاسخ‌های موفق. **و بعد سؤالِ سخت را جواب بده: در سرویسِ ما «رها کردنِ کار» واقعاً ممکن نیست، چون `predict` یک فراخوانیِ اتمی است. چه چیزی در معماری باید عوض شود تا رها کردن ممکن شود؟** — جوابت موضوعِ فصلِ ۴ است.

## در فصل بعد

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

</div>

---
Source: https://yaadestan.com/courses/darbast/lessons/t4/s02-service-design (یادستان, Yaadestan)
