У своїй попередній статті, , ми досліджували, як побудувати інструмент CLI з нуля. Тепер давайте зробимо наступний крок - як зробити його хорошим? В кінцевому підсумку, ключ полягає в простоті використання. Добре розроблений CLI відчуває себе інтуїтивно, передбачувано і ефективно для користувача. Однак, ця простота використання досягається через кілька різних принципів дизайну, які ми дослідимо в цій статті. Майстер мистецтва командної лінії: ваш остаточний посібник для розробки потужних інструментів Майстер мистецтва командної лінії: ваш остаточний посібник для розробки потужних інструментів Для демонстрації ми будемо використовувати , але принципи застосовуються практично до будь-якої рамки 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 підтримують цей шаблон. 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):
   ...
 Тим не менш, вам може знадобитися В нашому Приклад : custom logic copy 
 
 
 Якщо є одне джерело, то призначення може бути файлом або каталогом. Якщо існує кілька джерел, то місцем призначення має бути каталог — інакше файли можуть несподівано переписуватися. Загальні бібліотеки CLI не будуть автоматично обробляти такі випадки, тому ця валідація повинна жити у вашому коді. Повідомлення про допомогу Хороший інструмент завжди дає хороший . help message Користувачі повинні мати можливість виконувати такі функції, як щоб побачити: --help 
 
 
 
 Які параметри доступні Їх значення Прийняті типи або значення (наприклад, дійсні рівні журналу) Ясне повідомлення про допомогу заощаджує час, зменшує помилки та покращує довіру користувачів до вашого інструменту. Слідкуйте за своїми екосистемами Нарешті, чудові інструменти CLI відчувають Вивчайте інші інструменти у своєму середовищі і дотримуйтеся їх конвенцій - особливо для . native naming options and arguments Наприклад, у світі Unix такі інструменти, як , І Усі використання та Як аргументи позиції, з Завжди передує . cp mv rsync source destination source destination Повна назва і відомі варіанти листів ( для слів, Для рецидивуючих Для сухого бігу, для допомоги) зробити ваш інструмент бездоганно змішується в робочий процес користувача. -v -r -n -h/--help Коли ваш інструмент відчувається як природна частина екосистеми, користувачі будуть набагато частіше приймати його - і насолоджуватися його використанням. Інші аспекти Beyond parameters and arguments, there are several other factors that distinguish a  Ці аспекти впливають на те, як ваш інструмент інтегрується зі скриптами, як користувачі відправляють проблеми, і наскільки легко він вписується в більші робочі процеси. Доброго Вихідні коди Кожна програма повертає  when it finishes execution. This code lets the caller know whether the program succeeded or failed. exit code Згідно з Конвенцією: 
 
 
 0 означає успіх Будь-яке значення, що не є нульовим, вказує на помилку Хоча немає універсального стандарту для кодів виходу, це хороша практика, щоб принаймні . exit with a non-zero code on any error Для кращої послідовності розглянемо наступні конвенції: Вони широко визнані у світі Unix. Розширений Bash-Scripting Guide Ви також повинні Включити їх у  output or the tool’s manual page. When users or automation systems understand what exit code 3 means, they can handle errors more intelligently (e.g., retry, skip, or alert). document your exit codes --help Стрілець проти STDERR Хороший інструмент CLI розрізняє два стандартних потоки виходу: 
 
 
 STDOUT — для регулярного, очікуваного виходу STDERR — для помилок, попереджень або діагностичних повідомлень Наприклад, користувач може перенаправляти нормальний вихід на файл, зберігаючи на консолі видимі повідомлення про помилки: mytool > output.txt
 Щоб усунути помилки: mytool 2>/dev/null
 Якщо ваш інструмент записує як дані, так і помилки в STDOUT, користувачам доведеться фільтрувати вихід вручну - і це крихко. Особливо якщо вихід вашого інструменту споживається іншими програмами, важливо, щоб STDOUT був чистим і передбачуваним. Output format Якщо ваш інструмент виробляє дані, які можуть бути спожиті іншими інструментами або скриптами, мудро підтримувати форматів, таких як JSON або YAML. machine-readable output Наприклад: mytool --output json
 Це робить автоматизацію набагато простішою — інші інструменти можуть використовувати стандартні аналізатори замість того, щоб покладатися на аналіз крихких струн, які руйнуються, коли змінюються проміжки, вирівнювання або пунктування. Однак, не жертвуйте людською читабельністю. Багато користувачів все ще будуть запускати ваш інструмент інтерактивно. Найкращий підхід - це: 
 
 
 За замовчуванням до людського читального виходу (неформатований текст) Запропонуйте флаг (наприклад, --json або --format, якщо ви хочете підтримувати кілька форматів) для структурованого виходу Деякі інструменти CLI також забезпечують , відправляючи досить друкований текст при написанні в термінал, але JSON при переході в інший процес - схожий на те, як або поводитися auto-detection kubectl gh Помилки повідомлення Повідомлення про помилку має бути: 
 
 
 
 Яскраво — вкажіть, що пішло не так Дієздатний — пропонуємо, як його виправити Послідовність — використовуйте один і той же тон і структуру протягом усього Поганий приклад: 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.
 Хороше поводження з помилками економить час користувачів і допомагає їм побудувати довіру до вашого інструменту. Логістика і вербосність Користувачі цінують контроль над тим, скільки інформації вони бачать. 
 
 
 
 • Тихий для мінімальної продуктивності — verbose для детальних повідомлень - Debug для відстеження на рівні розробника Створіть рівні журналу, щоб користувачі могли вибрати правильну кількість інформації для свого контексту. У поєднанні з правильними кодами виходу ці рівні роблять дебування та автоматизацію набагато плавнішими. Responsiveness and Performance Якщо ваш CLI виконує важкі операції, розгляньте або Наприклад: progress indicators spinners Downloading files... 45% complete
 У той же час, уникайте непотрібних анімацій або вихід, коли інструмент працює в неінтерактивному режимі (наприклад, як частина сценарію). Висновок Building a CLI tool is relatively easy. Making a  Хороший інструмент командного рядка відчуває себе природно, поводиться передбачувано і тихо зникає в робочий процес користувача. — вона адаптується до того, як користувачі вже працюють. good Це Протягом всієї цієї статті ми розглянули, що сприяє цьому досвіду: 
 
 
 
 
 
 
 Ясні і послідовні параметри, які балансують між простотою та гнучкістю Значущі вихідні коди, які повідомляють про успіх або провал Правильне використання STDOUT і STDERR для відділення даних від діагностики Читані та структуровані формати випуску для людей та машин Корисні повідомлення про помилки та передбачувану поведінку Дотримання конвенцій вашої екосистеми, так що ваш інструмент відчуває себе знайомим з першого разу Зрештою, кращі інструменти CLI мають одну спільну особливість: вони Вони починаються швидко, проваляються швидко, пояснюють себе чітко і бездоганно інтегруються в більші системи і скрипти. respect the user’s time Якщо ви маєте на увазі ці принципи - чіткість, послідовність і співпереживання для ваших користувачів - ваш інструмент CLI не тільки Це буде приємно використовувати. роботи

Walkthroughs, tutorials, guides, and tips. This story will teach you how to do something new or how to do something better.

Read My Stories

Це аудіо створено мовою оригіналу історії!

Як розробити інструмент CLI, який розробники дійсно люблять використовувати

About Author

КОМЕНТАРІ

ПОВІСИТИ БИРКИ

ЦЯ СТАТТЯ БУЛА ПРЕДСТАВЛЕНА В

Related Stories

Light-Mode

Classic

Newspaper

Dark-Mode

Neon Noir

Minty

HN StartUps