Guide de style de codage OpenResty
API7.ai
December 15, 2022
De nombreux langages de développement ont leurs propres spécifications de codage pour indiquer aux développeurs certaines conventions dans le domaine, afin de maintenir un style de code cohérent et d'éviter certains pièges courants. Le PEP 8 de Python en est un excellent exemple, et presque tous les développeurs Python ont lu cette spécification de codage écrite par les auteurs de Python.
OpenResty n'a pas encore sa propre spécification de codage, et certains développeurs sont régulièrement revus et invités à modifier leur style de code après avoir soumis des PR, ce qui consomme beaucoup de temps et d'efforts qui pourraient être évités.
Il existe deux outils Lint dans OpenResty qui peuvent vous aider à détecter automatiquement le style de code : luacheck et lj-releng. Le premier est un outil Lint commun dans le monde Lua et OpenResty, et le second est un outil Lint écrit en Perl par OpenResty lui-même.
Personnellement, j'installe le plugin luacheck dans l'éditeur VS Code pour avoir un outil de suggestion automatique lorsque j'écris du code ; et dans le CI d'un projet, j'exécute les deux outils, par exemple :
luacheck -q lua
./utils/lj-releng lua/*.lua lua/apisix/*.lua
Après tout, un outil de test supplémentaire n'est jamais une mauvaise chose.
Cependant, ces deux outils se concentrent davantage sur la détection des variables globales, la longueur par ligne et d'autres styles de code de base, ce qui est encore loin du niveau détaillé du PEP 8 de Python, et il n'y a pas de documentation à laquelle se référer.
Aujourd'hui, en me basant sur mon expérience dans les projets open source liés à OpenResty, j'ai résumé la documentation du style de codage OpenResty. Cette spécification est également cohérente avec le style de code de certaines passerelles API comme APISIX et Kong.
Indentation
Dans OpenResty, nous utilisons 4 espaces comme marqueurs d'indentation, bien que Lua ne nécessite pas une telle syntaxe. Voici deux exemples de codes incorrect et correct.
--Non
if a then
ngx.say("hello")
end
--Oui
if a then
ngx.say("hello")
end
Pour plus de commodité, nous pouvons simplifier l'opération en changeant la tabulation en 4 espaces dans l'éditeur que vous utilisez.
Espace
Des deux côtés de l'opérateur, un espace est nécessaire pour les séparer. Voici deux exemples de codes incorrect et correct.
--Non
local i=1
local s = "apisix"
--Oui
local i = 1
local s = "apisix"
Ligne vide
De nombreux développeurs apportent des conventions de développement d'autres langages à OpenResty, comme ajouter un point-virgule à la fin d'une ligne :
--Non
if a then
ngx.say("hello");
end;
Mais en réalité, ajouter des points-virgules rend le code Lua très laid, ce qui est inutile. De plus, vous ne devriez pas transformer plusieurs lignes de code en une seule ligne pour économiser des lignes et être concis. Cela vous laissera sans idée de quelle section de code est en faute lorsque vous localiserez l'erreur.
--Non
if a then ngx.say("hello") end
--Oui
if a then
ngx.say("hello")
end
De plus, les fonctions doivent être séparées par deux lignes vides.
--Non
local function foo()
end
local function bar()
end
--Oui
local function foo()
end
local function bar()
end
S'il y a plusieurs branches if elseif, elles doivent également être séparées par une ligne vide.
--Non
if a == 1 then
foo()
elseif a== 2 then
bar()
elseif a == 3 then
run()
else
error()
end
--Oui
if a == 1 then
foo()
elseif a== 2 then
bar()
elseif a == 3 then
run()
else
error()
end
Longueur maximale par ligne
Chaque ligne ne doit pas dépasser 80 caractères ; si elle dépasse cela, nous devons faire un saut de ligne et aligner. Et lors de l'alignement des sauts de ligne, nous devons refléter la correspondance entre les lignes supérieure et inférieure. Pour l'exemple ci-dessous, l'argument de la fonction sur la deuxième ligne doit être à droite de la parenthèse gauche sur la première ligne.
--Non
return limit_conn_new("plugin-limit-conn", conf.conn, conf.burst, conf.default_conn_delay)
--Oui
return limit_conn_new("plugin-limit-conn", conf.conn, conf.burst,
conf.default_conn_delay)
S'il s'agit de l'alignement de la concaténation de chaînes, nous devons mettre .. sur la ligne suivante.
--Non
return limit_conn_new("plugin-limit-conn" .. "plugin-limit-conn" ..
"plugin-limit-conn")
--Oui
return limit_conn_new("plugin-limit-conn" .. "plugin-limit-conn"
.. "plugin-limit-conn")
Variable
Ce point a également été souligné plusieurs fois dans des articles précédents : nous devrions toujours utiliser des variables locales plutôt que des variables globales.
--Non
i = 1
s = "apisix"
--Oui
local i = 1
local s = "apisix"
En ce qui concerne la nomination des variables, le style snake_case doit être utilisé.
--Non
local IndexArr = 1
local str_Name = "apisix"
--Oui
local index_arr = 1
local str_name = "apisix"
Pour les constantes, en revanche, le style all-caps doit être utilisé.
--Non
local max_int = 65535
local server_name = "apisix"
--Oui
local MAX_INT = 65535
local SERVER_NAME = "apisix"
Table
Dans OpenResty, nous utilisons table.new pour pré-allouer la table.
--Non
local t = {}
for i = 1, 100 do
t[i] = i
end
--Oui
local new_tab = require "table.new"
local t = new_tab(100, 0)
for i = 1, 100 do
t[i] = i
end
De plus, notez que vous ne devez pas utiliser nil dans le tableau, et si vous devez utiliser null, utilisez ngx.null pour l'indiquer.
--Non
local t = {1, 2, nil, 3}
--Oui
local t = {1, 2, ngx.null, 3}
Chaîne de caractères
Ne jamais concaténer des chaînes sur un chemin de code critique.
--Non
local s = ""
for i = 1, 100000 do
s = s .. "a"
end
--Oui
local t = {}
for i = 1, 100000 do
t[i] = "a"
end
local s = table.concat(t, "")
Fonction
La nomination des fonctions suit également snake_case.
--Non
local function testNginx()
end
--Oui
local function test_nginx()
end
Et la fonction doit retourner le plus tôt possible.
--Non
local function check(age, name)
local ret = true
if age < 20 then
ret = false
end
if name == "a" then
ret = false
end
-- faire quelque chose d'autre
return ret
--Oui
local function check(age, name)
if age < 20 then
return false
end
if name == "a" then
return false
end
-- faire quelque chose d'autre
return true
Module
Toutes les bibliothèques require doivent être localisées :
--Non
local function foo()
local ok, err = ngx.timer.at(delay, handler)
end
--Oui
local timer_at = ngx.timer.at
local function foo()
local ok, err = timer_at(delay, handler)
end
Pour la cohérence du style, require et ngx doivent également être localisés :
--Non
local core = require("apisix.core")
local timer_at = ngx.timer.at
local function foo()
local ok, err = timer_at(delay, handler)
end
--Oui
local ngx = ngx
local require = require
local core = require("apisix.core")
local timer_at = ngx.timer.at
local function foo()
local ok, err = timer_at(delay, handler)
end
Gestion des erreurs
Pour les fonctions qui retournent des informations d'erreur, les informations d'erreur doivent être jugées et traitées :
--Non
local sock = ngx.socket.tcp()
local ok = sock:connect("www.google.com", 80)
ngx.say("successfully connected to google!")
--Oui
local sock = ngx.socket.tcp()
local ok, err = sock:connect("www.google.com", 80)
if not ok then
ngx.say("failed to connect to google: ", err)
return
end
ngx.say("successfully connected to google!")
Et dans le cas des fonctions que vous écrivez vous-même, les informations d'erreur doivent être retournées comme deuxième paramètre sous forme de chaîne :
--Non
local function foo()
local ok, err = func()
if not ok then
return false
end
return true
end
--Non
local function foo()
local ok, err = func()
if not ok then
return false, {msg = err}
end
return true
end
--Oui
local function foo()
local ok, err = func()
if not ok then
return false, "failed to call func(): " .. err
end
return true
end
Résumé
Ceci est une version initiale du guide de style de codage, et nous la rendrons disponible sur GitHub pour des mises à jour et une maintenance continues. Vous êtes invités à partager cette spécification afin que plus d'utilisateurs d'OpenResty puissent s'impliquer.