Rails ERD: visualisation rapide d'un projet rails

Nous sommes parfois amenés à devoir comprendre rapidement un projet rails en cours de développement. Les raisons peuvent être multiples:

• rejoindre une équipe de développement sur un projet existant
• besoin d’un renfort sur un projet afin de respecter une deadline
• faciliter les discussions avec les clients techniques
• revenir sur un projet qui peut être en standby depuis un moment
• etc …

Selon l’avancée du projet et selon votre expérience, il peut être difficile de comprendre les tenants et aboutissants de l’application rapidement. Cette étape est pourtant primordiale car elle vous fera gagner beaucoup de temps (ou en tout cas vous évitera d’en perdre).

Dans cet article, nous utiliserons la gem ‘rails-erd’ qui nous permettra en moins de 5 minutes d’avoir une représentation visuelle de notre schéma de base de données (tables, champs et relations) ainsi que des diagrammes visuels de nos modèles et contrôleurs.

Dans la majorité des cas, notre premier réflexe est de faire tourner l’application. Hors cela n’est pas indispensable, voir nécessaire à la compréhension de notre application.

Contexte

Nous allons prendre pour notre exemple un projet rails open-source: sample_app_rails_4. Vous pouvez bien évidemment prendre le projet qui vous plaît.

Nous devons rapidement comprendre le projet afin de commencer à développer. Premièrement nous allons récupérer la source du projet depuis Github.

git clone https://github.com/openbookie/sportbook.git

Installation Gem ‘Rails-erd’

Rails-erd a été conçu pour Rails 3 mais s’adapte bien à Rails 4. Il requiert cependant l’installation de la bibliothèque Graphviz (v2.26+ conseillée) afin de générer les fichiers PDF. Installons donc cette bibliothèque :

Mac OS X avec homebrew :

brew install graphviz

Mac OS X avec Macport :

sudo port install graphviz

Debian ou Ubuntu :

sudo aptitude install graphviz

Afin de pouvoir utiliser la gem dans votre application Rails, il est nécessaire de l’ajouter au Gemfile :

group :development do
  gem 'rails-erd'
end

Puis nous demandons à bundler de nous l’installer :

bundle install

Vous avez maintenant tout ce qu’il faut pour générer votre diagramme.

ATTENTION: Si vous êtes sur MAC OS X avec Mavericks, vous devez modifiez la police utilisée par la gem. Pour ce faire vous devez modifier les fichiers suivants :

“my_app/vendor/gems/rails-erd-1.1.0/lib/rails_erd/diagram/graphviz.rb”

Lignes: 60, 67, 74 changez la police Arial-Bold en Arial-BoldMT et Arial en ArialMT

“my_app/vendor/gems/rails-erd-1.1.0/lib/rails_erd/diagram/templates/node.html.erb”

Lignes: 3,9 changez la police Arial-Bold en Arial-BoldMT et Arial-Italic en Arial-ItalicMT

Utilisation

L’installation de la gem a ajouté une nouvelle tâche rake “rake erd”, nous pouvons le vérifier en tapant “rake -T” dans notre terminal.

Il est temps de générer notre diagramme, pour cela, je lance ma tâche rake associée :

rake erd

Cette commande va générer un fichier ERD.pdf à la racine de notre application, ouvrons le !

Nous voilà face au diagramme que nous attendions. Grâce à celui-ci, nous allons pouvoir identifier tous les modèles de l’application, leurs relations mais également leurs attributs et types associés.

Dans le cas de notre exemple, nous pouvons rapidement savoir que :

• il y a 3 modèles (User, Micropost et Relationship)
• le modèle User peut avoir plusieurs Micropost et plusieurs Relationship

Il y a deux choses importantes à comprendre pour faciliter la lecture :

• le détail des modèles (tables)
• et les relations entre les modèles

Présentation des modèles

Voici la représentation graphique de notre table nommée “User”. Nous apercevons ses attributs, leurs types ainsi que les attributs obligatoires (matérialisés par une étoile).

Relations entre modèles

Notre exemple ne nous permet pas de voir toutes les relations, les images utilisées ci-dessous ne correspondent donc pas (source).

Voici comment sont illustrés les relations entre modèles :

one to one

class Country < ActiveRecord::Base
  # A country may or may not have a head of state.
  has_one :head_of_state
end

class HeadOfState < ActiveRecord::Base
  belongs_to :country

  # A head of state always belongs to a country.
  validates_presence_of :country
end

one to many

class Galleon < ActiveRecord::Base
  # Galleons have up to 36 cannons.
  has_many :cannons

  validates_length_of :cannons, :maximum => 36
end

class Cannon < ActiveRecord::Base
  # A cannon belongs to a galleon.
  belongs_to :galleon
end

many-to-many

class Film < ActiveRecord::Base
  # A film belongs to one or more genres.
  has_and_belongs_to_many :genres
end

class Genre < ActiveRecord::Base
  # Each genre may be applicable for one or more films.
  has_and_belongs_to_many :films
end

many-to-many avec un modéle de jointure

class Wizard < ActiveRecord::Base
  has_many :spells, :through => :spell_masteries
  has_many :spell_masteries
end

class Spell < ActiveRecord::Base
  has_many :spell_masteries
end

class SpellMastery < ActiveRecord::Base
  belongs_to :wizard
  belongs_to :spell
end

inheritance

Inheritance est désactivé par défaut, il faut donc le spécifier rake erd inheritance=true

class Beverage < ActiveRecord::Base
end
class Beer < Beverage
end
class Whisky < Beverage
end

polymorphique

Le polymorphisme est désactivé par défaut, il faut le spécifier également rake erd polymorphism=true

class Barricade < ActiveRecord::Base
  # Defensible structures have many soldiers.
  has_many :soldiers, :as => :defensible
end

class Stronghold < ActiveRecord::Base
  # Defensible structures have many soldiers.
  has_many :soldiers, :as => :defensible
end

class Soldier < ActiveRecord::Base
  # Soldiers belong to a defensible structure.
  belongs_to :defensible, :polymorphic => true
end

Exemple d’un projet rails bien avancé

Afin de se rendre compte de la rapidité de compréhension d’une application grâce à cette gem, nous allons prendre l’exemple d’un projet open source avancé.

Gemcutter est une application qui gère toutes les gems disponibles pour ruby (RubyGems).

Voici son diagramme :

Sans parcourir les fichiers de l’application nous pouvons déjà savoir pour le modèle User par exemple :

• connaître tous les attributs de la table (types compris)
• has_many :web_hook, has_many :subscriptions, has_many :ownerships
• has_many :rubygems, through: ownerships
• has_may :rubygems, through: subscriptions

La lecture du fichier se fait assez facilement et donne une bonne vision globale de l’application. Vous pouvez, à partir de ce diagramme, déduire les relations pour les autres modèles.

Personnaliser notre diagramme

La gem “rails-erd” nous permet de spécifier des options pour notre tâche rake, afin de personnaliser le diagramme que nous voulons générer. Vous pouvez retrouver la totalité des options ici.

Voici quelques exemples de personnalisation:

• Si je génère plusieurs diagrammes, il est utile de spécifier le nom de fichier : rake erd title=’NomDeFichier’
• Vous pouvez également spécifier l’orientation et le type de fichier généré : rake erd orientation=vertical filetype=png
• Nous pouvons également lui demander de n’afficher que certains attributs : rake erd attributes = foreign_keys, primary_keys, timestamps
• Nous pouvons également changer de notation afin d’avoir des informations sur le caractère obligatoire ou non d’une relation (déduit des validations modèles et foreign_keys non nul). La notation Bachman permet de visualiser cela par l’utilisation de cercle vide ou plein aux extrémités de la flèche illustrant la relation : rake erd notation=Bachman

Ce diagramme ne comporte aucunes relations obligatoires (aucun cercle plein à l’extrémité des relations).

A titre d’exemple, voici un diagramme où :

• toutes les compagnies doivent avoir un “Orchar” et peuvent en avoir plusieurs
• certains “Orchar” peuvent avoir une compagnie (pas obligatoire)

Conclusion

Rails ERD permet donc, lorsqu’on doit rapidement s’approprier un projet rails en cours de développement, de pouvoir avoir une vision globale de l’application en un minimum de temps. Les options fournies par la gem nous permettent vraiment de pouvoir exporter à un diagramme selon nos besoins. Cela peut être utile dés que l’on a besoin de présenter le projet à un interlocuteur technique (client ou collaborateur).

Peut-être une gem en plus à votre trousse de travail pour un gain de productivité et support de travail.

L’équipe Synbioz.

Libres d’être ensemble.