দলগত সহযোগিতা FAQ: চুক্তি, কনফিগ ও ফিক্সচার

মূল কথা: দলের প্রথায় এসব একবার নিষ্পত্তি করুন — HTTP স্টেটাস কোডসহ {"data":…,"meta":…} এনভেলপ, সাইটজুড়ে এক নামকরণ শৈলী, টাইম জোনসহ RFC 3339 টাইমস্ট্যাম্প, আর স্ট্রিং এনাম — তারপর প্রতিটি নতুন API একই চুক্তির বিরুদ্ধে কেবল ফিল্ড যোগ করে বিকশিত করুন, কখনো বদলে বা মুছে নয়।

এসব প্রশ্নের একক সঠিক উত্তর নেই, কিন্তু দলের একক উত্তর থাকতেই হবে — নাহলে প্রতিটি নতুন API একই তর্ক আবার শুরু করে।

১. API চুক্তি

API কেমন কাঠামো ফেরত দেবে?

তিন প্রচলিত আকৃতি, প্রতিটির একটি দাম:

অভ্যন্তরীণ ব্যবসায়িক API-তে "রিসোর্স এনভেলপ + ফল প্রকাশকারী HTTP স্টেটাস কোড"-কে অগ্রাধিকার দিন:

复制{
  "data": [{ "id": "1", "name": "নমুনা" }],
  "meta": { "total": 128, "page": 2, "pageSize": 20 }
}

এররের জন্য আরেকটি code নেস্ট না করে HTTP স্টেটাস কোড প্লাস কাঠামোগত এরর বডি ব্যবহার করুন:

复制{
  "error": {
    "type": "validation_failed",
    "message": "রিকোয়েস্ট প্যারামিটার যাচাই ব্যর্থ",
    "details": [
      { "path": "/email", "reason": "ফরম্যাট ভুল" }
    ]
  }
}

মূল বিষয়: HTTP স্টেটাস কোড ইতিমধ্যে সফলতা বা ব্যর্থতা প্রকাশ করে, তাই ব্যবসায়িক কোড বাড়তি। দুই সিস্টেম একসঙ্গে থাকলে "২০১ কিন্তু code ৫০০" ধরনের অসামঞ্জস্য প্রায় অনিবার্য।

খালি অ্যারে এড়ান। টপ লেভেলে অ্যারে থাকলে পেজিনেশন, মোট বা কার্সর জোড়া লাগানো যায় না, আর পরে যোগ করা মানে প্রতিটি কলার বদলানো।

ফিল্ড-নাম snake_case নাকি camelCase?

একটি বাছুন, সাইটজুড়ে প্রয়োগ করুন, আর কখনো এক JSON ডকুমেন্টে মিশাবেন না।

মানদণ্ড:

1. এই JSON কে ভোগ করে: ফ্রন্টএন্ড প্রধান হলে camelCase, ডেটা পাইপলাইন ও Python সার্ভিস প্রধান হলে snake_case;
2. ডেটাবেস কলামে সরাসরি ম্যাপ করে কি: টেবিল কাঠামো সোজা পাঠালে snake_case একটি রূপান্তর স্তর বাঁচায়;
3. বিদ্যমান সিস্টেমের ধারাবাহিকতা: বিদ্যমান API যা ব্যবহার করে তা রাখুন; সামঞ্জস্য শুদ্ধতার চেয়ে বড়।

সত্যিই রূপান্তর দরকার হলে সীমানায় করুন (গেটওয়ে বা ফ্রন্টএন্ড রিকোয়েস্ট স্তর), ব্যবসায়িক কোডে ছড়িয়ে toCamelCase কল না করে।

সময় ফিল্ডে কোন ফরম্যাট?

টাইম জোন অফসেটসহ RFC 3339 / ISO 8601 স্ট্রিং ব্যবহার করুন:

复制{
  "createdAt": "2026-10-30T11:37:57+08:00",
  "updatedAt": "2026-10-30T03:37:57Z"
}

মূল বিষয়:

• টাইম জোন রাখুন: 2026-10-30 11:37:57 জোন ছাড়া ক্রস-টাইম-জোন পরিস্থিতিতে অগত্যা ভাঙবে;
• Z বা অফসেট সমানভাবে ব্যবহার করুন: দুটোই সঠিক, কিন্তু এক API-তে মিশাবেন না;
• সংখ্যিক টাইমস্ট্যাম্প এড়ান: সেকেন্ড নাকি মিলিসেকেন্ড, লিপ সেকেন্ড আছে কি না — প্রতিটি দলকে আবার ব্যাখ্যা করতে হয়। সংক্ষিপ্ততা দরকার হলে মিলিসেকেন্ড ইন্টিজার ব্যবহার করুন, কিন্তু ডকুমেন্টেশনে একক পিন করুন।

createdAt / updatedAt / deletedAt-এর মতো At সাফিক্সযুক্ত ফিল্ড-নাম পছন্দ করুন, যাতে এক নজরে বোঝা যায় মান একটি সময়বিন্দু, সময়কাল নয়। সময়কালের জন্য timeoutMs, ttlSeconds — একক নামের ভেতরে রাখুন।

null কি null হবে নাকি ফিল্ড বাদ?

এটি নির্ভর করে "এই ফিল্ড অর্থবহ কি না"-এর উপর:

তৃতীয় ক্ষেত্রটি সবচেয়ে উপেক্ষিত। PATCH রিকোয়েস্টে:

复制{ "nickname": null }

এর মানে "nickname মুছে ফেলো", অথচ রিকোয়েস্ট বডি থেকে nickname বাদ দিলে মানে "nickname ছুঁবে না"। দুটোই "মুছে ফেলা" ধরলে যে ব্যবহারকারী ইমেইল বদলায় তার nickname মুছে যাবে।

আরেকবার: undefined ব্যবহার করবেন না। এটি বৈধ JSON মান নয়, আর JSON.stringify কি পুরো ফেলে দেয়, তাই আচরণ "বাদ দেওয়া"-র সঙ্গে মেলে অথচ কোড দেখায় "স্পষ্টভাবে খালি মান পাঠানো হয়েছে"।

বুলিয়ান ফিল্ডের নাম কেমন হওয়া উচিত?

is / has / can / should প্রিফিক্স ব্যবহার করুন আর নেতিবাচক রূপ এড়ান।

复制{
  "isActive": true,
  "hasPassword": false,
  "canEdit": true
}

তিন শিক্ষা:

1. নেতিবাচক নয়: isDisabled: false পাঠককে একবার উল্টাতে বাধ্য করে; isEnabled: true সরাসরি। দ্বিগুণ নেতিবাচক (isNotDisabled) বিপর্যয়;
2. বুলিয়ানে সংখ্যা নয়: "enabled": 1 প্রতিটি ভোক্তাকে একবার === 1 লিখতে বাধ্য করে;
3. স্ট্রিং নয়: "enable": "true" JavaScript-এ truthy, আর if (data.enable) "false"-এর জন্যও সত্য; এমন বাগ ট্রেস করা অত্যন্ত কঠিন।

এনাম ফিল্ডে সংখ্যা নাকি স্ট্রিং?

স্পষ্ট স্টোরেজ বা ব্যান্ডউইথ সীমাবদ্ধতা না থাকলে স্ট্রিং ব্যবহার করুন।

复制{ "status": "active" }

{ "status": 1 }-এর তুলনায় স্ট্রিং জেতে কারণ:

• লগ, প্যাকেট ক্যাপচার ও ডেটাবেস ম্যাপিং টেবিল না দেখেই সরাসরি পাঠযোগ্য;
• এনাম মান যোগ করলে বিদ্যমান মানের অর্থ বদলায় না (সংখ্যিক এনামের মাঝখানে মান ঢুকালে সব সরে যায়);
• ফ্রন্টএন্ডকে 1 → 'active' ম্যাপিং সিঙ্কে রাখতে হয় না।

দাম কয়েক বাড়তি বাইট, যা কম্প্রেশনের পর প্রায় অগ্রাহ্য।

সঙ্গী অভ্যাস: স্ট্রিং এনাম মানে ছোট হাতের অক্ষর + আন্ডারস্কোর (pending_review), আর Schema-তে enum দিয়ে বাধ্যতামূলক করুন যাতে অবৈধ মান ভ্যালিডেশন স্তরেই প্রত্যাখ্যাত হয়।

২. কনফিগারেশন ও ফিক্সচার

কনফিগ JSON, YAML নাকি TOML হওয়া উচিত?

পছন্দ নয়, উদ্দেশ্য দিয়ে বাছুন:

দলে সাধারণ ভুল হলো ব্যবসায়িক কনফিগ YAML-এ রাখা — YAML-এর অন্তর্নিহিত টাইপ রূপান্তর (1.0 সংখ্যা হয়, NO বুলিয়ান হয়, 2026-10-30 তারিখ হয়) পার্সারভেদে আলাদা ফল দেয়।

কনফিগ প্রোগ্রাম দিয়ে কঠোরভাবে যাচাই করতে হলে JSON + Schema বাছুন, আর কমেন্ট _comment ফিল্ড বা আলাদা ডকে ডকুমেন্ট করুন।

টেস্ট ফিক্সচার কীভাবে সাজানো উচিত?

"এক বেসলাইন + ন্যূনতম ডিফ" দিয়ে সাজান, প্রতিটি টেস্ট কেসের জন্য বিশাল JSON কপি করে নয়।

复制fixtures/
├─ users/
│  ├─ base.json              # Baseline user object
│  ├─ no-email.json          # Only email is missing
│  └─ invalid-age.json       # Only age is out of range
└─ fixtures.ts               # Utility functions for loading and shallow merging

复制import baseUser from './users/base.json';

export function makeUser(overrides: Partial<User> = {}): User {
  return { ...baseUser, ...overrides };
}

তাতে নতুন টেস্ট কেসে কেবল ভিন্ন ফিল্ড লিখতে হয়, আর বেসলাইনের একটি ফিল্ড বদলালে সব কেস স্বয়ংক্রিয়ভাবে হালনাগাদ হয়।

তিন নিয়ম:

1. ফিক্সচার Schema ভ্যালিডেশন পাস করুক: বেসলাইন ফিক্সচার নিজেই বৈধ ডেটা হওয়া উচিত;
2. প্রোডাকশন থেকে বাস্তব ডেটা এক্সপোর্ট করবেন না: ফোন নম্বর, পরিচয়পত্র নম্বর ও ঠিকানা — সবই ব্যক্তিগত তথ্য;
3. ফিক্সচার ভার্সন কন্ট্রোলে থাকুক কিন্তু ছোট থাকুক: একটি ফাইল কয়েক ডজন KB ছাড়ালে ছাঁটা বা জেনারেট করা দরকার।

JSON ফাইলে মার্জ কনফ্লিক্ট কীভাবে কমাব?

JSON সহজে কনফ্লিক্ট করে: ফরম্যাটার একবারে পুরো ফাইল রিফ্লো করে, তাই দুইজন একটি করে লাইন বদলালেও পুরো ফাইলে সংঘর্ষ হয়।

চার কৌশল:

1. ফরম্যাটিং একীভূত করে .editorconfig-এ যোগ করুন: সামঞ্জস্যপূর্ণ ইনডেন্টেশন, লাইন এন্ডিং ও পিচ্ছে নিউলাইন অপ্রাসঙ্গিক ডিফ এড়ায়;
2. কি সাজান: বর্ণানুক্রমিক ক্রমে একমত হন যাতে নতুন ফিল্ড অন্যের ইনসার্ট পয়েন্টের সঙ্গে সংঘর্ষ না করে;
3. ফাইল ভাগ করুন: একটি বিশাল config.json-কে ডোমেইন অনুযায়ী কয়েকটি ফাইলে ভাগ করুন, সংঘর্ষের পৃষ্ঠপোষকতা এমনিতেই কমে;
4. "সব রিফরম্যাট" কমিট এড়ান: ফরম্যাটিং ও ব্যবসায়িক পরিবর্তন দুই কমিটে আলাদা করুন যাতে রিভিউ পাঠযোগ্য থাকে।

দল লকফাইল ব্যবহার করলে (pnpm-lock.yaml, package-lock.json), হাতে মার্জ করবেন না; আবার জেনারেট করুন:

复制git checkout --theirs pnpm-lock.yaml
pnpm install

সংস্করণ সামঞ্জস্য কীভাবে রক্ষণাবেক্ষণ করব?

নীতি "যোগ করুন, বদলাবেন না, সরাবেন না"।

সমর্থক ব্যবস্থা:

• ভোক্তা "শিথিল পার্সিং" ব্যবহার করে: অজানা ফিল্ড উপেক্ষা করে ও অনুপস্থিতের জন্য ডিফল্ট দেয়;
• সার্ভার কিছুকাল পুরোনো ফিল্ড রাখে আর রেসপন্সে Deprecation হেডার ইঙ্গিত হিসেবে দেয়;
• Schema-তে নতুন ফিল্ড required চিহ্নিত করবেন না, আর ডেপ্রিকেটেড ফিল্ডে deprecated: true ট্যাগ দিন।

CI-তে চুক্তি কীভাবে যাচাই করব?

Schema-কে কোডের অংশ ধরুন আর প্রতিটি কমিটে যাচাই করুন।

复制# Validate sample data against the Schema (using ajv-cli)
npx ajv-cli validate -s schemas/user.json -d "fixtures/users/*.json" --strict=false

CI-তে তিনটি জিনিস চালান:

1. Schema নিজের বৈধতা: $schema ঘোষণা বৈধ কি না, $ref রেজলভ হয় কি না;
2. ফিক্সচার Schema-এর সঙ্গে মেলে কি না: টেস্ট ডেটা সরে না যায় নিশ্চিত করে;
3. চুক্তি পশ্চাৎ-সামঞ্জস্যপূর্ণ কি না: আগের সংস্করণের সঙ্গে তুলনা করে সরানো ফিল্ড বা বদলানো টাইপ দেখুন।

তৃতীয় বিষয়ে টুলিং সমর্থন দরকার (যেমন openapi-diff বা json-schema-diff); তা না থাকলে অন্তত স্ক্রিপ্ট দিয়ে required অ্যারে ও properties কি-সেটের পরিবর্তন তুলনা করুন।

৩. দ্রুত রেফারেন্স