openUBMC社区通用编码规范 ​

【正例】
if found then
   ...
end

【反例】
if is_found then
   ...
end

【正例】
local function print_error_msg()
    local msg
    ...
end

【反例】
local function print_error_msg()
    local error_msg
    ...
end

【反例】
local table_a = setmetatable({}, {__mode = 'kv', __gc = function()
    ...
end}) -- Bad, 弱引用表与__gc元方法混用

【反例】
local table_a = {}
local table_b = {}
...
if table_a == {} then      -- Bad
    ...
end
if table_a == table_b then -- Bad
    ...
end
【正例】
 local table_a = {}
 local table_b = {}
...
if utils.table_compare(table_a, {}) then      -- Good
    ...
end

if utils.table_compare(table_a, table_b) then -- Good
    ...
end

if next(table_a) == nil then                  -- Good
    ...
end

【反例】

-- 线程一
local value = {
    ['Type'] = 'ABC'
}

-- 线程二
-- 可能先于线程一执行，value.Type为nil导致程序抛错
table_a[value.Type] = 1

【正例】

-- 划分到同一个线程先后执行，保证成员变量已构造
local value = {
    ['Type'] = 'ABC'
}

table_a[value.Type] = 1

【反例】
local a = { 1, 2, 3, 4, 5 }
for k, v in pairs(a) do
    print(v) -- Bad, 使用pairs遍历，不保证顺序
end

local b = {
    [1] = '1',
    ['a'] = 'a'
}
for k, v in ipairs(b) do
    print(v) -- Bad, 使用ipairs遍历，未完整遍历所有数据
end

【正例】
local a = {1, 2, 3, 4, 5}
for k, v in ipairs(a) do
    print(v) -- Good, 使用ipairs遍历有序数组
end

local b = {
    [1] = '1',
    ['a'] = 'a'
}
for k, v in pairs(b) do
    print(v) -- Good, 使用pairs遍历所有元素，但不保证顺序
end

【反例】
local a = {
    [2] = 1,
    [3] = 2
} -- Bad，正数健集{2,3}，缺少键值1，a不是序列

local b = {
    [1] = 1,
    [3] = 2,
    [4] = 3
} -- Bad，正数键集{1,3,4}，键值不连续。禁止对不连续的数组表求长度，结果不可预测

local c = {
    [-1] = 1,
    [0] = 2,
    [1] = 3,
    [2] = 4,
    ['s'] = 5
} -- Bad，正数健集{1,2}，c是序列，但不推荐使用#取长度，容易误认为其他键值也参与长度计算
【正例】
local d = {
    [1] = 1,
    [2] = 2,
    [3] = 3,
} -- Good，正数键集{1,2,3}，d是序列，且未包含其他类型键值，#d是预期的3

【反例】
local a = {
    [2] = 1,
    [3] = 2
}
table.remove(a, 2) -- Bad，报错bad argument #1 to 'remove' (position out of bounds)
【正例】
local a = {
    [1] = 1,
    [2] = 2,
    [3] = 3
}
table.remove(a, 2) -- Good，成功删除键为2的元素，删除后该表为{[1] = 1, [2] = 3}

local b = {
    [2] = 1,
    [3] = 2
}
b[2] = nil -- Good，成功删除键为2的元素，删除后该表为{[3] = 2}

【反例】
local a = { 1, 2, 3 }
for k, v in pairs(a) do
    a[k] = nil
    a[k + 3] = v -- Bad，报错invalid key to 'next'
end

【反例】
-- 弱引用表db_objs用来存放db对象
local db_objs = setmetatable({}, {__mode = 'kv'})
function add_db_obj(obj)
    -- 将需要持久化的obj添加到待持久化的对象列表db_objs中
    db_objs[obj] = context.get_context() or context.new()
    -- 由于db_objs是弱引用表，离开当前函数作用域之后obj可能被垃圾回收
end
local function save_all_objs()
    for obj, ctx in pairs(db_objs) do
        -- 遍历db_objs时，表中对象可能已经被垃圾回收，造成数据丢失
        obj:save()
    end
end

【正例】
-- 弱引用表g_obj_pool的作用是提供缓存池，避免频繁重复创建对象
local g_obj_pool = setmetatable({}, {__mode = 'kv'})
local function new_obj()
    local obj = table.remove(g_obj_pool)
    if not obj then
        -- 表中对象已被垃圾回收时可以重新创建，不影响业务功能
        return new_object()
    end
    -- 表中对象没有被垃圾回收时可以重复利用，避免频繁创建新对象的消耗
    return obj
end

【反例】
function plugin_method.set_property(parameter)
    local ok, rsp = pcall(func, parameter) -- Bad，table参数直接传入插件
    ...
end

【正例】
function plugin_method.set_property(parameter)
    local input_location = utils.table_copy(parameter)     -- Good，深拷贝一份table参数传入插件
    local ok, rsp = pcall(func, parameter)
    ...
end

local table_cache = require 'mc.table_cache'
local instance = table_cache.new()  -- 实例化
local config = instance:allocate()  -- 申请空表

instance:deallocate(config)  -- 销毁

【反例】
for i = 1, #array do
    local a
    a = array[i].number
    ...
end
【正例】
local a
for i = 1, #array do
    a = array[i].number
    ...
end

【反例】
local res, _ = func(cmd, _, request.data_out)  -- Bad, _可能已作为全局变量被赋值
...

function func(cmd, data_in, data_out)
    if data_in then -- 如果data_in非空，执行额外命令
        ...
    end
end
【正例】
local res, _ = func(cmd, nil, request.data_out, nil)  -- Good, 直接通过nil占位

【示例】
local a = 5 / 2
local b = 5 // 2

print('a = ', a)      -- 输出为 a =     2.5
print('b = ', b)      -- 输出为 b =     2

【反例】
if a > b then  -- a、b为字符串类型
    ...
end

-- 错误示例
local flag = table[Id]
if flag ~= 0 then
    ...
end
flag = 1  -- 对flag赋值不会改变table[Id]

【反例】
if #v.SRVersion > 0 then  -- Bad，未确保变量为table或string类型，程序可能抛错
    ...
end
【正例】
if type(v.SRVersion) == 'string' and #v.SRVersion > 0 then  -- Good，先确保变量为string类型再取长度
    ...
end

【反例】
function get_selLogEntries(processObj)
    local eventList = processObj.EventList
    local selLogEntries = {}
    for i, v in pairs(eventList) do
        selLogEntries[i] = {        -- Bad, 使用Lua的table，无序
            ["eventid"] = eventList[i].RecordId,
            ["subjecttype"] = "TODO",
            ["eventdesc"] = eventList[i].Description,
        }
    end
    return selLogEntries
end

【正例】
function get_selLogEntries(processObj)
    local eventList = processObj.EventList
    local selLogEntries = cjson.json_object_new_array()     -- Good, 使用cjson接口保证数据的有序性
    for i, v in pairs(eventList) do
        selLogEntries[i] = cjson.json_object_new_object()
        selLogEntries[i].eventid = eventList[i].RecordId
        selLogEntries[i].subjecttype = 'TODO'
        selLogEntries[i].eventdesc = eventList[i].Description
    end
    return selLogEntries
end

【示例】
-- 从uri中匹配文件后缀名.ISO
-- plain参数设置为true，表示进行简单搜索，不进行模式匹配，'.'不会被视为特殊字符
-- 如果需要传入第4个参数，第3个参数必须也传入，1表示从第1个字符开始搜索
local start_pos = string.find(uri, '.ISO', 1, true)

【反例】
local res1 = (val_a == 1) and false or true  -- Bad，结果恒为true

local res2 = (val_a == 1) and (val_b == 1) or true  -- Bad，当不满足val_b == 1时，结果恒为true

【正例】
local res1 = (val_a ~= 1)

local res2
if val_a == 1 then
    res2 = (val_b == 1)
else
    res2 = true
end

【示例】
-- 如果当前日志级别小于INFO，则不会进入分支执行 cjson.encode
if log:getLevel() >= log.INFO then
    log:info('RefVolumes:%s RefDrives:%s.', cjson.encode(array_obj.RefVolumes),
        cjson.encode(array_obj.RefDrives))
end

【反例】
function func()
    local co = coroutine.running()

    local function check()
        ...
        -- 此处的skynet.wakeup可能唤醒的是skynet.sleep挂起的协程，非代码预期情况
        skynet.wakeup(co)
    end

    -- 创建协程，在协程中唤醒co
    skynet.fork(check)
    -- skynet.sleep相当于skynet.wait()，挂起当前协程
    skynet.sleep(10)

    -- 预期在此处挂起和唤醒当前协程
    skynet.wait()
    co = nil
end

【正例】
function func()
    local co = coroutine.running()

    local function check()
        ···
        -- 唤醒的为skynet.wait()挂起的协程，与预期相符
        skynet.wakeup(co)
    end

    skynet.fork(function()
        skynet.fork(check)
        -- skynet.sleep挂起新协程，不会影响原协程
        skynet.sleep(10)
    end)

    -- 把创建协程与skynet.sleep的操作放在新协程中，当前skynet.wait()正常挂起
    skynet.wait()
    co = nil
end

【反例】
function c_network_adapter:set_npu_max_sfp_temp()
    local ops = c_optical_module.collection:fetch({NetworkAdapterId = self.NodeId})
    skynet.fork(function()   -- Bad，通过skynet.fork创建协程
        while true do
            self:update_npu_max_sfp_temp(ops)
        end
    end)
end
【正例】
function c_network_adapter:set_npu_max_sfp_temp()
    local ops = c_optical_module.collection:fetch({NetworkAdapterId = self.NodeId})
    self:next_tick(function()  -- Good，通过ORM自带方法创建协程
        while true do
            self:update_npu_max_sfp_temp(ops)
        end
    end)
end

【反例】
local_db:delete(local_db['Power']):exec()
for _, v in pairs(power_table) do
    local power_row_data = local_db['Power'](saved_data)
    power_row_data:save() -- Bad, 在循环中进行数据库插入
end

【正例】
local ok, err = pcall(local_db.db.tx, local_db.db, function ()
    local_db:delete(local_db.Power):exec()
    for _, v in pairs(power_table) do
        local_db.Power(v):save() -- Good, 将数据库插入放在事务中执行
    end
end)

【错误示例】
-- 以下通过路径直接访问了pcie_device组件的复位持久化数据库，可能会造成数据库异常
local Databases = require 'database'
local db = Databases('/opt/bmc/pram/persistence.local/pcie_device.db')
local vm = db:prepare(sql_cmd)

【反例】
-- 截取position后两位做为slot，若sr配置变化，则可能出现功能问题。Slot属性改为在sr配置即可
object.Slot = tonumber(string.sub(position, -2))

local log = require 'mc.logging'

local c = 5 / 2
local d = 5 // 2

log:info('c = %d', c)      -- Bad，  c = 2.5 程序会抛异常
log:info('d = %d', d)      -- Good， d = 2

【示例】
log:error('fail count = %s', a)  -- a为number类型，即使为nil也能正常运行

【反例】
utils.chmod(file_path, 0640)
【正例】
utils.chmod(file_path, utils.S_IRUSR | utils.S_IWUSR | utils.S_IRGRP) -- 0640权限

【反例】
local queue = require 'skynet.queue'
local cs = queue() -- 全局队列

local s = class()

function s:fun1()
    cs(funa, ...)
end

function s:fun2()
    cs(funb, ...) -- funa和funb共用全局队列，funa的执行也会对funb产生影响；不同的s实例对象之间的funa与funb执行也会互相影响；队列混用容易导致阻塞时间长，引发性能问题
end

【正例】
local queue = require 'skynet.queue'

local s = class()

function s:ctor()
    self.cs_a = queue()
    self.cs_b = queue() -- 不同对象以及不同函数的队列分开声明，避免互相影响
end

function s:fun1()
    self.cs_a(funa, ...)
end

function s:fun2()
    self.cs_b(funb, ...)
end

【反例】
self.run("sed -i '12 i\  chown root:root /dev/shm/dbus/.dbus' rundbus.sh") -- Bad，通过行号查找

【正例】
self.run("sed -i '$ i\chown root:root /dev/shm/dbus/.dbus' rundbus.sh") -- Good，基于行尾查找

【反例】
local ok, ret = pcall(function ()
    return skynet.send('main', 'lua', 'exec_function', parameter)  -- Bad，无论是否存在main服务或exec_function是否执行成功，pcall返回结果恒为true
end)

【正例】
local ok, ret = pcall(function ()
    return skynet.call('main', 'lua', 'exec_function', parameter)  -- Good，当main服务不存在或exec_function执行异常，pcall能正常捕获，ret也能正常接收到执行返回值
end)

function socket.read(id, sz)
    local s = socket_pool[id]
    assert(s)
    ...
end

function websocket.write(id, data, fmt, masking_key)
    local ws_obj = assert(ws_pool[id])
    fmt = fmt or "text"
    assert(fmt == "text" or fmt == "binary")
    write_frame(ws_obj, fmt, data, masking_key)
end

【反例】
"Name": "${Slot} |> string.format('Cpu%sChannel0', $1 * 2)"  -- Bad, string.format的参数使用了表达式。若${Slot}为1，结果为"Cpu1 * 2Channel0"
【正例】
"Name": "${Slot} |> expr($1 * 2) |> string.format('Cpu%sChannel0', $1)" -- Good, 将表达式的结果作为string.format的参数。若${Slot}为1，结果为"Cpu2Channel0"