sift

menyaring

SIFT adalah alat baris perintah yang menganalisis dan membalikkan desain sistem perangkat lunak dari JVM bytecode. Ini beroperasi dengan memproses file .class atau .jar menggunakan templat yang telah ditentukan yang dikenal sebagai templat model sistem. Templat ini memberikan pengetahuan tentang tumpukan teknologi atau konstruksi spesifik proyek, yang memungkinkan alat untuk menghasilkan model sistem yang komprehensif.

Model sistem yang dihasilkan terdiri dari entitas yang menggambarkan struktur dan perilaku sistem.

Menggunakan kasus

• Refactoring : Sederhanakan refactoring dengan mengidentifikasi dependensi dan mengisolasi komponen.
• Onboarding : Bantu anggota tim baru memahami arsitektur sistem dengan cepat.
• Analisis Dampak : Gunakan opsi --diff untuk menganalisis dampak fitur atau perubahan baru.
• Dokumentasi : Hasilkan representasi grafis atau tekstual dari sistem Anda untuk tujuan dokumentasi.
• Analisis Microservice : Dengan cepat memahami interaksi dalam lingkungan layanan mikro.

Fitur

• Alat CLI untuk membangun, meminta, dan membandingkan model sistem dari file .class parsed.
• DSL deklaratif untuk menulis templat yang ditentukan pengguna, secara opsional memperluas atau menggabungkan templat yang ada.
• Serialisasi Templat JSON untuk penggunaan kembali dan berbagi yang mudah.
• Render representasi sistem menggunakan GraphViz. Render inline untuk Kitty didukung melalui sift.sh | zsh.
• Secara opsional dibangun sebagai biner asli menggunakan gambar asli GraAlvm, memungkinkan waktu eksekusi yang jauh lebih cepat. Ini berarti bahwa SIFT biasanya dapat menganalisis sebagian besar proyek berukuran mikro dalam waktu kurang dari 0,5 detik.

Boot-boot dengan template kerangka kerja akson dalam tindakan; Penyaringan pada pesanan yang dikirim dan dikonfirmasi di https://github.com/eugenp/tutorials/tree/master/axon.

Opsi CLI

 Usage: sift [OPTIONS]

  Sift is a command-line tool that analyzes and reverse models software system designs
  from JVM bytecode.

Template options:
  -t, --template TEMPLATE               The template producing the system model.
  -l, --list-templates                  Print all installed templates.
  -T, --list-entity-types               Lists entity types defined by template.
  -f, --class-dir, --classes PATH|URI|MAVEN_COORD
                                        Provide class input as a directory, JAR file, URI
                                        (pointing to a JAR), or Maven coordinate.
  -d, --diff FILE_JSON|URI|MAVEN_COORD  Compare the system model from '-f' with another,
                                        specified as a JSON file (previously saved System
                                        Model), class input as a directory, JAR file, URI
                                        (pointing to a JAR), or Maven coordinate.
  --profile                             Print execution times and input/output for the
                                        executed template.
  -D, --dump-system-model               Print all entities along with their properties and
                                        metadata.

Entity tree/graph options:
  -L, --max-depth INT                   Max display depth of the tree.
  -F, --filter REGEX                    Filter nodes by label. (repeatable)
  -S, --filter-context REGEX            Filter nodes by label, while also including
                                        sibling nodes. (repeatable)
  -e, --exclude REGEX                   Exclude nodes when label matches REGEX.
                                        (repeatable)
  -c, --column [all|element-id|element-type|entity-type]
                                        Columns to display. (repeatable)
  -E, --exclude-type ENTITY_TYPE        Exclude entity types from tree. (repeatable)
  -r, --tree-root ENTITY_TYPE           Tree built around requested entity type.
                                        (repeatable)
  --no-emoji                            Disables printing emoji in entity labels.

Visualization options:
  -R, --render                          Render entities with graphviz's DOT language.
  --edge-layout [spline|polyline|ortho]
                                        Sets the layout for the lines between nodes.
                                        (default: spline)

Serialization options:
  -s, --save FILE_JSON  Save the resulting system model as json.
  --load FILE_JSON      Load a previously saved system model.

Debug options:
  --debug                               Print log/logCount statements from the executed
                                        template.
  -X, --debug-inverse-trace             Print the inverse element trace for the elements
                                        specified with --debug-element-traces
  -x, --debug-element-trace ELEMENT_ID  Print all element traces leading to the specified
                                        elements

Miscellaneous options:
  -a, --ansi [none|ansi16|ansi256|truecolor]
                                        Override automatically detected ANSI support.
  --stacktrace                          Print stacktrace to stderr if an error occurs
  --version                             Print version and release date.
  -m, --maven-repository VALUE          Additional maven repositories to use for
                                        downloading artifacts. Maven central
                                        (https://repo1.maven.org/maven2/) and local user
                                        repositories are always included.
  --statistics                          Print internal statistics about the system model
                                        template context.
  --generate-completion [bash|zsh|fish]
  -h, --help                            Show this message and exit

Examples:
  sift --template spring-axon -f my-spring-project
  Model the system using the "spring-axon" template on the classes in the
  "my-spring-project" directory.

  sift -t spring-axon -f . -F "Order(Created|Shipped)"
  Model the system using the "spring-axon" template on the current directory's
  classes, filter nodes containing the regular expression "Order(Created|Shipped)".

  sift -t spring-axon -f . --diff feature-01.json
  Compare the current design of the system using the "spring-axon" template on
  the classes in the current directory against a previously saved system model
  from "feature-01.json" and show the differences.

  sift -t sift -f "net.onedaybeard.sift:core:0.13.0" --diff "net.onedaybeard.sift:core:0.9.0"
  Compare two different versions of the DSL API using the 'sift' template, specified
  by their maven coordinates.

Templat dan entitas model sistem

Model sistem menggambarkan struktur dan hubungan entitas dalam suatu sistem. Entitas adalah objek atau komponen dalam sistem, secara unik diidentifikasi oleh kelas, metode, bidang, parameter atau tanda tangan generik.

Entitas dikategorikan oleh Entity.Type mereka. Jenis entitas mewakili bagian penting dari sistem. Misalnya, tipe dapat mencakup pengontrol REST, titik akhir HTTP, pesan masuk/keluar, RDS, repositori dan banyak lagi.

$ sift --template spring-axon -f target/classes --list-entity-types 
entity types of spring-axon
  1 aggregate
  2 aggregate-ctor
  1 aggregate-member
  6 command
  6 command-handler
  1 controller
 13 endpoint
  7 event
  7 event-handler
  7 event-sourcing-handler
  1 projection
  3 query
  4 query-handler

Templat model sistem menggambarkan bagaimana entitas diidentifikasi dalam tumpukan teknologi yang diberikan dan/atau konstruksi khusus proyek. Templat ditulis dalam DSL deklaratif dan digunakan untuk menghasilkan model sistem dari kelas input. DSL memberikan abstraksi tingkat tinggi untuk mengidentifikasi dan saling terkait entitas dari struktur atau penggunaan kelas.

Kode di bawah ini menunjukkan templat model sistem sederhana yang mengidentifikasi pengontrol REST dan titik akhir HTTP dalam suatu sistem dan mengaitkan kedua entitas tersebut.

 val controller = Entity . Type ( " controller " )
val endpoint = Entity . Type ( " endpoint " )

template {
    // iterate over all input classes
    classes {                                                      
        annotatedBy< RestController >() // filter classes 
        entity(controller)            // mark remaining as 'controller'  
        methods {                     // iterate all controller methods
            annotatedBy< Endpoint >()   // filter @Endpoint methods
            entity(endpoint)

            // associate controllers with their endpoints  
            controller[ " endpoints " ] = endpoint
        }
    }
}

Elemen input (kelas, metode, parameter, bidang, tanda tangan generik) diproses dalam batch, garis demi garis. Eksekusi templat model sistem dapat introspeksi dengan opsi --profile .

Template khas dapat diekspresikan dalam sekitar 100-200 baris kode. Beberapa templat, seperti yang untuk JPA dan JDBI, terutama lebih pendek. Template yang ditentukan pengguna dapat mencakup beberapa templat yang ada untuk lebih menggambarkan sistem yang mendasari sambil juga menjaga DSL yang dihasilkan ringkas.

Instalasi

SIFT membutuhkan runtime Java 17 atau yang lebih baru.

Untuk pengguna jendela, disarankan untuk menjalankan SIFT di bawah WSL, sampai jalur jendela yang tepat ada.

Cara termudah untuk menginstal SIFT adalah mengkloning repositori dan menjalankan mvn install , dan kemudian menyalin sift.zsh | sh ke lokasi di $PATH , misalnya:

• mvn install dari Project Root. Ini menginstal SIFT ke ~/.local/share/sift/bin
• Salin sift.zsh atau sift.sh ke ~/.local/bin/sift

Cabang main selalu menunjuk ke komit rilis terbaru.

Membangun biner asli di Linux menggunakan GraAlvm

Jika GraAlvm dan gambar asli dipasang, biner asli dapat dibangun dengan profil Maven native-image : mvn install -P native-image . Biner yang dihasilkan akan berlokasi di ~/.local/share/sift/bin/sift . sift.zsh dan sift.sh pertama -tama memeriksa apakah biner asli tersedia, jika tidak ia mencoba menjalankan toples.

Biner asli jauh lebih cepat daripada toples, tetapi dapat menyebabkan masalah jika perlu deserialisasi model sistem (melalui --load atau --diff ) atau templat model sistem yang mengandung tipe yang tidak diketahui (misalnya dari withValue() ).

Peringatan dan Batasan

• Tidak ada analisis aliran yang membuat identifikasi entitas yang tepat sulit untuk metode seperti dispatcher EG yang berurusan dengan banyak jenis entitas.