Faraday: Demande de fonctionnalité : définitions de méthode explicites pour les verbes HTTP

Salut @dduugg , plutôt que de définir explicitement les méthodes,
Nous utilisons également une définition de méta-programmation dans la connexion : https://github.com/lostisland/faraday/blob/master/lib/faraday/connection.rb#L195

Est-ce que cela fonctionne bien avec les points que vous avez mentionnés ci-dessus?
Si tel est le cas, nous pourrions également reproduire un extrait de documentation similaire pour le module Faraday .

Salut @iMacTia , merci pour la réponse. Je ne pense pas que le problème soit résolu avec la documentation. Puis-je vous déranger pour élaborer sur la résistance aux définitions explicites ? Je pense que cela cadrerait mieux la discussion. Par exemple, une approche de documentation est probablement aussi détaillée (en comptant diverses directives @!method & @!scope , en plus du code method_missing ) que les sept définitions de transfert explicites d'une ligne Je suggère sur Faraday . Mais je ne sais pas si c'est la raison ici (le code est lu beaucoup plus qu'il n'est écrit, donc je pense que l'optimisation pour le rédacteur de code est de toute façon une erreur).

Il y a principalement 2 points qui me mettent sur la clôture avec ce changement.

• Personnellement, je ne pense pas que l'utilisation de delegates soit un avantage uniquement pour l'auteur de code. J'utilise Ruby depuis des années et, comme d'autres, j'ai appris à apprécier la syntaxe succincte de ce langage. Quand je lis du code et que je trouve delegates je sais immédiatement ce que cela signifie et cela peut potentiellement condenser des dizaines de lignes de code en quelques-unes seulement.
• Les proxys de verbes HTTP ne sont pas la seule instance dans Faraday où nous tirons parti de la métaprogrammation, il existe de nombreuses autres instances, qui souffrent probablement du même problème que vous avez soulevé ici, mais qui n'ont pas encore été remarquées. Accepter ce changement fera soit une exception, soit créera un précédent, deux choses que j'aimerais éviter.

Mais au lieu de me concentrer sur ma résistance à ce changement, je préfère discuter du type d'avantages que nous essayons d'introduire ici. Je comprends parfaitement le problème que vous décrivez et je pense en fait que nous devrions essayer de le résoudre si possible !
Donc, si le problème principal ici est la compatibilité avec les IDE/outils pour les suggestions de code, la saisie semi-automatique et la documentation, alors je propose simplement de trouver une solution alternative comme les commentaires de documentation (nous utilisons déjà beaucoup YARD).
Et vous avez également raison lorsque vous dites que cette solution est tout aussi détaillée, même si je dirais qu'un commentaire n'aura pas autant d'impact sur la lisibilité qu'une liste de méthodes et qu'il est facilement reconnaissable.

Salut @iMacTia , merci pour votre réponse. Nous sommes passés à une bibliothèque différente avec une meilleure découverte des API et une meilleure prise en charge des outils, mais je partagerai mes réflexions au cas où vous les trouveriez utiles.

• La découvrabilité n'exclut pas l'utilisation de la métaprogrammation (bien que dans ce cas spécifique, je pense que les def explicites soient la voie à suivre), mais cela nécessiterait de remplacer l'approche method_missing , comme décrit précédemment.
• Je ne suis pas sûr de comprendre l'argument delegates . Faraday ne semble pas utiliser de délégants explicites dans la gestion des méthodes de verbe HTTP. (La confusion sur ce point est probablement une odeur de code que l'implémentation des méthodes de verbe HTTP est trop compliquée).
• Nous devrons être d'accord pour ne pas être d'accord sur le fait que delegate et autres sont une aide pour l'auteur de code. Je travaille avec des gens avec quelques décennies d'expérience collective de ruby, et nous n'avons trouvé aucun avantage de lisibilité à l'approche ici (même en tenant compte du temps perdu à essayer d'explorer l'API via pry, YARD, sorbet et solargraph ). Il peut être intéressant de regarder un rubyist tenter d'explorer cette API pour la première fois, du moins sur ce point précis.

J'essaie juste de fournir des commentaires honnêtes (et, espérons-le, utiles) ici. J'apprécie toujours le temps et les efforts consacrés à cette contribution à l'OSS.

Hé, merci pour tout votre travail acharné sur Faraday ! Je sais que c'est un vieux problème, mais j'ai tendance à convenir que la découvrabilité est un peu un problème. Je travaille sur un middleware et j'ai ajouté cette section à mon README. Ma bibliothèque est destinée à quelqu'un qui n'a peut-être jamais utilisé Faraday auparavant, il m'incombe donc d'expliquer les choses. Je dirai (un peu avec hésitation) qu'il n'a pas été facile de déchiffrer les choses.

@gurgeous Je suis d'accord que la documentation est définitivement une façade où nous pourrions faire un meilleur travail (bien que nous ayons commencé à résoudre ce problème en lançant le site Web de Faraday ), mais je ne vois pas comment la suggestion de ce numéro va résoudre votre point spécifique.

Peut-être que je manque le point parce que je suis simplement habitué à travailler d'une manière différente, mais si je ne sais pas comment utiliser une bibliothèque, je ne compte pas sur la saisie semi-automatique et je devine pour savoir quoi faire.
Au lieu de cela, je vérifie la documentation de la bibliothèque et, si cela ne vous aide pas, je plonge dans le code pour voir comment cela fonctionne.

C'est pourquoi je pense qu'une documentation améliorée (visuelle ou dans le code) est le moyen de résoudre ce problème.
Mais peut-être qu'il me manque quelque chose ici ou un cas d'utilisation particulier où une meilleure documentation ne serait pas utile ?
Ma compréhension de « découvrabilité » est-elle correcte ?

Ma compréhension de « découvrabilité » est-elle correcte ?

Pas dans mon cas. Mon attente était de pouvoir faire ls Faraday dans pry , suivi de $ Faraday.get , etc. si je voulais plonger dans une méthode spécifique. J'ai l'impression d'avoir été capable de le faire efficacement avec n'importe quel autre joyau que j'ai utilisé, ayant rarement (voire jamais) besoin de naviguer vers une page de documentation, d'où l'ouverture de ce ticket. (Cela s'ajoute aux autres problèmes mentionnés ci-dessus, tels que les outils d'analyse statique ne reconnaissant pas le code qui utilise la bibliothèque.)

Merci encore de nous avoir écoutés.

J'adore le site Faraday ! Peut-être que je peux soumettre un PR avec quelques suggestions ? Heureux d'aider. Je pense que ce genre d'effort est toujours payant pour les nouveaux arrivants. Faites-moi savoir si vous seriez intéressé.

En termes de pry + ls Faraday , je suis moi aussi fan de ce modèle et je l'utilise abondamment. S'éloigner de method_missing n'est pas une mauvaise idée. Ruby est lentement entraîné dans cette direction avec la montée en puissance de Ruby 3, des serveurs de langue, de RBS, etc. Je pense cependant que cela est secondaire par rapport à la documentation.

@gurgeous Nous docs/ avec un ensemble de Gemfile (et README) qui est utilisé pour publier le site Web sur les pages GitHub, que nous utilisons. Si son utilisation n'est pas claire, le processus de mise à jour du site Web, veuillez également ouvrir un problème ou un PR pour _that_.

Merci de vous soucier des utilisateurs de Faraday !

J'adore le site Faraday ! Peut-être que je peux soumettre un PR avec quelques suggestions ? Heureux d'aider. Je pense que ce genre d'effort est toujours payant pour les nouveaux arrivants. Faites-moi savoir si vous seriez intéressé.

@gurgeous absolument ! Nous accueillons toujours avec plaisir de l'aide pour améliorer la documentation ou le site Web, car les choses qui sont évidentes pour nous, les responsables, peuvent ne pas l'être pour les utilisateurs. De plus, nous avons vraiment du mal avec le temps et cela a souvent un coût pour la documentation. En fait, la documentation serait dans un état bien pire si ce n'était pas @olleolleolle a poursuivi ses efforts 😄!

Sur le point pry (cc @dduugg), je ne l'ai jamais utilisé, c'est pourquoi je ne comprenais probablement pas.
Je viens de l'essayer avec vos détails supplémentaires et j'ai remarqué que ls Faraday::Connection affiche les méthodes générées dynamiquement ainsi que celles déléguées 🙌.
Donc, ma compréhension initiale que nous ne pouvons pas utiliser ce genre de "magie" Ruby était fausse, et vraiment la seule limite est d'utiliser missing_method .

Ce que je n'aimais pas beaucoup, c'était l'introduction de méthodes explicites comme les suivantes :

def self.get(...)
  ...
end

def self.post(...)
  ...
end

# ... and so on ...

Mais si nous pouvons corriger la découverte de pry en ajoutant des définitions ou des délégations dynamiques au module principal Faraday , alors c'est quelque chose qui me convient. Désolé de ne pas l'avoir reçu du premier coup !

Pas de soucis de contraintes de temps. Ne vous sentez jamais mal d'être un mainteneur open source ! Nous apprécions vos efforts malgré tout. J'y ai été aussi...

Je vais lancer une discussion re: docs pour m'assurer que nous sommes sur la même longueur d'onde.

@iMacTia Comment un utilisateur saurait-il examiner Faraday::Connection ? Depuis, je suis passé à un joyau HTTP avec une API détectable, mais j'ai jeté un coup d'œil à https://lostisland.github.io/faraday/usage/ et aucun des exemples de code ne l'utilise explicitement (bien que le dernier le fasse implicitement). Les exemples invoquent principalement des méthodes statiques sur Faraday , mais elles ne sont pas trouvées dans pry. Je ne connais aucun autre joyau qui a adopté cette approche, et je considère toujours que c'est un anti-modèle.

Merci, comme toujours, de m'avoir écouté.