Architektur und Code im Einklang (JUG Nürnberg)

Umsetzung von Architekturkonzepten und Designvorgaben mit jQAssistant direkt im Quellcode überprüfen

jQAssistant ist ein Werkzeug zur statischen Analyse von Softwareartefakten. Mit jQAssistant ist es möglich, Architektur- und Designkonzepte als einen Satz von Regeln zu definieren. Die Einhaltung dieser Regeln kann anschließend bei jedem Bau einer Software automatisiert überprüft werden. Dadurch kann sichergestellt werden, dass eine vorgegebene Architektur sowie Designvorgaben auch wirklich im Quellcode umgesetzt wurden.

In meinem Vortrag stelle ich die Grundlagen von jQAssistant vor und zeige an einem Beispiel, wie sich mit dem Werkzeug eine sich selbst prüfende Architekturdokumentation erstellen lässt.

Transcript

1. Architektur und Code im Einklang Umsetzung von Architekturkonzepten und Designvorgaben mit jQAssistant und AsciiDoc direkt im Quellcode automatisiert überprüfen @feststelltaste feststelltaste.de talk@markusharrer.de Markus Harrer Sparda Datenverarbeitung e. G. Java User Group Nürnberg (28.06.2017)
2. “If you think good architecture is expensive, try bad architecture.” Brian Foote
3. “If you think bad architecture is expensive, try undocumented and non-validated architecture.” Markus Harrer
4. Plan Reality
5. + = scan document validate
6. Grundlegendes zu jQAssistant
7. jQAssistant Funktionsweise • Scanne Softwarestrukturen • Speichere diese in eine Datenbank • Führe Abfragen aus • Untersuche Zusammenhänge • Ergänze Konzepte • Validiere Regelverletzungen • Generiere Berichte
8. jQAssistant Kernideen: Concepts • Gescannte Elemente werden Konzepten („concepts“) zugeordnet, z. B. • Maven Project = Modul • Java Package = Schicht • Mit @Entity annotierte Klasse = JPA-Entity
9. jQAssistant Kernideen: Constraints • Regeln werden auf Basis der Konzepte textuell formuliert, z. B. „Alle JPA-Entitäten müssen sich in der Persistenz-Schicht befinden“ • Abweichungen von den Regeln („constraints“) werden geprüft, z. B. „Gib mir alle JPA-Entities, die sich nicht in der Persistenzschicht befinden.“
10. jQAssistant Kernideen: Constraints • Regeln werden auf Basis der Konzepte textuell formuliert, z. B. „Alle JPA-Entitäten müssen sich in der Persistenz-Schicht befinden“ • Abweichungen von den Regeln („constraints“) werden geprüft, z. B. „Gib mir alle JPA-Entities, die sich nicht in der Persistenzschicht befinden.“
11. jQAssistant Kernideen: Groups • Alles wird in einer gemeinsamen Dokumentation festgehalten, über Gruppen („groups“) strukturiert und beim Build ausgeführt. Ausschnitt:
12. Graphentheorie mit Neo4j und Cypher
13. Ein Graph Knoten Kante
14. Graph im Detail Knoten Mögliche Arten Java-Klasse Messpunkt Datei Repository URL ...
15. Graph im Detail Kanten Typ einer Beziehung DECLARES EXTENDS IMPLEMENTS ANNOTATED_BY DEPENDS_ON ...
16. Ein Graph – sogar mit Daten! File Class Type File key value name “entity“ file “Entity.java” fqn “jpa.thing.Entity” key value weight 3 key value name “Pet” file “Pet.java” fqn “foo.bar.Pet” Labels Properties
17. Beispiel Spring PetClinic
18. Sprint PetClinic: Verwaltung für Tierpraxis
19. Beispiel-Graph: Sprint PetClinic visibility: public name: Pet fqn: org.springframework.samples.petclinic.model.Pet … Class:Type:Java:File
20. Beispiel-Graph: Sprint PetClinic
21. Beispiel-Graph: Sprint PetClinic
22. Beispiel-Graph: Sprint PetClinic Kann ich abfragen!
23. Cypher Syntax
24. Cypher Abfrage von Knoten MATCH (p:Class)-[]->(e:Type) WHERE p.name = "Pet" AND e.name = "Entity" RETURN p, e
25. Explorative Analysen in Neo4j Demo 1 MATCH (p:Class)-[]->(e:Type) WHERE p.name = "Pet" AND e.name = "Entity" RETURN p, e
26. Dokumentieren mit AsciiDoc und Cypher
27. AsciiDoc Markup Language • Rendert zu • DocBook • HTML • PDF mit Cypher: ausführbare Spezifikation! • Programmiervorgaben • Design und Architektur
28. Definition eines Concepts == JPA Entities [[jpa2:Entity]] .Labels all types annotated with @javax.persistence.Entity with Jpa and Entity. [source,cypher,role=concept] ---- MATCH (t:Type)-[:ANNOTATED_BY]->()-[:OF_TYPE]->(a:Type) WHERE a.fqn ="javax.persistence.Entity" SET t:Jpa:Entity RETURN t AS Entity ----
29. Definition eines Constraints [[model:JpaEntityInModelPackage]] .All JPA entities must be located in packages named "model". [source,cypher,role=constraint, requiresConcepts="jpa2:Entity"] ---- MATCH (package:Package)-[:CONTAINS]- >(entity:Jpa:Entity) WHERE package.name <> "model" RETURN entity AS EntityInWrongPackage ----
30. Definition einer Group [[default]] [role=group,includesConstraints= "model:JpaEntityInModelPackage"]
31. Ergebnisbericht Z. B. als Maven Site Report
32. Selbstvalidierende Architekturdokumentation Demo 2 Spring PetClinic
33. Plan Reality
34. • jQAssistant bietet schnelle und flexible Sichten auf eine Vielzahl von Softwarestrukturen • Zusammenhänge können explorativ über die Graphdatenbank Neo4j erkundet werden • Definition von Spielregeln über Concepts und Constraints in Cypher / AsciiDoc Automatisierte Überprüfung von • Architekturkonzepten und • Designvorgaben • direkt im Code Zusammenfassung
35. Links • jQAssistant • http://jqassistant.org • Ausführliches Video • https://www.youtube.com/watch?v=kQr2c7yWbEA • Spring PetClinic Beispielprojekt • Repo: http://github.com/buschmais/spring-petclinic • Output: https://buschmais.github.io/spring-petclinic/ • Meine Erfahrungen soweit • https://www.feststelltaste.de/my-experiences-with- jqassistant-so-far/
36. Credits Einige Beispiele wurden aus Dirk Mahlers Vortrag “jQAssistant - Verify Your Design And Architecture” übernommen • https://jqassistant.org/wp-content/uploads/2016/06/ jQAssistant-Verify-Your-Design-And-Architecture.pdf Bilder • https://de.wikipedia.org/wiki/Datei:Yin_yang.svg • https://commons.wikimedia.org/wiki/File:Achitecture_time.jpg • https://commons.wikimedia.org/wiki/File:Adelaide_Street_aba ndoned_house.jpg
37. Fragerunde Eure Fragen