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

【反例】
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)

【反例】
-- 截取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)

-- 错误示例,使用os.execute可能导致进程卡死
os.execute('cp /tmp/config.json /dev/shm/config.json')
-- 正确示例,使用vos.system_s执行shell命令
vos.system_s('/bin/cp', '/tmp/config.json', '/dev/shm/config.json')

-- 错误示例：
vos.system_s('/bin/sh', '-c', 'cp', src_dir, '/tmp/test') -- 假设src_dir是外部输入

-- 正确示例: 不使用/bin/sh作为命令解释器
vos.system_s('/bin/cp', src_dir, 'dest_dir') -- 假设src_dir是外部输入

-- 正确示例：使用/bin/sh作为命令解释器，但是有对参数进行校验
local utils_file = require 'utils.file'
if utils_file.check_shell_special_character_s(src_dir) ~= 0 then
   return 
end
vos.system_s('/bin/sh', '-c', 'cp', src_dir, '/tmp/test') -- 假设src_dir是外部输入

require
- 原型：require([modulename])
- 解释：用于加载一个模块代码，如果代码文件是一个代码块，则会执行该代码库。require会搜索目录加载文件，并且会判断是否文件已经加载避免重复加载同一文件 。

load
- 原型：load (chunk [, chunkname [, mode [, env]]])
- 解释：load实现Lua 的反射机制，加载一个代码块，如果chunk是一个字符串，代码块就是这个字符串，chunk也可以是一个函数，通过函数调用获取代码块。如果chunk是一个字符串，且外部可控的话则存在安全风险，攻击者可以通过控制chunk导致一个代码注入。

loadfile
- 原型：loadfile ([filename [, mode [, env]]])
- 解释：通load相似，只是代码块是从文件中获取，如果文件内容可以外部控制，仍然存在代码注入风险。

dofile
- 原型：dofile([filename])
- 解释：加载文件中的代码，如果filename可控，则可以通过新增一个Lua脚本，将filename指定到新增脚本实现代码注入，如果文件内容可控则可以直接修改文件内容，导致代码注入问题。

loadstring
- 原型：loadstring(string [,chunkname])
- 解释：函数会从所给的字符串中来加载程序块并运行，如果省略参数`chunkname`，那么它默认为所给的字符串。

-- 错误示例：自定义SQL语句未进行预编译，存在SQL注入风险
local cmd = 'select * from tb_test where level = ' .. level -- 假设level是外部输入
db:exec(cmd)

-- 正确示例
local cmd = 'select * from tb_test where level = ?'
local vm = db:prepare(cmd) -- 通过框架封装的prepare函数执行预编译
vm:bind_values(level)
vm:step()
vm:finalize()

-- 假设变量ms的单位是毫秒，则：
-- 正确示例：
skynet.sleep(ms // 10)
-- 错误示例：
skynet.sleep(ms / 10)

【反例】
-- 正常new_path参数：/var/log/tmp.log。
-- 异常new_path参数：/var/log/tmp.log’);print('hello    异常场景下，会造成任意lua代码攻击
work:start(string.format([[
    local file_sec = require 'utils.file'
    file_sec.copy_file_s('%s', '%s')
]], tmp_path, new_path))

【正例】
work:start([[
    local file_sec = require 'utils.file'
    local tmp_path = worker:recv()
    local new_path = worker:recv()
    file_sec.copy_file_s(tmp_path, new_path)
]])

work:send(tmp_path, true)
work:send(new_path, true)

-- Lua语言版本
-- 文件安全打开，返回文件描述符，打开文件前会校验文件是否是绝对化路径，及是否存在软链接，是否在指定路径下。本函数返回的对象不支持seek方法，在需要使用seek方法指定写入点的特殊场景下，不能使用open_s替代原始的open函数，而是应该在open函数打开前使用check_realpath_before_open_s校验路径
open_s(filename, mode [, path_header])

-- 判断文件路径是否有效，是否在指定路径下，一般用于文件导入的场景
check_real_path_s(file_path [, path_header])

-- 在文件打开前，对文件路径的校验，判断文件路径是否是绝对路径以及是否存在软链接，是否在指定路径下，适用于文件导出场景
check_realpath_before_open_s(file_path [, path_header])

-- 适用于文件已经打开后，对文件操作前路径的一致性校验，判断文件路径是否是绝对化路径以及是否存在软链接，是否在指定路径下
check_realpath_after_open_s([file], file_path [, path_header])

-- 支持文件移动（源文件移动到目标文件，保留源文件的内容和属性，源文件删除），仅包括文件内容，打开文件进行路径和软链接检查
move_file_s(src_path, dest_path)

-- 支持文件完整拷贝接口，包括文件内容、文件属性（属主、创建时间、修改事件、访问时间等），打开文件进行路径和软链接检查
copy_file_s(src_path, dest_path)

-- 支持文件拷贝接口，仅包括文件内容，打开文件进行路径和软链接检查
copy_file_content_s(src_path, dest_path)

-- 支持文件读接口，读取指定字节数据，打开文件需要进行路径和软链接检查
read_file_s(file_name, size)

-- 支持文件写接口，写入指定数据，打开文件需要进行路径和软链接检查
write_file_s(file_name, data)

-- os.execute的安全版本，用于防命令注入执行shell命令，执行前会校验外部输入的字符串是否包含可能导致shell命令注入的特殊字符，检验失败会抛出错误，特殊字符包含"||", ";", "&&", "$", "|", "&", ">>", ">", "<", "`", "\", "!", "\n"
execute_s(cmd)

-- vos.system_s的安全版本，用于执行shell命令，执行前会校验外部输入的字符串是否包含可能导致shell命令注入的特殊字符，检验失败会抛出错误，特殊字符包含"||", ";", "&&", "$", "|", "&", ">>", ">", "<", "`", "\", "!", "\n"
check_before_system_s(cmd_path [, cmdstring])

-- chmod的安全版本，用于修改文件权限，执行前会判断文件路径是否是绝对化路径以及是否存在软链接，校验失败会返回-1
chmod_s(path, fd_mode)

-- chown的安全版本，用于修改文件的属主和属组，执行前会判断文件路径是否是绝对化路径以及是否存在软链接，校验失败会返回-1
chown_s(path, owner, group)

-- chdir的安全版本，用于切换目录，执行前会判断文件路径是否是绝对化路径以及是否存在软链接，校验失败会抛出错误
chdir_s(dir_path)

-- stat的安全版本，用于显示文件或文件系统的详细信息，执行前会判断文件路径是否是绝对化路径以及是否存在软链接，校验失败会抛出错误
stat_s(path)

-- 错误示例：
function export_event(list, path)
   -- 省略部分代码
    utils.remove(path) -- 错误,未对path进行校验
end

-- 正确示例：
function export_event(list, path)
    if check_realpath_before_open_s(path, '/tmp') ~= 0 then
        return -- path是非预期路径,不能直接删除
    end
    utils.remove(path) -- 正确,已对path进行校验
    -- 省略部分代码
end

-- 解压tar格式文件
-- 函数声明：secure_tar_unzip(file_path, dest_path, max_unzip_file_size, max_file_num)
local utils = require 'mc.utils'
local ok = utils.secure_tar_unzip(file_path, dest_path, max_unzip_file_size, max_file_num)
if not ok then
    log:error('secure_tar_unzip failed')
end

-- 解压zip格式文件
-- 函数声明：unzip_s(file_path, dest_path, max_unzip_file_size, max_file_num)
local utils = require 'mc.utils'
local ok = utils.unzip_s(file_path, dest_path, max_unzip_file_size, max_file_num)
if not ok then
    log:error('unzip_s failed')
end

local function check_owner(ctx, file_path)
    local uid = get_uid_gid_by_name(ctx)   -- 通过上下文获取当前用户的uid
    local file_owner = utils_core.stat_s(file_path).st_uid
    if file_owner ~= uid then
        log:error('file owner(%d) is not match current user(%d)', file_owner, uid)
        utils.remove_file(file_path)
        return false
    end

    return true
end

-- 错误示例
-- 根据cmd_type加载具体的消息处理类
function func(type)
    -- 错误,应该对handlers[cmd_type]判空后再使用,否则传入一个不存在的索引值,会触发程序断言失败
    self.handler_func = handlers[type].func
end

-- 正确示例
function func(type)
    local handler = handlers[type]
    if not handler then
        return
    end
    self.handler_func = handler.func
end

-- 错误案例：
if url:len() > 255 then
    error(base_messages.PropertyValueFormatError(url, '%Url')) -- 错误：url可能是敏感信息
end

-- 正确案例：
if url:len() > 255 then
    error(base_messages.PropertyValueFormatError('******', '%Url')) -- 正确：隐藏了敏感信息
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"