CLI pentru scurtat URL: scurtează linkuri din terminal

Scurtarea unui URL din terminal este o singură linie:

curl -s -X POST https://api.elido.app/v1/links \
  -H "Authorization: Bearer $ELIDO_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"destination_url":"https://example.com/spring-sale"}' | jq -r .short_url

Aceasta afișează https://s.elido.me/ab12cd și nimic altceva. curl face cererea, jq extrage un câmp din JSON, iar -r elimină ghilimelele din jur, ca valoarea să poată merge direct în clipboard sau într-o altă comandă.

Restul articolului sunt cele patru îmbunătățiri care transformă linia aceea în ceva ce chiar folosești: o funcție shell, coduri de ieșire sincere, operații în masă cu concurență limitată și clipboardul. Dacă preferi să o scrii într-un limbaj, nu în shell, același apel există în Python, Go și șase alte runtime-uri.

Fă din el o comandă

Un alias nu poate primi un argument, deci folosește o funcție. În .zshrc sau .bashrc:

short() {
  [ -z "$1" ] && { echo "usage: short <url> [slug]" >&2; return 2; }

  local body
  body=$(jq -n --arg url "$1" --arg slug "${2:-}" \
    '{destination_url: $url} + (if $slug == "" then {} else {slug: $slug} end)')

  curl -s --fail-with-body -X POST https://api.elido.app/v1/links \
    -H "Authorization: Bearer $ELIDO_API_KEY" \
    -H "Content-Type: application/json" \
    -H "Idempotency-Key: $(printf %s "$1" | shasum -a 256 | cut -d' ' -f1)" \
    -d "$body" | jq -r .short_url
}

Trei alegeri deliberate în el.

Construirea JSON-ului cu jq -n --arg, în loc de interpolare de șiruri, înseamnă că o destinație care conține un ghilimel sau un ampersand nu strică cererea. Este echivalentul în shell al SQL-ului parametrizat, iar omiterea ei este aceeași clasă de bug.

--fail-with-body este flagul pe care îl ratează oamenii. Implicit, curl iese cu 0 pentru orice schimb finalizat, deci un 401 trece prin pipe, jq afișează null, iar un script merge mai departe cu null unde ar trebui să fie un link. Cu el, un 4xx setează un cod de ieșire nenul și primești totuși corpul erorii ca să-l citești.

Idempotency-Key derivat din URL înseamnă că rularea aceleiași comenzi de două ori returnează același link, în loc să creeze două. Contează și mai mult în secțiunea despre operații în masă de mai jos, iar raționamentul este în limite de rată și idempotență.

Ai nevoie de o cheie? Creează una în planul gratuit, exportă-o din profilul shell-ului, iar funcția merge la următorul terminal nou.

Direct în clipboard

Ultimele câteva caractere care o fac să pară finalizată:

short "https://example.com/spring-sale" | tee /dev/tty | pbcopy      # macOS
short "https://example.com/spring-sale" | tee /dev/tty | xclip -sel c # Linux, X11
short "https://example.com/spring-sale" | tee /dev/tty | wl-copy     # Wayland
short "https://example.com/spring-sale" | tee /dev/tty | clip.exe    # WSL

tee /dev/tty afișează linkul și îl copiază în aceeași clipă, ceea ce bate copierea pe orbește cu speranța că a mers.

Operații în masă fără să colectezi 429

Un fișier de URL-uri, câte unul pe linie, scurtate câte opt deodată:

export -f short                      # bash; zsh users call the script directly
xargs -P 8 -I{} bash -c 'short "{}"' < urls.txt > short-urls.txt

-P 8 este întreaga strategie de limitare a ratei: opt cereri în zbor, indiferent dacă fișierul are cincizeci de linii sau cincizeci de mii. Fără el, xargs le rulează cât de repede poate porni procese, iar API-ul răspunde cu 429 la cele mai multe.

Două avertismente utile înainte să-l îndrepți spre un fișier real. xargs -P intercalează ieșirea, deci liniile pot ajunge în altă ordine; dacă asocierea dintre intrare și ieșire contează, afișează-le pe ambele:

xargs -P 8 -I{} bash -c 'printf "%s\t%s\n" "{}" "$(short "{}")"' < urls.txt > mapping.tsv

Iar un URL care conține un spațiu sau un ghilimel nu va supraviețui lui -I{} fără escapare. Pentru orice provine de la utilizator, xargs -0 cu un fișier de intrare delimitat prin null este varianta sigură. Din acel punct, un script real în Python este de obicei mai puțină muncă decât să nimerești corect ghilimelele.

Ține cheia departe de istoric

ELIDO_API_KEY=abc123 short <url> pune cheia în ~/.zsh_history și în lista de procese, unde orice alt cont de pe mașină o poate citi cu ps.

Exportă-o în schimb din profilul shell-ului sau, mai bine, preia-o dintr-un depozit de secrete la pornirea shell-ului:

export ELIDO_API_KEY="$(security find-generic-password -s elido -w)"      # macOS Keychain
export ELIDO_API_KEY="$(pass show elido/api-key)"                          # pass

Rotirea unei chei înseamnă atunci actualizarea unei singure intrări, nu căutarea cu grep în fișiere de configurare pe trei mașini. Același principiu se aplică pe partea de server a oricărui script pe care îl programezi, iar webhookurile pentru evenimente de link sunt tiparul prin care primești date înapoi fără ca încă o cheie să stea undeva.

Când terminalul este locul potrivit

Este locul potrivit când URL-urile sunt deja într-un fișier, când ești deja într-un shell sau când scurtarea este un pas dintr-un script mai mare: un proces de lansare care generează un link de distribuție, un job CI care scurtează URL-ul unui deployment de previzualizare, un hook git care produce un link pentru o intrare de changelog.

Este locul greșit pentru gestionarea unei campanii. Folderele, etichetele și compararea volumului de clicuri între plasamente cer un panou, iar încercarea de a face asta cu interogări jq pe un endpoint de listare este un proiect, nu o scurtătură. Soluțiile pentru dezvoltatori acoperă ce expune API-ul dincolo de creare, iar API-ul și SDK-urile acoperă clienții tipați pentru momentul în care un script shell nu mai ajunge.

Citește seria de bază

Acesta face parte din clusterul engineering. Începe cu ghidul API-ului gratuit de scurtat URL pentru forma endpointului, apoi limite de rată și idempotență. Referința live este documentația API.

Alte articole de pe blog

• Cum scurtezi un URL în Python cu biblioteca requests
• Cum vezi unde duce un URL scurt înainte să dai clic
• Linkuri scurte ca Terraform: administrare declarativă a linkurilor