Ringkasan: Untuk meningkatkan pengalaman pembangun, AgentStation mencipta pakej uuidkey untuk mengekod UUID ke dalam kunci API yang cantik dan mudah dibaca. Pakej ini menyokong UUIDv7 dan boleh menyahkod kunci untuk pengisihan dan pengindeksan pangkalan data.

Soalan:

Kunci API ialah bahagian penting dalam interaksi pertama pengguna dengan produk AgentStation. Kami mahu kunci menjadi cantik dan mudah digunakan, tetapi nampaknya terdapat kekurangan piawaian dalam industri. Sebagai permulaan yang memfokuskan pembangun, kami melaburkan masa dan usaha untuk mencari penyelesaian yang ideal.

Kebanyakan kunci API menyedut:

Kami mempunyai keperluan berikut untuk kunci API:

• Keselamatan
• Unik di peringkat global
• Boleh diisih
• Prestasi cemerlang dalam Postgres
• Penampilan yang cantik

Walau bagaimanapun, kebanyakan kunci API tidak mempunyai estetika dan selalunya merupakan aksara rawak yang diformatkan secara tidak konsisten yang sukar dibaca, diisih dan dikenal pasti. Kami mahu kunci API menyenangkan dari segi estetika dan simetri seperti perkara yang baik dalam kehidupan.

ID yang kami tolak:

Terlalu rambang, mudah diteka, rupa paras...semuanya tidak memuaskan.

• Integer dan BigInt: Mudah dibaca dan mudah diisih. Tetapi mereka mendedahkan bilangan kunci, mudah diteka dan menyediakan keselamatan yang tidak mencukupi.
• NanoID: Menyediakan ID rawak sepenuhnya, boleh disesuaikan, sesuai untuk pengecam yang dihadapi oleh orang ramai. Tetapi kekurangan maklumat cap masa untuk mengisih dan menyahpepijat.
• UUID: standard industri, dengan dua versi yang patut dipertimbangkan:
  • UUIDv4: Aksara rawak semata-mata, ringkas dan berkesan.
  • UUIDv7: Termasuk cap waktu untuk penyahpepijatan mudah dan pengisihan pertanyaan pangkalan data.
• ULID: mengandungi cap masa dan dikodkan menggunakan Base32 untuk kebolehbacaan yang lebih baik. Tetapi kami lebih suka sokongan Postgres asli UUID, dan estetikanya masih tidak mencukupi.

Penyelesaian kami:

Disebabkan kekurangan estetika (simetri) penyelesaian sedia ada, kami mencipta pendekatan kami sendiri:

1. Gunakan UUIDv7 sebagai ID asas, menggunakan maklumat cap masa.
2. Gunakan pengekodan Crockford Base32 untuk meningkatkan kebolehbacaan.
3. Tambah sengkang cantik untuk meningkatkan kesan visual.

Keputusan:

<code>key, _ := uuidkey.Encode("d1756360-5da0-40df-9926-a76abff5601d")
fmt.Println(key) // Output: 38QARV0-1ET0G6Z-2CJD9VA-2ZZAR0X</code>

Kunci kami:

• 31 aksara (28 tanpa sengkang), lebih pendek daripada 36 aksara UUID.
• Perenggan yang sangat mudah dibaca yang mengandungi 4 set 7 huruf besar dan nombor, dengan estetika dan kebolehbacaan "berhalangan".
• Boleh diisih mengikut kronologi apabila disimpan sebagai UUID yang dinyahkod.
• Cap masa dalam kekunci yang boleh dilihat pengguna dikelirukan (tetapi masih boleh dinyahkod oleh pengguna yang mahir teknologi). Kami berpendapat metadata cap masa dalam kunci adalah bonus tambahan, dan anda juga boleh memilih untuk menggunakan UUIDv4!

Mengapa memilih UUIDv7?

Selain kelebihan cap masa, UUIDv7 akan menerima sokongan asli dalam Postgres v18. Walaupun pada masa ini mungkin untuk menjana sisi pelayan UUIDv7 menggunakan sambungan, sokongan Postgres asli pasti akan berprestasi lebih baik dan berfungsi dengan baik dengan uuidkey.Encode().

Dalam pelaksanaan kami, kami kini menjana kunci pada lapisan aplikasi dan menyimpannya sebagai UUID untuk mengisih dan mengindeks. Setelah Postgres v18 dikeluarkan, kami akan beralih kepada binaan Postgres untuk mengurangkan beban pada lapisan aplikasi dan mencapai prestasi yang lebih baik.

Mengapa memilih Crockford Base32?

Kami memilih pengekodan Crockford Base32 kerana ia:

• Gunakan hanya huruf besar dan nombor untuk meningkatkan kebolehbacaan.
• Kurangkan panjang kunci kira-kira 1/5.
• Pemetaan adalah cekap dan boleh diramal.

Mengapa menggunakan dash?

Kunci sempang adalah "berhalang" dan simetri. Jika anda mengkelabukan aksara individu, ia kelihatan hampir seperti kod bar. Kami fikir ini memudahkan anda membaca sebahagian daripada kunci untuk mengenal pastinya dengan cepat.

Sempang memang mengalih keluar fungsi salinan klik dua kali yang mudah, tetapi kami fikir ini adalah pertukaran yang berbaloi untuk kebolehbacaan. Kami tidak mahu pengguna menyalin dan menampalnya di mana-mana, malah kami mahu mereka dikendalikan dengan berhati-hati. Sebaik-baiknya, pengguna hanya akan menyalin kunci sekali apabila menjananya dalam papan pemuka kami - jadi kami menambah butang salin pada UI untuk menyelesaikan masalah ini.

pakej uuidkey:

Kami sumber terbuka pilihan reka bentuk ini di github.com/agentstation/uuidkey. Jika anda bersetuju dengan estetika, penaakulan dan simetri kami, dan ingin memiliki kunci API anda sendiri yang cantik, jangan ragu untuk mencuba projek sumber terbuka kami.

uuidkey Teras pakej adalah untuk mengekod UUID ke dalam format kunci yang boleh dibaca melalui codec Base32-Crockford dan menyahkodnya kembali ke UUID.

Pengekodan:

Coretan kod telah diberikan dalam teks asal dan tidak akan diulang di sini.

Penyahkodan:

Coretan kod telah diberikan dalam teks asal dan tidak akan diulang di sini.

Pakej ini direka bentuk untuk berfungsi dengan mana-mana UUID yang mengikut spesifikasi UUID rasmi (RFC 4122), tetapi kami secara khusus menguji dan mengekalkan keserasian dengan dua penjana UUID Go yang paling popular:

• Gofs
• Google

Pemasangan adalah mudah:

<code>key, _ := uuidkey.Encode("d1756360-5da0-40df-9926-a76abff5601d")
fmt.Println(key) // Output: 38QARV0-1ET0G6Z-2CJD9VA-2ZZAR0X</code>

Penggunaan asas:

<code>go get github.com/agentstation/uuidkey</code>

Kami berusaha untuk mengekalkan overhed pada tahap minimum:

Data ujian penanda aras prestasi telah diberikan dalam teks asal dan tidak akan diulang di sini.

Sumbangkan kepada uuidkey:

Kami komited untuk mengekalkan uuidkey sebagai alat sumber terbuka yang boleh dipercayai kerana kami menggunakannya dalam pengeluaran - sumbangan dialu-alukan!

Jika anda rasa ia berguna atau mempunyai cadangan untuk penambahbaikan, kami ingin mendengar daripada anda dalam isu GitHub atau komuniti Discord kami.

Teknologi terdahulu dan bahu gergasi:

Selepas kami mengeluarkan projek, kami menemui beberapa projek dengan pelaksanaan yang serupa, tetapi masih tidak memenuhi kriteria kami untuk pengekodan dan penyahkodan UUID menggunakan Go.

• uuidapikey - Pergi, tetapi tidak menyokong pengekodan atau penyahkodan input UUID.
• based_uuid - Ruby, tetapi untuk ID awam.

Ringkasan:

Di AgentStation, kami sedang membina platform yang membolehkan ejen AI mempunyai stesen kerja maya mereka sendiri untuk menjalankan penyemak imbas, menghadiri mesyuarat dan melaksanakan kod. Semasa kami menskalakan kepada beribu-ribu stesen kerja, mempunyai kekunci berprestasi tinggi yang boleh diisih adalah infrastruktur yang praktikal.

Tetapi kami juga percaya bahawa pembangun menghargai keindahan simetri sama seperti kami, walaupun dalam kunci API.

Kami harap anda mendapati uuidkey praktikal dan cantik.

Nota kaki telah diberikan dalam teks asal dan tidak akan diulang di sini.

Atas ialah kandungan terperinci Membuat Kunci API Cantik. Untuk maklumat lanjut, sila ikut artikel berkaitan lain di laman web China PHP!