Architektur und Code im Einklang (DeveloperCamp 2017)

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
2. “If you think good architecture is expensive, try bad architecture.” Brian Foote
3. “If you think good 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: Groups • Alles wird in einer gemeinsamen Dokumentation festgehalten, über Gruppen („groups“) strukturiert und beim Build ausgeführt. Ausschnitt:
11. Technische Umsetzung: Alles Plugins Command Line/ Maven Scan Analyze Report Plugins Plugins Plugins
12. Scanner *.class RDBMS Schema Git JaCoCo FindBugs CheckStyle JAR, WAR, EAR ZIP application.xml web.xml MANIFEST.M F beans.xml pom.xml surefire-reports.xml GZ *.properties *.xsd M2 Repository *.yaml *.xml
13. Scanner *.class RDBMS Schema Git JaCoCo FindBugs CheckStyle JAR, WAR, EAR ZIP application.xml web.xml MANIFEST.M F beans.xml pom.xml surefire-reports.xml GZ *.properties *.xsd M2 Repository *.yaml *.xml
14. Scanner *.class RDBMS Schema Git JaCoCo FindBugs CheckStyle JAR, WAR, EAR ZIP application.xml web.xml MANIFEST.M F beans.xml pom.xml surefire-reports.xml GZ *.properties *.xsd M2 Repository *.yaml *.xml
15. Scanner *.class RDBMS Schema Git JaCoCo FindBugs CheckStyle JAR, WAR, EAR ZIP application.xml web.xml MANIFEST.M F beans.xml pom.xml surefire-reports.xml GZ *.properties *.xsd M2 Repository *.yaml *.xml
16. Scanner *.class RDBMS Schema Git JaCoCo FindBugs CheckStyle JAR, WAR, EAR ZIP application.xml web.xml MANIFEST.M F beans.xml pom.xml surefire-reports.xml GZ *.properties *.xsd M2 Repository *.yaml *.xml
17. Scanner *.class RDBMS Schema Git JaCoCo FindBugs CheckStyle JAR, WAR, EAR ZIP application.xml web.xml MANIFEST.M F beans.xml pom.xml surefire-reports.xml GZ *.properties *.xsd M2 Repository *.yaml *.xml
18. Graphentheorie mit Neo4j und Cypher
19. Ein Graph Knoten Kante
20. Graph im Detail Knoten Mögliche Arten Java-Klasse Messpunkt Datei Repository URL ...
21. Graph im Detail Kanten Typ einer Beziehung DECLARES EXTENDS IMPLEMENTS ANNOTATED_BY DEPENDS_ON ...
22. Ein Graph 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
23. Graph im Detail Labels Markierung eines Knotens :Class :Type :Java :File ... File
24. Graph im Detail Properties Eigenschaften eines Knotens fqn name visibility abstract static final ... key value name “Pet” file “Pet.java” fqn “foo.bar.Pet”
25. Beispiel Spring PetClinic
26. Sprint PetClinic: Verwaltung für Tierpraxis
27. Beispiel-Graph: Sprint PetClinic visibility: public name: Pet fqn: org.springframework.samples.petclinic.model.Pet … Class:Type:Java:File
28. Beispiel-Graph: Sprint PetClinic
29. Beispiel-Graph: Sprint PetClinic
30. Beispiel-Graph: Sprint PetClinic
31. Beispiel-Graph: Sprint PetClinic
32. Beispiel-Graph: Sprint PetClinic Kann ich abfragen!
33. Cypher Syntax
34. Cypher Syntax
35. Cypher Syntax
36. Cypher Syntax
37. Cypher Abfrage von Knoten ()-[]->()
38. Cypher Abfrage von Knoten (p)-[]->(e)
39. Cypher Abfrage von Knoten (p:Class)-[]->(e:Type)
40. Cypher Abfrage von Knoten (p:Class {name:"Pet"})-[]->(e:Type {name:"Entity"})
41. Cypher Abfrage von Knoten MATCH (p:Class {name:"Pet"})-[]->(e:Type {name:"Entity"}) RETURN p, e
42. Cypher Abfrage von Knoten MATCH (p:Class)-[]->(e:Type) WHERE p.name = "Pet" AND e.name = "Entity" RETURN p, e
43. Explorative Analysen in Neo4j Demo 1 MATCH (p:Class)-[]->(e:Type) WHERE p.name = "Pet" AND e.name = "Entity" RETURN p, e
44. Dokumentieren mit AsciiDoc und Cypher
45. AsciiDoc Markup Language • Rendert zu • DocBook • HTML • PDF mit Cypher: ausführbare Spezifikation! • Programmiervorgaben • Design und Architektur
46. 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 ----
47. 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 ----
48. Definition einer Group [[default]] [role=group,includesConstraints= "model:JpaEntityInModelPackage"] == Naming Rules The following naming rules apply: - <<model:JpaEntityInModelPackage>>
49. Ergebnisbericht Z. B. als Maven Site Report
50. Selbstvalidierende Architekturdokumentation Demo 2 Spring PetClinic
51. Plan Reality
52. • 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
53. 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/
54. 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
55. Fragerunde Eure Fragen