Son birkaç yılda dokümantasyonla daha fazla ilgilenmeye başladım. Belirli bir sistemin nasıl çalıştığına dair açıklayıcı bir metin yazmak genellikle oldukça basittir. Tüm önemli nesneleri ve bu nesneler arasındaki bağlantıları gösterecek bir diyagram çizmek de oldukça kolaydır.
Ancak en sorunlu husus bu dokümantasyonun güncel tutulmasıdır. Metin iyi olurdu ama diyagramlar... Çünkü... tüm belgeler çevrimiçidir, yani html formatında ise metne aslında diyagramları gösteren gif/jpeg/png resimleri eşlik eder. Ve diyagramlar Visio gibi çeşitli programlarda veya Draw.io gibi çevrimiçi hizmetlerde çizilir. Daha sonra diyagramı grafik formatına aktarır ve html'ye eklersiniz. Basit.
Sorun ne?
Şemalar genellikle basittir. Daha doğrusu çok karmaşık değil. Evet, nesne sayısı bir veya iki düzine, bağlantı sayısı ise yaklaşık olarak aynı. Artı imzalar, bazı isimler. Basit şemalar kelimelerle anlatılabilir ama çok karmaşık olanlar, öhöm... (c) "Anlamayacaklar efendim." Pek çok plan var, periyodik olarak, epizodik olarak bunlarda değişiklik yapılması gerekiyor, ör. sürekli çünkü Ürünlerimizin gelişimini takip ediyorlar.
Hizmetin html'sini gömebilirsiniz. Bunu denediniz mi?
Evet elbette. Mesela gliffy.com'un grafiklerini beğendim. Ancak değişiklik yapmak için üçüncü taraf bir hizmete gitmeniz ve orada düzenleme yapmanız gerekir. Ve düzeltmeleri bir meslektaşına devretmek daha zordur.
Ne yapmalı?
Son zamanlarda önerilerde Github'da bir depoya rastladım . Kod olarak diyagram. Onlar. İhtiyacımız olan devreyi js'de anlatıyoruz. Bu js'yi doğrudan diğer belge metninin bulunduğu aynı html'ye yazıyoruz.
Bu arada, belgeleri tamamen HTML'de yazmıyorum. Tipik olarak dokümantasyon, işaretleme metni içeren bir dizi dosyadır ve bunlar daha sonra bazı motorlar (örneğin, kış ustası) tarafından tam teşekküllü bir dokümantasyon sitesine dönüştürülür. Veya bir wiki sistemi.
Çok kullanışlı görünüyor: metni yazdık, ardından komut dosyası etiketi açılıyor ve şemanın JS kodu burada açıklanıyor.
Tekrar yanlış olan ne?
Bu depoyu beğendim ancak bir diyagramın kod veya metin gösterimi kullanılarak çizildiği tek örnek bu değil. (Yazının sonunda konu şemasında kod olarak Google'da arattığım proje ve makalelere bağlantılar olacak.)
Ve belgeleri düzenleyen tek kişi ben değilim. Bazen meslektaşlar da katkıda bulunur; bir kelimeyi düzeltin, açıklamayı değiştirin, yeni resimler ekleyin.
Bu nedenle diyagramı uzun bir öğrenme eğrisi gerektirmeyecek, okunabilir, anlaşılır bir metin formatında görmek isterim. Hatta bazı yerlerde yeni bir devre eklemeyi hızlandırmak için basitçe kopyalayıp yapıştırabilirsiniz.
Ve başka bir meslektaşım, kodun elbette iyi olduğunu, ancak yapıyı kullanırsanız her şeyin çok katı ve anlamlı olabileceğini belirtti.
Bu nedenle diyagramı, düğümleri, bağlantıları, düğüm gruplarını ve düğümlerin konumunu tanımlayan birkaç küçük diziden oluşan bir dizi olarak hayal etmeye çalıştım. Benim naçizane görüşüme göre oldukça kullanışlı olduğu ortaya çıktı, ancak elbette tadı ve rengi de...
Bu nasıl bir dizideki grafiktir?
- Her düğüm, düğümü benzersiz şekilde tanımlayan bir tanımlayıcıyla tanımlanır.
- Ayrıca düğüme bir simge ekleyebilir ve bir yazıt ekleyebilirsiniz.
- İki düğüm arasındaki ilişkiyi belirtebilirsiniz.
- Diyagramdaki iletişim için rengi ve yazıyı ayarlayabilirsiniz.
- İletişimin yönü kaynaktan hedefe doğru olarak tanımlanır. Kaynak ve hedef, düğüm tanımlayıcılarıyla gösterilir.
- Bir gruba bir veya daha fazla düğüm eklenebilir.
- İlişki aynı zamanda hem gruptan hem de gruba belirtilebilir.
Bu basit kuralları kullanarak aşağıdaki diyagramı elde ederiz. Sadece? Epeyce.
Ve aşağıdaki js koduyla açıklanmaktadır. Buradaki en önemli şey elementler nesnesidir. Hangi düğümlerin belirtildiği - düğümler, kenarlar - bağlantılar.
const elements = {
nodes: [ // описываем узлы
{ id: 'client', type: 'smartphone', label: 'Mobile App'},
{ id: 'server', type: 'server', label: 'Main Server'},
{ id: 'db1', type: 'database', label: 'DB 1'},
{ id: 'db2', type: 'database', label: 'DB 2'},
],
edges: [ // указываем связи
{ source: 'client', target: 'server', label: 'request' },
{ source: 'server', target: 'db1', label: 'request' },
{ source: 'server', target: 'db2', label: 'request' },
],
};
Diagram('scheme1', elements);
Elbette devrenin çizimini kendim bulamadım ama kütüphaneyi kullandım çok güçlü bir görselleştirme aracıdır. Çözümümde olasılıkların yalnızca bir kısmını kullanıyorum.
Tamam, bu basit bir örnek. Daha karmaşık olabilir mi?
Evet lütfen. Konumları belirtmek için konumları kullanırız, grupları belirtmek için gruplar halinde grupların listesini belirtiriz ve öğelerin kendilerinin bir grup özelliği vardır.
Ve bu kod:
<div id="scheme5" style="height:500px;width:800px;"></div>
<script>
const elements5 = {
groups: [
{ id: 'g1', label: 'Группа сервисов 1'},
{ id: 'g2', label: 'Группа сервисов 2'},
],
nodes: [
{ id: 'man1', type: 'person', label: 'Человек'},
{ id: 'client', type: 'smartphone', label: 'Смартфон'},
{ id: 'agent-backend', type: 'server', group: 'g1', label: 'agent-backend'},
{ id: 'web', type: 'server', group: 'g1', label: 'Приложение admin'},
{ id: 'www', type: 'server', group: 'g1', label: 'страница загрузки'},
{ id: 'mongodb1', type: 'database', group: 'g1', label: 'Mongo DB 1'},
{ id: 'mongodb2', type: 'database', group: 'g1', label: 'Mongo DB 2'},
{ id: 'runner-integration1', type: 'worker', group: 'g1', label: 'отправка'},
{ id: 'runner-integration2', type: 'worker', group: 'g1', label: 'отправка'},
{ id: 'api', type: 'server', group: 'g1', label: 'API'},
{ id: 'server2', type: 'server', group:'g2', label: 'сервер'},
{ id: 'otherServer', type: 'server', group:'g2', label: 'сервер'},
{ id: 'firebase', type: 'cloud', label: 'Google Firebase'},
],
edges: [
{ source: 'client', target: 'agent-backend', label: 'json', color: 'red' },
{ source: 'agent-backend', target: 'mongodb1', color: 'red' },
{ source: 'agent-backend', target: 'mongodb2', color: 'red' },
{ source: 'mongodb1', target: 'runner-integration1', label: 'данные' },
{ source: 'mongodb2', target: 'runner-integration2', label: 'данные' },
{ source: 'mongodb1', target: 'web', label: 'данные для отображения' },
{ source: 'runner-integration1', target: 'server2', label: 'данные' },
{ source: 'runner-integration2', target: 'otherServer', label: 'данные' },
{ source: 'api', target: 'firebase', label: 'запросы', color: 'blue', },
{ source: 'firebase', target: 'client', label: 'push', color: 'blue'},
{ source: 'server2', target: 'api', label: 'уведомления', color: 'blue'},
{ source: 'man1', target: 'client', },
],
positions: [
{ id: 'client', row: 2, col: 1,},
{ id: 'agent-backend', row: 2, col: 3,},
{ id: 'web', row: 6, col: 3,},
{ id: 'www', row: 1, col: 3,},
{ id: 'mongodb1', row: 1, col: 4,},
{ id: 'mongodb2', row: 2, col: 5,},
{ id: 'runner-integration1', row: 3, col: 3,},
{ id: 'runner-integration2', row: 4, col: 3,},
{ id: 'api', row: 5, col: 3,},
{ id: 'server2', row: 6, col: 7,},
{ id: 'otherServer', row: 4, col: 7,},
{ id: 'firebase', row: 5, col: 1,},
{ id: 'logger', row: 2, col: 7,},
{ id: 'crm', row: 5, col: 8,},
],
};
Diagram('scheme5', elements5, {layout: 'grid'});
</script>
Bir yandan böyle bir şema, bir dizüstü bilgisayarda neredeyse birkaç kod ekranıdır, diğer yandan, a la json yapısı, tüm verileri analoji yoluyla hızlı bir şekilde doldurmanıza ve kopyalayıp yapıştırmanıza olanak tanır.
Konumlar neden düğümlerden ayrı olarak yerleştiriliyor?
Daha rahat. İlk önce düğümleri belirliyoruz. Daha sonra birkaç grup belirleyip bunları düğümlerde belirtebiliriz. Daha sonra bağlantıları belirliyoruz. Ve ancak o zaman, ana nesneler ve aralarındaki bağlantılar orada olduğunda, bu nesnelerin diyagramdaki konumunu alırız. Ya da tam tersi.
Pozisyonlar olmadan mümkün mü?
Pozisyonlar olmadan da mümkündür. Ancak biraz buruşuk olacak, bu seçeneği örneklerde görebilirsiniz. Bunun nedeni sitoscape için düğümlerin konumu için bir algoritmanın bulunmasıdır. Bu aynı zamanda grupların varlığını da dikkate alır. Konumların belirtilmesi diyagramı daha kontrol edilebilir hale getirir, ancak diyagramın ilk taslağı aşamasında konumlar olmadan da mümkündür.
Pozisyonlar ayrıca Savaş Gemisi stilinde de belirtilebilir. Onlar. bir düğüm a1'de, diğeri d5'te bulunur. Özellikle sitoscape'in tuval üzerindeki nesneleri hareket ettirebilmesine yardımcı olur; onları hareket ettirebilir, farklı düzen seçeneklerini görebilir ve ardından kodda beğendiğimiz öğelerin düzenini düzeltebiliriz.
Genel olarak anlaşılabilir. Siz de deneyebilir misiniz?
Elbette hızlı bir şekilde devreler oluşturmak için kendime küçük bir şey yaptım şemayı kendisi günceller ve en son sürümü tarayıcıda (localStorage'da) saklar.
Bunu denediniz mi? Artık sayfanıza ekleyebilirsiniz.
Sonra tekrar:
1. Komut dosyasını bağlama
<script src="https://unpkg.com/@antirek/[email protected]/dist/code-full.min.js"></script>
2. Html'ye kod ekleme
<div id="scheme1" style="height:300px;width:800px;"></div>
<script>
const elements = {
nodes: [
{ id: 'client', type: 'smartphone', label: 'Mobile App'},
{ id: 'server', type: 'server', label: 'Main Server'},
{ id: 'db1', type: 'database', label: 'DB 1'},
{ id: 'db2', type: 'database', label: 'DB 2'},
],
edges: [
{ source: 'client', target: 'server', label: 'request' },
{ source: 'server', target: 'db1', label: 'request' },
{ source: 'server', target: 'db2', label: 'request' },
],
};
Diagram('scheme1', elements);
</script>
3. kodu ihtiyacımız olan şemaya göre düzenliyoruz (baykuş çizmekten daha kolay olduğunu düşünüyorum :)
Daha fazla ayrıntı github'da.
Sonuç?
Hedeflerime ulaştım - belgelere satır içi diyagramlar eklemek için format oldukça basit ve anlaşılır. Süper devreler için uygun değildir ancak bağlantıların yapısını açıklayan küçük devreler için kesinlikle uygundur. Zaman içinde her zaman hızlı bir şekilde ince ayar yapabilir ve bir şeyleri değiştirebilirsiniz. Evet ve meslektaşlar, özel bir eğitim almadan, en azından nesneler için başlıklar olmak üzere dock'taki bir şeyi kendileri düzeltebilirler))
Ne geliştirilebilir?
Elbette burada birçok seçenek var. Ek simgeler ekleyin (mevcut olanların tümü komut dosyasına satır içi olarak eklenir). Daha etkileyici bir simge seti seçin. Bağlantı hattının stilini belirtmeyi mümkün kılın. Bir arka plan resmi ekleyin.
Ne düşünüyorsun?
Zaten konularda uygulama için birkaç fikrim var, siz de yorumlara kendi fikirlerinizi ekleyebilirsiniz.
Benim çözümüm kesinlikle dar bir problem yelpazesinde uygulanabilir ve belki de diyagramları basitçe kodlayarak çizmek için daha uygun bir araç bulacaksınız - 'diyagramınızı bana kod olarak göster' derler.
- (9 tür grafik çevrimiçi editörü)
- Süper ayrıntılı ve karmaşık diyagramlardan hoşlanıyorsanız, bu projeye kesinlikle hayran kalacaksınız:
Kaynak: habr.com