Entwickler, lasst uns hier über die Entwicklungen v4 diskutieren!

Entwicklung
1

Hallo an alle Entwickler der v4 :slight_smile:

Zuerst einmal ein großes Dankeschön für euer Engagement bei der v4. Es ist super cool, so viele Entwickler zu sehen, die sich für diese Version interessieren, und wir kommen enorm dank euch voran, bravo :clap:

Ich wollte ein Thema starten, um allgemein über die Entwicklungen der v4 zu sprechen. Seht das als einen « allgemeinen » Kanal für Entwickler!

Ich beginne mit einem ersten Beitrag, um über den Entwicklungsprozess zu sprechen, aber ihr könnt über alles und nichts in diesem Kanal sprechen, dafür ist er da.

@AlexTrovato @joeypic @link39 @Pti_Nico @billona @VonOx @Reno @bertrandda

Lasst uns über den Entwicklungsprozess sprechen

Ich habe in letzter Zeit viele PRs überprüft und wollte einen Beitrag schreiben, um über die kleinen Dinge zu sprechen, die ich gesehen habe und die häufig auftreten, damit wir alle auf derselben Wellenlänge sind :slight_smile:

Ich warne euch: Ich werde hauptsächlich über Frontend sprechen, und ich weiß, dass ihr eher Technologie- und Backend-Entwickler seid (wie ich!). Für uns ist oft das Backend das Wichtigste: Ich möchte, dass wir das ändern :smiley:

Für den Benutzer ist Gladys das Frontend, das Backend ist ein Detail. Ja, es ist schwer, ein gutes Backend zu machen, aber ein gutes Frontend zu machen, ist noch schwieriger!

Hinweis: In meinen Entwicklungen von Gladys 4 gibt es einige Code-Schnipsel, die ich geschrieben habe, die nicht dem entsprechen, was ich hier sage, weil sich meine Überlegungen seit Beginn der Entwicklung vor über einem Jahr bis heute weiterentwickelt haben. Ich versuche, den Code kontinuierlich zu verbessern, um all das zu respektieren :slight_smile:

1. Der Entwicklungsprozess

Für mich ist in der v4 die UI/UX der Dienste der wichtigste Teil eurer Entwicklung. Normalerweise, wenn ich jetzt in der v4 entwickle, beginne ich zuerst mit dem Frontend, um von dem auszugehen, was ich visuell möchte, und gehe dann zur Technologie, zum Backend.

Das Backend muss entwickelt werden, um den Anforderungen der UI gerecht zu werden, und nicht umgekehrt!

Denkt an den Benutzerfluss!

2. Leere Zustände

Wenn ein Benutzer auf eine Integration zugreift, muss er sofort verstehen, was zu tun ist. Er muss verstehen, warum die Integration in diesem Zustand ist und was er tun muss, um dies zu beheben.

Beispiel: Auf der Startseite kann der Benutzer standardmäßig sehen:

Screenshot 2020-03-28 at 11.11.46
Screenshot 2020-03-28 at 11.11.462880×1408 219 KB

  • Ein nettes Icon verhindert, dass der Bildschirm « leer » wirkt
  • Der erste Satz sagt ihm, warum dieser Bildschirm leer ist: Sein Dashboard ist nicht konfiguriert.
  • Der zweite Satz sagt ihm, was er tun muss: Er muss auf die Schaltfläche « Bearbeiten » klicken, um seine Integration zu konfigurieren

Ein weiteres Beispiel: Die Seite « Nachricht », der Standardzustand zeigt ein nettes Icon, um zu füllen + eine Nachricht, die angibt, wie man beginnt:

Screenshot 2019-10-30 at 11.22.24
Screenshot 2019-10-30 at 11.22.242880×1252 181 KB

Alle Integrationen müssen so sein, der Benutzer muss auf die Seite kommen und wissen:

  • Der Zustand der Integration: Ist sie konfiguriert? Warum ist sie leer?
  • Was tun, um fortzufahren: Muss er 3 Sekunden auf den Rücken seines Geräts drücken? Muss er einen API-Schlüssel konfigurieren? Oder muss er ihn finden?

Die UI der Integration muss für sich selbst sprechen, der Benutzer muss die Integration konfigurieren können, ohne ins Internet oder auf das Forum zu gehen.

Für zusätzliche Informationen kann ein Link zur Dokumentation bereitgestellt werden: aber nur, um zusätzliche Informationen zu erhalten, dies sollte nicht das Grundlegende des leeren Zustands + was zu tun ist ersetzen.

3. Die « Ladezustände »

Wenn ihr Aktionen ausführt und die UI auf etwas wartet, muss der Benutzer wissen, dass etwas im Gange ist.

Nachricht wird gesendet…

Screenshot 2019-10-30 at 11.25.14
Screenshot 2019-10-30 at 11.25.141629×418 6.51 KB

Bild einer Kamera wird geladen..

Screenshot 2020-03-28 at 11.31.08
Screenshot 2020-03-28 at 11.31.08866×514 3.45 KB

Um all das zu testen, empfehle ich, euren Browser auf « Slow 3G » zu setzen, um die Anwendung mit vielen Ladezuständen zu testen:

Screenshot 2020-03-28 at 11.32.56
Screenshot 2020-03-28 at 11.32.562234×966 162 KB

4. Fehlerbehandlung

Wenn der Benutzer eine Aktion in der UI ausführt, durchläuft er verschiedene Zustände:

  • Die Anfrage wird an das Backend gesendet
  • Das Frontend wartet (Ladezustand), dann:
    • Das Frontend erhält eine positive Antwort: alles ist gut gelaufen
    • Das Frontend erhält einen Fehlercode + eine Fehlermeldung

Das Frontend muss alle Fehler behandeln, die das Backend sendet, und jeder Fehler des Backends muss eine Übersetzung in der UI haben.

Die Fehler müssen denselben Regeln wie die « leeren Zustände » folgen: eine Erklärung, was passiert, + eine klare Aktion, wie das Problem zu lösen ist.

Beispiel auf der Wetterbox:

Screenshot 2020-03-28 at 11.37.38
Screenshot 2020-03-28 at 11.37.38820×464 23.7 KB

Der Fehler gibt 1) an, was passiert, « der Darksky-Dienst ist nicht konfiguriert » 2) die Schritte zur Konfiguration, « er muss zum Integrations-Tab gehen, usw… »

Fazit

Es ist schwer, ein gutes Frontend zu machen! :smiley: Aber welche Belohnung, zu sehen, dass die Benutzer danach zurechtkommen, ohne 10 Beiträge im Forum lesen zu müssen und 10 Dokumente durchzublättern…

Ich habe momentan jeden Tag Gespräche mit Mitgliedern der Community, und sie sind alle begeistert von der Einfachheit der v4 im Vergleich zur v3, wo einige ganze Wochenenden damit verbracht haben, nur eine Information zu finden, die auf der Konfigurationsseite des Dienstes hätte stehen können… ^^

Danke an euch alle für eure Arbeit :folded_hands:

2

Ich nutze die Gelegenheit, um auf die Antwort eines PR einzugehen, den ich gerade an @bertrandda gemacht habe, bezüglich der Fehlerbehandlung.

In Ihrem Code empfehle ich Ihnen, Fehler zu werfen, die in den Dateien utils/coreErrors.js oder utils/httpErrors definiert sind, mit einem klaren Fehlercode, der auf eine Übersetzung in der UI abgebildet werden muss.

Beispiel für eine saubere Fehlerbehandlung auf der Backend-Seite:

const { BRIDGE_NOT_FOUND } = require('../utils/constants');

async function configureBridge(serialNumber) {
  const bridge = this.bridgesBySerialNumber.get(serialNumber);
  if (!bridge) {
    throw new NotFoundError(BRIDGE_NOT_FOUND);
  }
  // dann, den Rest machen
}

Im Fehlerfall:

  • ein nativen Fehler wird mit einem präzisen Fehlercode ausgegeben
  • im Fehler-Middleware wird dieser Fehler in einen 404-Fehler mit der Fehlermeldung des Fehlercodes umgewandelt
  • in der UI kann der Entwickler leicht erkennen, welches das Problem ist, und eine Fehler aus den Übersetzungen anzeigen! :slight_smile:
3

Ich brauche Hilfe :smiley:

Ich habe diesen Fehler

Invariant Violation: address should be an string or undefined
    at invariant (/home/vonox/Repository/GladysFork/server/services/onkyo/node_modules/invariant/invariant.js:40:15)
    at Onkyo.validate (/home/vonox/Repository/GladysFork/server/services/onkyo/node_modules/onkyo.js/lib/Onkyo.js:90:5)
    at new Onkyo (/home/vonox/Repository/GladysFork/server/services/onkyo/node_modules/onkyo.js/lib/Onkyo.js:48:10)
    at Object.OnkyoService [as onkyo] (/home/vonox/Repository/GladysFork/server/services/onkyo/index.js:9:25)
    at /home/vonox/Repository/GladysFork/server/lib/service/service.load.js:37:65
    at async Promise.all (index 4)
    at async Service.load (/home/vonox/Repository/GladysFork/server/lib/service/service.load.js:14:3)
    at async Object.start (/home/vonox/Repository/GladysFork/server/lib/index.js:103:9)
    at async /home/vonox/Repository/GladysFork/server/index.js:18:3 {
  framesToPop: 1
}

Ich denke, ich habe es verstanden, aber ich weiß nicht, wie ich es lösen soll.

Offensichtlich liegt es daran, dass die Bibliothek, die ich verwende, denselben Namen wie der Dienst hat (onkyo)

module.exports = function OnkyoService(gladys, serviceId) {
    const { Onkyo } = require('onkyo.js');
    const { OnkyoDiscover } = require('onkyo.js');
    const discover = new OnkyoDiscover();
    const onkyoClient = new Onkyo();
    const onkyoAvrHandler = new OnkyoAvrHandler(gladys, onkyoClient, discover, serviceId);

Habe ich recht oder liege ich falsch?

4

Verwende VSCode + Eslint + Prettier (als Modul in der IDE installiert), dann siehst du sofort den Fehler in der IDE :slight_smile:

5

Das ist bereits der Fall

image
image901×260 48.8 KB

Es ist grün, aber damit mein Dienst startet, muss ich die Zeile 7 entfernen.

6

Ich habe mir das Modul angesehen, das du verwendest:

Tatsächlich fehlt die Adresse in deinem Konstruktor:

const onkyo = Onkyo({address: '192.168.0.100'});
7

OK, ich habe meinen Kram falsch gedacht, ich kann da nicht « l’import » machen.

Aber die Fehlermeldung hat mir überhaupt nichts gesagt :sweat_smile:

Jedenfalls beweist das, dass Gladys auch mit einem kaputten Service startet :+1: