Bagaimana kami mencegah perubahan yang tidak dapat diperbaiki pada API GraphQL di beragampengetahuan – dan mengapa hal ini penting bagi pelanggan kami – Beragampengetahuan

Kita semua pernah mengalaminya – setelah menerapkan perubahan pada API, klien tiba-tiba berhenti bekerja.

Pengalaman pengguna memburuk, ulasan negatif mulai bermunculan, pendukung pelanggan mulai mengerjakan permintaan, banyak teknisi mulai menyelidiki masalahnya, dan dengan cepat hal ini menjadi situasi yang serba bisa.

Hal ini tidak hanya menghilangkan kepercayaan pengguna dan mengganggu alur kerja mereka, namun juga menghabiskan banyak waktu dan uang bagi organisasi untuk menyelesaikannya.

Salah satu cara untuk mencegah semua ini terjadi adalah dengan mendeteksi perubahan yang dapat menyebabkan gangguan ini sebelum digabungkan ke dalam repositori kami selama tahap permintaan penarikan.

Dengan cara ini kami mencegah perubahan tersebut digabungkan, sehingga menghindari pengalaman yang mengganggu bagi pelanggan dan mengurangi waktu henti pengguna.

Sebagai bagian dari komitmen kami terhadap transparansi dan pembangunan secara terbuka, saya akan membagikan cara kami melakukan ini untuk API GraphQL kami sendiri menggunakan GitHub Actions.

Saat mendeteksi perubahan yang dapat menyebabkan gangguan, kita dapat mendeteksi perubahan ini dengan mengambil representasi skema pada cabang permintaan tarik dan membandingkannya dengan representasi skema pada cabang master. Kami kemudian dapat menggunakan hasil perbedaan ini untuk menentukan apakah ada perubahan yang dapat menyebabkan gangguan pada perubahan skema kami.

Terkait alur kerja ini, kami dapat membaginya menjadi beberapa langkah:

• Hasilkan skema untuk cabang saat ini: Ini akan memberi kita skema yang mewakili perubahan yang kita buat di permintaan tarik
• Hasilkan skema untuk cabang utama: Ini akan memberi kita skema yang mewakili API produksi kita saat ini
• Lakukan verifikasi pola cabang saat ini terhadap pola cabang master: TDia akan memberi tahu kita perubahan apa yang ada dalam perbandingan skema dan apakah ada perubahan yang akan merusak klien
• Posting hasilnya ke permintaan Pull: Hal ini akan memungkinkan kita untuk “menggagalkan” permintaan penarikan untuk mencegah penggabungannya, sekaligus memperingatkan pembuat perubahan yang dapat menyebabkan gangguan

Dengan mengingat hal ini, kami akan membangun alur kerja otomatis yang akan menjalankan tindakan ini untuk setiap permintaan pull di repositori kami. Untuk pemeriksaan permintaan penarikan ini, kami menggunakan Tindakan GitHub, namun sebagian besar kode di bawah ini akan berlaku untuk pengaturan CI apa pun yang Anda gunakan.

catatan: Kami tidak akan mempelajari konsep GitHub Actions terlalu dalam di sini. Jika Anda baru mengenal pengoperasian ini, saya sarankan untuk mengikuti tutorial memulai cepat.

Siapkan alur kerja

Kami akan mulai dengan menyiapkan Aksi GitHub baru dan kami akan membuat file baru bernama Melanggar_perubahan_check.yml dan pertama-tama berikan tindakan kita a Nama.

name: Schema Change Verification

Selanjutnya, kita ingin menentukan kapan harus menjalankan tindakan ini – ini pada dasarnya memungkinkan kita untuk menentukan kapan kita ingin melakukan pemeriksaan di PR.

Kami tidak hanya ingin melakukan ini Membuka acara (saat PR pertama kali dibuka), tetapi jika dibuka kembali atau Sinkronis – Ini akan memungkinkan pemeriksaan dijalankan kembali jika ada komitmen lain yang didorong ke permintaan penarikan.

Hal ini memastikan bahwa kami selalu memeriksa komit terbaru yang dikirim ke cabang untuk mengetahui adanya perubahan yang dapat menyebabkan gangguan.

name: Schema Change Verification:  
on:
  pull_request:    
    types:      
      - opened      
      - reopened      
      - synchronize

Kami juga hanya ingin menjalankan pemeriksaan ini jika .graphql File skema telah berubah jadi kami akan menentukan aturan ini menggunakan jalur Properti.

name: Schema Change Verification
on:
  pull_request:
    types:
      - opened
      - reopened
      - synchronize
    paths:
      - 'graphql/*/**.graphql'

graphql/*/**.graphql adalah jalur tempat file skema GraphQl kami berada; Anda harus menyesuaikannya berdasarkan proyek Anda.

Hasilkan skema cabang saat ini

Sekarang setelah kita mengonfigurasi dasar-dasar operasi, kita dapat melanjutkan ke pendefinisian tugas yang bertanggung jawab untuk menghasilkan dan memvalidasi skema.

Kita akan mulai dengan mendefinisikan pekerjaan baru Hasilkan skema perubahan dan tentukan menggunakan ubuntu-program terbaru yang sedang berjalan.

name: Schema Change Verification
...

jobs:
  generateChangedSchema:
    runs-on: [ubuntu-latest]

Selanjutnya, kita perlu melakukan beberapa operasi pengaturan untuk pekerjaan kita. Pertama-tama kita ingin memeriksa repositori untuk cabang PR, untuk ini kita akan menggunakan Memeriksa tindakan.

Tindakan kami juga akan mengambil keuntungan dari simpuljadi kita perlu menginstalnya menggunakan perintah berikut Tetapkan simpul tindakan.

name: Schema Change Verification
...

jobs:
  generateChangedSchema:
    runs-on: [ubuntu-latest]
    steps:
      - uses: actions/checkout@v2
      - uses: actions/setup-node@v3
        with:
          node-version: '18'

Pada titik ini, kami siap untuk terus membuat skema. Untuk melakukan ini, kita perlu memuat file skema dan kemudian menggabungkannya menjadi satu file skema. Hal ini membuat proses verifikasi menjadi lebih sederhana karena kita hanya perlu menggunakan satu file, bukan beberapa file.

Untuk mempermudah proses ini kami akan menggunakan beberapa dependensi berikut alat graphql. Kita dapat melihat bahwa ini diberi nama sesuai dengan kegunaannya, kita hanya perlu menambahkannya ke milik kita paket.json file sebagai dependensi pengembangan.

"@graphql-tools/load-files": "7.0.0",
"@graphql-tools/merge": "9.0.1"

Dengan dependensi ini, sekarang kita akan menulis skrip kecil untuk memuat dan menggabungkan semuanya .graphql File di direktori tertentu.

import * as fs from 'fs'
import  loadFilesSync  from '@graphql-tools/load-files'
import  mergeTypeDefs  from '@graphql-tools/merge'
import  print  from 'graphql/language/printer'

const mergeFiles = async (): Promise<void> => 
  try 
    // using the provided path, load the types from the schema files
    const typesArray = loadFilesSync(`../../graphql/src`, 
      extensions: ['graphql'],
    )
 
    // merge all of the types from the recieved schemas, compressing all of the types     // into a single place
    const result = mergeTypeDefs(typesArray)
    // write the schema to a single file to be used for diffing
    await fs.promises.writeFile('generated/schema.graphql', print(result))
   catch (e) 
    console.error("We've thrown! Whoops!", e)
  


;(async (): Promise<void> => 
  try 
    // the merged schema file will be created in the generated directory, so create
    // the directory if it does not yet exist
    if (!fs.existsSync('generated')) 
      fs.mkdirSync('generated')
    
    await mergeFiles()
   catch (e) 
    console.error("We've thrown an error! Whoops!", e)
  
)()

Kemudian kami akan menambahkan yang baru [task] ke dalam file package.json kami sehingga kami dapat dengan mudah melakukan ini dengan parameter yang diperlukan. Skrip mengambil satu parameter saat dijalankan, yaitu jalur tempat pola penggabungan akan disimpan.

Jika Anda perlu menyediakan jalur ke lokasi file skema, hal ini dapat dilakukan melalui parameter tambahan. Skema kami ada dalam satu direktori, jadi kami melakukan hardcode di dalam skrip itu sendiri.

"graph:generateSchema": "ts-node scripts/generateSchema.ts"

Setelah ini selesai, sekarang kita dapat menghapusnya Hasilkan skema perubahan Bekerja. Untuk melakukan ini kita akan menggunakan langkah skrip bash yang perlu kita navigasikan Hasilkan mode perintah ada, lalu gunakan simpul perintah untuk menjalankannya.

name: Schema Change Verification
...

jobs:
  generateChangedSchema:
    runs-on: [ubuntu-latest]
    steps:
      ...
      - name: Generate Schema
        run: |
          cd services/api-gateway
          node graph:generateSchema

Pada titik ini, kita akan memiliki file skema gabungan yang berisi konten semua file skema. Untuk meringkas ini Bekerja Kami akan melampirkan file skema ini ke alur kerja kami sehingga kami dapat mengunduh file untuk digunakan dalam tugas berikutnya Bekerja dalam alur kerja kami.

Meskipun itu semua bisa dilakukan sekaligus Bekerja, Jika pekerjaan Anda dipecah menjadi bagian-bagian yang lebih kecil, tindakan Anda akan menjadi lebih terorganisir. Di sini kita akan menggunakan Unggah artefak Memanipulasi dan menambahkan file skema dari jalur tempat kita menyimpannya, beri nama pola bercabang untuk referensi di masa mendatang.

name: Schema Change Verification
...

jobs:
  generateChangedSchema:
    runs-on: [ubuntu-latest]
    steps:
      ...
      - name: Attach schema
        uses: actions/upload-artifact@v1
        with:
          name: branch-schema
          path: services/api-gateway/generated/schema.graphql

Pada titik ini, kita telah membuat file skema gabungan yang mewakili semua skema dalam proyek dan melampirkan file tunggal ini ke alur kerja kita, yang berarti langkah menghasilkan representasi skema untuk cabang saat ini telah selesai.

Verifikasi perubahan skema

Sekarang kita telah membuat skema untuk cabang tersebut, kita ingin memverifikasinya terhadap representasi skema pada cabang master.

Dari sini kita akan menyiapkan pekerjaan kedua dalam alur kerja, Lakukan validasi skema. kami akan menggunakan membutuhkan Properti menyatakan bahwa pekerjaan ini akan menunggu Hasilkan skema perubahan Selesai dengan sukses sebelum dijalankan.

name: Schema Change Verification
...

jobs:
  generateChangedSchema:
    ...
  performSchemaVerification:
    runs-on: [ubuntu-latest]
    needs: generateChangedSchema

Mirip dengan yang sebelumnya Bekerjakami akan mengonfigurasi beberapa dasar untuk ini Bekerja Dengan memeriksa repositori dan mengkonfigurasi node. Satu-satunya perbedaan di sini adalah saat dipicu Memeriksa kita akan melakukan suatu tindakan mengacu pada Nilai propertinya adalah utama.

Ini karena kita perlu membuat skema utama cabang untuk verifikasi, jadi kita perlu utama Jadikan cabang tersebut sebagai cabang saat ini ketika memeriksa repositori.

name: Schema Change Verification
...

jobs:
  generateChangedSchema:
    ...
  performSchemaVerification:
    runs-on: [ubuntu-latest]
    needs: generateChangedSchema
    steps:
      - uses: actions/checkout@v2
        with:
          ref: main
      - uses: actions/setup-node@v3
        with:
          node-version: '18'

Sebelum memvalidasi skema, kita perlu melanjutkan mendownload skema yang kita buat terakhir kali Bekerja.

Untuk ini kita bisa menggunakan Unduh artefak bertindak, menyediakan Nama Referensi file yang ingin kita unduh (yang sebelumnya kita definisikan sebagai pola bercabang), diikuti dengan jalur ke mana skema harus diunduh.

name: Schema Change Verification
...

jobs:
  generateChangedSchema:
    ...
  performSchemaVerification:
    runs-on: [ubuntu-latest]
    needs: generateChangedSchema
    steps:
      ...
      - name: Download branch schema
        uses: actions/download-artifact@v1
        with:
          name: branch-schema
          path: services/api-gateway/branch-schema

Kemudian kita memiliki representasi skema kita utama cabang untuk dibandingkan, kami akan terus mengeksekusi Hasilkan mode Memesan. Ini akan sama seperti sebelumnya, kecuali kali ini kita akan memiliki file skema yang mewakili file kita utama cabang bukannya cabang permintaan tarik kami.

name: Schema Change Verification
...

jobs:
  generateChangedSchema:
    ...
  performSchemaVerification:
    runs-on: [ubuntu-latest]
    needs: generateChangedSchema
    steps:
      ...
      - name: Generate main schema
        run: |
          cd services/api-gateway
          node  graph:generateSchema

Pada titik ini, kita sudah memiliki dua file skema yang diperlukan untuk langkah verifikasi. Kalau sampai pada langkah verifikasi yang akan kami gunakan inspektur graphql.

Alat ini berisi proses verifikasi yang memungkinkan Anda membandingkan dua skema dan mengembalikan hasil perubahan dari perbedaan tersebut. Dari sini kami akan menambahkannya sebagai dependensi pengembangan pada proyek kami.

"@graphql-inspector/ci": "^4.0.2",
"@graphql-inspector/diff-command": "^4.0.2"

Selanjutnya, kita akan menambahkan perintah lain ke perintah kita paket.json Kami akan menggunakan file ini untuk melakukan proses verifikasi ini. Untuk perintah ini kita akan menggunakan inspektur graphql dan perintah diffnya, yang mana kita perlu menyediakan dua parameter.

Yang pertama adalah jalur arsitektur ke cabang master yang baru saja kita buat pada langkah ini. Yang kedua adalah jalur pola cabang PR, yang sebelumnya kita unduh dan simpan pola bercabang jalur.

Yang penting di sini adalah milik Anda utama Skema diteruskan sebagai argumen pertama, karena argumen ini mewakili skema dasar Anda, sedangkan argumen kedua mewakili perubahan yang dilakukan cabang Anda.

"graph:verifySchema": "graphql-inspector diff generated/schema.graphql branch-schema/schema.graphql",

Dengan perintah ini, sekarang kita akan menambahkan melangkah. Kita memerlukan hasil dari perintah ini untuk dapat mendeskripsikan status perubahan yang dapat dihentikan, jadi kita menyimpan outputnya ke dalam referensi variabel.

name: Schema Change Verification
...

jobs:
  generateChangedSchema:
    ...
  performSchemaVerification:
    runs-on: [ubuntu-latest]
    needs: generateChangedSchema
    steps:
      ...
      - name: Generate main schema
        run: |
          cd services/api-gateway
          node graph:generateSchema
          OUTPUT=$(node graph:verifySchema || true)

Jika menyangkut hasil operasi diff, banyak yang dicetak ke konsol. Dalam konteks komentar PR, penulis hanya peduli pada informasi dalam konteks perubahannya. Jadi kami akan mengekstrak informasi ini dari keluarannya sehingga kami dapat menggunakannya untuk komentar PR.

Apa yang ingin kita ekstrak dimulai dengan “N perubahan yang mengganggu terdeteksi”, jadi kita akan menggunakannya untuk mengekstrak teks dari keluaran diff.

name: Schema Change Verification
...

jobs:
  generateChangedSchema:
    ...
  performSchemaVerification:
    runs-on: [ubuntu-latest]
    needs: generateChangedSchema
    steps:
      ...
      - name: Generate main schema
        run: |
          cd services/api-gateway
          node graph:generateSchema
          OUTPUT=$(node graph:verifySchema || true)
          // grab everything after the Detected string
          CONTENT=$OUTPUT#*Detected
          // reapply the Detected string at the start of the contnet
          FORMATTED="Detected"$CONTENT
          // write the extracted content to an environment variable
          echo "PR_COMMENT<<EOF" >> $GITHUB_ENV
          echo "$FORMATTED" >> $GITHUB_ENV
          echo "EOF" >> $GITHUB_ENV

Pada titik ini, kita sekarang memiliki pesan anotasi yang disimpan dalam variabel lingkungan, yang akan terlihat seperti berikut, bergantung pada hasil diff.

Detected the following changes (1) between schemas:
[log] ✖ Input field aNewType of type String! was added to input object type OrganizationIdInput
[error] Detected 1 breaking change

Sekarang setelah kami memilikinya, kami ingin mempublikasikannya sebagai komentar di Pull Request. Untuk ini kami akan menggunakan Buat atau perbarui komentar Tindakan, menerbitkan konten variabel lingkungan yang dibuat sebelumnya.

name: Schema Change Verification
...

jobs:
  generateChangedSchema:
    ...
  performSchemaVerification:
    runs-on: [ubuntu-latest]
    needs: generateChangedSchema
    steps:
      ...
      - name: Create comment
        uses: peter-evans/create-or-update-comment@v1
        with:
          issue-number: $ github.event.pull_request.number 
          body: $ env.PR_COMMENT 
        if: $ !contains(env.PR_COMMENT, 'No changes detected') 

Sekarang kita mengetahui status perubahan yang dapat menyebabkan gangguan, kita akan menetapkan status pemeriksaan PR berdasarkan ini. Di sini kita akan menambahkan langkah baru ke pekerjaan kita, namun hanya menjalankan langkah ini jika anotasi yang dihasilkan tidak mengandung label “sukses”.

Hal ini karena secara default operasi akan berstatus berhasil dan hanya akan muncul sebaliknya jika kita secara manual menandainya sebagai gagal (atau gagal karena alasan lain). Dalam hal ini kami akan memanfaatkan skrip github Tetapkan tindakan untuk memeriksa status kegagalan dan alasan kegagalan.

Dengan cara ini pemeriksaan permintaan penarikan akan gagal dan penulis tidak akan dapat menggabungkan permintaan penarikan hingga masalah teratasi.

name: Schema Change Verification
...

jobs:
  generateChangedSchema:
    ...
  performSchemaVerification:
    steps:
      ...
      - name: Set Breaking Change status
        if: $ !contains(env.PR_COMMENT, 'success') 
        uses: actions/github-script@v3
        with:
          script: |
            core.setFailed('Schema Breaking Changes detected')

bungkus

Setelah menyelesaikan semua hal di atas, sekarang kita dapat melihat status perubahan yang dapat menyebabkan gangguan diposting sebagai komentar pada Permintaan Tarik. Untuk status sukses, teknisi akan diberi tahu tentang perubahan skema mereka dan disorot bahwa tidak ada perubahan yang dapat menyebabkan gangguan terdeteksi.

Di sisi lain, setiap perubahan signifikan akan disorot dalam komentar yang diposting.

Ketika terjadi perubahan yang dapat menyebabkan gangguan, pemeriksaan akan ditandai sebagai gagal dan permintaan penarikan tidak akan digabungkan.

Sekarang setelah kami menerapkan pemeriksaan perubahan yang dapat menyebabkan gangguan, teknisi tidak akan dapat menggabungkan perubahan yang merusak pengalaman pelanggan. Hal ini mengurangi waktu henti pengguna, meningkatkan kepercayaan terhadap produk kami, dan mengurangi biaya bisnis manajemen insiden.

Jika Anda belum menggunakan pemeriksaan perubahan yang dapat menyebabkan gangguan di CI, mulailah sekarang! Saya ingin mendengar apa pun yang telah Anda pelajari saat menerapkannya ke dalam alur kerja pengembangan Anda. Silakan tinggalkan komentar di bawah atau temukan saya di LinkedIn.