Muhammad Fari Madyan
Hire me
Spring Boot · bagian 8 dari 8

Java Spring Boot + React E-Learning Part 8: Dokumentasi Arsitektur yang Sesuai Kode — Strategi Testing & JaCoCo di CI

Penutup series: mengoreksi klaim README yang tidak lagi sesuai kode, menulis docs/ARCHITECTURE.md dengan diagram Mermaid, keputusan desain, dan batas scaling yang jujur (PR #24), serta strategi testing di balik PR #25: 55 test backend yang cepat, mock di batas yang tepat, dan ringkasan coverage JaCoCo di setiap run GitHub Actions.

Muhammad Fari Madyan

· 11 menit baca

Read in English →

Pendahuluan: Saat README Berhenti Berkata Jujur

Setelah Part 5, Part 6, dan Part 7, kode mfarim/spring-elearning-react sudah banyak berubah. Sayangnya, README-nya hampir tidak berubah. Isinya masih menjanjikan "Redis cache", broker STOMP yang "backed by Redis", dan "decoupled micro-architecture".

Ternyata semuanya tidak benar. Redis hanya menyimpan refresh token, broker-nya adalah simple broker Spring di memori, dan backend-nya cuma satu service Spring Boot. Bahkan saya sendiri ikut mengulang klaim "Redis cache" itu di Part 1 series ini.

Menurut saya, dokumentasi yang tidak akurat lebih mahal daripada dokumentasi yang tidak ada. Kontributor bisa merencanakan pekerjaan di sekitar cache yang tidak ada. Pewawancara bisa bertanya bagaimana invalidasi cache-nya bekerja, dan jawaban jujurnya adalah "tidak ada cache". Operator bisa melakukan scale out karena "STOMP pakai Redis", lalu guru berhenti menerima event live.

Di bagian terakhir ini, saya cerita soal dua pull request:

Peta dokumentasi dan testing

Klik diagram untuk membukanya dalam ukuran penuh.


1. Mengaudit README Terhadap Kode

Saya memeriksa README satu klaim demi satu klaim terhadap source code, sama seperti audit kode keamanan di Part 5:

README bilangYang sebenarnya dilakukan kodeTeks perbaikan
"Redis cache"Tidak ada @Cacheable, tidak ada cache manager. Redis menyimpan jti refresh token"Redis-backed refresh-token rotation"
"STOMP message broker backed by Redis"config.enableSimpleBroker("/topic", "/queue"), di memori"in-memory simple broker" (fan-out Redis datang belakangan di PR #25, sebagai opsi)
"decoupled micro-architecture"Satu deployable Spring Boot dengan package per domain"modular monolith dengan SPA React terpisah"
Redis sebagai "Session & Telemetry Broker"Sesi berupa JWT stateless; telemetri lewat STOMP"Refresh-token store, rotasi & pencabutan per jti"
Node 20 AlpineDockerfile memakai node:22-alpine (sejak PR #6)Node 22, Nginx 1.28
Struktur proyek dengan modul learning/ dan config/ berisi JWTPackage-nya material/, announcement/, grade/, dan security/ terpisahStruktur dibuat ulang dari package yang sebenarnya

Perbaikannya bukan membuat sistem terdengar lebih kecil. Yang saya lakukan adalah mendeskripsikan apa yang benar-benar dikerjakan sistem, lalu menunjuk satu tempat yang menjelaskan kenapa.

Aturan yang sekarang saya pakai: setiap klaim arsitektur di README harus bisa dicek dengan grep. Kalau tertulis "Redis cache", berarti @Cacheable atau CacheManager harus ada di suatu tempat.


2. Isi docs/ARCHITECTURE.md

README menjawab "ini apa dan bagaimana menjalankannya". docs/ARCHITECTURE.md menjawab "bagaimana sistem ini dibangun, kenapa, dan di mana batasnya". Dokumen ini saya bagi menjadi sepuluh bagian:

#BagianFormatPertanyaan yang dijawab
1System contextMermaid flowchart + tabelApa berjalan di mana, dan siapa bicara dengan siapa?
2Backend modulesTabelDi mana sebuah logika seharusnya ditempatkan?
3Data modelMermaid erDiagramBagaimana kelas, ujian, attempt, dan jawaban saling terhubung?
4Authentication and token rotationMermaid sequenceDiagramApa yang terjadi saat login, refresh, pemakaian ulang, logout?
5Exam lifecyclesequenceDiagram + stateDiagram-v2Aturan apa yang ditegakkan server selama ujian?
6Real-time proctoringAturan + mode pengirimanSiapa boleh subscribe, dan bagaimana event sampai ke guru?
7Design decisionsKeputusan / alternatif / alasanKenapa ini dan bukan alternatif yang paling jelas?
8Scaling limits and roadmapTabel pengaturan + item terbukaApa yang berubah dengan beberapa instance, dan apa yang masih kurang?
9Testing strategySaat ini vs rencanaApa yang dites, di level mana?
10OperationsDaftarCI, deploy, health check, job background, log

Diagram sebagai kode

Semua diagram saya buat dengan Mermaid, sehingga GitHub langsung me-render-nya dan diagram tinggal di samping kode dalam pull request yang sama. Saat alur berubah, diagramnya ikut berubah di diff yang sama, dan reviewer melihat keduanya. Ini system context saat ini:

Keputusan, beserta alternatif yang ditolak

Bagian yang paling berguna bagi pembaca (dan bagi saya sendiri enam bulan lagi) adalah tabel keputusan. Setiap barisnya menyebut alternatif yang saya pertimbangkan dan kenapa alternatif itu kalah:

KeputusanAlternatif yang dipertimbangkanAlasan
Modular monolithMicroservicesSatu tim dan satu deployable; package per domain menjaga batas tetap jelas dan memungkinkan ekstraksi nanti
JWT stateless + refresh token di RedisSesi di server; JWT tanpa storeJalur utama tetap stateless, sementara logout, rotasi, dan revoke-all tetap bekerja
Refresh token di cookie httpOnlyRefresh token di localStorageTidak bisa dibaca script yang disuntikkan; dibatasi ke endpoint auth dengan SameSite=Strict
STOMP di memori + fan-out Redis pub/subSTOMP broker relay (RabbitMQ / ActiveMQ)Memakai ulang Redis; tidak ada broker baru yang harus dijalankan
Job kedaluwarsa + optimistic lockingFinalisasi hanya saat siswa kembaliHasil tepat waktu; @Version membuatnya aman lintas instance tanpa distributed lock
Waktu dan penilaian di serverMempercayai timer dan jawaban dari klienKlien tidak bisa dipercaya
Docker Compose di VPS di belakang CloudflareKubernetes; PaaS terkelolaBiaya rendah dan bisa diprediksi

Keputusan tanpa alternatif terbaca seperti selera. Dengan alternatif, keputusan itu terbaca sebagai trade-off yang sudah dipikirkan.

Menuliskan batasannya

Bagian scaling sengaja saya buka dengan kalimat yang kurang nyaman: konfigurasi default ditujukan untuk satu instance backend. Setelah itu ada daftar pengaturan untuk beberapa instance (tiga switch dari Part 7) dan apa saja yang masih terbuka:

  • LocalDateTime dengan zona waktu server; Instant / timestamptz dalam UTC akan menghilangkan ambiguitas lintas wilayah.
  • Access token tinggal di localStorage selama 15 menit; token di memori dengan silent refresh akan menutup celah itu.
  • Integration test dengan Testcontainers untuk alur login dan ujian secara penuh, serta test suite frontend.
  • Migrasi ke Spring Boot 4 di kemudian hari.

Awalnya, mencantumkan keterbatasan terasa berisiko untuk proyek portofolio. Kenyataannya justru kebalikan dari yang saya takutkan: daftar itu menunjukkan bahwa saya tahu di mana batas-batasnya.


3. Strategi Testing

Sebelum PR #25, backend saya hanya punya tiga class test: test context-load, JwtProviderTest, dan FileStorageServiceTest. Setiap aturan baru di Part 6 dan 7 saya kirim bersama test-nya. Sekarang suite-nya berisi 55 test di 12 class:

ClassTestYang dilindungi
AnswerGraderTest6Normalisasi isian singkat, alternatif `
ExamRunnerServiceTest10Penilaian, penilaian manual, deadline, ujian ulang, job kedaluwarsa
ExamRealtimeServiceTest5Pengiriman setelah commit, fan-out Redis, fallback, pesan rusak
RefreshTokenStoreTest4Simpan, konsumsi tepat sekali, user salah, revoke-all
RefreshTokenCookiesTest4Atribut cookie, penghapusan, pemindahan body ke cookie
JwtProviderTest7Claim typ dua arah, jti unik, secret publik ditolak
InMemoryRateLimiterTest3Kapasitas, key terpisah, reset
RedisRateLimiterTest4Counter bersama, penolakan, fail open, reset
S3StorageBackendTest3Upload, metadata download, objek tidak ada
FileStorageServiceKeyTest2Nama acak, key absolut/backslash ditolak
FileStorageServiceTest6Path traversal, ekstensi berbahaya
BackendApplicationTests1Context Spring berjalan dengan PostgreSQL dan Redis

Mock di batas, tes aturannya

Sebanyak 54 dari 55 test adalah JUnit 5 + Mockito biasa, tanpa context Spring, dan semuanya selesai dalam hitungan detik. Idenya sederhana: mock infrastrukturnya (Redis, client S3, repository JPA), lalu tes aturannya secara nyata.

Untuk RefreshTokenStore, aturannya adalah "refresh token hanya berlaku tepat sekali". Test-nya meniru Redis supaya berperilaku seperti GETDEL (ada nilai di panggilan pertama, null setelahnya), lalu memeriksa jawaban dari store:

JAVA
@Test
void aRefreshTokenCanBeConsumedExactlyOnce() {
    when(values.getAndDelete("auth:refresh:jti-1")).thenReturn("7").thenReturn(null);

    assertTrue(store.consume("jti-1", 7L));
    assertFalse(store.consume("jti-1", 7L), "a replayed refresh token must be rejected");
}

Keputusan fail open dari Part 7 juga sebuah aturan, jadi saya beri test, bukan sekadar komentar:

JAVA
@Test
void failsOpenWhenRedisIsUnavailable() {
    when(redis.execute(eq(RedisRateLimiter.INCREMENT_SCRIPT), eq(List.of("rate:login:ip:1")), eq("60000")))
            .thenThrow(new RedisConnectionFailureException("connection refused"));

    assertTrue(limiter.tryAcquire("login:ip:1", 5, minute));
}

Menguji "hanya setelah commit" tanpa database

Aturan yang paling sulit dites adalah "event monitor hanya dikirim setelah transaksi commit". Ternyata saya tidak butuh transaksi sungguhan. TransactionSynchronizationManager milik Spring bisa dikendalikan secara manual:

JAVA
@Test
void insideATransactionTheEventIsSentOnlyAfterCommit() {
    TransactionSynchronizationManager.initSynchronization();

    service("local").broadcastExamEvent(7L, "EXAM_SUBMITTED", Map.of("score", 80));
    verifyNoInteractions(messaging);                 // belum ada yang dikirim

    TransactionSynchronizationManager.getSynchronizations().forEach(TransactionSynchronization::afterCommit);
    verify(messaging).convertAndSend(eq(MONITOR), any(Object.class));
}

@AfterEach membersihkan synchronization supaya state tidak bocor antar-test.

Kode murni tidak butuh mock sama sekali

AnswerGrader dari Part 6 tidak punya dependensi, jadi test-nya cukup berisi input dan output. Itu alasan utama saya mengeluarkan logika penilaian dari service: aturan yang menentukan nilai siswa seharusnya menjadi kode yang paling mudah dites di proyek ini.

Menguji bug-nya, bukan hanya fiturnya

Test yang paling berharga buat saya adalah yang mereproduksi bug dari Part 6, sehingga bug itu tidak bisa kembali tanpa ketahuan:

JAVA
@Test void savingAnAnswerAfterTheDeadlineFinalizesTheAttempt()          // bug rollback
@Test void manualGradingKeepsAttemptPendingUntilEveryEssayIsGraded()  // penilaian parsial tampil sebagai final
@Test void startCreatesTheNextAttemptNumberWhenRetriesAreAllowed()     // crash ujian ulang
@Test void finalizeDoesNothingForAttemptsThatAreAlreadyFinished()      // penilaian ganda

Yang tidak bisa dibuktikan unit test

Mock tidak bisa membuktikan bahwa native SQL di findExpiredInProgressAttemptIds berjalan di PostgreSQL, bahwa @Version benar-benar menghasilkan konflik, atau bahwa migrasi V3 berjalan mulus di data lama. Untuk itu saya butuh database sungguhan. Satu-satunya integration test (contextLoads) berjalan dengan service container PostgreSQL 16 dan Redis 7 di CI, sehingga Flyway menerapkan V1 → V3 di setiap build. Namun, test alur penuh dengan Testcontainers masih ada di roadmap, dan dokumentasinya menyebutkan hal itu.


4. Coverage JaCoCo di Setiap Run CI

Coverage saya ukur dengan plugin Maven JaCoCo. prepare-agent menginstrumentasi test, dan report berjalan di fase test:

XML
<plugin>
    <groupId>org.jacoco</groupId>
    <artifactId>jacoco-maven-plugin</artifactId>
    <version>${jacoco.version}</version> <!-- 0.8.12 -->
    <executions>
        <execution>
            <id>prepare-agent</id>
            <goals><goal>prepare-agent</goal></goals>
        </execution>
        <execution>
            <id>report</id>
            <phase>test</phase>
            <goals><goal>report</goal></goals>
        </execution>
    </executions>
</plugin>

Workflow GitHub Actions menjalankan PostgreSQL dan Redis sebagai service container, menjalankan ./mvnw clean package, lalu mengubah jacoco.csv menjadi ringkasan satu baris di halaman job dan meng-upload laporan HTML-nya:

YAML
- name: Build and Package with Maven
  run: ./mvnw clean package

- name: Publish coverage summary
  if: always()
  run: |
    if [ -f target/site/jacoco/jacoco.csv ]; then
      awk -F, 'NR > 1 { missed += $8; covered += $9 }
        END { total = missed + covered; if (total > 0) printf "### Backend line coverage: %.1f%% (%d of %d lines)\n", 100 * covered / total, covered, total }' \
        target/site/jacoco/jacoco.csv >> "$GITHUB_STEP_SUMMARY"
    fi

- name: Upload coverage report
  if: always()
  uses: actions/upload-artifact@v4
  with:
    name: jacoco-report
    path: backend/target/site/jacoco
    if-no-files-found: ignore

Kolom 8 dan 9 di CSV JaCoCo adalah LINE_MISSED dan LINE_COVERED. Dengan if: always(), angkanya tetap dipublikasikan walaupun ada test yang gagal, karena justru saat itulah kita ingin melihatnya.

Kenapa belum ada batas minimum coverage

JaCoCo bisa menggagalkan build di bawah persentase tertentu, tetapi untuk saat ini saya memilih tidak memakainya. Controller dan kode import Excel sebagian besar belum dites, jadi batas minimum apa pun hari ini akan terlalu rendah sampai tidak bermakna, atau malah memblokir pull request yang tidak berhubungan. Rencana saya, yang tertulis di tabel strategi testing, adalah menambahkan batas itu setelah suite Testcontainers ada. Sampai saat itu, angkanya terlihat di setiap run, dan penurunan akan ketahuan saat review.


5. Seluruh Series dalam Satu Tabel

PartTopikPull request
1Membangun ulang monolit Laravel menjadi Spring Boot + React—
2Path traversal, refresh token, ketahanan Docker#1
3JWT stateless, RBAC level method, OWASP Top 10, rate limiting#1, #3, #4
4Deploy single VPS dengan Docker Compose, Nginx, dan SSL#2
5Audit kedua: IP klien asli, rotasi refresh, wajib ganti password, otorisasi file dan STOMP#5, #6
6Integritas ujian: noRollbackFor, job kedaluwarsa, attempt unik, @Version#25
7Cookie httpOnly, CSP, Redis dan S3 untuk beberapa instance#25
8Dokumentasi arsitektur, strategi testing, JaCoCo#24, #25

Kesimpulan

Series ini dimulai sebagai "membangun ulang platform e-learning Laravel dengan Spring Boot dan React". Akhirnya, perjalanan ini sampai di tempat yang lebih berguna: sistem yang keamanannya, aturan ujiannya, dan batas scaling-nya tertulis, dites, dan sesuai dengan kodenya.

Kalau saya harus menyimpan tiga kebiasaan dari delapan part ini, inilah yang saya pilih:

  1. Audit dengan pengetahuan penyerang. Anggap mereka sudah membaca repo kamu (Part 5).
  2. Biarkan database menjamin apa yang tidak bisa dijamin if. Unique key, kolom version, dan batas transaksi (Part 6).
  3. Buat dokumentasi yang bisa dicek. Setiap klaim harus berjarak satu grep dari kode yang membuktikannya (Part 8).

Terima kasih sudah mengikuti series ini sampai akhir. Kode, dokumentasi, dan demo live-nya semuanya publik, jadi issue dan pull request dari kamu sangat saya tunggu.

BagikanLinkedInXWhatsApp

Ditulis oleh Muhammad Fari Madyan

Senior Full Stack Engineer dan co-founder LampungDev. Saya menuliskan apa yang saya bangun supaya orang lain bisa ikut belajar.

Ajak kerja sama
← bagian 7Refresh Cookie httpOnly, CSP & Scaling Multi-Instance dengan Redis dan S3seri selesaiKembali ke semua artikel →

Muhammad Fari Madyan

Senior Full Stack Engineer building web and mobile systems that hold up in production. Co-founder of LampungDev. Based in Bandar Lampung, Indonesia (UTC+7), working remote.

Work

Case studiesCahTixExam platform, 4 stacksOpen source

© 2026 Muhammad Fari Madyan

Designed and built by Muhammad Fari Madyan