ਸਪਸ਼ਟ, ਇੱਕਸਾਰ ਜਵਾਬਾਂ ਲਈ Go API ਗਲਤੀ ਹੈਂਡਲਿੰਗ ਪੈਟਰਨ

ਜਦੋਂ API ਦੀਆਂ ਗਲਤੀਆਂ ਅਸਮਰੂਪ ਹੁੰਦੀਆਂ ਹਨ ਤਾਂ ਕਲਾਇੰਟ ਨਾਰਾਜ਼ ਹੋ ਜਾਂਦੇ ਹਨ

ਜਦੋਂ ਹਰ ਏਂਡਪੌਇੰਟ ਫੇਲ੍ਹਰ ਨੂੰ ਵੱਖਰੇ ਢੰਗ ਨਾਲ ਰਿਪੋਰਟ ਕਰਦਾ ਹੈ, ਤਾਂ ਕਲਾਇੰਟ ਤੁਹਾਡੇ API 'ਤੇ ਭਰੋਸਾ ਕਰਨਾ ਬੰਦ ਕਰ ਦਿੰਦੇ ਹਨ। ਇੱਕ ਰੂਟ { "error": "not found" } ਰਿਟਰਨ ਕਰਦਾ ਹੈ, ਦੂਜਾ { "message": "missing" }, ਅਤੇ ਤੀਜਾ ਸਧਾਰਨ ਟੈਕਸਟ ਭੇਜਦਾ ਹੈ। ਭਾਵੇਂ ਮਾਇਨੇ ਨੇੜੇ-ਨੇੜੇ ਹੋ ਸਕਦਾ ਹੈ, ਪਰ ਹੁਣ ਕਲਾਇੰਟ ਕੋਡ ਨੂੰ ਅਨੁਮਾਨ ਲਗਾਉਣਾ ਪੈ ਜਾਂਦਾ ਹੈ ਕਿ ਕੀ ਹੋਇਆ।

ਲਾਗਤ ਜਲਦੀ ਨਜ਼ਰ ਆਉਂਦੀ ਹੈ। ਟੀਮਾਂ ਨਾਜ਼ੁਕ ਪਾਰਸਿੰਗ ਲੌਜਿਕ ਬਣਾਉਂਦੀਆਂ ਹਨ ਅਤੇ ਹਰ ਏਂਡਪੌਇੰਟ ਲਈ ਅਲੱਗ-ਅਲੱਗ ਖਾਸ ਮਾਮਲੇ ਜੋੜਦੇ ਹਨ। ਰਿਟ੍ਰਾਈਜ਼ ਖਤਰਨਾਕ ਹੋ ਜਾਂਦੇ ਹਨ ਕਿਉਂਕਿ ਕਲਾਇੰਟ ਨਹੀਂ ਦੱਸ ਸਕਦਾ ਕਿ "ਬਾਅਦ ਵਿੱਚ ਮੁੜ ਕੋਸ਼ਿਸ਼ ਕਰੋ" ਜਾਂ "ਤੁਹਾਡੇ ਇਨਪੁੱਟ ਵਿੱਚ ਗਲਤੀ ਹੈ"। ਸਹਾਇਤਾ ਟਿਕਟ ਵਧਦੇ ਹਨ ਕਿਉਂਕਿ ਕਲਾਇੰਟ ਸਿਰਫ ਇੱਕ ਧੁੰਦਲੀ ਸੁਨੇਹਾ ਵੇਖਦਾ ਹੈ, ਅਤੇ ਤੁਹਾਡੀ ਟੀਮ ਆਸਾਨੀ ਨਾਲ ਉਸਨੂੰ ਸਰਵਰ-ਸਾਈਡ ਲੌਗ ਲਾਈਨ ਨਾਲ ਮੇਲ ਨਹੀਂ ਕਰ ਸਕਦੀ।

ਇੱਕ ਆਮ ਦ੍ਰਿਸ਼: ਇੱਕ ਮੋਬਾਈਲ ਐਪ ਸਾਈਨਅਪ ਦੌਰਾਨ ਤਿੰਨ ਏਂਡਪੌਇੰਟਾਂ ਨੂੰ ਕਾਲ ਕਰਦਾ ਹੈ। ਪਹਿਲਾ HTTP 400 ਨਾਲ ਫੀਲਡ-ਲੇਵਲ ਐਰਰ ਮੈਪ ਰਿਟਰਨ ਕਰਦਾ ਹੈ, ਦੂਜਾ HTTP 500 ਨਾਲ ਇੱਕ ਸਟੈਕ ਟਰੇਸ ਸਟਰਿੰਗ ਭੇਜਦਾ ਹੈ, ਅਤੇ ਤੀਜਾ HTTP 200 ਨਾਲ { "ok": false } ਰਿਟਰਨ ਕਰਦਾ ਹੈ। ਐਪ ਟੀਮ ਤਿੰਨ ਵੱਖਰੇ ਐਰਰ ਹੈਂਡਲਰ ਭੇਜਦੀ ਹੈ, ਅਤੇ ਤੁਹਾਡੀ ਬੈਕਏਂਡ ਟੀਮ ਨੂੰ ਅਜੇ ਵੀ ਅਜਿਹੇ ਰਿਪੋਰਟ ਮਿਲਦੇ ਹਨ: “signup ਕਦੇ-ਕਦੇ fail ਹੁੰਦੀ ਹੈ” ਬਿਨਾਂ ਕਿਸੇ ਸਪੱਸ਼ਟ ਨਿਸ਼ਾਨੇ ਦੇ।

ਹਦਾਫ਼ ਇੱਕ ਅੰਦਾਜ਼ਾ-ਸੁਧਾਰਿਤ ਕਾਂਟ੍ਰੈਕਟ ਹੈ। ਕਲਾਇੰਟਾਂ ਨੂੰ ਭਰੋਸੇਯੋਗ ਤਰੀਕੇ ਨਾਲ ਪਤਾ ਲੱਗਣਾ ਚਾਹੀਦਾ ਹੈ ਕਿ ਕੀ ਹੋਇਆ, ਕੀ ਇਹ ਉਨ੍ਹਾਂ ਦੀ ਗਲਤੀ ਹੈ ਜਾਂ ਤੁਹਾਡੀ, ਕੀ ਮੁੜ ਕੋਸ਼ਿਸ਼ ਕਰਨ ਯੋਗ ਹੈ, ਅਤੇ ਇੱਕ request ID ਜਿਸਨੂੰ ਉਹ ਸਪੋਰਟ ਵਿੱਚ ਪੇਸਟ ਕਰ ਸਕਣ।

ਵਿਆਪਕ ਨੋਟ: ਇਹ JSON HTTP APIs (gRPC ਨਹੀਂ) 'ਤੇ ਧਿਆਨ ਕੇਂਦ੍ਰਿਤ ਕਰਦਾ ਹੈ, ਪਰ ਉਹੀ ਵਿਚਾਰ ਉਹਨਾਂ ਹਰ ਥਾਂ ਲਾਗੂ ਹੁੰਦੇ ਹਨ ਜਿੱਥੇ ਤੁਸੀਂ ਦੂਜੇ ਸਿਸਟਮਾਂ ਨੂੰ ਗਲਤੀਆਂ ਵਾਪਸ ਭੇਜਦੇ ਹੋ।

ਇੱਕ ਸਾਦਾ ਲਕ਼ਸ਼: ਹਰ ਏਂਡਪੌਇੰਟ ਇੱਕੋ ਕਾਂਟ੍ਰੈਕਟ ਮੰਨੇ

ਇੱਕ ਸਾਫ਼ ਕਾਂਟ੍ਰੈਕਟ ਚੁਣੋ ਅਤੇ ਹਰ ਏਂਡਪੌਇੰਟ ਨੂੰ ਉਸ ਦੀ ਪਾਲਣਾ ਕਰਵਾਓ। “Consistency” ਦਾ ਮਤਲਬ ਹੈ ਇੱਕੋ JSON ਆਕਾਰ, ਫੀਲਡਾਂ ਦੇ ਇੱਕੋ ਹੀ ਮਾਇਨੇ ਅਤੇ ਇੱਕੋ ਹੀ ਵਿਵਹਾਰ ਭਾਵੇ ਕਿਸੇ ਵੀ ਹੈਂਡਲਰ ਤੋਂ ਗਲਤੀ ਆਵੇ। ਜਦੋਂ ਤੁਸੀਂ ਇਹ ਕਰੋਗੇ, ਤਾਂ ਕਲਾਇੰਟਾਂ ਨੂੰ ਅਨੁਮਾਨ ਲਗਾਉਣਾ ਬੰਦ ਹੋ ਜਾਵੇਗਾ ਅਤੇ ਉਹ ਗਲਤੀਆਂ ਨੂੰ ਸਹੀ ਤਰੀਕੇ ਨਾਲ ਹੇਠਾਂ ਲੈ ਸਕਣਗੇ।

ਇੱਕ ਉਪਯੋਗੀ ਕਾਂਟ੍ਰੈਕਟ ਕਲਾਇੰਟ ਨੂੰ ਫੈਸਲਾ ਕਰਨ ਵਿੱਚ ਮਦਦ ਕਰਦਾ ਹੈ ਕਿ ਅਗਲਾ ਕਦਮ ਕੀ ਹੋਵੇ। ਜ਼ਿਆਦਾਤਰ ਐਪਸ ਲਈ, ਹਰ ਗਲਤੀ ਰਿਸਪਾਂਸ ਨੇ ਤਿੰਨ ਸਵਾਲਾਂ ਦਾ ਜਵਾਬ ਦੇਣਾ ਚਾਹੀਦਾ ਹੈ:

• ਕੀ ਮੈਂ ਆਪਣਾ ਇਨਪੁੱਟ ਠੀਕ ਕਰ ਸਕਦਾ/ਸਕਦੀ ਹਾਂ?
• ਕੀ ਮੈਂ ਬਾਅਦ ਵਿੱਚ ਮੁੜ ਕੋਸ਼ਿਸ਼ ਕਰਾਂ?
• ਕੀ ਮੈਨੂੰ ਸਪੋਰਟ ਨੂੰ ਸੰਪਰਕ ਕਰਨ ਦੀ ਲੋੜ ਹੈ?

ਇੱਕ ਪ੍ਰਯੋਗੀ ਨਿਯਮਾਂ ਦਾ ਸੈੱਟ:

• ਸਾਰੀਆਂ ਗਲਤੀਆਂ ਲਈ ਇੱਕੋ ਜਿਹਾ ਰਿਸਪਾਂਸ ਸਕੀਮਾ।
• ਇੱਕੋ ਸਟੇਟਸ-ਕੋਡ ਨੀਤੀ (ਇਕੋ ਗਲਤੀ ਕਿਸਮ ਸਦਾ ਇੱਕੋ HTTP ਸਟੇਟਸ ਨਾਲ ਨਕਸ਼ਾ ਹੋਵੇ)।
• ਇੱਕੋ ਸੁਰੱਖਿਅਤ ਸੁਨੇਹਾ ਨੀਤੀ (ਉਪਭੋਗਤਾ ਲਈ ਕੀ ਦਿਖੇ ਤੇ ਕੀ ਅੰਦਰੂਨੀ ਰੱਖਿਆ ਜਾਵੇ)।
• ਇੱਕੋ ਕੋਰੇਲੇਸ਼ਨ ਹੁੱਕ (ਇੱਕ request ID ਜੋ ਸਹਾਇਤਾ ਲਈ ਮਿਲੇ)।

ਅਗਾਂਹ ਫੈਸਲਾ ਕਰੋ ਕਿ ਰਿਸਪਾਂਸ ਵਿੱਚ ਕਿਹੜੀਆਂ ਚੀਜ਼ਾਂ ਕਦੇ ਨਹੀਂ ਦਿਖਣੀਆਂ ਚਾਹੀਦੀਆਂ। ਆਮ “ਨੈਵਰ” ਆਈਟਮਾਂ ਵਿੱਚ SQL ਟੁਕੜੇ, ਸਟੈਕ ਟਰੇਸ, ਅੰਦਰੂਨੀ ਹੋਸਟਨੇਮ, ਸੀਕ੍ਰੇਟਸ ਅਤੇ ਡਿਪੈਂਡੈਂਸੀਜ਼ ਤੋਂ ਆਏ ਕੱਚੇ ਐਰਰ ਸਟਰਿੰਗ ਸ਼ਾਮਲ ਹੋ ਸਕਦੇ ਹਨ।

ਇੱਕ ਸਾਫ਼ ਵੰਡ ਰੱਖੋ: ਇੱਕ ਛੋਟਾ ਉਪਭੋਗਤਾ-ਚਿਹਰਾਵਾ ਸੁਨੇਹਾ (ਸੁਰੱਖਿਅਤ, ਨਮਰ, ਕਾਰਵਾਈਯੋਗ) ਅਤੇ ਅੰਦਰੂਨੀ ਵੇਰਵੇ (ਪੂਰਾ ਐਰਰ, ਸਟੈਕ, ਸੰਦਰਭ) ਸਿਰਫ ਲੌਗਜ਼ ਵਿੱਚ। ਉਦਾਹਰਣ ਲਈ, “ਤੁਹਾਡੇ ਬਦਲਾਅ ਸੇਵ ਨਹੀਂ ਹੋ ਸਕੇ। ਕ੍ਰਿਪਾ ਕਰਕੇ ਮੁੜ ਕੋਸ਼ਿਸ਼ ਕਰੋ।” ਸੁਰੱਖਿਅਤ ਹੈ। “pq: duplicate key value violates unique constraint users_email_key” ਸੁਰੱਖਿਅਤ ਨਹੀਂ।

ਜਦੋਂ ਹਰ ਏਂਡਪੌਇੰਟ ਇੱਕੋ ਕਾਂਟ੍ਰੈਕਟ ਫਾਲੋ ਕਰਦਾ ਹੈ, ਤਾਂ ਕਲਾਇੰਟ ਇੱਕੋ ਐਰਰ ਹੈਂਡਲਰ ਬਣਾ ਕੇ ਸਾਰਿਆਂ ਥਾਂ ਰੀਯੂਜ਼ ਕਰ ਸਕਦਾ ਹੈ।

ਇੱਕ ਐਰਰ ਰਿਸਪਾਂਸ ਸਕੀਮਾ ਪਰਿਭਾਸ਼ਿਤ ਕਰੋ ਜਿਸ 'ਤੇ ਕਲਾਇੰਟ ਭਰੋਸਾ ਕਰ ਸਕਣ

ਕਲਾਇੰਟ ਸਿਰਫ ਉਦੋਂ ਹੀ ਗਲਤੀਆਂ ਠੀਕ ਤਰੀਕੇ ਨਾਲ ਹੇਠਾਂ ਲੈ ਸਕਦੇ ਹਨ ਜਦੋਂ ਹਰ ਏਂਡਪੌਇੰਟ ਇੱਕੋ ਆਕਾਰ ਵਿੱਚ ਜਵਾਬ ਦੇਵੇ। ਇੱਕ JSON ਐਨਵਲਪ ਚੁਣੋ ਅਤੇ ਉਸਨੂੰ ਸਥਿਰ ਰੱਖੋ।

ਇੱਕ ਪ੍ਰਯੋਗੀ ਡਿਫੌਲਟ error ਆਬਜੈਕਟ ਅਤੇ ਉੱਪਰਲੇ ਸਤਰ request_id ਹੈ:

{
  "error": {
    "code": "VALIDATION_FAILED",
    "message": "Some fields are invalid.",
    "details": {
      "fields": {
        "email": "must be a valid email address"
      }
    }
  },
  "request_id": "req_01HV..."
}

HTTP ਸਟੇਟਸ ਵਿਆਪਕ ਵਰਗੀਕਰਨ ਦਿੰਦਾ ਹੈ (400, 401, 409, 500). ਮਸ਼ੀਨ-ਪੜ੍ਹਨਯੋਗ error.code ਵਿਸ਼ੇਸ਼ ਸਥਿਤੀ ਦੱਸਦਾ ਹੈ ਜਿਸ 'ਤੇ ਕਲਾਇੰਟ ਸ਼ਾਖਾ ਬਣਾ ਸਕਦਾ ਹੈ। ਇਹ ਵੰਡ ਮਹੱਤਵਪੂਰਨ ਹੈ ਕਿਉਂਕਿ ਕਈ ਵੱਖਰੇ ਸਮੱਸਿਆਵਾਂ ਇੱਕੋ ਸਟੇਟਸ ਸਾਂਝੀਆਂ ਕਰ ਸਕਦੀਆਂ ਹਨ। ਇੱਕ ਮੋਬਾਈਲ ਐਪ EMAIL_TAKEN ਅਤੇ WEAK_PASSWORD ਲਈ ਵੱਖਰੇ UI ਦਿਖਾ ਸਕਦੀ ਹੈ ਭਾਵੇਂ ਦੋਹਾਂ 400 ਹੋਣ।

error.message ਨੂੰ ਸੁਰੱਖਿਅਤ ਅਤੇ ਮਨੁੱਖ-ਉਪਯੋਗੀ ਰੱਖੋ। ਇਹ ਉਪਭੋਗਤਾ ਦੀ ਮਦਦ ਕਰੇ ਪਰ ਕਦੇ ਵੀ ਅੰਦਰੂਨੀ ਜਾਣਕਾਰੀ ਨਾ ਲੀਕ ਕਰੇ (SQL, ਸਟੈਕ ਟਰੇਸ, ਪ੍ਰੋਵਾਈਡਰ ਨਾਮ, ਫਾਇਲ ਪਾਥ)।

ਚੋਣੀਯਾ ਫੀਲਡ ਜਦੋਂ ਉਹ ਪੇਸ਼ਗੀ ਅਨੁਮਾਨਯੋਗ ਰਹਿਣ ਤਾਂ ਉਪਯੋਗੀ ਹੁੰਦੀਆਂ ਹਨ:

• Validation errors: details.fields ਜਿਸ ਵਿੱਚ ਫੀਲਡ-ਟੂ-ਮੇਸੇਜ ਮੈਪ।
• ਰੇਟ ਲਿਮਿਟ ਜਾਂ ਅਸਥਾਈ ਸਮੱਸਿਆਵਾਂ: details.retry_after_seconds.
• ਵਾਧੂ ਮਦਦ: details.docs_hint ਸਾਦਾ ਟੈਕਸਟ ਹੋਵੇ (URL ਨਹੀਂ)।

ਬੈਕਵਰਡ ਕੰਪੈਟਬਿਲਿਟੀ ਲਈ, error.code ਮੁਲਾਂਕਣ ਨੂੰ ਤੁਹਾਡੇ API ਕਾਂਟ੍ਰੈਕਟ ਦਾ ਹਿੱਸਾ ਮੰਨੋ। ਨਵੇਂ ਕੋਡ ਜੋੜੋ ਬਿਨਾਂ ਪੁਰਾਣੀਆਂ ਮੀਨਿੰਗਾਂ ਬਦਲੇ। ਸਿਰਫ ਚੋਣੀਯਾ ਫੀਲਡ ਜੋੜੋ ਅਤੇ ਮੰਨੋ ਕਿ ਕਲਾਇੰਟ ਉਹਨਾਂ ਫੀਲਡਾਂ ਨੂੰ ਅਣਜਾਣ ਕਰ ਦੇਣਗੇ।

Go ਵਿੱਚ ਟਾਈਪ ਕੀਤੀਆਂ ਗਲਤੀਆਂ: ਤੁਹਾਡੇ ਹੈਂਡਲਰਾਂ ਲਈ ਸਾਫ ਮਾਡਲ

ਹੈੰਡਲਿੰਗ ਗਲਤੀਆਂ ਗੜਬੜ ਹੁੰਦੀ ਹੈ ਜਦੋਂ ਹਰ ਹੈਂਡਲਰ ਆਪਣਾ ਹੀ ਢੰਗ ਬਣਾਉਂਦਾ ਹੈ। ਇੱਕ ਛੋਟਾ ਸੈੱਟ ਟਾਈਪਡ ਐਰਰ ਇਹ ਦੂਰ ਕਰ ਦਿੰਦਾ ਹੈ: ਹੈਂਡਲਰ ਜਾਣੇ-ਪਛਾਣੇ ਐਰਰ ਕਿਸਮਾਂ ਰਿਟਰਨ ਕਰਨ, ਅਤੇ ਇੱਕ ਰਿਸਪਾਂਸ ਲੇਅਰ ਉਹਨਾਂ ਨੂੰ ਇੱਕਸਾਰ ਰਿਸਪਾਂਸ ਵਿੱਚ ਬਣਾਉਂਦੀ ਹੈ।

ਇੱਕ ਪ੍ਰਯੋਗੀ ਸ਼ੁਰੂਆਤੀ ਸੈੱਟ ਜ਼ਿਆਦਾਤਰ ਏਂਡਪੌਇੰਟਾਂ ਨੂੰ ਢੱਕਦਾ ਹੈ:

• ValidationError (ਖਰਾਬ ਇਨਪੁੱਟ)
• NotFoundError (ਰਿਸੋర్స ਮੌਜੂਦ ਨਹੀਂ)
• ConflictError (ਯੂਨੀਕ ਕੰਸਟਰੇਨਟ, ਸਟੇਟ ਮੇਲ ਨਹੀਂ ਖਾਂਦਾ)
• UnauthorizedError (ਲੌਗਿਨ ਨਹੀਂ/ਅਥਾਰਟੀ ਨਹੀਂ)
• InternalError (ਬਾਕੀ ਸਾਰਾ)

ਮੁੱਖ ਗੱਲ ਇਹ ਹੈ ਕਿ ਊਪਰਲੇ ਸਤਰ 'ਤੇ ਸਥਿਰਤਾ ਰਹੇ, ਭਾਵੇਂ ਰੂਟ ਕਾਰਨ ਬਦਲੇ। ਤੁਸੀਂ ਨੀਚਲੇ-ਪੱਧਰ ਦੇ ਐਰਰ (SQL, ਨੈਟਵਰਕ, JSON ਪਾਰਸਿੰਗ) ਨੂੰ רੈਪ ਕਰ ਸਕਦੇ ਹੋ ਪਰ ਫਿਰ ਵੀ ਉਹੀ ਪਬਲਿਕ ਟਾਈਪ ਰਿਟਰਨ ਕਰੋ ਜਿਸਨੂੰ middleware ਪਛਾਣ ਸਕੇ।

type NotFoundError struct {
	Resource string
	ID       string
	Err      error // private cause
}

func (e NotFoundError) Error() string { return "not found" }
func (e NotFoundError) Unwrap() error { return e.Err }

ਆਪਣੇ ਹੈਂਡਲਰ ਵਿੱਚ, sql.ErrNoRows ਨੂੰ ਸਿੱਧਾ ਲੀਕ ਕਰਨ ਦੀ ਬਜਾਏ NotFoundError{Resource: "user", ID: id, Err: err} ਰਿਟਰਨ ਕਰੋ।

ਐਰਰ چੈੱਕ ਕਰਨ ਲਈ errors.As ਨੂੰ ਤਰਜੀਹ ਦਿਓ ਜੇ ਤੁਹਾਨੂੰ ਕਸਟਮ ਟਾਈਪਾਂ ਦੀ ਜਾਂਚ ਕਰਨੀ ਹੋਵੇ ਅਤੇ errors.Is ਸੈਂਟਿਨਲ ਐਰਰਾਂ ਲਈ। ਸਧਾਰਨ ਮਾਮਲਿਆਂ ਲਈ ਸੈਂਟਿਨਲ ਐਰਰ (ਉਦਾਹਰਣ: var ErrUnauthorized = errors.New("unauthorized")) ਠੀਕ ਹਨ ਪਰ ਜਦੋਂ ਤੁਹਾਨੂੰ ਸੁਰੱਖਿਅਤ ਸੰਦਰਭ ਚਾਹੀਦਾ ਹੈ (ਜਿਵੇਂ ਕਿਹੜਾ ਰਿਸੋурс ਗਾਇਬ ਸੀ) ਤਾਂ ਕਸਟਮ ਟਾਈਪ ਜਿੱਤਦੇ ਹਨ।

ਜੋ ਤੁਸੀਂ ਜੁੜਦੇ ਹੋ ਉਸ ਬਾਰੇ ਕੜੀ ਹੋਵੋ:

• ਪਬਲਿਕ (ਕਲਾਇੰਟਾਂ ਲਈ ਸੁਰੱਖਿਅਤ): ਇੱਕ ਛੋਟਾ ਸੁਨੇਹਾ, ਇੱਕ ਸਥਿਰ ਕੋਡ, ਕਦੇ-ਕਦੇ ਵੈਲਿਡੇਸ਼ਨ ਲਈ ਫੀਲਡ ਨਾਮ।
• ਪ੍ਰਾਈਵੇਟ (ਸਿਰਫ ਲੌਗਜ਼): ਅੰਡਰਲਾਈਂ Err, ਸਟੈਕ ਜਾਣਕਾਰੀ, ਕੱਚੇ SQL ਐਰਰ, ਟੋਕਨ, ਉਪਭੋਗਤਾ ਡੇਟਾ।

ਇਹ ਵੰਡ ਤੁਹਾਨੂੰ ਗਾਹਕਾਂ ਦੀ ਮਦਦ ਕਰਨ ਦਿੰਦੀ ਹੈ ਬਿਨਾਂ ਅੰਦਰੂਨੀ ਜਾਣਕਾਰੀ ਪ੍ਰਗਟ ਕੀਤੇ।

ਐਰਰ ਕਿਸਮਾਂ ਨੂੰ HTTP ਸਟੇਟਸ ਕੋਡ ਨਾਲ ਇੱਕਸਾਰ ਨਕਸ਼ਾ ਕਰੋ

ਜਦੋਂ ਤੁਸੀਂ ਟਾਈਪਡ ਐਰਰ ਰੱਖ ਲਏ, ਅਗਲਾ ਕੰਮ ਨਿਰੰਤਰਤਾ ਨਾਲ ਇਹ ਯਕੀਨੀ ਬਣਾਉਣਾ ਹੈ: ਇੱਕੋ ਐਰਰ ਟਾਈਪ ਹਮੇਸ਼ਾਂ ਇੱਕੋ HTTP ਸਟੇਟਸ ਦੇਣਾ ਚਾਹੀਦਾ ਹੈ। ਕਲਾਇੰਟ ਇਸ 'ਤੇ ਨਿਰਭਰ ਲਾਜਿਕ ਬਣਾਉਂਦੇ ਹਨ।

ਜ਼ਿਆਦਾਤਰ APIs ਲਈ ਇੱਕ ਪ੍ਰਯੋਗੀ ਨਕਸ਼ਾ:

ਦੋ ਵੰਡਾਂ ਜੋ ਬਹੁਤ ਗਲਤਫ਼ਹਮੀਆਂ ਰੋਕਦੀਆਂ ਹਨ:

• 400 ਬਨਾਮ 422: 400 ਉੱਥੇ ਵਰਤੋ ਜਦੋਂ ਤੁਸੀਂ ਰਿਕਵੈਸਟ ਨੂੰ ਭਰੋਸੇਯੋਗ ਤਰੀਕੇ ਨਾਲ ਸਮਝ ਨਹੀਂ ਸਕਦੇ (ਖਰਾਬ JSON, ਗਲਤ ਕਿਸਮਾਂ). 422 ਵਰਤੋ ਜਦੋਂ ਤੁਸੀਂ ਇਸਨੂੰ ਪਾਰਸ ਕਰ ਸਕਦੇ ਹੋ ਪਰ ਮੁੱਲ ਮਨਜ਼ੂਰਯੋਗ ਨਹੀਂ ਹਨ।
• 409 ਬਨਾਮ 422: 422 ਫੀਲਡ-ਸਤ੍ਹਰੀ ਵੈਲਿਡੇਸ਼ਨ ਲਈ (ਪਾਸਵਰਡ ਛੋਟਾ). 409 ਵਰਤੋ ਜਦੋਂ ਡੇਟਾ ਵੈਧ ਹੈ ਪਰ ਸਟੇਟ ਕਾਰਨ ਲਾਗੂ ਨਹੀਂ ਕੀਤਾ ਜਾ ਸਕਦਾ (ਈਮੇਲ ਪਹਿਲਾਂ ਹੀ ਹੈ, ਆਰਡਰ ਭੇਜ ਦਿੱਤਾ ਗਿਆ)।

ਰਿਟਾਈ ਨਿਰਦੇਸ਼ ਮਹੱਤਵਪੂਰਨ ਹਨ:

• ਆਮ ਤੌਰ 'ਤੇ ਮੁੜ ਕੋਸ਼ਿਸ਼ ਕਰਨ ਯੋਗ: 503, ਅਤੇ ਕਈ ਵਾਰੀ 429 (ਉਡੀਕ ਕਰਨ ਤੋਂ ਬਾਅਦ)।
• ਆਮ ਤੌਰ 'ਤੇ ਬਿਨਾਂ ਬਦਲਾਅ ਦੇ ਮੁੜ ਕੋਸ਼ਿਸ਼ ਨਹੀਂ ਕਰਨੀ ਚਾਹੀਦੀ: 400, 401, 403, 404, 409, 422।
• ਜੇ ਆਪਰੇਸ਼ਨ idempotent ਹੈ (ਇਕੋ সਰੀਰ ਨਾਲ PUT ਜਾਂ ਇੱਕ idempotency key ਵਾਲਾ POST), ਤਾਂ ਟ੍ਰਾਂਜ਼ੀਐਂਟ ਫੇਲ੍ਹਰਾਂ ਤੋਂ ਬਾਅਦ ਰਿਟ੍ਰਾਈਜ਼ ਜ਼ਿਆਦਾ ਸੁਰੱਖਿਅਤ ਹੋ ਜਾਂਦੇ ਹਨ।

Request IDs: ਕਲਾਇੰਟ ਮੁੱਦਿਆਂ ਨੂੰ ਡੀਬੱਗ ਕਰਨ ਦਾ ਸਭ ਤੋਂ ਤੇਜ਼ ਰਸਤਾ

ਇੱਕ request ID ਇਕ ਛੋਟੀ ਯੂਨੀਕ ਵੈਲੂ ਹੈ ਜੋ ਇੱਕ API ਕਾਲ ਨੂੰ ਆਖਰ ਤੱਕ ਪਛਾਣਦੀ ਹੈ। ਜੇ ਕਲਾਇੰਟ ਹਰ ਰਿਸਪਾਂਸ ਵਿੱਚ ਇਸਨੂੰ ਵੇਖ ਸਕਦਾ ਹੈ, ਤਾਂ ਸਹਾਇਤਾ ਆਸਾਨ ਹੋ ਜਾਂਦੀ ਹੈ: “ਮੈਨੂੰ request ID ਭੇਜੋ” ਅਕਸਰ ਬਿਲਕੁਲ ਕਾਫ਼ੀ ਹੁੰਦਾ ਹੈ ਸਹੀ ਲੌਗ ਅਤੇ ਅਸਲ ਫੇਲ੍ਹਰ ਲੱਭਣ ਲਈ।

ਇਹ ਆਦਤ ਸਫਲਤਾ ਅਤੇ ਗਲਤੀ ਦੋਵਾਂ ਤੱਕ ਫਾਇਦੇਮੰਦ ਹੈ।

ਬਣਾਉਣ ਅਤੇ propagation ਨੀਤੀਆਂ

ਇੱਕ ਸਾਫ ਨੀਤੀ ਵਰਤੋ: ਜੇ ਕਲਾਇੰਟ request ID ਭੇਜਦਾ ਹੈ ਤਾਂ ਉਸਨੂੰ ਰੱਖੋ। ਨਹੀਂ ਤਾਂ ਨਵਾਂ ਬਣਾਓ।

• ਇਕੋ ਸਿੰਗਲ ਹੇਡਰ ਨਾਮ ਤੋਂ ਆਉਣ ਵਾਲੀ ID ਨੂੰ ਸਵੀਕਾਰ ਕਰੋ (ਇੱਕ ਚੁਣੋ ਅਤੇ ਦਸਤਾਵੇਜ਼ ਕਰੋ, ਉਦਾਹਰਣ ਲਈ X-Request-Id).
• ਜੇ ਹੇਡਰ ਗੈਰ-ਮੌਜੂਦ ਜਾਂ ਖਾਲੀ ਹੈ ਤਾਂ ਐਜ (middleware) 'ਤੇ ਨਵੀਂ ID ਜਨਰੇਟ ਕਰੋ ਅਤੇ request context ਨਾਲ ਜੁੜੋ।
• ਰਿਕਵੈਸਟ ਦੌਰਾਨ ID ਨੂੰ ਕਦੇ ਬਦਲੋ ਨਹੀਂ। ਇਸਨੂੰ ਡਾਟਾਬੇਸ ਜਾਂ ਹੋਰ ਸਰਵਿਸਿਜ਼ ਨੂੰ context ਜਾਂ ਹੈਡਰ ਰਾਹੀਂ ਪਾਸ ਕਰੋ।

request ID ਤਿੰਨ ਥਾਵਾਂ 'ਤੇ ਰੱਖੋ:

• Response header (ਉਹੀ ਹੈਡਰ ਨਾਮ ਜੋ ਤੁਸੀਂ ਸਵੀਕਾਰ ਕਰਦੇ ਹੋ)
• Response body (ਤੁਹਾਡੇ ਸਟੈਂਡਰਡ ਸਕੀਮਾ ਵਿੱਚ request_id ਵਜੋਂ)
• Logs (ਹਰ ਲੌਗ ਲਾਈਨ 'ਤੇ structured field ਦੇ ਤੌਰ 'ਤੇ)

ਬੈਚ ਅਤੇ ਅਸਿੰਕ ਕੰਮ

ਬੈਚ ਏਂਡਪੌਇੰਟਾਂ ਜਾਂ ਬੈਕਗ੍ਰਾਊਂਡ ਜੌਬਾਂ ਲਈ, ਇਕ parent request ID ਰੱਖੋ। ਉਦਾਹਰਣ: ਇੱਕ ਕਲਾਇੰਟ 200 ਰੋਜ਼ ਅਪਲੋਡ ਕਰਦਾ ਹੈ, 12 ਵੈਲਿਡੇਸ਼ਨ ਵਿੱਚ fail ਹੋ ਜਾਂਦੇ ਹਨ ਅਤੇ ਤੁਸੀਂ ਕੰਮ enqueue ਕਰ ਦਿੰਦੇ ਹੋ। ਪੂਰੇ ਕਾਲ ਲਈ ਇੱਕ request_id ਰਿਟਰਨ ਕਰੋ, ਅਤੇ ਹਰ ਜੌਬ ਅਤੇ ਪ੍ਰਤੀ-ਆਇਟਮ ਐਰਰ 'ਤੇ parent_request_id ਸ਼ਾਮਲ ਕਰੋ। ਇਸ ਤਰ੍ਹਾਂ ਤੁਸੀਂ ਇੱਕ “ਆਪਲੋਡ” ਦਾ ਨਿਰੀਖਣ ਕਰ ਸਕਦੇ ਹੋ ਭਾਵੇਂ ਇਹ ਬਹੁਤ ਸਾਰੇ ਟਾਸਕਾਂ ਵਿੱਚ ਵੰਡਿਆ ਗਿਆ ਹੋਵੇ।

ਲੌਗਿੰਗ ਅਤੇ ਮੈਟ੍ਰਿਕਸ ਬਿਨਾਂ ਅੰਦਰੂਨੀ ਜਾਣਕਾਰੀ ਲੀਕ ਕੀਤੇ

ਕਲਾਇੰਟਾਂ ਨੂੰ ਇੱਕ ਸਪਸ਼ਟ, ਸਥਿਰ ਗਲਤੀ ਰਿਸਪਾਂਸ ਚਾਹੀਦਾ ਹੈ। ਤੁਹਾਡੇ ਲੌਗਜ਼ ਨੂੰ ਗੰਦੇ ਸਚਾਈ ਦੀ ਲੋੜ ਹੈ। ਇਹ ਦੋਨੋਂ ਦੁਨੀਆਂ ਅਲੱਗ ਰੱਖੋ: ਕਲਾਇੰਟ ਨੂੰ ਸੁਰੱਖਿਅਤ ਸੁਨੇਹਾ ਅਤੇ ਪਬਲਿਕ ਐਰਰ ਕੋਡ ਰਿਟਰਨ ਕਰੋ, ਜਦਕਿ ਅੰਦਰੂਨੀ ਕਾਰਨ, ਸਟੈਕ ਅਤੇ ਸੰਦਰਭ ਸਰਵਰ ਲੌਗਜ਼ ਵਿੱਚ ਲਿਖੋ।

ਹਰ ਗਲਤੀ ਰਿਸਪਾਂਸ ਲਈ ਇੱਕ structured ਘਟਨਾ ਲਾਗ ਕਰੋ, ਜਿਸ ਨੂੰ request_id ਨਾਲ ਖੋਜਿਆ ਜਾ ਸਕੇ।

ਜੋ ਫੀਲਡ ਇਕਸਾਰ ਰੱਖਣਯੋਗ ਹਨ:

• request_id
• user_id ਜਾਂ account_id (ਜੇ authenticated ਹੋ)
• ਪਬਲਿਕ error code ਅਤੇ HTTP status
• handler/route ਨਾਮ ਅਤੇ method
• ਅੰਦਰੂਨੀ ਐਰਰ ਵੇਰਵਾ (wrapped cause, validation field errors, upstream timeout)

ਅੰਦਰੂਨੀ ਵੇਰਵੇ ਸਿਰਫ ਸਰਵਰ ਲੌਗਜ਼ (ਜਾਂ ਅੰਦਰੂਨੀ ਏਰਰ ਸਟੋਰ) ਵਿੱਚ ਸਟੋਰ ਕਰੋ। ਕਲਾਇੰਟ ਨੂੰ ਕਦੇ ਵੀ ਕੱਚੇ ਡੇਟਾਬੇਸ ਐਰਰ, ਕਵੇਰੀ ਟੈਕਸਟ, ਸਟੈਕ ਟਰੇਸ ਜਾਂ ਪ੍ਰੋਵਾਈਡਰ ਸੁਨੇਹੇ ਨਹੀਂ ਵੇਖਣੇ ਚਾਹੀਦੇ। ਜੇ ਤੁਹਾਡੇ ਕੋਲ ਕਈ ਸਰਵਿਸਿਜ਼ ਹਨ ਤਾਂ ਇੱਕ ਅੰਦਰੂਨੀ ਫੀਲਡ ਜਿਵੇਂ source (api, db, auth, upstream) ਟ੍ਰਾਇਅਜ ਤੇਜ਼ ਕਰ ਸਕਦਾ ਹੈ।

ਜਿੰਨ੍ਹਾਂ ਏਂਡਪੌਇੰਟਾਂ ਤੋਂ ਬਹੁਤ ਸਾਰੀਆਂ 429 ਜਾਂ 400 ਆ ਸਕਦੀਆਂ ਹਨ ਉਹਨਾਂ ਦਾ ਧਿਆਨ ਰੱਖੋ। ਲੌਗ ਸਪੈਮ ਤੋਂ ਬਚਣ ਲਈ ਦੁਹਰਾਏ ਜਾ ਰਹੇ ਘਟਨਾਵਾਂ ਨੂੰ ਸੈਂਪਲ ਕਰੋ ਜਾਂ ਉਮੀਦ ਕੀਤੇ ਐਰਰਾਂ ਲਈ severity ਘੱਟ ਕਰੋ ਹਾਲਾਂਕਿ ਉਹ ਮੈਟ੍ਰਿਕਸ ਵਿੱਚ ਗਿਣੇ ਜਾਣ।

ਮੈਟ੍ਰਿਕਸ ਸਮੱਸਿਆਵਾਂ ਨੂੰ ਲੌਗਜ਼ ਨਾਲੋਂ ਪਹਿਲਾਂ ਫੜ ਲੈਂਦੇ ਹਨ। HTTP status ਅਤੇ error code ਮੁਤਾਬਕ ਗਿਣਤੀਆਂ ਟਰੈਕ ਕਰੋ ਅਤੇ ਅਚਾਨਕ spike 'ਤੇ ਅਲਾਰਮ ਲਗਾਓ। ਜੇ RATE_LIMITED ਕਿਸੇ ਡਿਪਲੌਇ ਤੋਂ ਬਾਅਦ 10x ਵੱਧ ਜਾਂਦਾ ਹੈ, ਤੁਹਾਨੂੰ ਇਹ ਜਲਦੀ ਪਤਾ ਲੱਗੇਗਾ ਭਾਵੇਂ ਲੌਗਜ਼ sampled ਹੋ ਰਹੇ ਹੋਣ।

ਕਦਮ-ਬਾਇ-ਕਦਮ: Go ਵਿੱਚ ਇੱਕ ਸਥਿਰ ਗਲਤੀ ਪਾਈਪਲਾਈਨ ਲਾਗੂ ਕਰੋ

ਸਭ ਤੋਂ ਆਸਾਨ ਤਰੀਕਾ ਗਲਤੀਆਂ ਨੂੰ ਸਥਿਰ ਬਣਾਉਣ ਦਾ ਇਹ ਹੈ ਕਿ ਉਹਨਾਂ ਨੂੰ ਹਰ ਥਾਂ ਹੇਠਾਂ ਸੰਭਾਲਣਾ ਬੰਦ ਕਰ ਦਿਓ ਅਤੇ ਉਨ੍ਹਾਂ ਨੂੰ ਇੱਕ ਛੋਟੀ ਬਹੁਤ ਸਧਾਰਨ ਪਾਈਪਲਾਈਨ ਰਾਹੀਂ ਰਾਊਟ ਕਰੋ। ਉਹ ਪਾਈਪਲਾਈਨ ਫੈਸਲਾ ਕਰਦਾ ਹੈ ਕਿ ਕਲਾਇੰਟ ਨੂੰ ਕੀ ਦਿਖੇ ਅਤੇ ਤੁਹਾਡੇ ਕੋਲ ਕੀ ਲੌਗ ਹੋਵੇ।

ਪਾਈਪਲਾਈਨ 5 ਪ੍ਰਯੋਗੀ ਕਦਮਾਂ ਵਿੱਚ

ਛੋਟੇ ਸੈੱਟ error codes ਨਾਲ ਸ਼ੁਰੂ ਕਰੋ ਜੋ ਕਲਾਇੰਟਾਂ ਲਈ ਭਰੋਸੇਯੋਗ ਹੋਣ (ਉਦਾਹਰਣ: INVALID_ARGUMENT, NOT_FOUND, UNAUTHORIZED, CONFLICT, INTERNAL). ਉਹਨਾਂ ਨੂੰ ਇੱਕ ਟਾਈਪਡ ਐਰਰ ਵਿੱਚ ਰੈਪ ਕਰੋ ਜੋ ਸਿਰਫ ਸੁਰੱਖਿਅਤ, ਪਬਲਿਕ ਫੀਲਡ (code, safe message, ਚੋਣੀਯਾ details) ਨੂੰ ਐਕਸਪੋਜ਼ ਕਰੇ। ਅੰਦਰੂਨੀ ਕਾਰਨ ਪ੍ਰਾਈਵੇਟ ਰੱਖੇ ਜਾ ਸਕਦੇ ਹਨ।

ਫਿਰ ਇੱਕ translator ਫੰਕਸ਼ਨ ਲਿਖੋ ਜੋ ਕਿਸੇ ਵੀ ਐਰਰ ਨੂੰ (statusCode, responseBody) ਵਿੱਚ ਬਦਲ ਦੇਵੇ। ਇੱਥੇ ਟਾਈਪਡ ਐਰਰ HTTP ਸਟੇਟਸਾਂ ਨਾਲ ਨਕਸ਼ੇ ਜਾਂਦੇ ਹਨ, ਅਤੇ ਅਣਜਾਣ ਐਰਰ ਸੁਰੱਖਿਅਤ 500 ਰਿਸਪਾਂਸ ਬਣ ਜਾਂਦੇ ਹਨ।

ਅਗਲਾ, middleware ਜੋੜੋ ਜੋ:

• ਹਰ ਰਿਕਵੈਸਟ ਲਈ request_id ਯਕੀਨੀ ਬਣਾਏ
• ਪੈਨਿਕ ਤੋਂ recover ਕਰੇ

ਇੱਕ panic ਕਦੇ ਵੀ ਕਲਾਇੰਟ ਨੂੰ ਸਟੈਕ ਟਰੇਸ ਨਹੀਂ ਦਿਖਾਉਣਾ ਚਾਹੀਦਾ। ਇੱਕ ਆਮ 500 ਰਿਸਪਾਂਸ ਸਗੋਂ generic ਸੁਨੇਹਾ ਰਿਟਰਨ ਕਰੋ, ਅਤੇ ਉਸੇ request_id ਨਾਲ ਪੂਰੇ panic ਨੂੰ ਲੌਗ ਕਰੋ।

ਅੰਤ ਵਿੱਚ, ਆਪਣੇ ਹੈਂਡਲਰਾਂ ਨੂੰ ਇੰਝ ਬਦਲੋ ਕਿ ਉਹ ਸਿੱਧਾ ਰਿਸਪਾਂਸ ਲਿਖਣ ਦੀ ਬਜਾਏ error ਰਿਟਰਨ ਕਰਨ। ਇੱਕ wrapper ਹੈਂਡਲਰ ਹੈ ਜੋ handler ਨੂੰ ਕਾਲ ਕਰੇ, translator ਚਲਾਏ ਅਤੇ ਸਟੈਂਡਰਡ ਫਾਰਮੈਟ ਵਿੱਚ JSON ਲਿਖ ਦੇਵੇ।

ਇੱਕ ਸੰਕੁਚਿਤ ਚੈੱਕਲਿਸਟ:

• ਸੁਰੱਖਿਅਤ ਫੀਲਡਾਂ ਅਤੇ ਸਥਿਰ ਕੋਡਾਂ ਨਾਲ ਟਾਈਪ ਕੀਤੀਆਂ ਐਰਰਾਂ ਪਰਿਭਾਸ਼ਿਤ ਕਰੋ।
• ਇੱਕ ਸਥਾਨ 'ਤੇ ਐਰਰਾਂ ਨੂੰ ਸਟੇਟਸ ਕੋਡ ਅਤੇ ਰਿਸਪਾਂਸ JSON ਵਿੱਚ ਨਕਸ਼ਾ ਕਰੋ।
• request ID ਅਤੇ panic recovery middleware ਜੋੜੋ।
• ਹੈਂਡਲਰਾਂ ਨੂੰ errors ਰਿਟਰਨ ਕਰਨ ਲਈ ਬਦਲੋ, ਰਿਸਪਾਂਸ ਲਿਖਣ ਲਈ ਨਹੀਂ।
• translator ਅਤੇ wrapper ਲਈ golden ਟੈਸਟ ਸ਼ਾਮਲ ਕਰੋ।

Golden ਟੈਸਟ ਮਹੱਤਵਪੂਰਨ ਹਨ ਕਿਉਂਕਿ ਉਹ ਕਾਂਟ੍ਰੈਕਟ ਨੂੰ ਲਾਕ ਕਰਦੇ ਹਨ। ਜੇ ਕੋਈ ਬਾਅਦ ਵਿੱਚ ਸੁਨੇਹਾ ਜਾਂ ਸਟੇਟਸ ਕੋਡ ਬਦਲਦਾ ਹੈ, ਟੈਸਟ ਫੇਲ ਹੋ ਜਾਵੇਗਾ ਪਹਿਲਾਂ ਹੀ ਕਲਾਇੰਟਾਂ ਨੂੰ ਹੈਰਾਨ ਕਰਨ ਤੋਂ ਪਹਿਲਾਂ।

ਉਦਾਹਰਣ: ਇੱਕ ਏਂਡਪੌਇੰਟ, ਤਿੰਨ ਗਲਤੀਆਂ, ਆਸਾਨੀ ਨਾਲ ਪਛਾਣਯੋਗ ਜਵਾਬ

ਕਲਪਨਾ ਕਰੋ ਇੱਕ ਏਂਡਪੌਇੰਟ: ਇੱਕ ਕਲਾਇੰਟ ਕਸਟਮਰ ਰਿਕਾਰਡ ਬਣਾਉਂਦਾ ਹੈ।

POST /v1/customers ਨਾਲ JSON ਜਿਵੇਂ { "email": "[email protected]", "name": "Pat" }. ਸਰਵਰ ਹਮੇਸ਼ਾਂ ਇੱਕੋ ਗਲਤੀ ਆਕਾਰ ਅਤੇ ਹਮੇਸ਼ਾਂ request_id ਸ਼ਾਮਲ ਕਰਦਾ ਹੈ।

1) Validation error (400)

ਈਮੇਲ ਗੈਰ-ਮੌਜੂਦ ਜਾਂ ਗਲਤ ਫਾਰਮੈਟ ਵਾਲੀ ਹੈ। ਕਲਾਇੰਟ ਫੀਲਡ ਨੂੰ ਹਾਈਲਾਈਟ ਕਰ ਸਕਦਾ ਹੈ।

{
  "request_id": "req_01HV9N2K6Q7A3W1J9K8B",
  "error": {
    "code": "VALIDATION_FAILED",
    "message": "Some fields need attention.",
    "details": {
      "fields": {
        "email": "must be a valid email address"
      }
    }
  }
}

2) Conflict (409)

ਈਮੇਲ ਪਹਿਲਾਂ ਹੀ ਮੌਜੂਦ ਹੈ। ਕਲਾਇੰਟ ਸਾਇਨ-ਇਨ ਜਾਂ ਹੋਰ ਈਮੇਲ ਚੁਣਨ ਦੀ ਸਲਾ ਦੇ ਸਕਦਾ ਹੈ।

{
  "request_id": "req_01HV9N3C2D0F0M3Q7Z9R",
  "error": {
    "code": "ALREADY_EXISTS",
    "message": "A customer with this email already exists."
  }
}

3) Transient failure (503)

ਇੱਕ ਡਿਪੈਂਡੈਂਸੀ ਡਾਉਨ ਹੈ। ਕਲਾਇੰਟ ਬੈਕਆਫ਼ ਦੇ ਨਾਲ ਮੁੜ ਕੋਸ਼ishy ਕਰ ਸਕਦਾ ਹੈ ਅਤੇ ਸ਼ਾਂਤ ਸੁਨੇਹਾ ਦਿਖਾ ਸਕਦਾ ਹੈ।

{
  "request_id": "req_01HV9N3X8P2J7T4N6C1D",
  "error": {
    "code": "TEMPORARILY_UNAVAILABLE",
    "message": "We could not save your request right now. Please try again."
  }
}

ਇੱਕੋ ਕਾਂਟ੍ਰੈਕਟ ਨਾਲ, ਕਲਾਇੰਟ ਸਥਿਰ ਤਰੀਕੇ ਨਾਲ ਕਾਰਵਾਈ ਕਰਦਾ ਹੈ:

• 400: details.fields ਵਰਤ ਕੇ ਫੀਲਡਾਂ ਨੂੰ ਨਿਸ਼ਾਨ ਲਗਾਓ
• 409: ਯੂਜ਼ਰ ਨੂੰ ਸੁਰੱਖਿਅਤ ਅਗਲਾ ਕਦਮ ਦੱਸੋ
• 503: ਰਿਟ੍ਰਾਈ ਪ੍ਰੇਰਨਾ ਦਿਓ ਅਤੇ request_id ਸਹਾਇਤਾ ID ਵਜੋਂ ਦਿਖਾਓ

ਸਹਾਇਤਾ ਲਈ, ਉਹੀ request_id ਅੰਦਰੂਨੀ ਲੌਗਜ਼ ਵਿੱਚ ਅਸਲ ਕਾਰਨ ਤੱਕ ਸਭ ਤੋਂ ਤੇਜ਼ ਰਸਤਾ ਹੁੰਦਾ ਹੈ, ਬਿਨਾਂ ਸਟੈਕ ਟਰੇਸ ਜਾਂ ਡੇਟਾਬੇਸ ਐਰਰ ਦਾ ਉਤਸ਼ਾਰ ਕੀਤੇ।

ਆਮ ਜਾਲ ਜੋ ਗਲਤੀਆਂ ਹੋਰ ਖਰਾਬ ਕਰ ਦਿੰਦੀਆਂ ਹਨ

ਕਲਾਇੰਟਾਂ ਨੂੰ ਗੁੱਸਾ ਕਰਨ ਦਾ ਤੇਜ਼ ترین ਤਰੀਕਾ ਇਹ ਹੈ ਕਿ ਉਨ੍ਹਾਂ ਨੂੰ ਅਨੁਮਾਨ ਲਾਉਣ ਦੀ ਲੋੜ ਪਏ। ਜੇ ਇੱਕ ਏਂਡਪੌਇੰਟ { "error": "..." } ਰਿਟਰਨ ਕਰਦਾ ਹੈ ਅਤੇ ਦੂਜਾ { "message": "..." }, ਤਾਂ ਹਰ ਕਲਾਇੰਟ ਵੱਖਰੇ ਖਾਸ ਕੇਸ ਬਣਾਉਂਦਾ ਹੈ ਅਤੇ ਕੀੜੇ ਹਫਤਿਆਂ ਤੱਕ ਲੁਕਕੇ ਰਹਿ ਜਾਂਦੇ ਹਨ।

ਕਈਆਂ ਗਲਤੀਆਂ ਬਾਰ-ਬਾਰ ਨਜ਼ਰ ਆਉਂਦੀਆਂ ਹਨ:

• HTTP 200 ਵਾਪਸ ਕਰਨਾ ਜਿਸ ਵਿੱਚ ਬਾਡੀ ਵਿੱਚ ਗਲਤੀ ਹੋਵੇ, ਜਾਂ ਐਂਡਪੌਇੰਟਾਂ ਵਿਚ ਵੱਖਰੇ ਗਲਤੀ ਸਕੀਮਾਂ।
• ਯੂਜ਼ਰ ਸੁਨੇਹੇ ਵਿੱਚ ਅੰਦਰੂਨੀ ਜਾਣਕਾਰੀ ਜਿਵੇਂ SQL errors, stack traces, IPs, dependency hostnames ਜਾਂ file paths ਨੂੰ ਪ੍ਰਗਟ ਕਰਨਾ।
• ਸਿਰਫ਼ ਮਨੁੱਖੀ ਟੈਕਸਟ ਨੂੰ ਹੀ ਪਛਾਣ ਲਈ ਵਰਤਣਾ ਬਦਲੇ, ਇੱਕ ਸਥਿਰ code ਦੀ ਥਾਂ ਨਹੀਂ ਰੱਖਣਾ।
• ਐਰਰ ਕੋਡਾਂ ਨੂੰ ਬੇਫਿਕਰੀ ਨਾਲ ਬਦਲਣਾ (ਜਾਂ ਇੱਕੋ ਕੋਡ ਨੂੰ ਵੱਖਰੇ ਸਮੱਸਿਆਵਾਂ ਲਈ ਦੁਹਰਾਉਣਾ) ਅਤੇ ਉਸ ਨਾਲ ਕਲਾਇੰਟਾਂ ਨੂੰ ਤੋੜਣਾ।
• request_id ਸਿਰਫ ਫੇਲ੍ਹਰ 'ਤੇ ਜੋੜਨਾ, ਤਾਂ ਕਿ ਤੁਸੀਂ ਇੱਕ ਯੂਜ਼ਰ ਰਿਪੋਰਟ ਨੂੰ ਸਫਲ ਕਾਲ ਨਾਲ ਜੋੜ ਨਹੀਂ ਸਕਦੇ।

ਅੰਦਰੂਨੀ ਜਾਣਕਾਰੀ ਲੀਕ ਹੋਣਾ ਸਭ ਤੋਂ ਆਸਾਨ ਜਾਲ ਹੈ। ਇੱਕ ਹੈਂਡਲਰ ਸੁਲਭਤਾ ਲਈ err.Error() ਵਾਪਸ ਕਰਦਾ ਹੈ ਅਤੇ ਫਿਰ constraint name ਜਾਂ ਤੀਜੀ-ਪੱਖੇ ਮੈਸੇਜ ਪ੍ਰੋਡਕਸ਼ਨ ਰਿਸਪਾਂਸ ਵਿੱਚ ਪਹੁੰਚ ਜਾਂਦਾ ਹੈ। ਕਲਾਇੰਟ ਸੁਨੇਹਾ ਸੁਰੱਖਿਅਤ ਅਤੇ ਛੋਟਾ ਰੱਖੋ ਅਤੇ ਵਿਸਥਾਰ ਸਿਰਫ ਲੌਗਜ਼ ਵਿੱਚ ਰੱਖੋ।

ਕੇਵਲ ਟੈਕਸਟ 'ਤੇ ਨਿਰਭਰ ਕਰਨਾ ਹੋਰ ਇੱਕ ਧੀਮੀ ਸਮੱਸਿਆ ਹੈ। ਜੇ ਕਲਾਇੰਟ ਨੂੰ "email already exists" ਵਰਗੇ ਅੰਗਰੇਜ਼ੀ ਵਾਕਾਂ ਨੂੰ ਪਾਰਸ ਕਰਨਾ ਪਏ, ਤਾਂ ਤੁਸੀਂ ਮੈਸਿਜ਼ ਬਦਲਦੇ ਹੀ ਲਾਜਿਕ ਤੋੜ ਸਕਦੇ ਹੋ। ਸਥਿਰ error codes ਤੁਹਾਨੂੰ ਸੁਨੇਹਿਆਂ ਨੂੰ ਬਦਲਣ, ਅਨੁਵਾਦ ਕਰਨ ਅਤੇ ਵਰਤਾਰਾਂ ਨੂੰ ਸਥਿਰ ਰੱਖਣ ਦੀ ਆਜ਼ਾਦੀ ਦਿੰਦੇ ਹਨ।

ਐਰਰ ਕੋਡਾਂ ਨੂੰ ਆਪਣੇ ਪਬਲਿਕ ਕਾਂਟ੍ਰੈਕਟ ਦਾ ਹਿੱਸਾ ਮੰਨੋ। ਜੇ ਤੁਹਾਨੂੰ ਕਿਸੇ ਕੋਡ ਨੂੰ ਬਦਲਣਾ ਪਏ ਤਾਂ ਨਵਾਂ ਕੋਡ ਜੋੜੋ ਅਤੇ ਇਕ ਸਮੇਂ ਲਈ ਪੁਰਾਣੇ ਕੋਡ ਨੂੰ ਵੀ ਰੱਖੋ, ਭਾਵੇਂ ਦੋਵੇਂ ਇੱਕੋ HTTP ਸਟੇਟਸ ਨਾਲ ਨਕਸ਼ੇ ਹੋਣ।

ਅੰਤ ਵਿੱਚ, ਹਰ ਰਿਸਪਾਂਸ, ਸਫਲ ਹੋਵੇ ਜਾਂ ਨਾਹ, ਵਿੱਚ ਉਹੀ request_id ਫੀਲਡ ਸ਼ਾਮਲ ਕਰੋ। ਜਦੋਂ ਕੋਈ ਯੂਜ਼ਰ ਕਹਿੰਦਾ ਹੈ “ਇਹ ਕੰਮ ਕਰ ਰਿਹਾ ਸੀ, ਫਿਰ ਟੁੱਟ ਗਿਆ”, ਉਹ ਇੱਕ ID ਅਕਸਰ ਇੱਕ ਘੰਟੇ ਦੀ ਖੋਜ ਬਚਾਉਂਦੀ ਹੈ।

ਸ਼ਿਪ ਕਰਨ ਤੋਂ ਪਹਿਲਾਂ ਇਕ quick ਚੈੱਕਲਿਸਟ

ਰਿਲੀਜ਼ ਤੋਂ ਪਹਿਲਾਂ ਇੱਕ ਝਲਕੀਕ ਜਾਂਚ ਕਰੋ ਕਿ:

• ਹਰ ਥਾਂ ਇੱਕੋ error shape. ਹਰ ਏਂਡਪੌਇੰਟ ਇੱਕੋ JSON ਫੀਲਡ ਰਿਟਰਨ ਕਰਦਾ ਹੈ (ਉਦਾਹਰਣ: error.code, error.message, request_id).
• ਸਥਿਰ error codes ਅਤੇ ਕਵਰੇਜ. ਕੋਡ ਛੋਟੇ ਅਤੇ ਸਪੱਸ਼ਟ ਰੱਖੋ (VALIDATION_FAILED, NOT_FOUND, CONFLICT, UNAUTHORIZED). ਟੈਸਟ ਰੱਖੋ ਤਾਂ ਕਿ ਹੈਂਡਲਰਾਂ ਅਣਜਾਣ ਕੋਡ ਰਿਟਰਨ ਨਾ ਕਰ ਸਕਣ।
• ਇੱਕ ਸਟੇਟਸ ਮੈਪਿੰਗ ਨੀਤੀ. ਹਰੇਕ ਐਰਰ ਕਿਸਮ ਨੂੰ ਕਿਸ HTTP ਸਟੇਟਸ ਨਾਲ ਨਕਸ਼ਾ ਕੀਤਾ ਜਾਵੇ ਇਹ ਇੱਕ ਸਾਂਝੀ ਥਾਂ 'ਤੇ ਫੈਸਲਾ ਕਰੋ ਅਤੇ ਲਗੂ ਕਰੋ।
• ਦੋ-ਤਰਫ਼ਾ request ID. ਹਮੇਸ਼ਾ request_id ਰਿਟਰਨ ਕਰੋ ਅਤੇ ਹਰ ਰਿਕਵੈਸਟ ਲਈ ਲੌਗ ਕਰੋ, ਜਿਸ ਵਿੱਚ panics ਅਤੇ timeouts ਵੀ ਸ਼ਾਮਲ ਹਨ।
• ਡਿਫਾਲਟ ਤੌਰ 'ਤੇ ਸੁਰੱਖਿਅਤ ਸੁਨੇਹੇ. ਯੂਜ਼ਰ-ਮੁੱਖੀ ਸੁਨੇਹੇ ਛੋਟੇ, ਸਪਸ਼ਟ ਅਤੇ ਕਾਰਵਾਈਯੋਗ ਹੋਣ, ਕਦੇ ਵੀ ਸਟੈਕ ਟਰੇਸ, SQL ਐਰਰ ਜਾਂ vendor ਨਾਮ ਨਾ ਸ਼ਾਮਲ ਕਰਨ।

ਫਿਰ ਕੁਝ ਏਂਡਪੌਇੰਟਾਂ ਨੂੰ ਹੱਥੋਂ ਚੈੱਕ ਕਰੋ। ਇੱਕ validation error, ਇੱਕ missing record, ਅਤੇ ਇੱਕ ਅਣਪੇਸ਼ਕੀ ਫੇਲ੍ਹਰ ਟ੍ਰਿਗਰ ਕਰੋ। ਜੇ ਰਿਸਪਾਂਸ ਦਰਮਿਆਨ ਵੱਖਰੇ-ਵੱਖਰੇ ਲੱਗਦੇ ਹਨ (ਫੀਲਡ ਬਦਲ ਜਾਂਦੇ, ਸਟੇਟਸ ਕੋਡ ਭਟਕਦੇ, ਸੁਨੇਹੇ ਜਿਆਦਾ ਖੁਲਾਸਾ ਕਰਦੇ), ਤਾਂ ਸਾਂਝਾ ਪਾਈਪਲਾਈਨ ਠੀਕ ਕਰੋ ਪਹਿਲਾਂ ਕਿ ਹੋਰ ਫੀਚਰ ਜੋੜੋ।

ਇੱਕ ਪ੍ਰਯੋਗੀ ਨਿਯਮ: ਜੇ ਕੋਈ ਸੁਨੇਹਾ ਇੱਕ attackers ਦੀ ਮਦਦ ਕਰੇਗਾ ਜਾਂ ਆਮ ਉਪਭੋਗਤਾ ਨੂੰ ਭਰਮਿਤ ਕਰੇਗਾ, ਤਾਂ ਉਹ ਲੌਗਜ਼ ਵਿੱਚ ਹੋਣਾ ਚਾਹੀਦਾ ਹੈ, ਰਿਸਪਾਂਸ ਵਿੱਚ ਨਹੀਂ।

ਅਗਲੇ ਕਦਮ: ਹੁਣ ਹੀ ਸਟੈਂਡਰਡ ਕਰੋ ਅਤੇ ਬਾਅਦ ਵਿੱਚ ਸਧਾਰਨ ਰੱਖੋ

ਉਹ error contract ਲਿਖੋ ਜੋ ਤੁਸੀਂ ਹਰ ਏਂਡਪੌਇੰਟ ਲਈ ਚਾਹੁੰਦੇ ਹੋ, ਭਾਵੇਂ ਤੁਹਾਡਾ API ਪਹਿਲਾਂ ਹੀ ਲਾਈਵ ਹੋ। ਇੱਕ ਸਾਂਝਾ ਕਾਂਟ੍ਰੈਕਟ (ਸਟੇਟਸ, ਸਥਿਰ error code, ਸੁਰੱਖਿਅਤ ਸੁਨੇਹਾ, ਅਤੇ request_id) ਉਹ ਸਭ ਤੋਂ ਤੇਜ਼ ਰਸਤਾ ਹੈ ਜੋ ਗਲਤੀਆਂ ਕਲਾਇੰਟਾਂ ਲਈ ਭਰੋਸੇਯੋਗ ਬਣਾਉਂਦਾ ਹੈ।

ਫਿਰ ਹੌਲੀ-ਹੌਲੀ ਮਾਈਗਰੇਟ ਕਰੋ। ਮੌਜੂਦਾ ਹੈਂਡਲਰ ਰੱਖਦੇ ਹੋਏ, ਉਨ੍ਹਾਂ ਦੀਆਂ ਫੇਲ੍ਹਰਾਂ ਨੂੰ ਇੱਕ ਮੈਪਪਰ ਰਾਹੀਂ ਰਾਹੌਟ ਕਰੋ ਜੋ ਅੰਦਰੂਨੀ ਐਰਰਾਂ ਨੂੰ ਤੁਹਾਡੇ ਪਬਲਿਕ ਰਿਸਪਾਂਸ ਆਕਾਰ ਵਿੱਚ ਬਦਲ ਦੇਵੇ।ਇਹ ਬਿਨਾਂ ਵੱਡੇ ਰੀਰਾਈਟ ਦੇ ਸਥਿਰਤਾ ਸੁਧਾਰਦਾ ਹੈ ਅਤੇ ਨਵੀਆਂ ਏਂਡਪੌਇੰਟਾਂ ਨੂੰ ਨਵੇਂ ਫਾਰਮੈਟ ਬਣਾਉਣ ਤੋਂ ਰੋਕਦਾ ਹੈ।

ਇੱਕ ਛੋਟਾ ਐਰਰ ਕੋਡ ਕੈਟਾਲੌਗ ਰੱਖੋ ਅਤੇ ਇਸਨੂੰ API ਦਾ ਹਿੱਸਾ ਮੰਨੋ। ਜਦੋਂ ਕੋਈ ਨਵਾਂ ਕੋਡ ਜੋੜਣਾ ਚਾਹੇ, ਇੱਕ ਛੋਟਾ ਸਮੀਖਿਆ ਕਰੋ: ਕੀ ਇਹ ਵਾਕਈ ਨਵਾਂ ਹੈ, ਕੀ ਇਸਦਾ ਨਾਮ ਸਪਸ਼ਟ ਹੈ, ਅਤੇ ਕੀ ਇਹ ਸਹੀ HTTP ਸਟੇਟਸ ਲਈ ਨਕਸ਼ਾ ਕਰਦਾ ਹੈ?

ਕੁਝ ਟੈਸਟ ਜੋ ਡ੍ਰਿਫਟ ਨੂੰ ਫੜਣਗੇ:

• ਹਰ error ਰਿਸਪਾਂਸ ਵਿੱਚ request_id ਸ਼ਾਮਲ ਹੋਵੇ।
• ਸਟੇਟਸ ਕੋਡ error ਕਿਸਮ (ਟਾਈਪ) ਨਾਲ ਮਿਲਦਾ ਹੋਵੇ (ਨਾ ਕਿ error ਟੈਕਸਟ ਨਾਲ)।
• error.code ਮੌਜੂਦ ਹੋਵੇ ਅਤੇ ਕੈਟਾਲੌਗ ਦਾ ਹੋਵੇ।
• error.message ਸੁਰੱਖਿਅਤ ਰਹੇ ਅਤੇ ਕਦੇ ਵੀ ਅੰਦਰੂਨੀ ਵੇਰਵੇ ਨਾ ਸ਼ਾਮਲ ਕਰਨ।
• ਅਣਜਾਣ ਐਰਰ 500 ਤੇ fallback ਹੋ ਕੇ generic ਸੁਨੇਹਾ ਰਿਟਰਨ ਕਰਨ।

ਜੇ ਤੁਸੀਂ ਨਵੇਂ Go ਬੈਕਐਂਡ ਬਣਾ ਰਹੇ ਹੋ ਤਾਂ ਪਹਿਲਾਂ ਹੀ ਕਾਂਟ੍ਰੈਕਟ ਲਾਕ ਕਰ ਦੇਣਾ ਮਦਦਗਾਰ ਹੋ ਸਕਦਾ ਹੈ। ਉਦਾਹਰਣ ਲਈ, Koder.ai (koder.ai) ਇੱਕ planning ਮੋਡ ਸ਼ਾਮਲ ਕਰਦਾ ਹੈ ਜਿੱਥੇ ਤੁਸੀਂ ਪਹਿਲਾਂ ਹੀ ਐਰਰ ਸਕੀਮਾ ਅਤੇ ਕੋਡ ਕੈਟਾਲੌਗ ਵਰਗੀਆਂ ਰੀਤਾਂ ਪਰਿਭਾਸ਼ਿਤ ਕਰ ਸਕਦੇ ਹੋ, ਫਿਰ API ਵਧਣ ਤੇ ਹੈਂਡਲਰਾਂ ਨੂੰ aligned ਰੱਖ ਸਕਦੇ ਹੋ।