Mano ankstesniame straipsnyje, , mes išnagrinėjome, kaip sukurti CLI įrankį nuo pat pradžių. Dabar imkime kitą žingsnį – kaip tai padaryti gerai? Galų gale, raktas yra naudojimo paprastumas. Gerai suprojektuotas CLI jaučiasi intuityvus, nuspėjamas ir efektyvus vartotojui. Tačiau šis naudojimo paprastumas pasiekiamas naudojant keletą skirtingų dizaino principų, kuriuos išnagrinėsime šiame straipsnyje. Valdymo linijos menas: jūsų galutinis vadovas, kaip kurti galingus įrankius Valdymo linijos menas: jūsų galutinis vadovas, kaip kurti galingus įrankius Demonstravimo tikslais mes naudosime , bet principai taikomi beveik bet kuriai CLI sistemai, kurią galite naudoti. „Python“ biblioteka Parametrai Dauguma CLI įrankių priima vartotojo įvestį. Daugeliu atvejų šis įvestis nėra interaktyvus – jis ateina kaip  that define how the tool behaves. parameters Pavyzdžiui, į Komanda turi turėti bent du parametrus: cp 
 
 
 Kelias į failą ar katalogą, kurį norite nukopijuoti, ir Kelias į paskirties vietą. Taip pat galima pasirinkti tokius parametrus kaip Tai leidžia sukurti verbalinį išvestį. -v Apskritai yra dviejų tipų parametrai: ir Daugumoje CLI bibliotekų reikalaujami parametrai vadinami (arba pozicijos argumentai), o pasirenkami parametrai vadinami . required optional arguments options Teigiami argumentai Kaip rodo pavadinimas, Vartotojas pateikia reikšmes tam tikra tvarka, o įrankis jas atitinkamai interpretuoja. positional arguments Pavyzdžiui, jei Komanda tikisi dviejų pozicijų argumentų - ir Vartotojas tai vadintų: cp Šaltinis Paskirties cp source destination
 Net jei jūsų įrankis reikalauja įvesties, dažnai sunku (ir nereikalinga) reikalauti, kad vartotojai kiekvieną reikšmę nurodytų rankiniu būdu. . if you can provide a sensible default, make it an option instead of an argument Pavyzdžiui, a Parametrai gali išnykti Priversti vartotojus prisiminti poziciją ir visada perduoti informaciją neprideda vertės – tai tik prideda trinties. --log-level info Daugybė argumentų Kartais įrankis gali prireikti priimti  for a single argument. A common example is specifying multiple source files to copy into a single destination directory. This allows the user to run one command instead of several: multiple values cp source1 source2 destination
 Yra keletas įspėjimų - paprastai Jūsų kodas (o ne argumentų analizatorius) turi tvarkyti papildomą patvirtinimą ir logiką. only one argument Pasirinkimai leidžia vartotojams nurodyti parametrus pagal pavadinimą, dažnai formą Jei vartotojas nepateikia parinkties, įrankis naudoja numatytąją reikšmę. Options --option value Pavyzdžiui: --log-level debug
 Ypatingas variantas yra vėliava – ji neturi reikšmės. vien vėliavos buvimas pakeičia elgesį, pvz., leidžia žodinį išvestį: --verbose
 Alternatyvūs pavadinimai turėtų būti Naudotojas gali lengvai suprasti savo tikslą. clear and descriptive Įgyvendinimo pavyzdžiai: @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):
   ...
 Dabar įrankį galima vadinti keliais būdais: cp --verbose --log-level trace source1 source2 destination
cp source destination
 Trumpi pasirinkimai Iki šiol mes naudojome ilgus parinkčių pavadinimus, kurie idealiai tinka scenarijams, nes jie yra savaime paaiškinami ir lengvai suprantami iš pirmo žvilgsnio. Tačiau, norint greitai, vienkartinius komandas, vartotojai dažnai nori Kaip Vietoj Būkite selektyvūs įvedant trumpas formas.Ne kiekviena parinktis turi vieną.Jei jūsų įrankis turi daug parinkčių, greitai išnyks intuityvios raidės – ypač todėl, kad kelios parinktys gali prasidėti tuo pačiu. . short options -v --verbose frequently used options Pavyzdys : @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):
   ...
 Dabar abi formos veikia: cp -v source destination
cp --verbose source destination
 Vartotojo įvesties patvirtinimas ir greitas gedimas Stiprus CLI įrankis turėtų ir nepavyksta su aiškiu, veiksmingu pranešimu. Dauguma CLI sistemų palaiko šį modelį. validate user input early For example, Click can enforce valid log levels and path arguments automatically: @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):
   ...
 Tačiau jums vis dar gali prireikti Į mūsų Pavyzdys : custom logic copy 
 
 
 Jei yra vienas šaltinis, paskirties vieta gali būti failas arba katalogas. Jei yra keletas šaltinių, paskirties vieta turi būti katalogas - kitaip failai gali netikėtai užrašyti vienas kitą. Bendrosios CLI bibliotekos tokių atvejų neapdoroja automatiškai, todėl šis patvirtinimas turi būti jūsų kodas. Pagalbos žinutė Geras įrankis visada suteikia gerą . help message Vartotojai turėtų galėti paleisti kažką panašaus Žiūrėti čia: --help 
 
 
 
 Kokie parametrai yra prieinami Jų reikšmė Priimti tipai arba reikšmės (pvz., galiojantys žurnalo lygiai) Aiškus pagalbos pranešimas taupo laiką, sumažina klaidas ir pagerina vartotojų pasitikėjimą savo įrankiu. Sekite savo ekosistemos modelius Galiausiai, puikūs CLI įrankiai jaučiasi Studijuokite kitus įrankius savo aplinkoje ir laikykitės jų konvencijų – ypač . native naming options and arguments Pavyzdžiui, „Unix“ pasaulyje tokios priemonės kaip , ir Visą naudojimą ir kaip pozicijos argumentus, su Visada priešakyje . cp mv rsync source destination source destination Nuoseklūs vardai ir pažįstamos pasirinkimo raidės ( Dėl žodžių dėl atsinaujinimo, Dėl sauso bėgimo, už pagalbą) padaryti, kad jūsų įrankis sklandžiai įterptų į vartotojo darbo eigą. -v -r -n -h/--help Kai jūsų įrankis jaučiasi kaip natūrali ekosistemos dalis, vartotojai bus daug labiau linkę jį priimti ir mėgautis. Kiti aspektai Be parametrų ir argumentų, yra keletas kitų veiksnių, kurie išskiria Šie aspektai turi įtakos, kaip jūsų įrankis integruojasi su scenarijais, kaip vartotojai išsprendžia problemas ir kaip lengvai jis tinka didesniems darbo srautams. Geras Išėjimo kodai Kiekviena programa grąžina Šis kodas leidžia skambinančiajam žinoti, ar programa pavyko, ar nepavyko. exit code Pagal konvenciją : 
 
 
 0 reiškia sėkmę Bet kuri ne nulinė reikšmė rodo klaidą Nors nėra universalaus išėjimo kodų standarto, gera praktika yra bent jau . exit with a non-zero code on any error Siekiant geresnio nuoseklumo, apsvarstykite, kaip laikytis konvencijų iš Jie plačiai pripažįstami Unix pasaulyje. Išplėstinis Bash-Scripting vadovas Jūs taip pat turite Įtraukti juos į Kai vartotojai ar automatizavimo sistemos supranta, ką reiškia išėjimo kodas 3, jie gali tvarkyti klaidas protingiau (pvz., atnaujinti, praleisti ar įspėti). document your exit codes --help Žvaigždė prieš Stenderį Gerai naudojamas CLI įrankis išskiria savo du standartinius išvesties srautus: 
 
 
 STDOUT – reguliariam, tikėtinam išėjimui STDERR – klaidoms, įspėjimams ar diagnostikos pranešimams Šis atskyrimas leidžia vartotojams ir scenarijams tvarkyti kiekvieną srautą atskirai.Pavyzdžiui, vartotojas gali nukreipti įprastą išvestį į failą, išlaikydamas klaidų pranešimus konsole: mytool > output.txt
 or suppress errors: mytool 2>/dev/null
 Jei jūsų įrankis parašo tiek duomenis, tiek klaidas STDOUT, vartotojams reikės filtruoti išvestį rankiniu būdu, o tai yra trapi. Ypač jei jūsų įrankio išvestį sunaudoja kitos programos, svarbu išlaikyti STDOUT švarą ir nuspėjamumą. Išėjimo formatas Jei jūsų įrankis gamina duomenis, kuriuos gali sunaudoti kiti įrankiai ar scenarijai, protinga palaikyti Formatas yra JSON arba YAML. machine-readable output Pavyzdžiui: mytool --output json
 Tai palengvina automatizavimą - kitos priemonės gali naudoti standartinius analizatorius, o ne pasikliauti trapiomis eilutėmis, kurios sulaužomos, kai pasikeičia tarpas, išlyginimas ar punktavimas. Tačiau nepraraskite žmogiškojo skaitymo. Daugelis vartotojų vis dar veiks jūsų įrankį interaktyviai. 
 
 
 Pagal numatytuosius nustatymus į žmogaus skaitomą išvestį (neformatuotas tekstas) Siūlykite vėliavą (pvz., --json arba --formatą, jei norite palaikyti kelis formatus) struktūrizuotai išeigai Kai kurie CLI įrankiai taip pat suteikia , siunčiant gražiai spausdintą tekstą rašant į terminalą, bet JSON, kai nukreipiamas į kitą procesą - panašus į tai, kaip  or  elgtis kaip auto-detection kubectl gh Klaidingos žinutės Geras klaidų pranešimas turėtų būti: 
 
 
 
 Aiškiai - nurodyti, kas nutiko neteisingai Veiksmingas - pasiūlyti, kaip jį ištaisyti Nuoseklus – visą laiką naudokite tą patį toną ir struktūrą Blogas pavyzdys: Error: failed
 Geresnis pavyzdys: Error: Could not open file '/tmp/input.txt' — file not found.
Hint: Verify that the path is correct and you have read permissions.
 Geras klaidų tvarkymas taupo vartotojams laiką ir padeda jiems sukurti pasitikėjimą jūsų įrankiu. Verbositas ir verbositas Vartotojai vertina kontrolę, kiek informacijos jie mato. 
 
 
 
 Tylus dėl minimalios išeigos • Išsamių pranešimų verbas - Debug kūrėjo lygio sekimui Sukurkite savo žurnalų lygius, kad vartotojai galėtų pasirinkti tinkamą informacijos kiekį savo kontekstui. Kartu su tinkamais išėjimo kodus, šie lygiai padaryti debugging ir automatizavimas daug sklandžiau. Atsiliepimai ir našumas Jei jūsų CLI atlieka sunkias operacijas, apsvarstykite galimybę arba Pavyzdžiui: progress indicators spinners Downloading files... 45% complete
 Tuo pačiu metu venkite nereikalingų animacijų ar išvesties, kai įrankis veikia neinteraktyviu režimu (pvz., kaip scenarijaus dalis). Išvada CLI įrankio kūrimas yra palyginti paprastas. Geras komandų eilutės įrankis jaučiasi natūralus, elgiasi nuspėjamai ir tyliai išnyksta į vartotojo darbo eigą.  — it adapts to how users already work. good Tai Per šį straipsnį mes pažvelgėme į tai, kas prisideda prie šios patirties: 
 
 
 
 
 
 
 Clear and consistent   that balance simplicity and flexibility parameters Svarbūs išėjimo kodai, kurie praneša apie sėkmę ar nesėkmę Tinkamas STDOUT ir STDERR naudojimas norint atskirti duomenis nuo diagnostikos Skaidrūs ir struktūrizuoti išvesties formatai žmonėms ir mašinoms Naudingos klaidų žinutės ir nuspėjamas elgesys Laikykitės savo ekosistemos konvencijų, kad jūsų įrankis jaučiasi pažįstamas nuo pat pirmojo paleidimo Galiausiai geriausi CLI įrankiai turi vieną bendrą bruožą: jie Jie pradeda greitai, nepavyksta greitai, aiškiai paaiškina save ir sklandžiai integruojasi į didesnes sistemas ir scenarijus. respect the user’s time Jei turite šiuos principus - aiškumą, nuoseklumą ir empatija savo vartotojams - jūsų CLI įrankis ne tik Tai bus malonu naudoti. work

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

Read My Stories

Šis garso įrašas sukurtas originalia istorijos kalba!

Kaip sukurti CLI įrankį, kurį kūrėjai iš tikrųjų mėgsta naudoti

About Author

KOMENTARAI

PABAIGTI ŽYMES

ŠIS STRAIPSNIS BUVO PRISTATYMAS

Related Stories

Light-Mode

Classic

Newspaper

Dark-Mode

Neon Noir

Minty

HN StartUps