Membangunkan CLI

Membina ciri CLI selalunya berpunca daripada:

• Keluarkan titik akhir API baharu.
• Bina tindakan CLI baharu yang memerlukan perubahan API.
• Sedar kesilapan telah dibuat dalam API yang baru anda keluarkan.
• Cuba betulkan API untuk ciri ini tanpa menimbulkan lebih banyak masalah pada masa hadapan.
• Cuba ingat apa yang anda cuba capai dalam CLI dan kemudian benar-benar mencapainya.  
• GOTO: sedar kesilapan telah dilakukan.

Setiap langkah memerlukan langkah sebelumnya dan oops kami telah mencipta semula pengurusan projek air terjun. Anda akan letih dengan kesakitan yang cuba untuk menebus kesilapan dengan anggun sehingga anda lemas untuk berfungsi, tetapi tunduk dengan baik sebelum luar biasa. Dan jangan biarkan saya mula mengekalkan kelompok "pembetulan" ad-hoc dan ketuat yang terhasil.

Pernah ke sana, lakukan itu. Kami tahu kami perlu melepasi pendekatan seperti air terjun.

Berikut ialah kisah bagaimana kami sampai ke sana dan beberapa alatan yang membantu sepanjang perjalanan.

Pergi ke Permulaan Sketchy

Kami mahukan lelaran yang murah dan pantas sehingga kami memahami ciri tersebut, dan kemudian komited kepada pelaksanaan yang mahal dan sokongan jangka panjang. Sebagai sebuah pasukan kecil, saya sering melakukan proses ini hujung ke hujung, dan mahu fokus pada setiap bahagian secara bergilir-gilir. Kami mahu memalsukan bahagian pelaksanaan sehingga kami berasa cukup yakin untuk membuatnya.

Berbalik kepada proses, ia bermula dengan mencadangkan ciri. Kami mahu keluar dari abstrak, tetapi tidak jika ia bermaksud pelaksanaan separuh masak. Kami memalsukannya dengan "lakaran", diilhamkan oleh pendekatan lakaran Google Docs CLI yang diterangkan Github di sini.

Malangnya, lakaran statik tidak memberikan maklum balas yang kami mahukan. CLI kami mengubah output dari semasa ke semasa, lebih seperti animasi daripada lukisan. Untuk mencapai kesetiaan yang lebih tinggi, saya menulis program Ruby kecil untuk mengambil input asas dan bertindak balas dengan mencetak respons dalam tin yang sesuai.

Sejak itu kami telah menemui cara yang lebih baik untuk menangkap output CLI animasi, tetapi untuk menjelaskannya memerlukan sedikit lencongan.

Adakah Anda Malah Menguji?

Semasa kami mula menyempurnakan CLI kami, kami juga ingin menguji kes tepi dan mengesan regresi. Saya meninjau CLI berasaskan ular tedung/bubbletea awam untuk mencari idea, dan mendapati beberapa ujian yang mengecewakan. Kemudian kami terjumpa teatest Charm yang memberi kami titik permulaan.

Teatest memfokuskan pada ujian emas, merakam keluaran bagus yang diketahui dan kemudian menegaskan bahawa keluaran masa hadapan terus sepadan dengannya. Yang membawa kami kembali, sekali lagi, kepada menangkap kesetiaan tinggi output CLI animasi. Teatest memberi kami idea hebat tentang penyelesaian berasaskan bingkai, seperti buku flip, yang telah kami bina di atasnya:

─── SigninHeader ───────────────────────────────────────────────────────────────
# Signin To Your CLI Account `cli auth signin`
─── SigninInput --──────────────────────────────────────────────────────────────
# Signin To Your CLI Account `cli auth signin`
    ? What is your username?
    ? user
─── SigninInput ────────────────────────────────────────────────────────────────
# Signin To Your CLI Account `cli auth signin`
    * Signing in to your CLI account… ⠋
─── SigninInput ────────────────────────────────────────────────────────────────
# Signin To Your CLI Account `cli auth signin`
    * Signed in to your CLI account: user@example.com

Contoh ringkas ini menunjukkan rupa output emas untuk arahan kebenaran asas. Garis mendatar menggambarkan bingkai, dengan label yang menunjukkan model aktif. Disatukan, kami mendapat tangkapan output ketelitian tinggi walaupun garisan ditambah, dialih keluar atau diganti.

Kami menggunakan bendera dalam suite ujian kami untuk mengemas kini fail dengan output emas, dan sebaliknya ujian gagal jika output tidak sepadan dengan fail. Ini membuatkan kami sedar tentang perubahan output dan memudahkan semakan PR dengan membenarkan kami memahami rupa output yang sepatutnya dan jika ia telah berubah. Kami sangat menyukainya sehingga kami bercadang untuk menggantikan program lakaran kami dengan output gaya emas dalam dokumen google gaya Github supaya kami boleh menangkap kedua-dua idea animasi dan gaya.

Dengan lakaran kami yang dahulu dan akan datang, mari kita kembali untuk bermula dengan titik akhir API baharu.

Merekabentuk API dan CLI Bersama

Kami mengusahakan API dan CLI secara serentak, kerana reka bentuk terbaik untuk ini berkembang daripada penyepaduan yang ketat. Kami dapat melakukan ini, sambil masih mengelakkan bahaya air terjun, dengan mengulangi reka bentuk dalam konteks yang lebih murah dan menunggu untuk melaksanakan sehingga keperluan menjadi kukuh. Untuk API kami, ini bermakna membuat lakaran dengan OpenAPI:

openapi: 3.1.0
info:
  contact:
    email: contact@example.com
  description: An example API.
  title: Example API
  version: 0.0.1
servers:
  - url: https://api.example.com
tags:
  - description: account operations
    name: account
paths:
  '/v0/auth/signin':
    post:
      description: Signin to CLI.
      operationId: auth_signin
      responses:
        '200':
          content:
            'application/json':
              schema:
                additionalProperties: false
                properties:
                  email:
                    description: Email address for authenticated user.
                    example: username@example.com
                    type: string
                required:
                  - email
                type: object
          description: Successful signin.
      summary: Signin to CLI.
      tags:
        - account

Contoh ringkas ini menunjukkan rupa skema untuk arahan kebenaran asas. Kami menggunakan linter spektrum untuk memudahkan kerja pada fail ini.

Dengan lakaran di tangan, kami kemudian menggunakan prisma sebagai pelayan API olok-olok semasa kami melaksanakan CLI. Apabila kita tidak dapat tidak menyedari kesilapan telah dibuat, kita hanya boleh mengubah suai spesifikasi dan kembali kepada lelaran CLI kami. Bekerja pada tahap tinggi ini membolehkan kami mengembangkan API dan CLI bersama-sama dan menangguhkan pelaksanaan yang mahal sehingga kami mempunyai pengetahuan yang lebih baik.

Melaksanakan API

Kami juga bergantung pada spesifikasi OpenAPI kami untuk memastikan kami jujur ​​semasa pelaksanaan menggunakan jawatankuasa. assert_schema_conform menguji penjajaran dan middleware memberitahu kami tentang sebarang percanggahan langsung. Ini digabungkan untuk membolehkan pelaksanaan hijau merah sambil melindungi kami daripada regresi.

Menguji dengan Olok-olok dan Proksi

Untuk melengkapkan perkara, suite ujian kami menggunakan bendera untuk menjalankan prisma sama ada dalam mod olok-olok atau proksi. Dengan menggunakan bendera kita boleh menumpukan pada menulis hanya satu jenis ujian, walaupun ini bermakna kita melangkau beberapa ujian dalam satu mod atau yang lain. Kami menggunakan ujian olok-olok untuk kelajuannya dan pada Windows dan macOS di mana tindanan penuh kami tidak dijalankan dalam CI. Ujian proksi kami membolehkan kami menjalankan ujian terhadap keseluruhan timbunan kami hanya dengan menambahkan bendera, menjadikannya mudah untuk menjalankan ujian hujung ke hujung apabila kami rasa perlu.

Menariknya Bersama-sama

Lakaran dan spesifikasi membantu kami melepasi abstrak tanpa perlu terperangkap dalam pelaksanaan. Kemudian olok-olok dan proksi membantu kami memastikan pelaksanaan sepadan dengan lakaran. Dengan terus mengulangi proses kami, setiap ciri menyebabkan lebih sedikit kesakitan, yang amat kami hargai sambil membina pengalaman pasukan yang akan kami sampaikan pada akhir bulan ini.

Kami akan terus mengulangi proses kami, saya harap anda belajar sesuatu daripadanya dan saya ingin belajar daripada anda. Apa yang anda telah cuba, di manakah anda berbangga dan apa yang masih mengecewakan?

Atas ialah kandungan terperinci Membangunkan CLI. Untuk maklumat lanjut, sila ikut artikel berkaitan lain di laman web China PHP!