Création d'une API fluide

Question

Comment crée-t-on une API qui est fluide par nature ?

Est-ce en utilisant principalement des méthodes d'extension ?

Answer 1

Cet article explique beaucoup mieux que je ne pourrais le faire.

MODIFICATION, je ne peux pas tout mettre dans un commentaire...

Il y a deux côtés aux interfaces, l'implémentation et l'utilisation. Il y a plus de travail à faire du côté de la création, je suis d'accord avec cela, cependant les principaux avantages se trouvent du côté de l'utilisation des choses. En effet, pour moi, l'avantage principal des interfaces fluides est une API plus naturelle, plus facile à mémoriser et à utiliser et pourquoi pas, plus esthétiquement agréable. Et peut-être que l'effort de devoir adapter une API de manière fluide pourrait conduire à une API mieux réfléchie ?

Comme le dit Martin Fowler dans l'article original sur les interfaces fluides:

Probablement la chose la plus importante à noter à propos de ce style est que l'intention est de faire quelque chose le long des lignes d'un Langage de Domaine Spécifique interne. En fait, c'est pourquoi nous avons choisi le terme "fluide" pour le décrire, de nombreuses manières les deux termes sont synonymes. L'API est principalement conçue pour être lisible et pour couler. Le prix de cette fluidité est plus d'efforts, à la fois dans la réflexion et dans la construction de l'API elle-même. L'API simple des méthodes de constructeur, de définition et d'ajout est bien plus facile à écrire. Trouver une belle API fluide nécessite une bonne réflexion.

Comme dans la plupart des cas les API sont créées une fois pour être utilisées encore et encore, l'effort supplémentaire peut en valoir la peine.

Et verbeux ? Je suis tout pour la verbosité si elle sert à la lisibilité d'un programme.

Answer 2

MrBlah,

Bien que vous puissiez écrire des méthodes d'extension pour écrire une interface fluide, une meilleure approche consiste à utiliser le pattern builder. Je suis dans la même situation que vous et j'essaie de comprendre quelques fonctionnalités avancées des interfaces fluides.

Vous trouverez ci-dessous un exemple de code que j'ai créé dans un autre fil de discussion

public class Coffee
{
    private bool _cream;
    private int _ounces;

    public static Coffee Make { get { return new Coffee(); } }

    public Coffee WithCream()
    {
        _cream = true;
        return this;
    }
    public Coffee WithOuncesToServe(int ounces)
    {
        _ounces = ounces;
        return this;
    }
}

var myMorningCoffee = Coffee.Make.WithCream().WithOuncesToServe(16);

Answer 3

Alors que de nombreuses personnes citent Martin Fowler comme étant un important partisan de la discussion sur les API fluides, ses premières revendications en matière de conception tournent en réalité autour d'un pattern builder fluide ou d'un enchaînement de méthodes. Les API fluides peuvent évoluer en véritables langages spécifiques à un domaine internes. Un article expliquant comment une notation BNF d'une grammaire peut être transformée manuellement en une "API fluide" peut être vu ici :

http://blog.jooq.org/2012/01/05/the-java-fluent-api-designer-crash-course/

Il transforme cette grammaire :

En cette API Java :

// Interface initiale, point d'entrée du DSL
interface Début {
  Fin motUnique();
  Fin motParamétré(String paramètre);
  Intermédiaire1 mot1();
  Intermédiaire2 mot2();
  Intermédiaire3 mot3();
}

// Interface de terminaison, peut également contenir des méthodes comme execute();
interface Fin {
  void fin();
}

// Intermédiaire "étape" du DSL étendant l'interface retournée par motOptionnel(), pour rendre cette méthode "optionnelle"
interface Intermédiaire1 extends Fin {
  Fin motOptionnel();
}

// Intermédiaire "étape" du DSL offrant plusieurs choix (similaire à Début)
interface Intermédiaire2 {
  Fin choixMotA();
  Fin choixMotB();
}

// Interface intermédiaire se retournant sur elle-même sur word3(), afin de permettre les répétitions. Les répétitions peuvent être arrêtées à tout moment car cette interface étend Fin
interface Intermédiaire3 extends Fin {
  Intermédiaire3 mot3();
}

Java et C# étant quelque peu similaires, l'exemple se traduit certainement également à votre cas d'utilisation. La technique ci-dessus a été largement utilisée dans jOOQ, un modelage de langage SQL en Java utilisant une API fluide / un langage spécifique à un domaine interne

Answer 4

KISS : Garder les choses simples et stupides.

Le design fluide concerne un principe esthétique utilisé uniformément dans toute l'API. Bien que votre méthodologie utilisée dans votre API puisse changer légèrement, il est généralement préférable de rester cohérent.

Même si vous pensez que "tout le monde peut utiliser cette API, car elle utilise toutes sortes de méthodologies différentes", la vérité est que l'utilisateur commencerait à se sentir perdu car vous changez constamment la structure/la structure des données de l'API vers un nouveau principe de conception ou une nouvelle convention de nommage.

Si vous souhaitez changer en cours de route vers un autre principe de conception, par exemple... Passer de codes d'erreur à la gestion des exceptions en raison d'une puissance de commande supérieure. Ce serait une folie et entraînerait généralement beaucoup de douleur. Il vaut mieux rester sur la bonne voie et ajouter des fonctionnalités que vos clients peuvent utiliser et vendre que de les obliger à réécrire et à redécouvrir tous leurs problèmes à nouveau.

En suivant ce qui précède, vous pouvez voir qu'il y a plus à faire pour écrire une API fluide que ce que l'on voit. Il y a des choix psychologiques et esthétiques à faire avant de commencer à en écrire une, et même alors, le sentiment, le besoin et le désir de se conformer aux demandes des clients et de rester cohérents est le plus difficile de tous.

Answer 5

Qu'est-ce qu'une API fluide

Wikipedia les définit ici http://en.wikipedia.org/wiki/Fluent_interface

Pourquoi ne pas utiliser une interface fluide

Je suggérerais de ne pas implémenter une interface fluide traditionnelle, car cela augmente la quantité de code que vous devez écrire, complique votre code et ajoute simplement du code inutile.

Une autre option, ne rien faire!

Ne pas implémenter quoi que ce soit. Ne pas fournir de constructeurs "faciles" pour définir les propriétés et ne pas fournir une interface intelligente pour aider votre client. Permettez au client de définir les propriétés comme il le ferait normalement. En .Net C# ou VB, cela pourrait être aussi simple que d'utiliser les initialiseurs d'objets.

Car myCar = new Car { Name = "Chevrolet Corvette", Color = Color.Yellow };

Vous n'avez donc pas besoin de créer d'interface intelligente dans votre code, et c'est très lisible.

Si vous avez des ensembles de propriétés très complexes qui doivent être définis, ou définis dans un certain ordre, utilisez un objet de configuration séparé et transmettez-le à la classe via une propriété séparée.

CarConfig conf = new CarConfig { Color = Color.Yellow, Fabric = Fabric.Leather };
Car myCar = new Car { Config = conf };