Perkara Penting untuk Mereka Bentuk Kontrak Data JSON API

Kesimpulan utama: kunci sampul respons, format kesalahan, perwakilan ID dan masa, serta semantik null berbanding ketiadaan dalam kontrak sebelum berbincang butiran penomboran halaman dan penamaan; sentiasa balut tahap atas dalam sampul data supaya penomboran halaman dan ID penjejakan boleh ditambah kemudian tanpa memecahkan pemanggil sedia ada.

Tiada jawapan standard dalam reka bentuk API, tetapi ada keputusan "sukar ditarik balik selepas dipilih" yang lebih baik difikirkan sebelum anda menulis baris kod pertama.

1. Sampul respons atau tidak

Tiga gaya:

复制// Style A: bare response
{ "id": 1, "name": "张三" }

// Style B: data envelope
{ "data": { "id": 1, "name": "张三" } }

// Style C: data + metadata
{ "data": { "id": 1, "name": "张三" }, "meta": { "requestId": "a1b2" } }

Syor: gunakan sampul data secara seragam untuk senarai dan butiran, dan jangan sekali-kali menjadikan tahap atas sebagai tatasusunan. Dengan itu, menambah penomboran halaman atau ID penjejakan kemudian tidak pernah memecahkan kontrak.

2. Format kesalahan: salin RFC 9457

Mencipta struktur kesalahan sendiri ialah punca besar kos kerjasama. RFC 9457 (yang menggantikan RFC 7807) mentakrifkan application/problem+json:

复制{
  "type": "https://bbdrug.com/problems/insufficient-balance",
  "title": "余额不足",
  "status": 422,
  "detail": "账户余额 12.00 元，本次扣款需要 30.00 元",
  "instance": "/accounts/A1001/payments/p-889",
  "balance": "12.00",
  "required": "30.00"
}

Medan sambungan (seperti balance / required di atas) dibenarkan oleh spesifikasi, dan bahagian hadapan boleh menggunakannya untuk mesej tepat dan bukannya menghurai teks detail.

3. Penomboran halaman: kursor mengalahkan offset

复制// Offset pagination
{ "data": [], "page": { "offset": 40, "limit": 20, "total": 137 } }

// Cursor pagination
{ "data": [], "page": { "nextCursor": "eyJpZCI6MTAwfQ", "hasMore": true } }

Syor: gunakan penomboran halaman offset untuk jadual pentadbir (ia memerlukan lompatan halaman dan jumlah), dan penomboran halaman kursor untuk suapan infiniti yang menghadap pengguna.

4. ID dan masa

4.1 Sentiasa gunakan string untuk ID

Alasannya dibincangkan dalam artikel tentang jenis: pada bahagian JavaScript, nilai melebihi 2^53 kehilangan ketepatan secara senyap. Walaupun ID semasa ialah integer auto-inkremen kecil, menggunakan string meninggalkan ruang untuk beralih ke ID snowflake kemudian.

复制{ "id": "1000000000000000001" }

4.2 Gunakan string RFC 3339 untuk masa

复制{
  "createdAt": "2026-10-30T10:41:45+08:00",
  "updatedAt": "2026-10-30T02:41:45Z"
}

• Jangan gunakan nombor cap masa milisaat: ia sukar dibaca, dan unitnya (saat/milisaat) sering tersalah;
• Nyatakan zon masa secara eksplisit: sama ada dengan Z atau dengan offset; jangan sekali-kali menggunakan "masa setempat tanpa zon masa";
• Namakan medan secara seragam sebagai xxxAt supaya jelas sekali pandang bahawa ia titik masa.

5. null dan ketiadaan

Anda mesti memilih satu dan menulisnya ke dalam dokumentasi:

Masalah dengan Pendekatan A ialah "diabaikan" dan "dihantar sebagai null" bermaksud perkara berbeza dalam PATCH, yang mudah disalahtafsir; masalah dengan Pendekatan B ialah JSON.stringify bahagian hadapan menggugurkan medan yang nilainya undefined, yang kebetulan sepadan dengan semantik.

Syor praktikal:

• Gunakan Pendekatan A untuk badan respons (null jelas bermaksud tiada nilai, dan bahagian hadapan tidak perlu membezakan undefined);
• Gunakan Pendekatan B untuk badan permintaan (terutamanya PATCH), digabungkan dengan Merge Patch atau JSON Patch untuk menjadikan semantik eksplisit.

6. Penamaan medan dan struktur

Memulangkan [] dan bukannya null untuk tatasusunan kosong sangat penting: data.items.map(...) pada bahagian hadapan tidak akan ranap kerana null.

7. Strategi evolusi

Tiga peraturan disiplin:

1. Klien mesti toleran terhadap medan tidak dikenali (jangan kurung diri anda dengan additionalProperties: false);
2. Klien mesti mempunyai cabang sandaran untuk nilai enum tidak dikenali;
3. Kekalkan medan usang selama sekurang-kurangnya satu versi utama, dan tandakannya dengan Deprecation dalam pengepala respons atau dokumentasi.

8. Contoh lengkap

复制{
  "data": [
    {
      "id": "1001",
      "name": "JSON 权威指南",
      "price": "89.50",
      "tags": ["json", "spec"],
      "publishedAt": "2026-09-01T00:00:00+08:00",
      "author": null
    }
  ],
  "page": { "nextCursor": null, "hasMore": false },
  "meta": { "requestId": "req-7f3a", "tookMs": 12 }
}

Respons ini mencerminkan semua konvensyen di atas: sampul data, ID string, jumlah sebagai string, cap masa dengan zon masa, null bermaksud tiada, tatasusunan kosong, penomboran halaman kursor, dan meta untuk maklumat kebolehan cerapan.

9. Senarai semak

• [ ] Tahap atas bukan tatasusunan; gunakan sampul data secara seragam;
• [ ] Respons kesalahan mengikut RFC 9457 dan termasuk type yang stabil;
• [ ] Bentuk penomboran halaman sepadan dengan senario perniagaan;
• [ ] ID ialah string, dan masa menggunakan RFC 3339;
• [ ] Semantik null dan ketiadaan ditulis ke dalam dokumentasi;
• [ ] Gaya penamaan seragam merentasi projek, dan enum menggunakan string huruf kecil;
• [ ] Klien mempunyai sandaran untuk medan tidak dikenali dan nilai enum tidak dikenali;
• [ ] Perubahan memecahkan melalui versi atau peralihan tulis berganda.

FAQ

Bagaimana saya harus mereka bentuk JSON API yang boleh berevolusi?

Balut senarai dan butiran secara seragam dalam sampul data dan jangan sekali-kali menjadikan tahap atas tatasusunan, supaya penomboran halaman dan ID penjejakan boleh ditambah tanpa memecahkan kontrak. Gunakan ID string dan cap masa RFC 3339, dan tulis semantik null berbanding ketiadaan ke dalam dokumentasi. Kekalkan medan baharu sebagai pilihan dan bebas semantik, dan beri klien sandaran untuk medan tidak dikenali dan nilai enum.

Mengapa tidak mencipta format kesalahan tersuai?

Mencipta struktur kesalahan sendiri ialah punca besar kos kerjasama. Salin application/problem+json RFC 9457, kenal pasti masalah dengan type yang stabil, dan benarkan medan sambungan seperti balance dan required, supaya bahagian hadapan boleh membina mesej tepat tanpa menghurai teks detail.

Patutkah setiap endpoint menggunakan penomboran halaman kursor?

Tidak. Jadual pentadbir memerlukan lompatan halaman dan jumlah, jadi penomboran halaman offset lebih sesuai; suapan infiniti yang menghadap pengguna harus menggunakan penomboran halaman kursor, yang kekal stabil pada halaman dalam dan mengelakkan pendua atau jurang apabila data berubah. Pilih berdasarkan sama ada senario memerlukan lompatan halaman dan jumlah.