<!-- What goes in this file will appear on near the end of <head>--><linkrel='preload'href='_emanote-static/fonts/Maven_Pro/MavenPro-VariableFont_wght.ttf'as='font'type='font/ttf'crossorigin/>
<style>
@font-face {
font-family: 'MavenPro';
/* FIXME: This ought to be: ${ema:emanoteStaticLayerUrl}/fonts/Maven_Pro/MavenPro-VariableFont_wght.ttf */
<!-- What goes in this file will appear on top of note body-->
<pclass='mb-3'>
Step-by-Step-Anleitung, wie man ein neues Projekt mit einer bereits erprobten Pipeline erstellt.
</p>
<h2id='definition-der-api'class='inline-block mt-6 mb-4 text-4xl font-bold text-gray-700 border-b-2'>Definition der API</h2>
<pclass='mb-3'>
Erster Schritt ist immer ein wünsch-dir-was bei der Api-Defenition.
</p>
<pclass='mb-3'>
Die meisten Services haben offensichtliche Anforderungen (Schnittstellen nach draußen, Schnittstellen intern, …). Diese kann man immer sehr gut in einem <codeclass='py-0.5 px-0.5 bg-gray-100'>Request -> Response</code>-Model erfassen.
</p>
<pclass='mb-3'>
Diese Definition läuft über openapi-v3 und kann z.b. mit Echtzeit-Vorschau im <ahref='http://editor.swagger.io/'class='text-red-600 hover:underline'target='_blank'rel='noopener'>http://editor.swagger.io/</a> erspielen. Per Default ist der noch auf openapi-v2 (aka swagger), kann aber auch v3.
</p>
<pclass='mb-3'>
Nach der Definition, was man am Ende haben möchte, muss man sich entscheiden, in welcher Sprache man weiter entwickelt. Ich empfehle aus verschiedenen Gründen primär 2 Sprachen: Python-Microservices (weil die ML-Libraries sehr gut sind, allerdings Änderungen meist schwer sind und der Code wenig robust - meist nur 1 API-Endpunkt pro service) und Haskell (stabilität, performace, leicht zu ändern, gut anzupassen).
</p>
<pclass='mb-3'>
Im folgenden wird (aus offensichtlichen Gründen) nur auf das Haskell-Projekt eingegangen.
</p>
<h2id='startprojekt-in-haskell'class='inline-block mt-6 mb-4 text-4xl font-bold text-gray-700 border-b-2'>Startprojekt in Haskell</h2><h3id='erstellen-eines-neuen-projektes'class='mt-6 mb-2 text-3xl font-bold text-gray-700'>Erstellen eines neuen Projektes</h3>
<divclass='py-0.5 mb-3 text-sm'><pre><codeclass='bash language-bash'>stack new myservice</code></pre></div>
<pclass='mb-3'>
Dies erstellt ein neues Verzeichnis und das generelle scaffolding. Nach einer kurzen anpassung der stack.yaml (resolver auf unserer setzen; aktuell: lts-17.4) fügen wir am Ende der Datei
ein. Anschließend organisieren™ wir uns noch eine gute <codeclass='py-0.5 px-0.5 bg-gray-100'>.gitignore</code> und initialisieren das git mittels <codeclass='py-0.5 px-0.5 bg-gray-100'>git init; git add .; git commit -m "initial scaffold"</code>
<h3id='generierung-der-api'class='mt-6 mb-2 text-3xl font-bold text-gray-700'>Generierung der API</h3>
<pclass='mb-3'>
Da die API immer wieder neu generiert werden kann (und sollte!) liegt sich in einem unterverzeichnis des Haputprojektes.
</p>
<pclass='mb-3'>
Initial ist es das einfachste ein leeres temporäres Verzeichnis woanders zu erstellen, die <codeclass='py-0.5 px-0.5 bg-gray-100'>api-doc.yml</code> hinein kopieren und folgendes ausführen:
Dieses erstellt einem dann eine komplette library inkl. Datentypen. Wichtig: Der Name in der api-doc sollte vom Namen des Services (oben myservice) abweichen - entweder in Casing oder im Namen direkt. Suffixe wie API schneidet der Generator hier leider ab. (Wieso das ganze? Es entstehen nachher 2 libraries, foo & fooAPI. Da der generator das API abschneidet endet man mit foo & foo und der compiler meckert, dass er nicht weiss, welche lib gemeint ist).
</p>
<pclass='mb-3'>
danach: wie gewohnt <codeclass='py-0.5 px-0.5 bg-gray-100'>git init; git add .; git commit -m "initial"</code>. Auf dem Server der Wahl (github, gitea, gitlab, …) nun ein Repository erstellen (am Besten: myserviceAPI - alles auf API endend ist autogeneriert!) und den Anweisungen nach ein remote hinzufügen & pushen.
</p>
<h4id='wieder-zurück-im-haskell-service'class='mt-6 mb-2 text-2xl font-bold text-gray-700'>Wieder zurück im Haskell-Service</h4>
<pclass='mb-3'>
In unserem eigentlichen Service müssen wir nun die API einbinden. Dazu erstellen wir ein Verzeichnis <codeclass='py-0.5 px-0.5 bg-gray-100'>libs</code> (konvention) und machen ein <codeclass='py-0.5 px-0.5 bg-gray-100'>git submodule add <repository-url> libs/myserviceAPI</code>
</p>
<pclass='mb-3'>
Git hat nun die API in das submodul gepackt und wir können das oben erstellte temporäre verzeichnis wieder löschen.
</p>
<pclass='mb-3'>
Anschließend müssen wir stack noch erklären, dass wir die API da nun liegen haben und passen wieder die stack.yaml an, indem wir das Verzeichnis unter packages hinzufügen.
nun können wir in der <codeclass='py-0.5 px-0.5 bg-gray-100'>package.yaml</code> (oder <codeclass='py-0.5 px-0.5 bg-gray-100'>myservice.cabal</code>, falls kein hpack verwendet wird) unter den dependencies unsere api hinzufügen (name wie die cabal-datei in libs/myserviceAPI).
Funktioniert komplett analog zu dem vorgehen oben (ohne das generieren natürlich <spanclass='emoji'data-emoji='grin'style='font-family: emoji'>😁</span>). <codeclass='py-0.5 px-0.5 bg-gray-100'>stack.yaml</code> editieren und zu den packages hinzufügen:
in der <codeclass='py-0.5 px-0.5 bg-gray-100'>package.yaml</code> (oder der cabal) die dependencies hinzufügen und schon haben wir die Features zur Verfügung und können gegen diese Services reden.
</p>
<h3id='entfernen-von-anderen-technologienmicroservices'class='mt-6 mb-2 text-3xl font-bold text-gray-700'>Entfernen von anderen Technologien/Microservices</h3>
<pclass='mb-3'>
In git ist das entfernen von Submodules etwas frickelig, daher hier ein copy&paste der <ahref='https://gist.github.com/myusuf3/7f645819ded92bda6677'class='text-red-600 hover:underline'target='_blank'rel='noopener'>GitHub-Antwort</a>:
</p>
<divclass='py-0.5 mb-3 text-sm'><pre><codeclass='bash language-bash'>## Remove the submodule entry from .git/config
git submodule deinit -f path/to/submodule
## Remove the submodule directory from the superproject's .git/modules directory
rm-rf .git/modules/path/to/submodule
## Remove the entry in .gitmodules and remove the submodule directory located at path/to/submodule
git rm-f path/to/submodule</code></pre></div>
<pclass='mb-3'>
Falls das nicht klappt, gibt es alternative Vorschläge unter dem Link oben.
</p>
<h3id='woher-weiss-ich-was-wo-liegt-dokumentation-halloo'class='mt-6 mb-2 text-3xl font-bold text-gray-700'>Woher weiss ich, was wo liegt? Dokumentation? Halloo??</h3>
<pclass='mb-3'>
Keine Panik. Ein <codeclass='py-0.5 px-0.5 bg-gray-100'>stack haddock --open</code> hilft da. Das generiert die Dokumentation für alle in der <codeclass='py-0.5 px-0.5 bg-gray-100'>package.yaml</code> (oder cabal-file) eingetragenen dependencies inkl. aller upstream-dependencies. Man bekommt also eine komplette lokale Dokumentation von allem. Geöffnet wird dann die Paket-Startseite inkl. der direkten dependencies:
</p>
<pclass='mb-3'>
Es gibt 2 wichtige Pfade im Browser:
</p>
<ulclass='my-3 ml-6 space-y-1 list-disc'>
<li>
…../all/index.html - hier sind alle Pakete aufgeführt
</li>
<li>
…../index.html - hier sind nur die direkten dependencies aufgeführt.
</li>
</ul>
<pclass='mb-3'>
Wenn man einen lokalen Webserver startet kann man mittels “s” auch die interaktive Suche öffnen (Suche nach Typen, Funktionen, Signaturen, etc.). In Bash mit python3 geht das z.b. einfach über:
firefox "http://localhost:8000"</code></pre></div><h3id='implementation-des-services-und-start'class='mt-6 mb-2 text-3xl font-bold text-gray-700'>Implementation des Services und Start</h3><h4id='loaderbootstrapper'class='mt-6 mb-2 text-2xl font-bold text-gray-700'>Loader/Bootstrapper</h4>
<pclass='mb-3'>
Generelles Vorgehen:
</p>
<ulclass='my-3 ml-6 space-y-1 list-disc'>
<li>
<pclass='mb-3'>
in app/Main.hs: Hier ist quasi immer nur eine Zeile drin: <codeclass='py-0.5 px-0.5 bg-gray-100'>main = myServiceMain</code>
</p>
<pclass='mb-3'>
Grund: Applications tauchen nicht im Haddock auf. Also haben wir ein “src”-Modul, welches hier nur geladen & ausgeführt wird.
</p>
</li>
<li>
<pclass='mb-3'>
in src/MyService.hs: <codeclass='py-0.5 px-0.5 bg-gray-100'>myServiceMain :: IO ()</code> definieren
</p>
</li>
</ul>
<pclass='mb-3'>
Für die Main kann man prinzipiell eine Main andere Services copy/pasten. Im folgenden eine Annotierte main-Funktion - zu den einzelnen Vorraussetzungen kommen wir im Anschluss.
Wie man das verwendet, siehe <ahref='Haskell/Webapp-Example'class='text-red-600 mavenLinkBold hover:underline'data-wikilink-type='WikiLinkTag'>Webapp-Development in Haskell</a>.
-- activeMQ-Transaktional-Queue zum schreiben nachher vorbereiten
amqPost <- newTQueueIO
-- bracket a b c == erst a machen, ergebnis an c als variablen übergeben. Schmeisst c ne exception/wird gekillt/..., werden die variablen an b übergeben.
-- H.myApiEndpointV1Post ist ein Handler (alle Handler werden mit alias H importiert) und in einer eigenen Datei
-- Per Default bekommen Handler sowas wie die server-config, die Funktionen um mit anderen Services zu reden, die AMQ-Queue um ins Kibana zu loggen und eine Datei-Logging-Funktion
-- Man kann aber noch viel mehr machen - z.b. gecachte Daten übergeben, eine Talk-Instanz, etc. pp.
server = MyServiceBackend{ myApiEndpointV1Post = H.myApiEndpointV1Post sc calls amqPost log
<h4id='weitere-instanzen-und-definitionen-die-der-generator-noch-nicht-macht'class='mt-6 mb-2 text-2xl font-bold text-gray-700'>Weitere Instanzen und Definitionen, die der Generator (noch) nicht macht</h4>
In der <codeclass='py-0.5 px-0.5 bg-gray-100'>Myservice.Types</code> werden ein paar hilfreiche Typen und Typinstanzen definiert. Im Folgenden geht es dabei um Dinge für:
</p>
<ulclass='my-3 ml-6 space-y-1 list-disc'>
<li>
Envy
<ulclass='my-3 ml-6 space-y-1 list-disc'>
<li>
Laden von $ENV_VAR in Datentypen
</li>
<li>
Definitionen für Default-Settings
</li>
</ul>
</li>
<li>
ServerConfig
<ulclass='my-3 ml-6 space-y-1 list-disc'>
<li>
Definition der Server-Konfiguration & Benennung der Environment-Variablen
</li>
</ul>
</li>
<li>
ExtraTypes
<ulclass='my-3 ml-6 space-y-1 list-disc'>
<li>
ggf. Paketweite extra-Typen, die der Generator nicht macht, weil sie nicht aus der API kommen (z.B. cache)
</li>
</ul>
</li>
<li>
Out/BSON-Instanzen
<ulclass='my-3 ml-6 space-y-1 list-disc'>
<li>
Der API-Generator generiert nur wenige Instanzen automatisch (z.B. Aeson), daher werden hier die fehlenden definiert.
-- Out hat hierfür keine Instanzen, daher kurz eine einfach Definition.
instance Out Text where
doc = text . unpack
docPrec i a = text $ showsPrec i a ""
instance Out UTCTime where
doc = text . show
docPrec i a = text $ showsPrec i a ""
-- Der ServerConfig-Typ. Wird mit den defaults unten initialisiert, dann mit den Variablen aus der .env-Datei überschrieben und zum Schluss können Serveradmins diese via $MYSERVICE_FOO nochmal überschreiben.
Den Service implementieren. Einfach ein neues Modul aufmachen (z.B. <codeclass='py-0.5 px-0.5 bg-gray-100'>MyService.Handler</code> oder <codeclass='py-0.5 px-0.5 bg-gray-100'>MyService.DieserEndpunktbereich</code>/<codeclass='py-0.5 px-0.5 bg-gray-100'>MyService.JenerEndpunktbereich</code>) und dort die Funktion implementieren, die man in der <codeclass='py-0.5 px-0.5 bg-gray-100'>Main.hs</code> benutzt hat. In dem Handler habt ihr dann keinen Stress mehr mit validierung, networking, logging, etc. pp. weil alles in der Main abgehandelt wurde und ihr nur noch den “Happy-Case” implementieren müsst. Beispiel für unseren Handler oben:
Generieren einer Serverantwort und ausliefern dieser über die Schnittstelle
</li>
</ul>
<h4id='tipps--tricks'class='mt-6 mb-2 text-2xl font-bold text-gray-700'>Tipps & Tricks</h4><h5id='dateien-die-statisch-ausgeliefert-werden-sollen'class='mt-6 mb-2 text-xl font-bold text-gray-700'>Dateien, die statisch ausgeliefert werden sollen</h5>
<pclass='mb-3'>
Hierzu erstellt man ein Verzeichnis <codeclass='py-0.5 px-0.5 bg-gray-100'>static/</code> (konvention; ist im generator so generiert, dass das ausgeliefert wird). Packt man hier z.b. eine <codeclass='py-0.5 px-0.5 bg-gray-100'>index.html</code> rein, erscheint die, wenn man den Service ansurft.
</p>
<h5id='wie-bekomme-ich-diese-fancy-preview-hin'class='mt-6 mb-2 text-xl font-bold text-gray-700'>Wie bekomme ich diese fancy Preview hin?</h5>
<pclass='mb-3'>
Der Editor, der ganz am Anfang zum Einsatz gekommen ist, braucht nur die <codeclass='py-0.5 px-0.5 bg-gray-100'>api-doc.yml</code> um diese Ansicht zu erzeugen. Daher empfielt sich hier ein angepasster Fork davon indem die Pfade in der index.html korrigiert sind. Am einfachsten (und von den meisten services so benutzt): In meiner Implementation liegt dann nach dem starten auf http://localhost:PORT/ui/ und kann direkt dort getestet werden.
</p>
<h5id='wie-sorge-ich-für-bessere-warnungen-damit-der-compiler-meine-bugs-fängt'class='mt-6 mb-2 text-xl font-bold text-gray-700'>Wie sorge ich für bessere Warnungen, damit der Compiler meine Bugs fängt?</h5><divclass='py-0.5 mb-3 text-sm'><pre><codeclass='bash language-bash'>stack build --file-watch --ghc-options '-freverse-errors -W -Wall -Wcompat' --interleaved-output</code></pre></div>
<pclass='mb-3'>
Was tut das?
</p>
<ulclass='my-3 ml-6 space-y-1 list-disc'>
<li>
<codeclass='py-0.5 px-0.5 bg-gray-100'>--file-watch</code>: automatisches (minimales) kompilieren bei dateiänderungen
<codeclass='py-0.5 px-0.5 bg-gray-100'>-freverse-errors</code>: Fehlermeldungen in umgekehrter Reihenfolge (Erster Fehler ganz unten; wenig scrollen )
</li>
<li>
<codeclass='py-0.5 px-0.5 bg-gray-100'>-W</code>: Warnungen an
</li>
<li>
<codeclass='py-0.5 px-0.5 bg-gray-100'>-Wall</code>: Alle sinnvollen Warnungen an (im gegensatz zu <codeclass='py-0.5 px-0.5 bg-gray-100'>-Weverything</code>, was WIRKLICH alles ist )
</li>
<li>
<codeclass='py-0.5 px-0.5 bg-gray-100'>-Wcompat</code>: Warnungen für Sachen, die in der nächsten Compilerversion kaputt brechen werden & vermieden werden sollten
</li>
</ul>
</li>
<li>
<codeclass='py-0.5 px-0.5 bg-gray-100'>--interleaved-output</code>: stack-log direkt ausgeben & nicht in dateien schreiben und die dann am ende zusammen cat'en.
</li>
</ul>
<pclass='mb-3'>
Um pro Datei Warnungen auszuschalten (z.B. weil man ganz sicher weiss, was man tut -.-): <codeclass='py-0.5 px-0.5 bg-gray-100'>{-# OPTIONS_GHC -Wno-whatsoever #-}</code> als Pragma in die Datei.
</p>
<pclass='mb-3'>
<strong>Idealerweise sollte das Projekt keine Warnungen erzeugen.</strong>
Als Beispiel sei hier ein einfaches Docker-Build mit Jenkins-CI gezeigt, weil ich das aus Gründen rumliegen hatte. Kann man analog in fast alle anderen CI übrsetzen.
Die angehängten Scripte gehen von einer Standard-Einrichtung aus (statische sachen in static, 2-3 händische Anpassungen auf das eigene Projekt nach auspacken). Nachher liegt dann auch unter static/version die gebaute Versionsnummer & kann abgerufen werden. In der Dockerfile.release und der Jenkinsfile müssen noch anpassungen gemacht werden. Konkret:
</p>
<ulclass='my-3 ml-6 space-y-1 list-disc'>
<li>
in der Dockerfile.release: alle <codeclass='py-0.5 px-0.5 bg-gray-100'><<<HIER>>></code>-Stellen sinnvoll befüllen
</li>
<li>
in der Jenkinsfile die defs für “servicename” und “servicebinary” ausfüllen. Binary ist das, was bei stack exec aufgerufen wird; name ist der Image-Name für das docker-repository.
Environment-Vars anpasses ($BRANCH = test & live haben keine zusatzdinger im docker-image-repository; ansonsten hat das image $BRANCH im namen)
</li>
</ul>
<pclass='mb-3'>
Wenn das durchgebaut ist, liegt im test/live-repository ein docker-image namens <codeclass='py-0.5 px-0.5 bg-gray-100'>servicename:version</code>.
</p>
<h3id='omg-ich-muss-meine-api-ändern-was-mache-ich-nun'class='mt-6 mb-2 text-3xl font-bold text-gray-700'>OMG! Ich muss meine API ändern. Was mache ich nun?</h3>
<div><p>Wie man das verwendet, siehe <ahref='Haskell/Webapp-Example'class='text-gray-600 font-bold hover:bg-gray-50'data-wikilink-type='WikiLinkTag'>Webapp-Development in Haskell</a>.</p></div>
