Masalah utama di artikel ini adalah bug cache invalidation yang membuat resolver GraphQL mengembalikan data usang atau duplikat. Setelah mengetahui gejala observabilitas di latency dan response stale, artikel ini langsung membahas langkah investigasi, root cause, serta perbaikan teknis yang mengembalikan konsistensi data.

1. Gejala dan observabilitas yang menunjukkan cache invalidation gagal

Dalam kasus nyata, tim backend melihat grafik latency meningkat secara sporadis bersamaan dengan respons berisi data lama pada query userFeed. Ketika permintaan baru terus masuk, superior caching layer seharusnya memvalidasi data setelah mutation, tetapi response tetap menampilkan status lama.

Observabilitas menunjukkan dua indikator utama:

  • Latency spike setelah mutation yang seharusnya invalidasi cache: resolver menunggu cache miss lalu mengembalikan data lama, menghasilkan timeout atau queuing.
  • Response stale yang tidak memperbarui field tertentu meskipun mutation berhasil (misalnya isPinned tetap false setelah update).

Trace distributed menunjukkan resolver melakukan bypass cache dan tetap membaca data dari layer lama, menandakan partial invalidation atau konflik cache key.

2. Studi kasus: cache invalidation resolver GraphQL yang tidak lengkap

Arsitektur menggunakan Apollo Server dengan middleware caching berbasis Redis per resolver. Cache key dibangun dari nama resolver dan argumen utama (userId, afterCursor). Setelah mutation pinPost dijalankan, sistem memanggil invalidate function berbasis cache.invalidate(key). Namun, beberapa query userFeed dengan cursor berbeda masih membaca cache karena key tidak mencakup parameter clientLocale.

Root cause: conflict cache key hybrid resolver—mutation menginvalidasi key default tanpa menyertakan variaasi tambahan, sehingga hanya subset cache members yang dibersihkan. Akibatnya, query tertentu tetap menghasilkan data duplikat.

2.1 Potongan kode resolver sebelum perbaikan

const userFeedResolver = async (_, { userId, afterCursor }, { cache }) => {
  const key = `userFeed:${userId}:${afterCursor}`;
  const cached = await cache.get(key);
  if (cached) return cached;

  const feed = await dataSource.getFeed(userId, afterCursor);
  await cache.set(key, feed, { ttl: 60 });
  return feed;
};

Mutation yang memicu invalidasi hanya memanggil cache.invalidate(`userFeed:${userId}`) tanpa cursor atau locale. Akibatnya, cache entry lain (misalnya userFeed:42:cursorB) tidak dibersihkan.

3. Langkah investigasi dan debugging

Investigasi dilakukan dengan checklist berikut:

  1. Trace observability: Telusuri trace resolver untuk memastikan apakah cache hit atau miss terjadi setelah mutation.
  2. Audit cache key generation: Pastikan semua variabel input yang memengaruhi respons diikutsertakan dalam key.
  3. Review invalidation hook: Lihat apakah middleware cache dijalankan di resolver yang benar dan dengan argumen lengkap.
  4. Reproduce dengan client: Jalankan query berulang setelah mutation, bandingkan response dari cache dan sumber data asli.
  5. Instrumentasi tambahan: Pasang logging TTL cache, periksa apakah entry yang seharusnya invalidated masih ada.

Tambahkan metric custom pada cache layer untuk mencatat invalidation event beserta key lengkap.

4. Perbaikan teknis dan regresi

Perbaikan dilakukan dengan strategi multi-layer:

  • Ekspansi cache key: Sertakan seluruh variabel yang memengaruhi respons (misalnya locale, filters). Kode baru:
const buildFeedCacheKey = ({ userId, afterCursor, locale }) =>
  `userFeed:${userId}:${afterCursor || 'start'}:${locale || 'default'}`;

const userFeedResolver = async (_, args, { cache }) => {
  const key = buildFeedCacheKey(args);
  const cached = await cache.get(key);
  if (cached) return cached;

  const feed = await dataSource.getFeed(args);
  await cache.set(key, feed, { ttl: 60 });
  return feed;
};
  • Invalidation middleware update: Mutation memanggil invalidateFeedCache(userId) yang kini mencatat semua key yang pernah dibuat via registry dan membersihkan batch melalui cache.invalidateMany.
  • Instrumentasi tambahan: Pasang log dan tracer pada cache invalidation untuk memantau apakah key berhasil dibersihkan.
  • Regression test: Tambahkan test otomatis yang mensimulasikan mutation dan memastikan cache tidak menyajikan data lama.

Regresi ini memverifikasi bahwa setelah mutation invalidation terjadi untuk semua kombinasi cursor/locale.

5. Checklist tindakan preventif

  • Dokumentasikan semua informasi yang memengaruhi respons resolver untuk mencegah cache key tidak lengkap.
  • Pasang monitoring khusus: hit rate, invalidation count, failed invalidation.
  • Gunakan cache registry atau tagging untuk memudahkan invalidasi grup cache.
  • Operasikan regression test yang menjalankan mutation + query beragam param secara otomatis.
  • Pastikan middleware cache memiliki fallback ketika invalidation gagal, misalnya TTL pendek atau forced refresh.

Penutup

Bug cache invalidation resolver GraphQL bisa menyebabkan data stale atau duplikat yang sulit ditangkap tanpa observabilitas menyeluruh. Dengan audit key, memperbaiki middleware invalidation, serta menambahkan instrumentation dan regression test, tim berhasil menyelesaikan kasus ini dan menghindari regresi serupa.