Πώς να σχεδιάσετε ένα εργαλείο CLI που οι προγραμματιστές αγαπούν πραγματικά να χρησιμοποιούν

Στο προηγούμενο άρθρο μου, , διερευνήσαμε πώς να δημιουργήσετε ένα εργαλείο CLI από την αρχή. Τώρα, ας κάνουμε το επόμενο βήμα - πώς το κάνετε καλό; Τελικά, το κλειδί έγκειται στην ευκολία χρήσης. Ένα καλά σχεδιασμένο CLI αισθάνεται διαισθητικό, προβλέψιμο και αποτελεσματικό για τον χρήστη. Ωστόσο, αυτή η ευκολία χρήσης επιτυγχάνεται μέσω αρκετών ξεχωριστών αρχών σχεδιασμού, τις οποίες θα διερευνήσουμε σε αυτό το άρθρο. Μάθετε την τέχνη της γραμμής εντολών: Ο τελικός οδηγός σας για την ανάπτυξη ισχυρών εργαλείων Μάθετε την τέχνη της γραμμής εντολών: Ο τελικός οδηγός σας για την ανάπτυξη ισχυρών εργαλείων For demonstration, we’ll use the , αλλά οι αρχές ισχύουν για σχεδόν οποιοδήποτε πλαίσιο CLI που μπορεί να χρησιμοποιήσετε. Κάντε κλικ στην βιβλιοθήκη Python Παράμετροι Τα περισσότερα εργαλεία CLI δέχονται εισαγωγές από τον χρήστη. Στις περισσότερες περιπτώσεις, αυτή η εισαγωγή δεν είναι διαδραστική - έρχεται με τη μορφή Αυτό καθορίζει τον τρόπο με τον οποίο λειτουργεί το εργαλείο. parameters Για παράδειγμα, η Η εντολή λαμβάνει τουλάχιστον δύο παραμέτρους: cp Η διαδρομή προς το αρχείο ή τον κατάλογο για αντιγραφή και Ο δρόμος προς τον προορισμό. Μπορεί επίσης να υποστηρίξει προαιρετικές παραμέτρους όπως Αυτό επιτρέπει την απλή έκδοση. -v Σε γενικές γραμμές, υπάρχουν δύο τύποι παραμέτρων: και Στις περισσότερες βιβλιοθήκες CLI, οι απαιτούμενες παραμέτρους ονομάζονται (ή επιχειρήματα θέσης) και οι προαιρετικές παραμέτρους ονομάζονται . required optional arguments options Θετικά επιχειρήματα Όπως υποδηλώνει το όνομα, Ο χρήστης παρέχει τις τιμές σε μια συγκεκριμένη σειρά και το εργαλείο τις ερμηνεύει αναλόγως. positional arguments Για παράδειγμα, αν η Η εντολή αναμένει δύο επιχειρήματα θέσης - και - ο χρήστης θα το αποκαλούσε ως: cp πηγή Προορισμός cp source destination Ακόμη και αν το εργαλείο σας απαιτεί εισαγωγή, είναι συχνά κουραστικό (και περιττό) να κάνετε τους χρήστες να καθορίζουν κάθε τιμή χειροκίνητα. . if you can provide a sensible default, make it an option instead of an argument Για παράδειγμα, η Η παράμετρος μπορεί να Το να αναγκάζετε τους χρήστες να θυμούνται τη θέση και να μεταδίδουν πάντα πληροφορίες δεν προσθέτει αξία – προσθέτει μόνο τριβή. --log-level info Πολλαπλά επιχειρήματα Μερικές φορές ένα εργαλείο μπορεί να χρειαστεί να αποδεχθεί Ένα κοινό παράδειγμα είναι ο καθορισμός πολλαπλών αρχείων προέλευσης για αντιγραφή σε έναν ενιαίο κατάλογο προορισμού. Αυτό επιτρέπει στον χρήστη να εκτελέσει μία εντολή αντί για πολλές: multiple values cp source1 source2 destination Υπάρχουν κάποιες προειδοποιήσεις - τυπικά, Μπορεί να δέχεται πολλαπλές τιμές. ο κώδικας σας (όχι ο αναλυτής των στοιχείων) πρέπει να χειρίζεται πρόσθετη επικύρωση και λογική. only one argument Επιλογές επιτρέπουν στους χρήστες να καθορίζουν τις παραμέτρους με το όνομα, συχνά στη φόρμα Εάν ο χρήστης δεν παρέχει μια επιλογή, το εργαλείο χρησιμοποιεί την προεπιλεγμένη τιμή του. Options --option value Για παράδειγμα: --log-level debug Ένας ειδικός τύπος επιλογής είναι μια σημαία – δεν παίρνει αξία.Η απλή παρουσία της σημαίας διακόπτει μια συμπεριφορά, όπως η δυνατότητα λεκτικής εξόδου: --verbose Τα ονόματα επιλογής θα πρέπει να είναι Έτσι, οι χρήστες μπορούν εύκολα να κατανοήσουν το σκοπό τους. clear and descriptive Παράδειγμα εφαρμογής : @click.command() @click.option('--verbose', is_flag=True) @click.option('--log-level', default="info") @click.argument('srcs', nargs=-1) @click.argument('dst') def copy(verbose: bool, log_level: str, srcs: tuple[str, ...], dst: str): ... Τώρα, το εργαλείο μπορεί να καλέσει με διάφορους τρόπους: cp --verbose --log-level trace source1 source2 destination cp source destination Σύντομες επιλογές Μέχρι στιγμής, έχουμε χρησιμοποιήσει μεγάλα ονόματα επιλογών. Αυτά είναι ιδανικά για σενάρια, καθώς είναι αυτο-εξηγηματικά και εύκολα κατανοητά με μια ματιά. Ωστόσο, για γρήγορες, εφάπαξ εντολές, οι χρήστες συχνά προτιμούν όπως Αντί να Να είστε επιλεκτικοί όταν εισάγετε σύντομες φόρμες.Όχι κάθε επιλογή χρειάζεται μία. Εάν το εργαλείο σας έχει πολλές επιλογές, θα εξαντληθούν γρήγορα οι διαισθητικές γραμματοσειρές - ειδικά επειδή πολλές επιλογές μπορεί να ξεκινήσουν με την ίδια. . short options -v --verbose frequently used options Το παράδειγμα: @click.command() @click.option('-v', '--verbose', is_flag=True) @click.option('--log-level', default="info") @click.argument('srcs', nargs=-1) @click.argument('dst') def copy(verbose: bool, log_level: str, srcs: tuple[str, ...], dst: str): ... Τώρα λειτουργούν και οι δύο μορφές: cp -v source destination cp --verbose source destination Επιβεβαιώστε την είσοδο του χρήστη και αποτύχετε γρήγορα Ένα ισχυρό εργαλείο CLI θα πρέπει και αποτύχει με ένα σαφές, ενεργό μήνυμα. τα περισσότερα πλαίσια CLI υποστηρίζουν αυτό το μοτίβο. validate user input early Για παράδειγμα, το Click μπορεί να επιβάλει αυτόματα έγκυρα επίπεδα καταγραφής και επιχειρήματα διαδρομής: @click.command() @click.option('-v', '--verbose', is_flag=True) @click.option('--log-level', default="info", type=click.Choice(["debug", "info", "error"])) @click.argument('srcs', nargs=-1, type=click.Path()) @click.argument('dst', type=click.Path()) def copy(verbose: bool, log_level: str, srcs: tuple[str, ...], dst: str): ... However, you may still need Στην δική μας Το παράδειγμα: custom logic copy Εάν υπάρχει μία πηγή, ο προορισμός μπορεί να είναι ένα αρχείο ή ένας κατάλογος. Εάν υπάρχουν πολλαπλές πηγές, ο προορισμός πρέπει να είναι ένας κατάλογος - διαφορετικά τα αρχεία ενδέχεται να υπεργράψουν το ένα το άλλο απροσδόκητα. Οι γενικές βιβλιοθήκες CLI δεν θα χειρίζονται αυτές τις περιπτώσεις αυτόματα, οπότε αυτή η επικύρωση πρέπει να ζει στον κώδικα σας. Μήνυμα βοήθειας A good tool always provides a good . help message Οι χρήστες θα πρέπει να είναι σε θέση να εκτελέσουν κάτι σαν Για να δείτε: --help Ποιες παραμέτρους είναι διαθέσιμες Η σημασία τους Αποδεκτοί τύποι ή τιμές (π.χ. έγκυρα επίπεδα καταγραφής) Ένα σαφές μήνυμα βοήθειας εξοικονομεί χρόνο, μειώνει τα σφάλματα και βελτιώνει την εμπιστοσύνη των χρηστών στο εργαλείο σας. Ακολουθήστε τα οικοσυστήματα σας Τέλος, τα μεγάλα εργαλεία CLI αισθάνονται Μελετήστε άλλα εργαλεία στο περιβάλλον σας και ακολουθήστε τις συμβάσεις τους - ειδικά για . native naming options and arguments Για παράδειγμα, στον κόσμο του Unix, εργαλεία όπως , και Όλες οι χρήσεις και as positional arguments, with Πάντα προηγείται . cp mv rsync source destination source destination Συνεπείς ονομασίες και γνωστές επιστολές επιλογής ( Για τη Βουλή, Για την αναδρομή, Για το ξηρό τρέξιμο, για βοήθεια) να κάνετε το εργαλείο σας να αναμιχθεί ομαλά στη ροή εργασίας του χρήστη. -v -r -n -h/--help Όταν το εργαλείο σας αισθάνεται σαν ένα φυσικό μέρος του οικοσυστήματος, οι χρήστες θα είναι πολύ πιο πιθανό να το υιοθετήσουν - και να απολαύσουν τη χρήση του. Άλλες πτυχές Πέρα από τις παραμέτρους και τα επιχειρήματα, υπάρχουν αρκετοί άλλοι παράγοντες που διακρίνουν ένα Αυτές οι πτυχές επηρεάζουν τον τρόπο με τον οποίο το εργαλείο σας ενσωματώνεται με τα σενάρια, τον τρόπο με τον οποίο οι χρήστες χειραγωγούν τα προβλήματα και πόσο εύκολα ταιριάζει σε μεγαλύτερες ροές εργασίας. Καλή Κωδικός εξόδου Κάθε πρόγραμμα επιστρέφει ένα Ο κώδικας αυτός επιτρέπει στον καλούντα να γνωρίζει αν το πρόγραμμα πέτυχε ή απέτυχε. exit code Με τη σύμβαση: 0 σημαίνει επιτυχία Κάθε μη μη μηδενική τιμή υποδεικνύει σφάλμα Αν και δεν υπάρχει καθολικό πρότυπο για τους κωδικούς εξόδου, είναι καλή πρακτική να . exit with a non-zero code on any error Για καλύτερη συνέπεια, σκεφτείτε να ακολουθήσετε τις συμβάσεις από το Αυτά είναι ευρέως αναγνωρισμένα στον κόσμο του Unix. Προηγμένος οδηγός Bash-Scripting Θα πρέπει επίσης να Να τις συμπεριλάβουμε στην Όταν οι χρήστες ή τα συστήματα αυτοματισμού κατανοούν τι σημαίνει ο κώδικας εξόδου 3, μπορούν να χειριστούν τα σφάλματα πιο έξυπνα (π.χ. retry, skip, ή alert). document your exit codes --help Στέφανος vs Στέφανος Ένα καλά διαχειριζόμενο εργαλείο CLI διακρίνει μεταξύ των δύο τυποποιημένων ροών εξόδου: STDOUT – για τακτική, αναμενόμενη παραγωγή STDERR – για σφάλματα, προειδοποιήσεις ή διαγνωστικά μηνύματα Αυτός ο διαχωρισμός επιτρέπει στους χρήστες και τα σενάρια να χειρίζονται ανεξάρτητα κάθε ροή. Για παράδειγμα, ένας χρήστης μπορεί να ανακατευθύνει την κανονική έξοδο σε ένα αρχείο, διατηρώντας παράλληλα τα μηνύματα σφάλματος ορατά στην κονσόλα: mytool > output.txt Για να καταργήσετε τα λάθη: mytool 2>/dev/null Εάν το εργαλείο σας γράφει τόσο δεδομένα όσο και σφάλματα στο STDOUT, οι χρήστες θα πρέπει να φιλτράρουν την έξοδο χειροκίνητα - και αυτό είναι εύθραυστο. Ειδικά αν η παραγωγή του εργαλείου σας καταναλώνεται από άλλα προγράμματα, η διατήρηση του STDOUT καθαρή και προβλέψιμη είναι απαραίτητη. ΦΩΤΟΓΡΑΜΜΑ ΕΞΟΔΟΥ Εάν το εργαλείο σας παράγει δεδομένα που μπορεί να καταναλωθούν από άλλα εργαλεία ή σενάρια, είναι σοφό να υποστηρίξετε μορφές όπως το JSON ή το YAML. machine-readable output Για παράδειγμα: mytool --output json Αυτό καθιστά την αυτοματοποίηση πολύ πιο εύκολη - άλλα εργαλεία μπορούν να χρησιμοποιήσουν τυπικούς αναλυτές αντί να βασίζονται σε εύθραυστη ανάλυση σειράς που σπάει κάθε φορά που αλλάζει ο διαχωρισμός, η ευθυγράμμιση ή η διάκριση. Ωστόσο, μην θυσιάσετε την ανθρώπινη αναγνωσιμότητα. Πολλοί χρήστες θα εξακολουθήσουν να εκτελούν το εργαλείο σας διαδραστικά. Από προεπιλογή σε ανθρώπινη αναγνώσιμη εξαγωγή (nicely μορφοποιημένο κείμενο) Προσφέρετε μια σημαία (π.χ. μορφή --json ή --αν θέλετε να υποστηρίξετε πολλαπλές μορφές) για δομημένη έξοδο Ορισμένα εργαλεία CLI παρέχουν επίσης , στέλνοντας όμορφα τυπωμένο κείμενο όταν γράφετε σε ένα τερματικό, αλλά JSON όταν τροφοδοτείται σε άλλη διαδικασία - παρόμοιο με το πώς or Να συμπεριφέρεσαι auto-detection kubectl gh Λάθος μηνύματα Ένα καλό μήνυμα σφάλματος πρέπει να είναι: — state what went wrong Clear Λειτουργικό - προτείνετε πώς να το διορθώσετε Συνεπής - χρησιμοποιήστε τον ίδιο τόνο και δομή σε όλη τη διάρκεια Το κακό παράδειγμα: Error: failed Καλύτερο παράδειγμα : Error: Could not open file '/tmp/input.txt' — file not found. Hint: Verify that the path is correct and you have read permissions. Η καλή διαχείριση σφαλμάτων εξοικονομεί χρόνο στους χρήστες και τους βοηθά να οικοδομήσουν εμπιστοσύνη στο εργαλείο σας. Λογισμικό και Verbosity Οι χρήστες εκτιμούν τον έλεγχο σχετικά με το πόσες πληροφορίες βλέπουν. Σιωπή για ελάχιστη παραγωγή --verbose για λεπτομερή μηνύματα --debug για την παρακολούθηση σε επίπεδο προγραμματιστή Σχεδιάστε τα επίπεδα καταγραφής σας έτσι ώστε οι χρήστες να μπορούν να επιλέξουν το σωστό ποσό πληροφοριών για το πλαίσιο τους. Όταν συνδυάζονται με τους σωστούς κωδικούς εξόδου, αυτά τα επίπεδα καθιστούν την απομάκρυνση και την αυτοματοποίηση πολύ πιο ομαλή. Ανταπόκριση και απόδοση Εάν το CLI σας εκτελεί βαριές εργασίες, εξετάστε την παροχή ή Για παράδειγμα: progress indicators spinners Downloading files... 45% complete Ταυτόχρονα, αποφύγετε περιττές κινούμενες εικόνες ή εξόδους όταν το εργαλείο εκτελείται σε μη διαδραστική λειτουργία (π.χ. ως μέρος ενός script). Συμπέρασμα Η δημιουργία ενός εργαλείου CLI είναι σχετικά εύκολη. Ένα καλό εργαλείο γραμμής εντολών αισθάνεται φυσικό, συμπεριφέρεται προβλέψιμα και εξαφανίζεται ήσυχα στην ροή εργασίας του χρήστη. - προσαρμόζεται στον τρόπο με τον οποίο λειτουργούν ήδη οι χρήστες. good Αυτό Σε όλο αυτό το άρθρο, έχουμε εξετάσει τι συμβάλλει σε αυτή την εμπειρία: Σαφείς και συνεπείς παράμετροι που εξισορροπούν την απλότητα και την ευελιξία Σημαντικοί κωδικοί εξόδου που επικοινωνούν επιτυχία ή αποτυχία Σωστή χρήση STDOUT και STDERR για τον διαχωρισμό των δεδομένων από τη διάγνωση Διαβαστές και δομημένες μορφές εξόδου τόσο για ανθρώπους όσο και για μηχανές Χρήσιμα μηνύματα σφάλματος και προβλέψιμη συμπεριφορά Συμμόρφωση με τις συμβάσεις του οικοσυστήματός σας, έτσι ώστε το εργαλείο σας να αισθάνεται εξοικειωμένο από την πρώτη κίνηση Ultimately, the best CLI tools share a common trait: they Ξεκινάνε γρήγορα, αποτυγχάνουν γρήγορα, εξηγούνται με σαφήνεια και ενσωματώνονται ομαλά σε μεγαλύτερα συστήματα και σενάρια. respect the user’s time Εάν έχετε αυτές τις αρχές στο μυαλό σας - σαφήνεια, συνέπεια και ενσυναίσθηση για τους χρήστες σας - το εργαλείο CLI σας δεν θα Θα είναι ευχαρίστηση να το χρησιμοποιήσετε. Εργασία